ChatDev Ability Units

Ability units represent capability units. You can browse what's available, inspect

required args, run them, or upload new ones. Use these endpoints when you need to

invoke a predefined ability unit (e.g., paper review, data visualization) via the

local API.

Run ability units via the local API and return final_message from the JSON response.

API endpoints

1) Browse ability units

• Method: GET
• URL: http://127.0.0.1:6400/api/workflows
• Example:

```

curl --noproxy 127.0.0.1 -v http://127.0.0.1:6400/api/workflows

```

2) Get ability unit raw content

• Method: GET
• URL: http://127.0.0.1:6400/api/workflows//get
• Purpose: fetch the raw YAML content for an ability unit file.
• Example:

```

curl --noproxy 127.0.0.1 -v \

http://127.0.0.1:6400/api/workflows/test.yaml/get

```

3) Get ability unit args

• Method: GET
• URL: http://127.0.0.1:6400/api/workflows/.yaml/args
• Purpose: fetch input parameter schema for an ability unit.
• Example:

```

curl --noproxy 127.0.0.1 -v -X GET \

http://127.0.0.1:6400/api/workflows/test.yaml/args

```

4) Run ability unit

• Method: POST
• URL: http://127.0.0.1:6400/api/workflow/run
• Content-Type: application/json
• SSE support: set Accept: text/event-stream to stream events (started, log,

completed, error). Omit the header to get the normal JSON response.

• Output: parse JSON and return final_message. If missing, report failure and

include any error fields. After you get output_dir, move it to your working

directory.

• Available ability units:

1) Paper Review

• yaml_file: yaml_instance/paper_review.yaml
• task_prompt: arXiv URL/ID or paper title.
• Purpose: fetch content and deliver technical + writing reviews.
• Example:

```

curl --noproxy 127.0.0.1 -v -X POST http://127.0.0.1:6400/api/workflow/run \

-H "Content-Type: application/json" \

-H "Accept: text/event-stream" \

-d '{

"yaml_file": "yaml_instance/paper_review.yaml",

"task_prompt": "https://arxiv.org/abs/1706.03762"

}'

```

2) Data Visualization

• yaml_file: yaml_instance/data_visualization_basic.yaml
• task_prompt: dataset description + analysis goals.
• attachments: absolute paths to CSV files.
• Purpose: profile, clean, plan 4-6 charts, iterate visualizations.
• Example:

```

curl --noproxy 127.0.0.1 -v -X POST http://127.0.0.1:6400/api/workflow/run \

-H "Content-Type: application/json" \

-d '{

"yaml_file": "yaml_instance/data_visualization_basic.yaml",

"task_prompt": "please analyze and visualize the data",

"attachments": ["/Users/yufan/Projects/bugfix/ChatDev/sample_sales.csv"]

}'

```

5) Upload ability unit

• Method: POST
• URL: http://127.0.0.1:6400/api/workflows/upload/content
• Content-Type: application/json
• Format notes: filename should end with .yaml; content must be a valid YAML

string that includes version, vars, and a graph with id, start,

nodes, and edges (as in the example).

• Tip: if uploads keep failing with format errors, call the "get ability unit raw content" endpoint to inspect

an existing ability unit's structure and copy its format.

• Example:

```

curl --noproxy 127.0.0.1 -v -X POST \

http://127.0.0.1:6400/api/workflows/upload/content \

-H "Content-Type: application/json" \

-d @- <<'EOF'

{

"filename": "test.yaml",

"content": "version: 0.4.0\nvars: {}\ngraph:\n id: paper_review\n description: Three agents collaboratively review academic papers from different perspectives. Input can be an arxiv URL or paper title.\n is_majority_voting: false\n start:\n - Paper Fetcher\n nodes:\n - id: Paper Fetcher\n type: agent\n config:\n name: gpt-4o\n provider: openai\n role: |\n You are a paper content fetcher.\n base_url: ${BASE_URL}\n api_key: ${API_KEY}\n description: Fetches paper content from arxiv\n context_window: 0\n edges: []"

}

EOF

```

6) Update ability unit

• Method: PUT
• URL: http://127.0.0.1:6400/api/workflows//update
• Content-Type: application/json
• Format notes: same payload as upload (filename + YAML content string).
• Example:

```

curl --noproxy 127.0.0.1 -v -X PUT \

http://127.0.0.1:6400/api/workflows/test.yaml/update \

-H "Content-Type: application/json" \

-d @- <<'EOF'

{

"filename": "test.yaml",

"content": "version: 0.4.0\nvars: {}\ngraph:\n id: paper_review\n description: Update example.\n is_majority_voting: false\n start:\n - Paper Fetcher\n nodes:\n - id: Paper Fetcher\n type: agent\n config:\n name: gpt-4o\n provider: openai\n role: |\n You are a paper content fetcher.\n base_url: ${BASE_URL}\n api_key: ${API_KEY}\n description: Fetches paper content from arxiv\n context_window: 0\n edges: []"

}

EOF

```

7) Rename ability unit

• Method: POST
• URL: http://127.0.0.1:6400/api/workflows//rename
• Content-Type: application/json
• Body: { "new_filename": "new_name.yaml" }
• Example:

```

curl --noproxy 127.0.0.1 -v -X POST \

http://127.0.0.1:6400/api/workflows/test.yaml/rename \

-H "Content-Type: application/json" \

-d '{"new_filename":"renamed.yaml"}'

```

8) Copy ability unit

• Method: POST
• URL: http://127.0.0.1:6400/api/workflows//copy
• Content-Type: application/json
• Body: { "new_filename": "copy.yaml" }
• Example:

```

curl --noproxy 127.0.0.1 -v -X POST \

http://127.0.0.1:6400/api/workflows/test.yaml/copy \

-H "Content-Type: application/json" \

-d '{"new_filename":"test-copy.yaml"}'

```

9) Delete ability unit

• Method: DELETE
• URL: http://127.0.0.1:6400/api/workflows//delete
• Example:

```

curl --noproxy 127.0.0.1 -v -X DELETE \

http://127.0.0.1:6400/api/workflows/test.yaml/delete

```

10) List local tools (function_calling)

• Method: GET
• URL: http://127.0.0.1:6400/api/tools/local
• Example:

```

curl --noproxy 127.0.0.1 -X GET http://127.0.0.1:6400/api/tools/local

```

Tools hot updates

Local function tools are managed via the same backend (port 6400).

Endpoints:

• List local tools: GET http://127.0.0.1:6400/api/tools/local
• Create/overwrite local tool file: POST http://127.0.0.1:6400/api/tools/local

Create example:

curl --noproxy 127.0.0.1 -X POST http://127.0.0.1:6400/api/tools/local \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "add.py",
    "content": "def add(a: int, b: int) -> dict:\n    return {\"result\": a + b}\n",
    "overwrite": true
  }'

YAML example (local function_calling):

tooling:
  - type: function
    config:
      tools:
        - name: add

Common scenarios and tool suggestions

• If the agent needs to search the web, use web_search.
• If the agent needs to fetch a URL's content, use read_webpage_content.
• If the agent needs to inspect local files, use describe_available_files and list_directory.
• If the agent needs to read a file snippet, use read_text_file_snippet or read_file_segment.
• If the agent needs to write output files, use save_file.

Advanced Workflow Templates

Below are advanced YAML templates you can copy and adapt. They cover debate loops,

subgraph reuse, conditional edges, and selective payload routing.

1) Two-Agent Debate Loop with Judge Stop Criteria

version: 0.4.0
vars: {}
graph:
  id: debate_loop
  description: Two agents debate until the judge outputs "Verdict: STOP".
  is_majority_voting: false
  start:
    - Topic
  nodes:
    - id: Topic
      type: passthrough
      config: {}
    - id: Pro
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          You are the PRO debater. Respond with arguments and counterpoints.
    - id: Con
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          You are the CON debater. Respond with arguments and counterpoints.
    - id: Judge
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          Evaluate the debate. Output:
          Score: <0-1>
          Notes: <brief>
          Verdict: CONTINUE|STOP
    - id: Final
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          Produce the final summary of the debate and recommendation.
  edges:
    - from: Topic
      to: Pro
      keep_message: true
    - from: Topic
      to: Con
      keep_message: true
    - from: Pro
      to: Judge
    - from: Con
      to: Judge
    - from: Judge
      to: Pro
      condition: need_reflection_loop
    - from: Judge
      to: Con
      condition: need_reflection_loop
    - from: Judge
      to: Final
      condition: should_stop_loop

2) Subgraph Reuse + Selective Payload Passing

version: 0.4.0
vars: {}
graph:
  id: parent_with_subgraph
  description: Uses a subgraph and only forwards the "Summary" section.
  start:
    - Request
  nodes:
    - id: Request
      type: passthrough
      config: {}
    - id: ResearchSubgraph
      type: subgraph
      config:
        type: file
        config:
          path: "subgraphs/deep_research_executor_sub.yaml"
    - id: Writer
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          Write the final report using only the provided Summary.
  edges:
    - from: Request
      to: ResearchSubgraph
      keep_message: true
    - from: ResearchSubgraph
      to: Writer
      process:
        type: regex_extract
        config:
          pattern: "Summary:\\s*(.*)"
          group: 1
          multiline: true
          dotall: true
          on_no_match: pass

3) Conditional Routing + Minimal Payload

version: 0.4.0
vars: {}
graph:
  id: router_with_conditions
  description: Route to different nodes based on tags; forward only CONTENT block.
  start:
    - Router
  nodes:
    - id: Router
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          Decide the route. Output exactly:
          ROUTE: QA|REPORT
          CONTENT: <payload to forward>
    - id: QA
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          Answer the question concisely.
    - id: REPORT
      type: agent
      config:
        provider: openai
        base_url: ${BASE_URL}
        api_key: ${API_KEY}
        name: gpt-4o
        role: |
          Write a structured report.
  edges:
    - from: Router
      to: QA
      condition:
        type: keyword
        config:
          any: ["ROUTE: QA"]
      process:
        type: regex_extract
        config:
          pattern: "CONTENT:\\s*(.*)"
          group: 1
          dotall: true
          on_no_match: drop
    - from: Router
      to: REPORT
      condition:
        type: keyword
        config:
          any: ["ROUTE: REPORT"]
      process:
        type: regex_extract
        config:
          pattern: "CONTENT:\\s*(.*)"
          group: 1
          dotall: true
          on_no_match: drop

Tips

• Any workflow YAML can be used as a subgraph to compose more complex tasks, including existing ability units/workflows. Example:

```

• id: Research Subgraph

type: subgraph

config:

type: file

config:

path: "yaml_instance/deep_research_v1.yaml"

```

• Ensure that all generated artifacts are output to your workspace file paths whenever possible
• Ensure that all agents’ roles are concise, sophisticated, and equipped with sufficient tools