ChatDev 2.0 (DevAll)

The DevAll backend documentation is organized by user role and functional area. Use the following map to find relevant guides:

• Frontend & Operations: Use Web UI Quick Start for interface operations, workflow execution, and human review.
• Workflow Design: Use Workflow Authoring for YAML structure, node types, and CLI execution.
• Advanced Execution: Refer to Graph Execution Logic for DAG/cyclic graph details and Dynamic Parallel Execution for Map/Tree modes.
• Module Customization:
  • Memory: Memory Module for simple/file/blackboard behaviors.
  • Reasoning: Thinking Module for self-reflection and custom modes.
  • Tools: Tooling Module for Function/MCP modes and context injection.
• API & Standards:
  • Node Configs: Node Types Reference for Agent, Python, Human, etc.
  • Data/Files: Attachment & Artifact APIs for upload/download and manifest schemas.
  • Metadata/Schema: FIELD_SPECS Standard for UI form metadata and Config Schema API Contract for /api/config/schema(*) integrations.

The executor automatically passes a _context dictionary into your functions. This allows your tools to interact with the agent's environment.

Available Context Keys

Usage Pattern

Declare the parameter as _context: dict | None = None in your function signature. You can then parse it to access workspace paths or attachment stores.

from typing import Annotated
from utils.function_catalog import ParamMeta

def read_text_file(
    path: Annotated[str, ParamMeta(description="workspace-relative path")],
    *,
    encoding: str = "utf-8",
    _context: dict | None = None,
) -> str:
    # Example of using context to resolve paths
    ctx = FileToolContext(_context)
    target = ctx.resolve_under_workspace(path)
    return target.read_text(encoding=encoding)

The Loop Counter node acts as a circuit breaker or iteration guard. To function correctly within a graph, it must follow specific topological patterns because it suppresses all output until the limit is reached.

Core Logic

1. Triggered: Counter increments by 1.
2. Counter < max_iterations: No output is produced; outgoing edges are not triggered.
3. Counter == max_iterations: The message is produced, triggering outgoing edges.

Required Graph Structure

To prevent premature termination or broken loops, you must connect the nodes as follows:

1. Human/Agent Connection: The node responsible for continuing the loop (e.g., a Human or Agent) must connect to both the loop participant (to continue the work) and the Loop Counter (to increment the count).
2. In-Loop Connection: The Loop Counter must connect back to the node inside the loop (e.g., the Writer) so it is recognized as part of the loop cycle.
3. Out-of-Loop Connection: The Loop Counter must connect to an End Node (outside the loop) to trigger the termination of the entire workflow once the limit is reached.

Visual Pattern:

    ┌──────────────────────────────────────┐
    ▼                                      │
  Agent ──► Human ─────► Loop Counter ──┬──┘
    ▲         │                         │
    └─────────┘                         ▼
                                   End Node (outside loop)

Understanding these core terms is essential for interacting with the DevAll backend:

• Session: A unique identifier (composed of a timestamp and name) for a single execution run, used to track data across the Web UI, backend, and WareHouse/ storage.
• code_workspace: A shared directory located at WareHouse/<session>/code_workspace/ used by Python nodes; it is synchronized with relevant attachments.
• Attachment: Files that are either uploaded by users or generated during a workflow run. These are accessible via REST or WebSocket APIs.
• Memory Store / Attachment: Memory Stores are the persistence backends (e.g., simple, file, blackboard). Memory Attachments define how agent nodes interact with these stores across different execution phases.
• Tooling: The execution environment associated with agent nodes, implemented via Function or MCP (Model Context Protocol) modes.

The Memory module allows Agents to retrieve and store information. It is a two-step configuration process:

1. Declare a Memory Store at the Graph Level

Use the Manage Memories interface in the Workflow UI to add a new Memory Store.

Supported Memory Types:

Note: simple and file types require an Embedding Provider (e.g., OpenAI text-embedding-3-small).

2. Attach Memory to an Agent Node

In the Agent node configuration, use Memory Attachments to select a store and configure:

• Read/Write: Control if the node can read from or write to the memory.
• Top K: Number of items to retrieve.
• Retrieve Stage: When to perform retrieval (e.g., Gen Stage).

DevAll operates as a workflow orchestration engine that parses YAML DAGs and coordinates various node types (model, python, tooling, and human) within a shared context.

Execution Lifecycle

1. Entry: Requests enter via the FastAPI server (e.g., server_main.py) through endpoints like /api/workflow/execute.
2. Validation & Setup: WorkflowRunService validates the YAML, initializes a unique Session, and prepares the code_workspace/attachments/ directories.
3. Execution: The scheduler in workflow/ resolves dependencies. Node executors manage context propagation, tool calls, and memory retrieval via MemoryManager, ToolingConfig, and ThinkingManager.
4. Observability: Real-time updates (node states, stdout/stderr, artifact events) are streamed via WebSockets to the UI. Structured JSON logs are stored in logs/.
5. Asset Management: All run assets (attachments, Python workspace, context snapshots) are stored in WareHouse/<session>/ and can be downloaded via Attachment APIs.