开源多智能体协作框架Tianji：架构设计与实战指南

1. 项目概述：当AI学会“社交”，一个开源智能体协作平台的诞生

最近几年，AI领域最让人兴奋的突破，除了大模型本身能力的跃升，莫过于“智能体”概念的落地。我们不再满足于让AI被动地回答一个问题，而是希望它能像人一样，拥有目标、能规划、会使用工具，甚至能与其他AI协作，共同完成一个复杂的任务。这听起来像是科幻电影里的场景，但“SocialAI-tianji/Tianji”这个开源项目，正在将这种多智能体协作的愿景，以一种非常工程化和可复现的方式带到我们面前。

简单来说，Tianji是一个开源的多智能体协作框架与平台。它的核心目标，是让开发者能够像搭积木一样，轻松地创建、管理和调度多个具备不同能力的AI智能体，让它们通过“社交”（即相互通信与协作）来解决单个智能体难以处理的复杂问题。你可以把它想象成一个数字世界的“项目团队”，里面有擅长数据分析的“分析师”、文笔流畅的“文案”、精通代码的“工程师”，而Tianji就是那个协调他们工作、确保项目顺利推进的“项目经理”兼“协作平台”。

这个项目解决了什么痛点？在单智能体场景下，我们常常遇到瓶颈：一个AI可能擅长总结，但不擅长写代码；另一个可能检索能力强，但逻辑推理弱。面对一个需要“分析市场数据、生成报告、并开发一个可视化图表”的复合任务，我们不得不手动在多个AI工具或对话窗口间切换，充当那个“粘合剂”，效率低下且容易出错。Tianji的出现，正是为了自动化这个“粘合”过程，通过定义清晰的智能体角色、规划协作流程，让AI们自己“开会讨论”、“分工合作”，最终产出整合后的结果。它非常适合那些希望将AI能力深度集成到复杂工作流中的开发者、研究者和企业，无论是用于自动化办公、智能客服系统、复杂决策支持，还是前沿的AI研究本身。

2. 核心架构与设计哲学：如何让AI“社会”运转起来

要让一群AI智能体有效地协作，绝非简单地把几个模型调用接口堆在一起。Tianji的设计背后，蕴含着一套清晰的、关于如何构建“AI社会”的工程哲学。

2.1 分层架构：清晰的责任边界

Tianji采用了典型的分层架构思想，将复杂的多智能体系统解耦为几个核心层次，每一层都有明确的职责。

基础设施层：这是整个平台的基石。它负责最底层的资源管理和通信。包括：

• 智能体运行时环境：为每个智能体提供独立的“沙箱”，确保它们的执行过程互不干扰，同时能安全地访问必要的工具（如Python解释器、网络请求库等）。
• 消息总线与通信协议：这是智能体之间“说话”的渠道。Tianji需要定义一套高效、可靠的消息传递机制。通常，这会采用基于事件或发布/订阅的模式。智能体不直接知道彼此的存在，而是向特定的“频道”或“主题”发送消息，由消息总线负责路由。这种松耦合的设计使得系统扩展性极强，新增或移除智能体不会影响整体架构。
• 持久化与状态管理：协作过程往往不是一蹴而就的，可能需要多轮对话和状态保持。这一层负责保存对话历史、任务上下文、智能体的内部状态等，确保在长时间运行或意外中断后能恢复现场。

智能体核心层：这一层定义了“智能体”究竟是什么。在Tianji中，一个智能体通常包含以下几个关键模块：

• 规划模块：智能体的“大脑”。它根据当前接收到的任务或消息，决定下一步要做什么。这可能是一个基于规则的决策树，也可能是一个轻量级的规划模型（如ReAct， Reasoning and Acting）。
• 记忆模块：智能体的“经验”。分为短期记忆（当前对话的上下文）和长期记忆（通过向量数据库存储的历史经验和知识）。记忆模块让智能体不再是“金鱼”，能够从过去的交互中学习。
• 工具使用模块：智能体的“双手”。这是智能体与外部世界交互的关键。一个智能体可以被赋予一系列工具，如调用搜索引擎API、执行Python代码、查询数据库、操作文件等。Tianji需要提供一套安全、规范的机制来定义和调用这些工具。
• 通信模块：智能体的“嘴巴和耳朵”。负责按照协议格式化消息、发送到消息总线，以及监听和解析来自其他智能体或系统的消息。

编排与调度层：这是Tianji的“指挥中心”。单个智能体能力再强，也需要被有效地组织起来。这一层负责：

• 工作流定义：允许用户通过图形化界面或领域特定语言来定义智能体之间的协作流程。例如，可以定义一个“写作流水线”：先由“研究员”智能体搜集资料，然后将结果交给“大纲师”智能体生成提纲，再交由“撰稿人”智能体撰写初稿，最后由“校对员”智能体润色。
• 任务分解与分配：接收一个顶层的复杂任务（如“为我制定一份下周的营销方案”），并自动将其分解为一系列子任务，然后根据智能体的能力标签，将子任务分配给最合适的智能体。
• 异常处理与监督：监控整个协作过程。当某个智能体执行失败、陷入循环或产出结果不符合预期时，调度层需要介入，可能进行任务重试、重新分配或触发人工审核流程。

应用与接口层：这是用户与Tianji平台交互的界面。提供RESTful API、WebSocket接口、命令行工具以及可能的前端管理界面，让用户能够方便地创建、监控和管理智能体团队。

设计心得：这种分层架构的核心优势在于“高内聚、低耦合”。每一层的技术栈可以独立演进。例如，你可以更换底层的消息队列（从Redis换成RabbitMQ），或者为智能体升级更强的规划模型，只要接口不变，上层应用就无需修改。这为项目的长期维护和社区生态发展奠定了坚实基础。

2.2 通信模式：智能体如何“对话”

智能体间的通信模式是协作的血液。Tianji主要支持以下几种模式，适用于不同场景：

1. 广播模式：一个智能体向所有其他智能体发送消息。这适用于发布公告、寻求集体帮助的场景。例如，一个“协调员”智能体可以广播：“我们收到了一个新任务：分析Q3财报。请相关智能体准备。”
2. 定向消息模式：点对点的通信。智能体A明确指定消息发送给智能体B。这适用于私密、高效的任务交接。例如，“数据分析师”完成计算后，直接告诉“可视化工程师”：“数据已处理完毕，文件路径是/data/processed.csv。”
3. 黑板模式：这是一个共享的、结构化的信息存储区。所有智能体都可以向“黑板”上读写信息。这非常适合需要共享中间状态或进行投票决策的场景。例如，多个“评审”智能体可以将自己对同一份稿件的修改意见写到黑板上，由“主编”智能体汇总决策。
4. 订阅/发布模式：智能体可以订阅自己感兴趣的主题。当有相关消息发布到该主题时，所有订阅者都会收到。这实现了智能体间的动态、兴趣驱动的协作。例如，一个“漏洞监控”智能体可以订阅“安全警报”主题，一旦有智能体发布相关警报，它就能立即响应。

在实际实现中，Tianji往往会混合使用这些模式。一个常见的协作流程可能是：任务通过API发布 -> 调度器（订阅了“新任务”主题）接收并分解 -> 将子任务以定向消息模式分配给特定智能体 -> 智能体执行过程中将中间结果写入黑板 -> 其他智能体从黑板读取所需信息继续工作 -> 最终结果通过广播或定向消息汇总。

3. 核心组件深度解析：从智能体定义到工具调用

理解了宏观架构，我们深入到Tianji的几个核心组件，看看它们是如何被具体设计和实现的。

3.1 智能体定义与配置：打造个性鲜明的AI成员

在Tianji中，创建一个智能体远不止是初始化一个模型。它是一个完整的、可配置的实体。通常，一个智能体的定义会包含以下核心配置文件（以YAML或JSON格式为例）：

agent_name: “数据分析师” description: “擅长使用Python进行数据清洗、分析和可视化” core_llm: # 核心语言模型配置 provider: “openai” # 或 local, anthropic, google 等 model_name: “gpt-4” api_key: ${ENV:OPENAI_API_KEY} # 支持环境变量 temperature: 0.1 # 较低的温度，保证分析结果的稳定性 capabilities: # 能力标签，用于任务匹配 - “data_cleaning” - “statistical_analysis” - “plot_generation” tools: # 可使用的工具列表 - name: “execute_python” module: “tianji.tools.code_executor” config: timeout: 30 allowed_imports: [“pandas”, “numpy”, “matplotlib”] - name: “read_csv” module: “tianji.tools.file_io” memory: # 记忆配置 short_term: type: “window” # 滑动窗口记忆，只保留最近N轮对话 window_size: 10 long_term: type: “vector_db” # 向量数据库存储长期记忆 connection: “chromadb://localhost:8000” collection_name: “analyst_memories” communication: # 通信偏好 default_mode: “directed” # 默认使用定向消息 subscribed_topics: [“data_request”, “analysis_task”] # 订阅的主题

关键设计点解析：

• 模型抽象层：Tianji需要封装不同厂商（OpenAI、Anthropic、国内大模型等）和本地模型的调用，提供统一的接口。这通常通过一个LLMProvider抽象类来实现，不同的提供商实现具体的调用逻辑。
• 工具的安全沙箱：execute_python这样的工具极其强大，也极其危险。Tianji必须实现一个安全的代码执行环境。常见的做法是使用 Docker 容器或seccomp等系统调用过滤机制，在资源（CPU、内存、网络、文件系统）受限的沙箱中运行用户代码，并设置超时限制。
• 记忆的向量化：长期记忆不是简单存储文本，而是将对话或经验转换成向量，存入向量数据库（如Chroma、Weaviate）。当智能体需要相关记忆时，系统会将当前问题也向量化，进行相似度搜索，召回最相关的几条记忆作为上下文注入给模型。这模拟了人类的“联想”能力。

3.2 工具生态系统：扩展智能体的“技能树”

工具是智能体能力的放大器。Tianji的工具系统设计，直接决定了智能体能做什么。

工具的定义规范：一个工具通常由一个标准的函数签名和描述文本来定义。例如：

@tool def search_web(query: str, max_results: int = 5) -> str: """ 使用搜索引擎在互联网上搜索信息。 Args: query: 搜索查询关键词。 max_results: 返回的最大结果数量，默认为5。 Returns: 返回搜索结果的摘要文本。 """ # ... 实际的搜索逻辑（调用SerpAPI、Google Custom Search等） return formatted_results

@tool装饰器会将该函数注册到Tianji的工具库中，并自动提取其描述和参数schema。这个描述文本至关重要，因为大模型（LLM）正是通过阅读这些文本来理解工具的功能和用法。

工具的发现与调用：

1. 工具发现：当智能体需要解决一个问题时，它的规划模块（或由调度器）会获得一个可用的工具列表及其描述。LLM根据当前任务和上下文，判断是否需要使用工具，以及使用哪一个。
2. 参数生成：LLM根据工具的函数签名和描述，生成符合要求的参数。例如，对于search_web(query=”多智能体协作框架”, max_results=3)。
3. 安全执行：生成的调用请求会被发送到工具执行引擎。引擎会进行参数校验、权限检查（该智能体是否有权使用此工具），然后在安全环境中执行。
4. 结果处理：工具执行的结果（成功或错误）会被格式化，返回给智能体，作为下一轮推理的输入。

内置工具与自定义工具：Tianji项目通常会提供一批开箱即用的内置工具，如文件读写、HTTP请求、时间日期、数学计算等。更重要的是，它必须提供极简的接口，让开发者能够轻松封装自己的业务API或代码逻辑为工具，从而无限扩展智能体的能力边界。

实操心得：工具描述的“艺术”：工具描述的质量直接影响LLM使用工具的准确率。描述要清晰、具体、无歧义。最好包含示例。避免使用过于宽泛的词汇。例如，“处理数据”就比“使用pandas读取data.csv文件，计算某列的平均值并返回”要差得多。好的描述是智能体正确使用工具的“说明书”。

3.3 任务规划与工作流引擎：协作的“剧本”

多智能体协作的核心在于“规划”。Tianji如何让智能体们知道自己该在何时、做什么事？

基于LLM的规划：这是目前的主流方法。一个顶层的“规划者”智能体（或调度器中的规划模块）接收用户指令，利用LLM强大的理解和推理能力，将模糊的指令分解为具体的、有序的子任务步骤。例如，用户说“帮我写一份关于Tianji的技术博客”，规划者可能输出：

1. 任务：调研。调用“研究员”智能体，使用网络搜索工具搜集关于Tianji开源项目的资料、技术文章和社区评价。 2. 任务：列提纲。将调研结果交给“大纲师”智能体，生成博客文章的结构化大纲。 3. 任务：撰写。将大纲交给“撰稿人”智能体，撰写博客正文。 4. 任务：校对润色。将初稿交给“编辑”智能体，进行语法检查、风格统一和润色。 5. 任务：发布准备。将终稿交给“格式化”智能体，转换为Markdown或HTML格式。

然后，调度器根据每个步骤的描述，匹配具有相应capabilities的智能体来执行。

基于DSL的工作流：对于固定、常见的协作模式，使用领域特定语言或图形化界面来定义工作流会更可靠、高效。Tianji可能提供一种YAML格式的DSL：

workflow: name: “技术博客创作” steps: - step: “research” agent: “researcher” input: “{{user_input}}” tools: [“search_web”] - step: “outline” agent: “outliner” input: “基于以下资料生成博客大纲：{{steps.research.output}}” - step: “write” agent: “writer” input: “根据以下大纲撰写博客正文：{{steps.outline.output}}” - step: “polish” agent: “editor” input: “校对和润色以下文章：{{steps.write.output}}” output: “{{steps.polish.output}}”

这种方式将控制逻辑从LLM中剥离，更加稳定和可预测，适合生产环境。

混合规划模式：最强大的系统往往是混合的。Tianji可以先使用DSL定义高层次的、稳定的协作骨架（如“调研->写作->校对”），而在每个步骤内部，由负责的智能体利用LLM进行更细粒度的规划和工具调用（如在“调研”步骤中，研究员智能体自主决定搜索哪些关键词、如何筛选信息）。这既保证了流程的可靠性，又保留了应对不确定性的灵活性。

4. 从零搭建与实战：部署一个你自己的智能体团队

理论说了这么多，我们来点实际的。假设我们要用Tianji搭建一个简单的“智能内容创作团队”，包含一个“研究员”和一个“撰稿人”。

4.1 环境准备与项目初始化

首先，确保你的开发环境满足基本要求：Python 3.9+，以及pip或conda包管理器。

# 1. 克隆Tianji仓库（假设项目托管在GitHub） git clone https://github.com/SocialAI-tianji/Tianji.git cd Tianji # 2. 创建并激活虚拟环境（强烈推荐） python -m venv venv # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate # 3. 安装核心依赖 pip install -e . # 如果项目支持可编辑安装 # 或者根据 requirements.txt 安装 pip install -r requirements.txt # 4. 配置环境变量 # 你需要准备大模型的API密钥，例如OpenAI echo “OPENAI_API_KEY=sk-your-key-here” > .env # 加载环境变量（可以使用python-dotenv库）

注意：大型开源项目依赖可能复杂。如果遇到安装错误，首先检查Python版本，其次查看项目文档是否有特殊的系统依赖（如某些数据库客户端）。使用虚拟环境可以避免污染系统Python环境。

4.2 定义你的第一个智能体：研究员

在Tianji的项目结构中，通常有一个agents/目录用于存放智能体配置。我们创建一个researcher.yaml：

# agents/researcher.yaml name: “researcher” role: “互联网信息研究员，擅长快速搜集和整理网络上的公开技术信息。” llm_config: model: “gpt-4-turbo” # 或你配置的其他模型 temperature: 0.2 max_tokens: 2000 tools: - name: “duckduckgo_search” # 假设Tianji内置了DDG搜索工具 description: “使用DuckDuckGo搜索引擎进行网络搜索。输入是搜索查询字符串。” - name: “summarize_text” description: “对长文本进行摘要总结，提取核心要点。” instruction: | 你是一名专业的研究员。当接到一个调研任务时，你应该： 1. 分析任务主题，构思2-3个最相关的搜索关键词。 2. 使用`duckduckgo_search`工具进行搜索。 3. 从搜索结果中筛选出最相关、最权威的3-5条信息。 4. 使用`summarize_text`工具，将筛选出的信息整合成一份结构清晰、事实准确的调研报告。 5. 在报告末尾注明关键信息来源。 你的回答应当直接是最终的调研报告。

这个配置文件定义了智能体的身份、使用的模型、可用的工具以及最重要的——行为指令。instruction字段是引导智能体行为的关键，写得越具体，智能体的表现就越可控。

4.3 定义第二个智能体：撰稿人

同理，创建writer.yaml：

# agents/writer.yaml name: “writer” role: “技术专栏作家，文风清晰易懂，擅长将复杂的技术概念转化为生动的叙述。” llm_config: model: “gpt-4” temperature: 0.7 # 写作可以更有创造性，温度稍高 max_tokens: 3000 tools: - name: “improve_tone” description: “优化文本的语气和风格，使其更符合目标读者（如技术爱好者、初学者等）。” instruction: | 你是一名资深技术博客作者。你将收到一份调研报告和一个写作主题。 你的任务是： 1. 仔细阅读调研报告，理解所有技术要点。 2. 以调研报告为事实基础，撰写一篇吸引人的技术博客文章。 3. 文章需包含：一个引人入胜的开头、清晰的问题阐述、技术原理的通俗解释、实践案例或步骤、以及一个有力的结尾。 4. 文章应结构分明，段落清晰，适当使用加粗强调重点。 5. 完成初稿后，使用`improve_tone`工具，将文章风格调整为“面向中级开发者的亲切科普风”。 请直接输出完整的博客文章。

4.4 编写协作工作流

现在，我们需要一个“导演”来让研究员和撰稿人协作。在workflows/目录下创建blog_creation.yaml：

# workflows/blog_creation.yaml name: “技术博客创作流程” description: “根据一个主题，自动完成调研和博客撰写。” agents: researcher: “@agents/researcher.yaml” # 引用智能体配置 writer: “@agents/writer.yaml” steps: - name: “conduct_research” agent: “researcher” input: “请调研以下主题：{{topic}}。请提供一份详细的调研报告，包含技术要点、应用场景和社区反馈。” output_key: “research_report” # 将输出存储到变量 - name: “write_article” agent: “writer” input: | 写作主题：{{topic}} 这是研究员提供的调研报告： {{steps.conduct_research.output}} 请基于以上信息撰写博客文章。 output_key: “final_article” output: “{{steps.write_article.output}}” # 工作流的最终输出

这个工作流定义了两个顺序执行的步骤。第一步由研究员执行，其输出（research_report）会被自动注入到第二步撰稿人的输入中。{{topic}}是一个变量，将在运行工作流时由用户提供。

4.5 运行与监控

最后，我们通过Tianji提供的命令行工具或Python API来运行这个工作流。

# run_workflow.py import asyncio from tianji import TianjiClient async def main(): # 初始化客户端，连接到本地或远程的Tianji服务 client = TianjiClient(“http://localhost:8000”) # 定义输入参数 inputs = {“topic”: “开源多智能体协作框架 Tianji 的设计原理与实战”} # 运行工作流 execution_id = await client.run_workflow( workflow_path=“workflows/blog_creation.yaml”, inputs=inputs ) # 轮询获取结果（或使用WebSocket监听事件） while True: status = await client.get_execution_status(execution_id) if status == “completed”: result = await client.get_execution_result(execution_id) print(“最终生成的博客文章：”) print(result[“output”]) break elif status == “failed”: error = await client.get_execution_errors(execution_id) print(f“工作流执行失败：{error}”) break else: print(f“当前状态：{status}，等待3秒...”) await asyncio.sleep(3) if __name__ == “__main__”: asyncio.run(main())

运行这个脚本，你就能看到两个智能体开始“工作”：研究员先去搜索资料并整理成报告，然后撰稿人接过报告，创作出一篇完整的技术博客草稿。通过Tianji可能提供的Web管理界面，你还可以实时看到每个步骤的执行状态、智能体之间的消息传递以及中间结果，就像在监控一个真实的项目团队。

5. 进阶技巧与避坑指南

在实际使用和开发基于Tianji的应用时，你会遇到各种挑战。以下是一些从实战中总结出的经验和常见问题的解决方案。

5.1 智能体设计的“人性化”技巧

• 给智能体一个清晰的“人设”：role和instruction不能太空泛。像“你是一个助手”这样的描述效果很差。要像给演员写角色小传一样，描述其专业背景、性格倾向（如“严谨”、“富有创造力”、“注重细节”）、甚至沟通风格。这能显著提升智能体行为的稳定性和专业性。
• 使用少样本示例：在instruction中，除了规则描述，最好提供1-2个完整的输入输出示例。这能更直观地告诉LLM你期望的对话或任务完成格式。
• 管理上下文长度：智能体的记忆（尤其是对话历史）会不断增长，很快会触及模型上下文窗口的限制。务必合理配置短期记忆的窗口大小，并利用向量检索长期记忆，只召回最相关的部分注入上下文，这是保证系统长期稳定运行的关键。

5.2 工作流设计的可靠性保障

• 设置明确的超时和重试机制：在步骤配置中，一定要为每个智能体调用设置超时时间。网络波动、模型API不稳定都可能导致单个调用卡住。配置合理的重试策略（如最多3次，指数退避）可以自动处理临时性故障。
• 实现结果验证与人工审核节点：并非所有步骤都适合全自动化。对于关键决策点或最终输出，可以在工作流中插入“人工审核”节点。智能体将结果提交到一个队列，等待用户在管理界面上点击“通过”或“驳回”，然后再继续流程。
• 设计优雅的失败处理：工作流中某个步骤失败时，不应该直接导致整个流程崩溃。Tianji应支持定义失败处理策略，例如：重试该步骤、跳过该步骤执行备选方案、或者将任务转交给另一个备用智能体。

5.3 性能优化与成本控制

• 智能体调用合并与批处理：如果多个智能体需要调用同一个昂贵的模型API，可以考虑设计一个“路由”或“代理”智能体，将请求合并后批量发送，减少API调用次数和延迟。
• 模型分层使用：不是所有任务都需要GPT-4。对于简单的文本格式化、信息提取等任务，完全可以使用更便宜、更快的模型（如GPT-3.5-Turbo甚至小型开源模型）。在智能体配置中根据任务复杂度分配不同等级的模型，能大幅降低成本。
• 缓存机制：对于内容不变或变化缓慢的查询（如“什么是Python？”），可以将智能体的回答缓存起来。下次遇到相同或高度相似的查询时，直接返回缓存结果，避免不必要的模型调用。

5.4 常见问题排查表

构建和调试一个多智能体系统，初期更像是在“驯服”一群各有想法的AI。你需要通过精细的提示词工程、合理的流程设计以及完善的监控反馈，逐步引导它们形成高效、可靠的协作习惯。这个过程充满挑战，但当你看到它们真正像一个团队一样自动完成复杂任务时，那种成就感是无与伦比的。Tianji这类框架的价值，就在于它提供了实现这一切所需的基础设施和最佳实践，让开发者能够专注于智能体本身的行为设计和业务逻辑，而不必从头发明通信轮子、任务调度器等复杂组件。