从操作数到智能体：operand/agency框架构建多智能体协作系统实战

1. 项目概述：从“操作数”到“智能体”的范式跃迁

最近在开源社区里，operand/agency这个项目引起了我的注意。乍一看标题，operand（操作数）和agency（智能体/代理）这两个词放在一起，充满了张力。操作数通常指代被动等待处理的数据或对象，而智能体则代表着主动、自治、能感知环境并采取行动的主体。这个组合本身就暗示了一种理念的转变：将传统意义上被动的数据或功能单元，转化为能够自主协作、完成复杂任务的智能实体。

简单来说，operand/agency是一个用于构建和编排多智能体（Multi-Agent）系统的开源框架。它不是一个单一的、庞大的AI模型，而是一个“智能体工厂”和“调度中心”。你可以用它快速地将各种AI能力（比如大语言模型、图像生成模型、代码执行器、乃至自定义的工具函数）封装成独立的、可交互的智能体，然后通过清晰的流程设计，让这些智能体像一支训练有素的团队一样协同工作，解决单个模型或工具难以处理的复杂问题。

这解决了什么痛点呢？在AI应用开发中，我们常常遇到“一把锤子敲所有钉子”的困境。一个大语言模型或许能写诗、能聊天、能总结，但让它去精确执行一个需要多步骤、调用外部API、处理结构化数据的业务流程时，就显得力不从心，容易“胡言乱语”或出错。operand/agency的思路是“专业的人做专业的事”：拆解任务，让不同的智能体各司其职，一个负责理解用户意图并规划，一个负责调用搜索API获取信息，一个负责编写和验证代码，另一个负责生成最终报告。它提供了一套标准化的“沟通协议”和“工作流引擎”，让这些智能体能够可靠、有序地对话与合作。

无论你是想构建一个能自动处理客服工单的AI助手，一个能根据自然语言描述自动编写并部署代码的开发工具，还是一个能联网搜索、分析数据并生成可视化图表的分析平台，operand/agency都提供了一个极具潜力的底层架构。它适合有一定Python基础的开发者、AI应用创业者，以及对AI智能体协同技术感兴趣的探索者。接下来，我将深入拆解它的设计思路、核心用法，并分享一个从零开始的实战案例。

2. 核心架构与设计哲学解析

2.1 智能体作为一等公民：从函数到协作者

operand/agency最核心的设计哲学，就是“智能体即服务”。在这个框架里，智能体（Agent）不是一个模糊的概念，而是一个具有明确定义接口的实体。每个智能体都拥有：

1. 身份（Identity）：一个名字和一段系统提示词（System Prompt），用于定义它的角色、能力和行为准则。
2. 行动（Actions）：一组它可以执行的具体操作。这些操作本质上就是Python函数，但被框架赋予了特殊的能力——可以被其他智能体或用户通过自然语言调用。
3. 上下文（Context）：智能体能够访问的会话历史、知识或环境状态。

框架通过装饰器（如@action）将普通的Python函数“升级”为智能体的可执行行动。当一个智能体接收到一条消息（来自用户或其他智能体），框架会利用大语言模型（LLM）来理解这条消息的意图，并自动匹配和调用该智能体拥有的最合适的action。这意味着，你不需要写复杂的逻辑来判断该调用哪个函数，LLM会充当一个“意图路由器”。

例如，你有一个“数据科学家”智能体，它拥有query_database、generate_chart、write_summary三个行动。当用户对它说“帮我分析一下上个月的销售数据，并生成趋势图”，LLM会理解到需要先后调用query_database和generate_chart两个行动。这种设计将自然语言的灵活性与程序逻辑的精确性结合了起来。

2.2 空间与编排：智能体社会的运行规则

单个智能体能力有限，真正的威力在于多智能体协作。operand/agency引入了“空间（Space）”的概念。你可以把空间想象成一个虚拟的会议室或协作平台。

• 空间是智能体的容器：多个智能体可以加入同一个空间。
• 空间是通信的媒介：在空间内，智能体之间可以相互发送消息。消息传递是异步的，模拟了真实世界的协作。
• 空间是流程的沙盒：你可以在空间内定义复杂的交互流程。框架提供了多种流程控制模式，这是其编排能力的核心。

目前，框架主要支持两种协作模式：

1. 广播（Broadcast）模式：一条消息被发送到空间后，空间内的所有智能体都能“听到”并有机会响应。这适用于需要集思广益的场景，比如头脑风暴。
2. 路由（Router）模式：这是更常用、更精确的模式。你可以指定一个“路由智能体”（通常是一个具备较强理解和规划能力的LLM智能体，如基于GPT-4的智能体）。所有用户消息先发给这个路由智能体，由它来分析任务，决定将任务分解成哪些子步骤，并指定由哪个专门的智能体来执行每个子步骤。它像一个项目经理或指挥家，协调整个团队的工作。

这种基于空间的架构，使得系统非常灵活和可扩展。你可以为不同的业务场景创建不同的空间，每个空间里有不同的智能体团队。

2.3 工具集成与外部世界连接

智能体不能闭门造车，必须能与外部世界交互。operand/agency让智能体集成外部工具变得异常简单。任何Python可调用的库或API，都可以被封装成智能体的action。

• 网络搜索：集成duckduckgo-search或SerpAPI，让智能体拥有实时获取信息的能力。
• 代码执行：在安全沙箱中执行Python代码，用于计算、数据处理或原型验证。
• 文件操作：读写本地文件或云存储，处理文档、图片等。
• 第三方API：调用天气预报、股票信息、邮件发送、数据库查询等任何Web API。

框架处理了身份验证、请求构造、错误处理等繁琐细节，你只需要定义好函数。更重要的是，当这些工具被暴露为action后，智能体可以通过自然语言来使用它们，用户也可以通过自然语言来要求智能体使用它们，实现了交互层的统一。

注意：赋予智能体执行代码或访问敏感API的能力时，必须高度重视安全性。务必在沙箱环境或严格的权限控制下运行，避免执行不可信的代码或进行危险操作。operand/agency本身提供了基本的隔离，但对于生产环境，你需要设计更完善的安全边界。

3. 从零开始构建一个多智能体协作系统

理论说得再多，不如动手实践。我们来构建一个简单的“智能内容创作团队”系统。这个团队由三个智能体组成：一个策划（Planner），负责理解用户需求并制定大纲；一个研究员（Researcher），负责联网搜索最新信息；一个写手（Writer），负责整合信息撰写文章。

3.1 环境搭建与基础配置

首先，确保你的Python环境在3.8以上。创建一个新的虚拟环境是好的实践。

# 创建并激活虚拟环境（以conda为例） conda create -n agency-demo python=3.10 conda activate agency-demo # 安装 operand/agency 核心库 pip install agency

agency是核心框架，它抽象了智能体、空间、通信的基础设施。但要让智能体真正“智能”起来，我们需要为其接入“大脑”——大语言模型。框架支持多种LLM后端，这里我们使用OpenAI的API（你也可以替换为Anthropic Claude、本地部署的Ollama等）。

# 安装OpenAI适配器 pip install openai

接下来，你需要准备一个OpenAI的API密钥。将其设置为环境变量：

# 在终端中设置（临时） export OPENAI_API_KEY='your-api-key-here' # 或者在代码中设置（不推荐，容易泄露） import os os.environ['OPENAI_API_KEY'] = 'your-api-key-here'

3.2 定义第一个智能体：策划者

我们从核心的“策划”智能体开始。它将使用GPT-4模型，负责任务分解和规划。

# planner_agent.py import asyncio from agency import Agent, action from agency.spaces import Space # 导入OpenAI的LLM封装，框架会处理与后端的通信 from agency.llm import OpenAIChatCompletionsModel class PlannerAgent(Agent): """策划智能体：负责理解复杂需求，拆解任务步骤。""" def __init__(self, id, model="gpt-4"): # 初始化父类，并指定使用的LLM模型 super().__init__( id=id, model=OpenAIChatCompletionsModel(model=model), # 系统提示词至关重要，它定义了智能体的角色和行为 instructions="""你是一个资深的内容策划专家。你的职责是分析用户的内容创作需求（如博客主题、报告方向等），并将其分解为具体、可执行的任务步骤。 步骤通常包括：1. 明确核心主题与关键词。2. 进行初步的信息调研（需要研究员协助）。3. 拟定内容大纲与结构。4. 撰写具体内容（需要写手协助）。 你的回复必须清晰、结构化，直接输出步骤规划，并指明每一步建议由哪个角色（Researcher 或 Writer）执行。 例如，用户说“写一篇关于量子计算最新进展的科普文章”，你应该回复： “任务分解： 1. 【主题明确】核心主题：量子计算原理与近期突破。关键词：量子比特、超导电路、量子霸权、纠错。 2. 【信息调研】需要研究员（Researcher）搜索以下信息：2023年以来量子计算领域的主要实验进展、领先公司与研究机构、当前面临的主要挑战。 3. 【大纲拟定】基于调研结果，拟定文章大纲：引言、原理简述、近期突破案例（分点）、挑战与未来展望、结语。 4. 【内容撰写】将大纲交由写手（Writer）进行具体内容撰写，要求语言通俗易懂，面向科普读者。” """ ) @action def plan(self, task_description: str) -> str: """ 核心规划行动。接收用户的任务描述，返回分解后的步骤计划。 Args: task_description: 用户的任务描述，如“写一篇关于XX的文章”。 Returns: 结构化的任务计划字符串。 """ # 这里我们直接让LLM根据系统提示词和当前消息生成规划。 # 框架的 `_prompt` 方法会处理与LLM的交互。 # 在实际调用中，这个函数体通常很简单，因为逻辑主要在LLM的提示词中。 # 我们这里模拟一个直接返回LLM响应的action。 # 更复杂的实现可以在这里添加后处理逻辑。 prompt = f"请为以下任务制定创作计划：{task_description}" # 注意：在实际的agency框架中，`_prompt`或类似方法可能被封装。 # 这里为了演示，我们假设智能体接收到消息后，其内置的LLM会根据消息和系统指令自动响应。 # 因此，这个action可以只是一个“入口”。 return f"我已收到任务：'{task_description}'。正在思考规划..." # 实际上，规划结果会通过智能体对消息的响应返回，而不是这个函数的直接返回值。 # 下面的写法更贴近框架的常见模式： # 在实际使用中，我们更多是通过给智能体发送消息来触发其能力。 # 因此，这个类定义好后，将其加入空间，并向其发送消息即可。

上面的代码展示了智能体的基本结构。但请注意，在operand/agency的常见使用模式中，智能体的大部分“思考”能力来源于其系统提示词（instructions）和绑定的LLM。@action装饰的函数更像是为智能体暴露了可供其他智能体精确调用的“工具”。对于主要依靠对话完成任务的智能体（如这里的Planner），我们可能不需要定义很多action，而是依靠其默认的消息处理能力。

让我们调整一下，采用更符合框架常规的写法：

# 修正后的 planner_agent.py 更简化的版本 from agency import Agent from agency.llm import OpenAIChatCompletionsModel class PlannerAgent(Agent): def __init__(self, id): super().__init__( id=id, model=OpenAIChatCompletionsModel(model="gpt-4"), # 使用gpt-4以获得更好的规划能力 instructions="""（同上，系统提示词保持不变）""" ) # 这个智能体没有定义额外的@action，它将纯粹依靠LLM来响应用户消息，进行规划。

3.3 创建工具型智能体：研究员与写手

接下来创建两个工具型智能体，它们拥有具体的、可编程的action。

研究员智能体：集成网络搜索功能。

# 先安装搜索库 pip install duckduckgo-search

# researcher_agent.py from agency import Agent, action from agency.llm import OpenAIChatCompletionsModel from duckduckgo_search import DDGS import asyncio class ResearcherAgent(Agent): """研究员智能体：负责根据查询词进行网络搜索，并汇总信息。""" def __init__(self, id): super().__init__( id=id, # 研究员可以使用能力稍弱但更经济的模型，如 gpt-3.5-turbo，因为它主要执行结构化任务 model=OpenAIChatCompletionsModel(model="gpt-3.5-turbo"), instructions="""你是一个信息研究员。你擅长使用搜索工具获取网络上的最新信息，并对搜索结果进行整理和摘要。 当你收到一个搜索任务时，你会执行搜索，并返回一个格式清晰、信息准确的摘要，注明关键信息来源。 你的回答应客观、简洁，聚焦于事实。""" ) self.ddgs = DDGS() # 初始化搜索客户端 @action def search_web(self, query: str, max_results: int = 5) -> str: """ 执行网络搜索并返回摘要。 Args: query: 搜索关键词。 max_results: 最大返回结果数。 Returns: 搜索结果的摘要文本。 """ try: # 执行搜索 results = self.ddgs.text(query, max_results=max_results) if not results: return f"未找到关于 '{query}' 的相关信息。" # 整理结果 summary_lines = [f"针对查询『{query}』的搜索结果摘要："] for i, r in enumerate(results[:max_results], 1): summary_lines.append(f"{i}. 【标题】{r.get('title', 'N/A')}") summary_lines.append(f" 【链接】{r.get('href', 'N/A')}") summary_lines.append(f" 【摘要】{r.get('body', 'N/A')[:150]}...") # 截取部分内容 summary_lines.append("") # 空行分隔 # 让附带的LLM对原始结果做一个更精炼的总结（可选） # 这里为了演示，我们直接返回原始整理结果 return "\n".join(summary_lines) except Exception as e: return f"搜索过程中出现错误：{str(e)}"

写手智能体：负责根据大纲和材料撰写内容。

# writer_agent.py from agency import Agent, action from agency.llm import OpenAIChatCompletionsModel class WriterAgent(Agent): """写手智能体：根据主题、大纲和材料，撰写高质量文本。""" def __init__(self, id): super().__init__( id=id, model=OpenAIChatCompletionsModel(model="gpt-4"), # 写作需要更强的创造力，用GPT-4 instructions="""你是一名专业的科技文章写手。你擅长根据提供的主题、详细大纲和背景材料，撰写结构清晰、语言流畅、通俗易懂的文章。 你会严格遵循给定的大纲结构，将调研材料有机地整合到文章中，并用自己的话进行阐述，避免直接抄袭。 你的文章应该包含引人入胜的开头、逻辑连贯的主体和有力的结尾。面向的读者是具备基础知识的普通大众。""" ) @action def write_article(self, topic: str, outline: str, research_materials: str = "") -> str: """ 撰写文章。 Args: topic: 文章主题。 outline: 详细的内容大纲。 research_materials: 研究员提供的调研材料（可选）。 Returns: 撰写的完整文章。 """ # 构建给LLM的提示词 prompt = f""" 请根据以下要求撰写一篇完整的文章。 主题：{topic} 详细大纲： {outline} {f"参考调研材料：\n{research_materials}\n" if research_materials else ""} 请严格按照大纲的结构进行撰写，确保章节完整。合理利用提供的调研材料，但请用自己的语言重新组织，使其读起来自然连贯。 文章长度应在800-1500字左右。现在开始撰写： """ # 在实际框架中，我们可能需要通过self.model或其他方式调用LLM。 # 这里为了简化，我们假设这个action被调用时，框架会利用智能体的LLM能力来处理这个prompt。 # 更准确的做法是，这个函数返回一个“任务”，由框架调度LLM生成。 # 以下是一种模拟实现： return f"我将根据主题『{topic}』和提供的大纲/材料，开始撰写文章。这是一个需要LLM生成的过程，在实际运行中会返回完整文章。" # 注：在真实的@action方法中，如果你需要直接使用智能体的LLM，可能需要访问self._model属性或使用框架提供的响应机制。

实操心得：在定义智能体的instructions时，要尽可能具体、明确地描述其角色、职责和输出格式。模糊的指令会导致LLM行为不稳定。好的指令是智能体表现良好的关键。对于工具型智能体（如Researcher），其action方法的逻辑应尽可能健壮，做好错误处理，因为这是确定性的代码部分。

3.4 组建空间与编排工作流

现在，让我们把三个智能体放到一个“空间”里，并设计它们的协作流程。

# main_orchestration.py import asyncio from agency.spaces import Space from planner_agent import PlannerAgent from researcher_agent import ResearcherAgent from writer_agent import WriterAgent async def main(): # 1. 创建协作空间 space = Space() # 2. 实例化智能体并加入空间 planner = PlannerAgent(id="planner") researcher = ResearcherAgent(id="researcher") writer = WriterAgent(id="writer") space.add(planner) space.add(researcher) space.add(writer) print("智能体团队已就位：Planner, Researcher, Writer") # 3. 模拟用户发起一个任务 user_task = "写一篇关于2024年人工智能在天气预报领域最新应用与挑战的科普文章。" print(f"\n用户任务：{user_task}") # 4. 方案A：手动编排（演示明确控制流） # 在实际复杂流程中，我们可能需要一个“主控”程序来协调。 print("\n--- 开始手动编排流程 ---") # 步骤1：将任务发送给策划者（Planner） print("1. 咨询策划者（Planner）...") # 在空间中向指定智能体发送消息并等待响应 plan_response = await planner.send(planner.id, user_task) print(f"策划者回复：\n{plan_response[:500]}...\n") # 截取部分显示 # 假设我们从策划者的回复中，解析出了需要搜索的关键词和文章大纲。 # 这里为了演示，我们手动定义（在实际中，你需要用LLM或规则来解析planner的回复）。 search_query = "2024年 人工智能 天气预报 应用 挑战 最新进展" article_outline = """ 一、引言：天气预报的传统难题与AI的引入 二、AI如何赋能天气预报：核心技术（如深度学习、物理信息神经网络PINN） 三、2024年最新应用案例（分点介绍2-3个代表性研究或项目） 四、当前面临的挑战与局限性（数据、可解释性、计算资源等） 五、未来展望与总结 """ # 步骤2：让研究员（Researcher）搜索信息 print("2. 派遣研究员（Researcher）进行调研...") # 调用研究员的 search_web action search_result = await researcher.send(researcher.id, f"执行搜索：{search_query}") # 注意：这里我们直接发送文本消息，框架会尝试让研究员理解并执行。 # 更精确的方式是直接调用其action：`await researcher.request('search_web', {'query': search_query})` # 这取决于框架版本和具体API。我们假设send消息能触发其默认处理。 print(f"研究员调研结果摘要：\n{search_result[:600]}...\n") # 步骤3：让写手（Writer）根据大纲和调研结果撰写文章 print("3. 委托写手（Writer）进行创作...") # 调用写手的 write_article action writing_instruction = f"主题：{user_task}\n大纲：{article_outline}\n调研材料：{search_result}" article_response = await writer.send(writer.id, writing_instruction) print(f"写手完成文章：\n{article_response[:800]}...\n") # 截取文章开头部分 print("--- 手动编排流程结束 ---") # 5. 方案B：自动路由编排（更接近智能体自主协作） # 我们可以设置一个“路由智能体”（可以用另一个LLM智能体或Planner兼任）， # 将用户任务直接交给它，由它来决定如何分解并调用其他智能体。 # 这需要更复杂的空间配置和消息处理设置，是operand/agency更高级的用法。 print("\n演示完成。") # 运行主函数 if __name__ == "__main__": asyncio.run(main())

这个示例展示了最基本的“手动编排”流程。在实际的operand/agency框架中，可以通过定义更复杂的Space行为或使用其提供的路由（Router）模式来实现智能体间的自动对话与任务传递，从而更贴近“多智能体自主协作”的愿景。例如，你可以设置让所有发送到空间的消息，先被Planner接收，由它分析后，再通过空间的消息系统@提及Researcher或Writer，触发他们的行动。

4. 深入核心：消息流、工具调用与高级模式

4.1 理解框架的消息循环与Hook机制

operand/agency的核心是一个异步的消息传递系统。每个智能体在空间中都是一个独立的异步任务（asyncio Task），监听消息队列。

• 消息格式：消息通常包含发送者（from）、接收者（to）、内容（content）以及可能的动作（action）和参数（args）。
• 消息处理流程：
  1. 消息被投递到空间。
  2. 空间根据消息的接收者(to)，将其放入对应智能体的消息队列。
  3. 智能体从自己的队列中取出消息。
  4. 如果消息指定了action，智能体直接调用对应的@action方法。
  5. 如果未指定action，智能体将消息内容（content）连同自己的系统提示词（instructions）一起，提交给其绑定的LLM，由LLM决定如何响应。LLM的响应可能会包含调用自身或其他智能体action的指令（框架会解析并执行）。
• Hook（钩子）：框架提供了before_action,after_action,on_message等钩子函数，允许你在消息处理的生命周期中注入自定义逻辑，例如日志记录、权限检查、消息修改等。这是实现监控、审计和高级控制的关键。

# 示例：为智能体添加一个记录所有消息的钩子 class LoggingAgent(Agent): def __init__(self, id): super().__init__(id=id, model=...) async def on_message(self, message): """在智能体处理任何消息之前被调用。""" print(f"[LOG] {self.id} 收到消息来自 {message['from']}: {message.get('content', '')[:100]}...") # 必须返回message，以便继续处理 return message async def after_action(self, action_name, result, message): """在智能体执行完一个action后被调用。""" print(f"[LOG] {self.id} 执行了动作 {action_name}， 结果长度：{len(str(result))}")

4.2 实现智能体间的自动对话与任务分发

手动调用send虽然直观，但失去了智能体自主协作的魅力。更优雅的方式是利用空间的路由功能或智能体的推理能力来实现自动分发。

一种常见模式是设置一个协调者（Coordinator）智能体，它拥有强大的规划能力（如使用GPT-4）。用户只与协调者对话。协调者分析任务后，不是自己完成所有步骤，而是通过向空间发送动作请求（Action Request）来指挥其他智能体工作。

# 假设我们有一个CoordinatorAgent，它知道所有其他智能体的能力。 class CoordinatorAgent(Agent): def __init__(self, id, researcher_id, writer_id): super().__init__(id=id, model=OpenAIChatCompletionsModel(model="gpt-4"), instructions="你是团队协调员。你需要处理用户请求，并决定调用研究员（Researcher）或写手（Writer）来完成子任务。你知道研究员能执行'search_web'，写手能执行'write_article'。你的回复应直接调用它们。") self.researcher_id = researcher_id self.writer_id = writer_id # Coordinator 本身可能没有具体的@action，它主要靠LLM来生成指挥命令。 # 框架可以配置为将LLM生成的包含特定格式（如 `@researcher search_web(...)`）的文本，解析为对其他智能体的动作调用。

在operand/agency的某些版本或配置中，可以直接在系统提示词里告诉LLM：“你可以通过@智能体ID 动作名(参数)的格式来调用其他智能体”。当LLM在响应中输出这样的文本时，框架的空间处理器（Space Handler）会截获这些特殊格式的文本，将其转化为真正的动作调用消息，从而实现智能体间的链式反应。

4.3 状态管理与持久化

真实的业务场景往往涉及多轮对话和状态保持。operand/agency中的智能体可以通过实例变量来维护简单的内部状态。

class ConversationalAgent(Agent): def __init__(self, id): super().__init__(id=id, model=...) self.conversation_history = [] # 维护会话历史 async def on_message(self, message): # 将消息加入历史 self.conversation_history.append({"role": "user", "content": message.get('content')}) # 限制历史长度，避免上下文过长 if len(self.conversation_history) > 10: self.conversation_history = self.conversation_history[-10:] # 将历史作为上下文的一部分提供给LLM # 这通常需要在生成提示词时手动整合，框架可能不会自动处理。 return message

对于更复杂或需要持久化的状态（如用户会话数据、任务进度），通常需要外部的数据库或缓存（如Redis、SQLite）来配合。智能体的action方法可以去读写数据库。

5. 生产环境部署考量与常见问题排查

5.1 性能、安全与成本优化

将多智能体系统投入生产，必须考虑以下几点：

1. LLM API成本：智能体间频繁的对话会产生大量LLM调用。

   • 优化策略：为不同角色选择合适的模型。协调员、写手用能力强的模型（如GPT-4），工具执行、简单分类用成本低的模型（如GPT-3.5-Turbo）。合理设置对话的max_tokens，避免生成过长内容。使用流式响应（如果支持）以提升用户体验。

2. 异步与并发：operand/agency基于asyncio，适合IO密集型（如网络请求）操作。

   • 优化策略：确保你的action方法都是异步的（使用async def），避免阻塞操作。对于CPU密集型任务，考虑使用run_in_executor将其放到线程池中执行，防止阻塞事件循环。

3. 安全性：

   • 工具调用安全：严格审查智能体可执行的action。特别是execute_code这类高危操作，必须在完全隔离的沙箱（如Docker容器）中运行，并施加资源限制（CPU、内存、运行时间）。
   • 输入输出过滤：对用户输入和LLM输出进行必要的清洗和过滤，防止提示词注入攻击或生成有害内容。
   • API密钥管理：切勿将密钥硬编码在代码中。使用环境变量或专业的密钥管理服务。

4. 错误处理与鲁棒性：智能体协作链路长，任何一个环节失败都可能导致整个任务卡住。

   • 优化策略：在每个action和消息处理环节添加完善的try...except。设计重试机制（特别是对于可能暂时失败的API调用）。设置任务超时，避免无限等待。

5.2 常见问题与调试技巧

下面是一个快速排查指南：

调试心得：在开发初期，务必开启框架的详细日志。operand/agency通常可以通过设置日志级别（如logging.basicConfig(level=logging.DEBUG)）来查看所有内部消息传递和动作调用。这能帮你清晰看到“谁对谁说了什么”、“谁调用了什么”，是理解系统行为最直接的方式。另外，为每个智能体的关键方法（__init__,on_message,@action）添加打印语句，也是快速定位问题的好习惯。

构建多智能体系统就像组建一支球队，你需要明确每个队员的角色（智能体定义），设计有效的战术（工作流编排），并确保他们沟通顺畅（消息传递）。operand/agency提供了一个强大的中场发动机和战术板，但最终球队的表现，取决于你对每个“球员”能力的调教（提示词工程）和整体战术设计的合理性。从一个小而精的智能体组合开始，逐步迭代复杂的交互逻辑，是驾驭这类框架的最佳路径。