AgentFlow Runtime: Structured Multi-Agent Workflow Runtime, Making Coding Agent Collaboration Predictable and Traceable

Core Introduction: A TypeScript/Node.js-based multi-agent workflow runtime that configures structured roles (e.g., Researcher, Planner) via JSON templates, enabling deterministic execution, output validation, and full traceability. It supports Mock mode by default without requiring an API key. This solves the problems of unpredictable behavior and difficulty in tracing in LLM agent collaboration, positioning itself as an engineering collaboration framework rather than a chat-based agent tool.

Problem Background: In LLM agent application development, the predictability and traceability of multi-agent collaborative behavior are core challenges. Design Philosophy: Adhere to the principles of explicit over implicit, verification over trust, traceability over memory, and determinism over flexibility. The goal is to make agent collaboration predictable, verifiable, and auditable.

System Architecture: TaskBrief input → WorkflowRunner/WorkflowRuntime loads JSON template → AgentNode role node processes → TraceStore stores trace data. Runtime Responsibilities: Load configurations, call executors, validate outputs, write context, parse edge conditions, record traces, etc. (does not determine role behavior or hardcode processes). Predefined Roles: Provides structured roles such as Researcher (research), FeasibilityEvaluator (feasibility evaluation), Planner (planning), Executor (execution), etc. Workflow Templates: Examples include research-feasibility-execute-verify (feasibility gating), code-test-verify (code verification), etc.

Quick Start: Clone the repository → npm run demo (Mock mode) → run a specific template (e.g., npm run workflow -- --template code-test-verify). Configuration Management: Supports layered configuration (profiles directory), allows switching configurations (e.g., rag-optimization, coding-safe-fix), and automatically routes tasks to the appropriate configuration. Resumable Sessions: Can resume via sessionId when a session is interrupted, supporting manual approval steps.

Validation and Gating: The code-test-verify template checks code execution status, test results, etc., via validators. If it fails, it routes to a repair plan or manual approval. Traceability and Verifiability: Each execution record is persisted to .workflow-runs/, and roles are only displayed when there is a runtime_trace record (ensuring verifiability). LLM Integration: Mock mode is enabled by default without requiring an API key; optional real LLM calls (e.g., OpenAI/DeepSeek) are supported (requires explicit configuration). Tech Stack: Node.js (supports --experimental-strip-types), no additional dependencies (uses only built-in modules).

Applicable Scenarios: Strictly controlled automated processes (e.g., code review), multi-step approvals (security fixes), reproducible experiments, multi-agent collaboration demos. Inapplicable Scenarios: Open-ended conversations, real-time interactions, highly creative tasks. Comparison with Chat-based Frameworks: AgentFlow Runtime is a deterministic workflow (highly reproducible), structured communication, full traceability; traditional frameworks are non-deterministic conversations, free text, low reproducibility.

Conclusion: AgentFlow Runtime provides an engineering multi-agent collaboration framework, with core value in controllability (predictable, verifiable, auditable), suitable for scenarios requiring strict control (e.g., code generation, production changes). Recommendations: 1. For developers needing controlled collaboration, try Mock mode for quick experiments; 2. Study its structured role and workflow template design for reference in your own projects; 3. For open-ended scenarios, you may need to combine it with other chat-based frameworks.