Agency框架实战：构建自主协作的多智能体AI系统

1. 项目概述当AI学会“自主思考”与“团队协作”最近在AI应用开发圈里一个名为“neurocult/agency”的开源项目热度持续攀升。简单来说它不是一个单一的AI模型而是一个智能体Agent编排与协作框架。你可以把它想象成一个“AI团队”的指挥中枢和操作系统。过去我们调用大语言模型LLMAPI往往是“一问一答”的单次交互模式。而Agency框架的核心思想是将多个具备不同能力的“AI员工”智能体组织起来让它们能够自主规划、分解任务、调用工具、相互沟通并最终协同完成一个复杂目标。这解决了什么实际问题举个例子你想开发一个“智能数据分析助手”。传统做法可能需要你写一个复杂的后端程序手动调用数据分析库、图表生成库再调用LLM API来生成报告文本整个过程是线性的、僵硬的。而使用Agency你可以创建几个智能体一个“分析师”智能体负责理解用户问题并制定分析步骤一个“数据查询”智能体专门与数据库交互一个“可视化”智能体调用图表生成工具一个“报告撰写”智能体负责整合结果并生成最终报告。你只需要定义好每个智能体的角色和能力然后把用户的一个自然语言请求比如“帮我分析上季度销售数据找出增长最快的三个区域并生成总结报告”丢给这个“AI团队”它们就会自己商量着把活干了。这个框架特别适合两类人一是希望快速构建复杂AI工作流的应用开发者它能极大减少胶水代码的编写二是对多智能体系统和AI自动化感兴趣的研究者或爱好者它提供了一个清晰、可扩展的实践平台。接下来我将深入拆解Agency的设计思路、核心组件并手把手带你搭建一个实用的多智能体应用。2. 核心架构与设计哲学拆解要理解Agency不能只把它当成一个工具库而要从其设计哲学入手。它的核心目标是降低构建“可行动AI”Actionable AI系统的门槛。2.1 从“工具调用”到“智能体社会”早期的AI应用多围绕“Function Calling”函数调用展开。即LLM根据用户请求决定调用哪个预设函数工具然后开发者处理函数返回的结果。这仍然是“中心化”的一个LLM大脑指挥一切。Agency则推进到了“去中心化”或“联邦化”的智能体网络。在这个网络里每个智能体都是独立的拥有自己的名字、角色描述、记忆可选和一套专属的工具Actions。例如一个“邮件智能体”的工具可能就是send_email和read_inbox。智能体之间通过消息传递进行协作它们可以像人类同事一样互相发送消息、请求帮助、传递任务结果。框架负责路由这些消息并确保它们被正确处理。存在“编排者”或“管理者”智能体虽然网络是去中心化的但通常需要一个或几个智能体来负责接收初始用户请求并协调整个工作流。这个管理者本身也是一个智能体它的“工具”可能就是调用其他智能体。这种架构的优势在于高内聚、低耦合。你可以独立开发、测试和部署每一个智能体。当需要增加新功能时不是去修改一个庞大的单体应用而是直接加入一个新的、具备特定能力的智能体到网络中。2.2 Agency框架的核心组件Agency的代码结构清晰地反映了这一哲学。主要包含以下几个核心部分Agent智能体这是最基本的构建块。每个Agent类都需要定义__init__初始化其属性和工具和action方法虽然框架通常会帮你封装工具调用。最关键的是你需要为Agent定义一套Actions行动。Action行动/工具这是智能体能力的具象化。一个Action本质上是一个Python函数或方法但需要用框架的装饰器如action进行标注。框架会自动将Action的描述函数名、文档字符串、参数schema注入到智能体的系统提示词中这样LLM就知道这个智能体能“做”什么。例如from agency import action, Agent class CalculatorAgent(Agent): action def add(self, a: float, b: float) - float: Adds two numbers together. return a b这里add就是一个Action。LLM在知道CalculatorAgent存在后如果需要计算就会生成一个包含add函数和参数a5, b3的调用请求。Space空间这是智能体们“生活”和交互的环境。你可以创建一个Space实例然后将多个Agent添加到这个Space中。一旦加入智能体就能发现彼此并通过Space进行消息传递。一个Space可以理解为一个特定的协作场景或一个微服务边界。消息路由与生命周期框架内部处理了复杂的消息流。当智能体A想联系智能体B时它并不直接调用B的方法而是向Space发送一条消息。框架根据消息头中的接收者信息将消息路由给B并触发B相关的Action。这带来了极大的灵活性你可以轻松实现消息日志、审计、甚至自定义的路由逻辑比如让某些消息先经过一个审核智能体。这种组件化设计使得整个系统像搭积木一样灵活。你的关注点从“如何让一个LLM做完所有事”变成了“如何设计一组职责清晰的智能体并定义好它们之间的协作协议”。3. 从零搭建你的第一个多智能体系统实战演练理论说得再多不如动手做一遍。让我们来构建一个经典的“老板-员工”多智能体场景一个ManagerAgent老板接收用户关于天气和数学计算的混合请求然后指派两个专业员工WeatherAgent天气专员和CalculatorAgent计算专员去完成任务最后汇总结果回复给用户。3.1 环境准备与基础配置首先确保你的Python环境在3.8以上。然后安装agency框架。通常它可以通过pip安装其开源版本或开发中的版本这里我们假设从源码或指定仓库安装请以实际项目README为准pip install agency-swarm # 注意这是一个示例真实包名可能是 agency 或 neurocult-agency # 或者从源码安装 # git clone https://github.com/neurocult/agency.git # cd agency # pip install -e .接下来你需要准备LLM的API密钥。Agency设计上支持多种LLM后端OpenAI Anthropic 本地模型等。这里以最通用的OpenAI为例import os os.environ[OPENAI_API_KEY] your-api-key-here注意在实际项目中永远不要将API密钥硬编码在代码里。使用环境变量或安全的密钥管理服务是必须遵守的安全规范。3.2 定义专属工具智能体我们先创建两个“员工”智能体一个负责天气查询一个负责数学计算。WeatherAgent天气智能体 这个智能体需要一个真实的工具来获取天气。我们可以用一个模拟函数或者集成一个免费的天气API如OpenWeatherMap。这里为了演示使用模拟数据。from agency import Agent, action import random from datetime import datetime class WeatherAgent(Agent): def __init__(self, id): super().__init__(idid, descriptionA helpful agent that can provide weather information for cities.) # 可以在这里初始化API客户端等 action def get_current_weather(self, city: str) - str: Get the current weather for a given city. Args: city: The name of the city (e.g., London, New York). Returns: A string describing the current weather. # 模拟天气数据。真实场景应调用如OpenWeatherMap API。 # 示例https://api.openweathermap.org/data/2.5/weather?q{city}appid{API_KEY} temperatures {Beijing: 22, Shanghai: 25, New York: 18, London: 15} conditions [sunny, cloudy, partly cloudy, rainy] temp temperatures.get(city, random.randint(10, 30)) condition random.choice(conditions) return fThe current weather in {city} is {condition} with a temperature of {temp}°C.CalculatorAgent计算智能体 这个智能体提供基本的数学运算。class CalculatorAgent(Agent): def __init__(self, id): super().__init__(idid, descriptionA precise agent that performs mathematical calculations.) action def add(self, a: float, b: float) - float: Adds two numbers. return a b action def multiply(self, a: float, b: float) - float: Multiplies two numbers. return a * b action def divide(self, a: float, b: float) - float: Divides the first number by the second. Raises an error if dividing by zero. if b 0: raise ValueError(Cannot divide by zero.) return a / b关键点在于action装饰器和类型注解。框架会利用这些信息为LLM生成清晰的工具定义。文档字符串Adds two numbers.至关重要它是LLM理解该工具用途的主要依据。3.3 创建核心管理者智能体ManagerAgent是这个系统的“大脑”。它本身不直接查询天气或计算但它知道WeatherAgent和CalculatorAgent的存在并能向它们分派任务。class ManagerAgent(Agent): def __init__(self, id, weather_agent_id, calc_agent_id): super().__init__(idid, descriptionA manager that coordinates tasks between specialized agents.) self.weather_agent_id weather_agent_id self.calc_agent_id calc_agent_id action def handle_complex_request(self, user_request: str) - str: Handles a complex user request that may involve both weather and calculations. The manager will parse the request, delegate subtasks, and compile the final answer. Args: user_request: The full request from the user (e.g., Whats the weather in Beijing and also calculate 15 * 8?) Returns: A comprehensive response combining information from all involved agents. # 注意在实际完整实现中这里应该集成一个LLM来理解用户请求并规划步骤。 # 以下是一个高度简化的、硬编码的逻辑演示。 response_parts [] # 模拟请求解析真实场景用LLM if weather in user_request.lower() and beijing in user_request.lower(): # 委托任务给 WeatherAgent # 在真实框架中这里可能是 yield 一个给其他agent的消息或调用一个 delegate action。 # 我们假设框架提供了 send 方法。 weather_result yield self.send(self.weather_agent_id, get_current_weather, {city: Beijing}) response_parts.append(fWeather Info: {weather_result}) if calculate in user_request.lower() or 15 * 8 in user_request: # 委托任务给 CalculatorAgent calc_result yield self.send(self.calc_agent_id, multiply, {a: 15, b: 8}) response_parts.append(fCalculation Result: 15 * 8 {calc_result}) if not response_parts: return I couldnt identify any tasks I can handle in your request. return Here is what I found:\n \n.join(response_parts)这里的yield self.send(...)语法是Agency框架中一个关键且精妙的设计它代表了异步协作。它并不意味着Python生成器而是在框架的上下文中表示“暂停当前动作的执行发送一个消息给另一个智能体并等待其回复拿到回复后再继续执行当前动作”。这完美模拟了管理者等待员工汇报的场景。3.4 组装智能体空间并运行现在我们把所有智能体放进一个“办公室”Space并让它们开始协作。from agency import Space def main(): # 1. 创建智能体实例 weather_agent WeatherAgent(idweather_man) calc_agent CalculatorAgent(idcalc_pro) manager ManagerAgent(idboss, weather_agent_idweather_man, calc_agent_idcalc_pro) # 2. 创建空间并添加智能体 office_space Space() office_space.add(weather_agent) office_space.add(calc_agent) office_space.add(manager) # 3. 设置空间的默认入口点通常是管理智能体或一个路由智能体 # 这里我们简单地将用户输入直接发给 ManagerAgent def run_cli(): print(Multi-Agent System Started. Type quit to exit.) while True: try: user_input input(\nYou: ) if user_input.lower() quit: break # 将用户输入作为 handle_complex_request 的动作参数触发 # 实际框架调用方式可能不同例如使用 run 或 process 方法 result office_space.run(agent_idboss, action_namehandle_complex_request, action_args{user_request: user_input}) print(fSystem: {result}) except Exception as e: print(fError: {e}) run_cli() if __name__ __main__: main()运行这个程序你就拥有了一个简单的多智能体命令行应用。当你输入“Whats the weather in Beijing and calculate 15 * 8?”时ManagerAgent会在我们简化的逻辑里识别出两个子任务分别委托给WeatherAgent和CalculatorAgent收集它们的回复然后组合成最终答案返回给你。实操心得在初次搭建时最容易混淆的是消息流。务必理解智能体A调用智能体B的Action并不是直接的函数调用B.action()而是通过Space发送一条格式化的消息。框架负责序列化、路由、执行和返回结果。这种间接性带来了灵活性如中间件、日志、权限控制但也增加了调试的复杂度。善用框架的日志功能打印出在Space中流动的消息是理解系统行为的关键。4. 深入核心Action定义、模型集成与消息流掌握了基础搭建后我们需要深入三个核心机制这是构建稳定、高效多智能体系统的基石。4.1 Action设计的艺术与规范Action是与LLM交互的合约。设计好坏直接决定智能体是否“听话”。命名与描述函数名应清晰动词开头get_,calculate_,send_。文档字符串docstring必须精确描述功能、参数和返回值。LLM主要靠它来理解何时使用该Action。action def search_web(self, query: str, max_results: int 5) - list: Searches the web for relevant information based on a query. Args: query: The search query string. max_results: Maximum number of results to return (default 5). Returns: A list of dictionaries, each containing title, url, and snippet. # ... 实现搜索逻辑糟糕的描述如Does stuff.会导致LLM误用或根本不用这个工具。参数类型与默认值使用明确的类型注解str,int,bool,List[str]等。合理的默认值可以简化LLM的调用。对于复杂对象可以考虑使用Pydantic模型来定义action_args框架通常能很好地支持。错误处理与边界情况Action内部必须有健壮的错误处理。不要抛出LLM无法理解的原始异常。应该捕获异常并返回结构化的错误信息或者让框架层统一处理。action def read_file(self, filepath: str) - str: try: with open(filepath, r, encodingutf-8) as f: return f.read() except FileNotFoundError: return fError: The file at {filepath} was not found. except Exception as e: return fError reading file: {str(e)}4.2 灵活集成不同的大语言模型Agency框架通常抽象了LLM的调用层。这意味着你可以相对容易地切换模型提供商。配置模型参数在创建Agent时你通常可以传入一个llm_config字典或对象。from agency.llm import OpenAIChatCompletionsModel class SmartAgent(Agent): def __init__(self, id): llm_config { model: gpt-4-turbo-preview, # 或 claude-3-opus-20240229 api_key: os.getenv(OPENAI_API_KEY), temperature: 0.1, # 对工具调用类任务低温度更可靠 max_tokens: 2000, } super().__init__(idid, llmOpenAIChatCompletionsModel(**llm_config)) # ... 其他初始化切换后端如果框架支持Anthropic、Cohere或本地VLLM服务器你只需要更换llm参数对应的类或配置即可。这允许你根据成本、速度、能力为不同智能体选择最合适的模型。例如让负责创意的智能体使用GPT-4而负责简单分类的智能体使用更便宜的Claude Haiku。系统提示词工程每个智能体的“角色”主要通过其系统提示词System Prompt定义。框架会将Agent的description、拥有的Actions列表及其描述自动整合到系统提示词中。但你也可以覆盖默认的提示词模板为其注入更具体的指令、约束和输出格式要求。这是塑造智能体行为的最有效手段。4.3 剖析消息生命周期与自定义中间件理解消息如何在Space中流动是进行高级控制和调试的基础。一条消息的生命周期通常包括发送(Send)-预处理(Pre-process)-路由(Route)-目标智能体处理(Process)-动作执行(Action Execution)-响应生成(Response Generation)-后处理(Post-process)-返回(Return)。Agency的强大之处在于你可以在预处理和后处理环节插入自定义的中间件Middleware。这开启了无限可能日志与审计记录所有智能体间的对话用于复盘、调试或合规审查。class LoggingMiddleware: def on_receive(self, message): print(f[LOG] Received: {message.sender} - {message.recipient} | Action: {message.action}) return message def on_send(self, message): print(f[LOG] Sent: {message.sender} - {message.recipient} | Result: {message.result}) return message权限控制在路由前检查发送者是否有权调用接收者的某个Action实现简单的安全沙箱。消息改写在消息到达目标前修改其内容。例如自动为所有发送给翻译智能体的消息添加“请将以下内容翻译成法语”的前缀。限流与排队防止某个智能体被过多请求淹没。通过space.add_middleware(LoggingMiddleware())即可注册。这种可插拔架构使得核心框架保持简洁而将扩展能力交给开发者。5. 构建复杂工作流编排模式与实战案例当任务超出简单的“一问一答”或“一对一派单”就需要更高级的编排模式。Agency框架本身提供了基础的消息传递原语而复杂工作流建立在它们之上。5.1 常见的多智能体协作模式链式调用 (Chain)智能体A完成任务后将结果传给智能体BB再传给C。这是最简单直接的顺序工作流。可以通过在Action中连续使用yield self.send(...)来实现。广播与聚合 (Broadcast/Aggregate)管理者智能体将一个查询同时发送给多个专家智能体如三个不同的搜索引擎智能体然后收集所有结果进行汇总分析。这需要管理者具备并行发送消息和等待多个响应的能力框架可能提供gather之类的辅助函数。竞争与选择 (Competition/Selection)将同一个任务发给多个同类型智能体如三个代码生成智能体然后根据结果的质量、速度或成本选择一个最优的。这需要在后处理环节进行比较逻辑。递归分解 (Recursive Decomposition)一个“规划者”智能体将复杂目标分解成子任务子任务可能继续被分解直到成为可被“执行者”智能体直接处理的原子任务。这类似于AI领域的“思维树”Tree of Thoughts在多个智能体上的实现。5.2 实战案例AI会议纪要生成系统让我们设计一个更贴近真实业务的系统自动会议纪要生成器。假设我们有音频流系统需要自动完成转录、摘要、提取行动项和发送邮件通知。智能体团队设计TranscriberAgent负责调用语音转文本API如Whisper将音频转为文字稿。SummarizerAgent接收文字稿生成会议核心内容的摘要。ActionItemExtractorAgent从文字稿中提取具体的行动项谁、做什么、何时。EmailAgent负责格式化摘要和行动项并发送邮件给参会者。CoordinatorAgent总协调员接收音频文件按顺序调用上述智能体并处理错误。工作流实现要点class CoordinatorAgent(Agent): def __init__(self, id, transcriber_id, summarizer_id, action_extractor_id, emailer_id): super().__init__(idid, descriptionOrchestrates the meeting minutes generation pipeline.) self.transcriber_id transcriber_id # ... 存储其他agent id action def generate_minutes(self, audio_file_path: str, recipient_emails: List[str]) - dict: Full pipeline: Transcribe - Summarize - Extract Actions - Email. Returns a status report. status {steps: {}, success: True} try: # 1. 转录 status[steps][transcription] Started transcript yield self.send(self.transcriber_id, transcribe_audio, {file_path: audio_file_path}) status[steps][transcription] Completed # 2. 摘要 (可并行于行动项提取) summary_future self.send(self.summarizer_id, summarize_text, {text: transcript}) # 3. 提取行动项 actions_future self.send(self.action_extractor_id, extract_action_items, {text: transcript}) # 等待并行任务完成 summary, action_items yield [summary_future, actions_future] status[steps][summarization] Completed status[steps][action_extraction] Completed # 4. 发送邮件 email_result yield self.send(self.emailer_id, send_meeting_minutes, { summary: summary, action_items: action_items, recipients: recipient_emails }) status[steps][email_notification] Completed status[final_result] email_result except Exception as e: status[success] False status[error] str(e) # 可以在这里添加错误恢复逻辑例如通知管理员 yield self.send(self.emailer_id, send_alert, {alert_message: fPipeline failed: {e}}) return status这个案例展示了如何将线性与并行任务结合并加入基本的错误处理。在实际部署中每个智能体都可以独立部署和扩展例如TranscriberAgent可以部署在有GPU的服务器上而其他Agent可以部署在普通CPU服务器上。5.3 状态管理、记忆与长期会话对于需要多轮交互的复杂任务智能体需要有“记忆”。Agency框架通常通过以下几种方式支持会话级记忆在Space或Agent级别维护一个对话历史列表。每次交互都将先前的消息作为上下文提供给LLM。这简单有效但上下文长度受模型限制。向量数据库长期记忆为智能体集成一个向量数据库如Chroma Weaviate。将重要的交互信息如用户偏好、项目详情转换成向量存储起来。当需要相关记忆时通过语义搜索召回。这需要你在Action中显式地进行“存储”和“查询”操作。外部数据库对于高度结构化的数据如用户账户、订单信息直接让智能体通过Action调用数据库接口需注意SQL注入安全最好提供封装好的查询Action。实现一个带记忆的客服智能体示例class CustomerSupportAgent(Agent): def __init__(self, id, vector_db_client): super().__init__(idid, descriptionA support agent with long-term memory.) self.db vector_db_client self.conversation_history [] # 短期会话记忆 action def answer_question(self, user_id: str, question: str) - str: # 1. 从长期记忆检索相关历史 past_interactions self.db.search(queryquestion, user_iduser_id, limit3) # 2. 构建包含记忆的提示词 memory_context \n.join([fPrevious: {i[query]}\nResponse: {i[answer]} for i in past_interactions]) full_prompt f You are a support agent. Here is relevant past context for user {user_id}: {memory_context} Current conversation history (latest first): {self.format_history(self.conversation_history[-5:])} Users new question: {question} # 3. 调用LLM生成回答 (这里简化实际使用框架的LLM调用) answer self.llm.generate(full_prompt) # 4. 存储本次交互到长期记忆 self.db.store(user_iduser_id, queryquestion, answeranswer) # 5. 更新会话历史 self.conversation_history.append({user: question, agent: answer}) return answer记忆机制是智能体体现“个性化”和“连续性”的关键但同时也带来了数据隐私和管理的复杂性在设计时需要权衡。6. 部署、监控与性能优化实战指南开发完成的多智能体系统最终需要稳定、可靠地运行。这部分分享从开发环境到生产环境的实战经验。6.1 部署架构选型Agency应用的本质是一个或多个Python进程。部署方式取决于规模和要求单进程部署对于轻量级应用所有智能体在同一个Python进程中运行。部署简单但一个智能体的阻塞或崩溃会影响整体。适用于原型或内部工具。# 直接运行你的主Python脚本 python your_agency_app.py多进程/分布式部署这是生产环境的常见选择。每个智能体或每组智能体作为独立的服务运行通过网络如HTTP gRPC进行通信。Agency框架的消息总线需要适配为网络消息队列如Redis RabbitMQ ZeroMQ。优势资源隔离、独立扩缩容、高可用。挑战需要处理网络延迟、序列化/反序列化、服务发现。工具可以使用Docker容器化每个智能体服务用Kubernetes或Docker Compose编排。框架可能需要你实现一个NetworkSpace类来代替本地的Space。Serverless部署将每个智能体的Action包装成云函数AWS Lambda Google Cloud Functions。由网关或主协调器触发。成本效益高伸缩自动但冷启动可能影响延迟且状态管理复杂。6.2 日志、监控与可观测性“黑盒”的多智能体系统调试起来是噩梦。必须建立完善的可观测性体系。结构化日志不要用简单的print。使用logging模块为每条日志记录清晰的级别INFO DEBUG ERROR、时间戳、智能体ID、动作ID、消息ID和上下文。import logging logging.basicConfig(levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - [Agent:%(agent_id)s] - %(message)s) logger logging.getLogger(__name__) class MyAgent(Agent): action def some_action(self, arg): logger.info(fStarting some_action with arg{arg}, extra{agent_id: self.id}) # ... do work logger.info(Action completed successfully, extra{agent_id: self.id})将日志收集到中央系统如ELK Stack Loki便于搜索和分析。指标监控跟踪关键指标。延迟每个Action的平均执行时间、LLM调用耗时。吞吐量每秒处理的消息数/请求数。错误率Action调用失败的比例、LLM API错误次数。Token使用量各智能体的输入/输出Token消耗是成本控制的核心。 可以使用Prometheus客户端库在代码中暴露指标然后用Grafana展示。分布式追踪一个用户请求可能流经多个智能体。为每个初始请求生成一个唯一的trace_id并让这个trace_id随着消息在所有智能体间传递。这样可以在日志和监控中完整还原整个请求的生命周期快速定位瓶颈或故障点。6.3 性能优化与成本控制策略多智能体系统容易在性能和成本上失控。以下是一些关键策略LLM调用优化缓存对具有确定性的LLM请求例如固定提示词固定参数的查询的结果进行缓存。可以使用functools.lru_cache或外部缓存如Redis。批处理如果框架和模型支持将多个独立的、小的文本生成请求批处理成一个大的API调用可以显著降低延迟和成本如果按Token计价。模型分级如前所述让不同的智能体使用不同能力的模型。简单的路由、格式化任务用廉价/快速模型如GPT-3.5-Turbo复杂的推理、创意任务再用强大模型如GPT-4。精简提示词不断优化每个智能体的系统提示词和上下文移除冗余信息减少不必要的Token消耗。智能体并发与异步确保你的Action定义尽可能使用异步IOasync def特别是在Action内部需要调用网络API数据库、外部服务时。这能极大提高单个智能体处理多个并发请求的能力。利用框架的异步消息传递机制如yield和gather让可以并行的任务真正并行起来而不是串行等待。超时与重试为所有对外部服务LLM API、数据库、其他微服务的调用设置合理的超时。避免一个慢速响应拖垮整个系统。对于可能因网络抖动导致的瞬时失败实现指数退避重试机制。但对于LLM的4xx错误如内容过滤则不应重试。流量控制与限流在Space或智能体入口处实现限流Rate Limiting防止突发流量击垮下游LLM API或智能体本身。可以使用令牌桶等算法。对成本高昂的智能体如调用GPT-4的设置更严格的并发数限制。7. 避坑指南常见问题与进阶技巧在开发和运营Agency系统的过程中我踩过不少坑也积累了一些让系统更稳健、更智能的技巧。7.1 典型问题与解决方案速查表问题现象可能原因排查步骤与解决方案智能体不调用预期的Action1. Action描述docstring不清晰。2. LLM温度temperature设置过高导致输出不稳定。3. 系统提示词未正确包含Action列表或角色定义模糊。1. 检查并重写Action的docstring确保清晰无歧义。2. 将temperature调低如0.1-0.3。3. 打印或记录框架生成的完整系统提示词确认所有Action描述都已正确注入。消息丢失或智能体无响应1. 消息路由错误发送者ID或接收者ID拼写错误。2. 目标智能体的Action执行抛出未处理的异常。3. 在分布式部署中网络问题或服务未注册。1. 启用框架的详细日志检查消息的sender和recipient字段。2. 在Action内部添加全面的try-except并记录错误日志。3. 检查服务发现机制如Consul和网络连通性。系统响应速度极慢1. 链式调用过长且全是同步阻塞操作。2. 某个外部API如LLM、数据库响应慢。3. 未使用异步IO导致并发能力差。1. 分析工作流将无依赖的任务改为并行。2. 为外部调用设置超时并考虑增加缓存或备用服务源。3. 将Action改为async def并使用异步客户端库。Token消耗超出预算1. 提示词过于冗长包含不必要的历史上下文。2. 智能体陷入循环反复生成长文本。3. 未对用户输入长度做限制。1. 实现“摘要式记忆”用摘要代替完整历史。2. 设置每个会话或Action的最大Token限制并在达到时强制终止或总结。3. 在前置网关对用户输入进行长度截断。智能体做出危险或越权操作1. Action权限控制缺失。2. 系统提示词中的安全约束不够强。3. 用户输入未经过滤直接传递给LLM。1. 实现基于角色的权限中间件检查发送者是否有权调用某个Action。2. 在系统提示词中强化“仅能使用提供的工具”、“不得假设或执行未授权操作”。3. 对所有用户输入进行内容安全过滤如敏感词、Prompt注入检测。7.2 提升智能体协作效率的进阶技巧动态智能体发现与注册在大型系统中硬编码智能体ID不可扩展。可以实现一个“注册中心”智能体。新智能体启动时向注册中心报道宣告自己的ID和能力Action列表。协调者智能体需要帮手时先向注册中心查询。这实现了系统的动态扩展。让智能体学会“求助”在智能体的系统提示词中加入这样一条规则“如果你无法独自完成用户请求但知道哪个同事智能体可能擅长你可以向我或协调者发送一个内部消息请求将该任务转交给它。” 这需要框架支持智能体主动发起消息。通过少量示例微调或提示工程可以让LLM学会这种协作行为。工作流可视化与调试工具开发一个简单的Web面板实时显示Space中流动的消息用箭头图可视化智能体间的调用关系。这对于调试复杂工作流和向非技术人员解释系统行为 invaluable无比珍贵。基于评估的自我优化引入一个“评估者”智能体。在关键任务完成后评估者会对结果质量进行评分根据准确性、完整性、格式等。这些评分可以作为反馈用于优化相关智能体的提示词甚至通过RAG检索增强生成动态为它们提供更优质的示例。这就形成了一个简单的强化学习循环。多智能体系统是构建下一代AI应用的重要范式而Agency这类框架极大地降低了其入门门槛。从简单的任务分发到复杂的自主协作生态其可能性正在被不断探索。我个人的体会是设计一个好的多智能体系统与其说是编程不如说是在设计一个组织的架构和沟通流程。你需要思考的是每个角色的职责边界、它们如何高效沟通、如何应对失败以及如何让整个组织朝着共同目标前进。开始时不妨从一个小而具体的场景入手比如自动化的周报生成或信息检索助手逐步积累对模式和框架的理解再扩展到更宏大的构想中去。