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: text

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

1. 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: text

  curl --noproxy 127.0.0.1 -v \
    http://127.0.0.1:6400/api/workflows/test.yaml/get
  
  

1. Get ability unit args

• Method: GET

• URL: http://127.0.0.1:6400/api/workflows/ <ability_unit>.yaml/args

• Purpose: fetch input parameter schema for an ability unit.

• Example: text

  curl --noproxy 127.0.0.1 -v -X GET \
    http://127.0.0.1:6400/api/workflows/test.yaml/args
  
  

1. 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: text

    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"
      }'
    
    

  1. 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: text

    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"]
      }'
    
    

1. 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: text

  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
  
  

1. 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: text

  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
  
  

1. 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: text

  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"}'
  
  

1. 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: text

  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"}'
  
  

1. Delete ability unit

• Method: DELETE

• URL: http://127.0.0.1:6400/api/workflows//delete

• Example: text

  curl --noproxy 127.0.0.1 -v -X DELETE \
    http://127.0.0.1:6400/api/workflows/test.yaml/delete
  
  

1. List local tools (function_calling)

• Method: GET

• URL: http://127.0.0.1:6400/api/tools/local

• Example: text

  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:

text

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):

text

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#

yaml

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#

yaml

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#

yaml

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: text

• 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