ChatDev Python SDK

This package is a Python SDK wrapper around the upstream ChatDev project. By passing a yaml_file path, you can load and execute the multi-agent system defined by the graph and nodes in the YAML file. In Python, you only need to provide yaml_file + task_prompt (and optionally api_key / model / etc.) to run the workflow and get results.

Quick Start

Installation

From the repository root:

pip install chatdev

Environment Variables:

Some YAML configurations require api_key and base_url. You can use export to add global environment variables:

export API_KEY="YOUR_API_KEY"
export BASE_URL="YOUR_BASE_URL"

Test Example:

from chatdev import run_workflow

result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="This is a minimal run example",
)

print(result.success)
print(result.final_message)
print(result.output_dir)

Pass configs (default: the first node ID in the YAML file):

result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="test",
    agent_configs=AgentConfig(
        provider="openai",
        model="gpt-4o",
        api_key="YOUR_API_KEY",
        base_url="https://api.openai.com/v1",
        temperature=1.0,
    ),
)

Specify a node ID:

result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="test",
    agent_configs={
        "Programmer Code Review": AgentConfig(
            provider="openai",
            model="gpt-4o",
            api_key="YOUR_API_KEY",
            base_url="https://api.openai.com/v1",
            temperature=1.0,
        ),
    },
)

Tools & Skills registration example:

from chatdev import AgentConfig, register_skill, register_tool, run_workflow

@register_skill(
    name="data_analyzer",
    description="Analyze data and generate a report",
    instructions="Please analyze the input in a structured way and output three conclusions.",
)

@register_tool(name="my_echo", description="Echo input")
def my_echo(text: str) -> str:
    return text

result = run_workflow(
    yaml_file="ChatDev_v1.yaml",
    task_prompt="test",
    agent_configs={
        "Programmer Code Review": AgentConfig(
            provider="openai",
            model="gpt-4o",
            api_key="YOUR_API_KEY",
            base_url="https://api.openai.com/v1",
            temperature=1.0,
            tools=["my_echo"],
            skills=["data_analyzer"]
        ),
    },
)

SDK API Reference

chatdev.run_workflow(...)

Execute a workflow YAML file and return ChatDevResult:

• yaml_file: str | Path — the workflow YAML path
• task_prompt: str — your task input
• attachments: list[str | Path] | None — optional attachment paths (packaged into the execution workspace)
• variables: dict | None
• agent_configs: AgentConfig | dict[str, AgentConfig] | None
  • Passing a single AgentConfig: automatically attach it to the first node whose type is agent or model (the order of nodes in the YAML). If there is no such node, it falls back to the first node with a non-empty id.
  • Passing a dict[node_id, AgentConfig]: only update the node with that exact id (no "default" fallback).

chatdev.AgentConfig

Optional parameters for overriding/injecting model configuration (merged into the matched node’s config; commonly the agent / model nodes in YAML):

• provider: "openai" / "gemini" / ...
• model: e.g. "gpt-4o"
• api_key
• base_url
• system_prompt: overrides the YAML role
• temperature/top_p/max_tokens
• skills: add custom skills
• tools: add custom tools

chatdev.ChatDevResult

The return object of run_workflow (common fields):

• success: whether it succeeded
• final_message: the final output text (string)
• output_dir: the output directory of this run (Path)

Extensions: Register Tools & Skills (Optional)

You can register tools/skills with decorators:

• @chatdev.register_tool(name=..., description=...)
• @chatdev.register_skill(name=..., description=..., ...)

Citation

If you use this project in research or products, please cite ChatDev's GitHub repository: OpenBMB/ChatDev