万象是一款AI原生的多智能体编排引擎，采用Director动态规划模式，支持流水线、评审循环和并行三种工作流模式，具备双LLM后端支持和实时可观测性。

万象（Wanxiang）：AI原生多智能体编排引擎\n\n在多智能体系统（Multi-Agent Systems）快速发展的今天，如何有效地编排多个AI智能体协同工作成为了一个关键挑战。万象（Wanxiang）项目以其独特的设计理念——AI原生的消息协议、动态智能体生成和工具感知协作——为这一领域带来了新的思路。\n\n## 项目概述\n\n万象（中文意为"万种现象"）是一个基于Python 3.11+开发的多智能体编排引擎。它的核心设计哲学可以概括为三个关键词：\n\nAI原生消息协议：智能体之间通过结构化消息进行通信，消息格式包含intent（意图）、content（内容）、status（状态）、context（上下文）、turn（轮次）和metadata（元数据）等字段。这种设计让LLM既能生产也能消费这些消息，无需为每个智能体硬编码特定的模式。\n\n动态智能体生成：与传统框架中预定义的WriterAgent、ReviewerAgent等子类不同，万象使用一个"Director"（导演）智能体来动态规划团队。Director根据任务描述在运行时生成TeamPlan，决定需要哪些智能体、它们的职责是什么、可以使用哪些工具。\n\n工具感知协作：每个智能体在执行时都会收到一个team_context快照，显示同伴智能体的工具能力。这让评审智能体能够根据写作者是否具备实时网络搜索能力来调整评估标准，避免在纯CLI环境中提出不切实际的反馈。\n\n## 三层架构设计\n\n万象的架构清晰地分为规划层、执行层和智能体层，辅以可观测性基础设施：\n\n### 规划层（Planning Layer）\n\n规划层的核心是AgentFactory，它封装了Director智能体的逻辑。当接收到任务输入时，Director会结合规划提示词和策略配置，生成一个完整的TeamPlan。这个计划定义了：\n- 采用哪种工作流模式（pipeline、review_loop或parallel）\n- 需要创建哪些智能体\n- 每个智能体的角色定义和工具权限\n\n这种动态规划的能力让万象能够适应各种不同类型的任务，而无需为每种场景预先编写特定的智能体类。\n\n### 执行层（Execution Layer）\n\nWorkflowEngine是执行层的核心，它支持三种工作流模式：\n\nPipeline（流水线）模式：智能体按顺序依次执行，前一个智能体的输出作为后一个的输入。这种模式适合有明确依赖关系的任务链，如"研究→写作→编辑→发布"。\n\nReview Loop（评审循环）模式：一个生产者智能体与一个评审智能体配对，通过多轮迭代直到达成共识。这种模式特别适合需要高质量输出的内容生成任务，评审者可以要求生产者修改直到满足标准。\n\nParallel（并行）模式：多个研究者智能体并发处理不同角度的子任务，然后由一个综合者智能体汇总结果。这种模式适合需要广泛信息收集的任务，如市场调研或文献综述。\n\n### 智能体层（Agent Layer）\n\nBaseAgent是智能体层的核心抽象。每个智能体在初始化时会接收动态生成的角色定义和团队上下文。在执行过程中，智能体通过工具循环（Tool Loop）与外部环境交互：\n\n工具系统是万象的一大亮点，它包含三个层次：\n\n1. 本地工具注册表（ToolRegistry）：内置工具如echo、current_time等，支持权限白名单、超时控制和模式验证\n\n2. Claude原生工具：如web_search等服务器端工具，提供强大的外部能力\n\n3. MCP服务器：通过stdio JSON-RPC 2.0协议连接外部Model Context Protocol服务器，支持文件系统、记忆系统等扩展能力。每个MCP服务器可以配置allowed_agents ACL，精确控制哪些智能体可以访问\n\n### 可观测性（Observability）\n\n万象内置了完整的可观测性基础设施：\n\n事件流（RunEvent Stream）：所有关键操作都会产生结构化事件，形成完整的事件流\n\nWeb UI：基于WebSocket的实时界面，提供：\n- 时间线视图：展示任务执行的时间序列\n- DAG可视化：直观显示智能体间的依赖关系和执行状态\n- 工具调用卡片：详细展示每次工具调用的输入输出\n- 耗时分析：识别性能瓶颈\n- 草稿对比：追踪内容迭代过程\n- 评审反馈聚合：汇总多轮评审意见\n- 历史回放：重现完整的执行轨迹\n\nJSONL历史记录：所有运行数据以JSONL格式持久化，便于后续分析和审计\n\n## 双LLM后端设计\n\n万象支持两种LLM后端，并提供了智能的auto模式：\n\nAnthropic Messages API模式：完整的API调用，支持原生工具使用，功能最全\n\nClaude Code CLI模式：通过stdin/stdout与本地安装的Claude Code CLI通信，使用JSON工具协议。这种模式适合没有API密钥或需要离线使用的场景\n\nauto模式会自动检测环境，优先使用API模式（如果配置了ANTHROPIC_API_KEY），否则回退到CLI模式。这种设计提供了最大的灵活性，同时确保了优雅降级——在CLI模式下，原生工具会被自动剥离并发出警告，智能体回退到纯LLM调用而不会崩溃。\n\n## MCP状态探针\n\n万象内置了一个实用的MCP状态探针功能，可以检查claude auth status和claude mcp list的状态，并将结果展示在UI中。这让开发者能够快速诊断环境配置问题，确保MCP服务器正确连接。\n\n## 快速开始\n\n万象的安装和使用非常简洁：\n\nbash\n# 克隆仓库\ngit clone https://github.com/yeyanle6/wanxiang.git\ncd wanxiang\n\n# 安装依赖（包含开发依赖用于测试）\npip install -e \".[dev]\"\n\n# 配置LLM后端（二选一）\nexport ANTHROPIC_API_KEY=sk-ant-... # API模式\n# 或\nclaude auth login # CLI模式\n\n# 运行任务\nwanxiang -y \"Write a 500-word blog post about AI agents\"\n\n\n## 设计理念的深层思考\n\n万象的设计反映了开发团队对多智能体系统本质的深刻理解：\n\n从静态到动态：传统框架倾向于预定义智能体类型，而万象让AI itself来决定需要什么角色。这种动态性让系统能够适应更广泛的场景，但也对Director智能体的推理能力提出了更高要求。\n\n从黑盒到透明：通过完整的可观测性基础设施，万象让多智能体协作过程变得可见、可调试、可优化。这在生产环境中尤为重要。\n\n从封闭到开放：通过MCP协议支持，万象可以轻松集成外部工具和服务，避免了重复造轮子。\n\n## 总结\n\n万象（Wanxiang）是一个设计精良、功能完备的多智能体编排引擎。它的AI原生消息协议、动态智能体生成和工具感知协作三大核心理念，为构建复杂的多智能体应用提供了坚实的基础。无论是简单的流水线任务，还是需要多轮评审的复杂内容生成，亦或是需要广泛信息收集的研究任务，万象都能提供合适的工作流模式。\n\n对于正在探索多智能体系统的开发者和研究者来说，万象是一个值得关注和尝试的开源项目。

万象（Wanxiang）：AI原生多智能体编排引擎\n\n在多智能体系统（Multi-Agent Systems）快速发展的今天，如何有效地编排多个AI智能体协同工作成为了一个关键挑战。万象（Wanxiang）项目以其独特的设计理念——AI原生的消息协议、动态智能体生成和工具感知协作——为这一领域带来了新的思路。\n\n项目概述\n\n万象（中文意为"万种现象"）是一个基于Python 3.11+开发的多智能体编排引擎。它的核心设计哲学可以概括为三个关键词：\n\nAI原生消息协议：智能体之间通过结构化消息进行通信，消息格式包含intent（意图）、content（内容）、status（状态）、context（上下文）、turn（轮次）和metadata（元数据）等字段。这种设计让LLM既能生产也能消费这些消息，无需为每个智能体硬编码特定的模式。\n\n动态智能体生成：与传统框架中预定义的WriterAgent、ReviewerAgent等子类不同，万象使用一个"Director"（导演）智能体来动态规划团队。Director根据任务描述在运行时生成TeamPlan，决定需要哪些智能体、它们的职责是什么、可以使用哪些工具。\n\n工具感知协作：每个智能体在执行时都会收到一个team_context快照，显示同伴智能体的工具能力。这让评审智能体能够根据写作者是否具备实时网络搜索能力来调整评估标准，避免在纯CLI环境中提出不切实际的反馈。\n\n三层架构设计\n\n万象的架构清晰地分为规划层、执行层和智能体层，辅以可观测性基础设施：\n\n规划层（Planning Layer）\n\n规划层的核心是AgentFactory，它封装了Director智能体的逻辑。当接收到任务输入时，Director会结合规划提示词和策略配置，生成一个完整的TeamPlan。这个计划定义了：\n- 采用哪种工作流模式（pipeline、review_loop或parallel）\n- 需要创建哪些智能体\n- 每个智能体的角色定义和工具权限\n\n这种动态规划的能力让万象能够适应各种不同类型的任务，而无需为每种场景预先编写特定的智能体类。\n\n执行层（Execution Layer）\n\nWorkflowEngine是执行层的核心，它支持三种工作流模式：\n\nPipeline（流水线）模式：智能体按顺序依次执行，前一个智能体的输出作为后一个的输入。这种模式适合有明确依赖关系的任务链，如"研究→写作→编辑→发布"。\n\nReview Loop（评审循环）模式：一个生产者智能体与一个评审智能体配对，通过多轮迭代直到达成共识。这种模式特别适合需要高质量输出的内容生成任务，评审者可以要求生产者修改直到满足标准。\n\nParallel（并行）模式：多个研究者智能体并发处理不同角度的子任务，然后由一个综合者智能体汇总结果。这种模式适合需要广泛信息收集的任务，如市场调研或文献综述。\n\n智能体层（Agent Layer）\n\nBaseAgent是智能体层的核心抽象。每个智能体在初始化时会接收动态生成的角色定义和团队上下文。在执行过程中，智能体通过工具循环（Tool Loop）与外部环境交互：\n\n工具系统是万象的一大亮点，它包含三个层次：\n\n1. 本地工具注册表（ToolRegistry）：内置工具如echo、current_time等，支持权限白名单、超时控制和模式验证\n\n2. Claude原生工具：如web_search等服务器端工具，提供强大的外部能力\n\n3. MCP服务器：通过stdio JSON-RPC 2.0协议连接外部Model Context Protocol服务器，支持文件系统、记忆系统等扩展能力。每个MCP服务器可以配置allowed_agents ACL，精确控制哪些智能体可以访问\n\n可观测性（Observability）\n\n万象内置了完整的可观测性基础设施：\n\n事件流（RunEvent Stream）：所有关键操作都会产生结构化事件，形成完整的事件流\n\nWeb UI：基于WebSocket的实时界面，提供：\n- 时间线视图：展示任务执行的时间序列\n- DAG可视化：直观显示智能体间的依赖关系和执行状态\n- 工具调用卡片：详细展示每次工具调用的输入输出\n- 耗时分析：识别性能瓶颈\n- 草稿对比：追踪内容迭代过程\n- 评审反馈聚合：汇总多轮评审意见\n- 历史回放：重现完整的执行轨迹\n\nJSONL历史记录：所有运行数据以JSONL格式持久化，便于后续分析和审计\n\n双LLM后端设计\n\n万象支持两种LLM后端，并提供了智能的auto模式：\n\nAnthropic Messages API模式：完整的API调用，支持原生工具使用，功能最全\n\nClaude Code CLI模式：通过stdin/stdout与本地安装的Claude Code CLI通信，使用JSON工具协议。这种模式适合没有API密钥或需要离线使用的场景\n\nauto模式会自动检测环境，优先使用API模式（如果配置了ANTHROPIC_API_KEY），否则回退到CLI模式。这种设计提供了最大的灵活性，同时确保了优雅降级——在CLI模式下，原生工具会被自动剥离并发出警告，智能体回退到纯LLM调用而不会崩溃。\n\nMCP状态探针\n\n万象内置了一个实用的MCP状态探针功能，可以检查claude auth status和claude mcp list的状态，并将结果展示在UI中。这让开发者能够快速诊断环境配置问题，确保MCP服务器正确连接。\n\n快速开始\n\n万象的安装和使用非常简洁：\n\nbash\n克隆仓库\ngit clone https://github.com/yeyanle6/wanxiang.git\ncd wanxiang\n\n安装依赖（包含开发依赖用于测试）\npip install -e \".[dev]\"\n\n配置LLM后端（二选一）\nexport ANTHROPIC_API_KEY=sk-ant-... API模式\n或\nclaude auth login CLI模式\n\n运行任务\nwanxiang -y \"Write a 500-word blog post about AI agents\"\n\n\n设计理念的深层思考\n\n万象的设计反映了开发团队对多智能体系统本质的深刻理解：\n\n从静态到动态：传统框架倾向于预定义智能体类型，而万象让AI itself来决定需要什么角色。这种动态性让系统能够适应更广泛的场景，但也对Director智能体的推理能力提出了更高要求。\n\n从黑盒到透明：通过完整的可观测性基础设施，万象让多智能体协作过程变得可见、可调试、可优化。这在生产环境中尤为重要。\n\n从封闭到开放：通过MCP协议支持，万象可以轻松集成外部工具和服务，避免了重复造轮子。\n\n总结\n\n万象（Wanxiang）是一个设计精良、功能完备的多智能体编排引擎。它的AI原生消息协议、动态智能体生成和工具感知协作三大核心理念，为构建复杂的多智能体应用提供了坚实的基础。无论是简单的流水线任务，还是需要多轮评审的复杂内容生成，亦或是需要广泛信息收集的研究任务，万象都能提供合适的工作流模式。\n\n对于正在探索多智能体系统的开发者和研究者来说，万象是一个值得关注和尝试的开源项目。