1. 项目概述一个中文智能体开发框架的诞生最近在GitHub上闲逛发现了一个挺有意思的项目叫jnMetaCode/agency-agents-zh。光看名字就能猜个八九不离十这大概率是一个围绕“智能体”Agents概念构建的、面向中文开发者的开源框架或工具集。作为一名长期在AI应用开发一线摸爬滚打的从业者我立刻来了兴趣。因为“智能体”这个概念从去年开始就火得不行但真正能降低门槛、让开发者快速上手构建实用智能体的中文工具其实并不多见。这个项目在我看来瞄准的正是这个痛点。它不是一个简单的API封装而更像是一个“脚手架”或“工具箱”旨在为开发者提供一套标准化的组件、清晰的架构模式和中文友好的开发体验让大家能更专注于智能体本身的业务逻辑而不是反复折腾底层通信、任务调度这些“脏活累活”。简单说它想解决的是如何让一个具备自主规划、工具调用、记忆和协作能力的AI智能体从一个复杂的概念变成几行代码就能跑起来的现实。我花了一些时间深入研究它的代码、文档和设计理念。接下来我就从一个实践者的角度为你彻底拆解这个项目。我会聊聊它背后的核心思路、关键组件怎么用、实际搭建一个智能体的完整流程以及在这个过程中我踩过的坑和总结的经验。无论你是想快速体验AI智能体的威力还是计划将其集成到自己的产品中相信这篇深度解析都能给你带来实实在在的参考。2. 核心架构与设计哲学拆解在动手写代码之前理解一个框架的设计哲学至关重要。这决定了你用起来是顺手还是别扭。agency-agents-zh的核心思想我认为可以概括为“模块化”和“事件驱动”。2.1 模块化像搭积木一样构建智能体传统的AI应用开发往往是一个“黑盒”。你输入提示词Prompt它返回结果中间的过程难以控制和干预。而智能体框架则反其道而行之它把智能体拆解成多个可插拔的模块大脑Brain/Core这是智能体的核心通常是一个大语言模型LLM。它负责理解用户指令、进行逻辑推理、制定计划。框架会封装与不同模型如OpenAI GPT、智谱GLM、百度文心等的交互提供统一的接口。工具Tools智能体“手”和“脚”。这些是具体的函数让智能体能执行现实世界的操作比如搜索网页、查询数据库、发送邮件、执行代码等。框架需要提供一套优雅的工具注册、描述和调用机制。记忆Memory智能体的“经验”。分为短期记忆当前会话的上下文和长期记忆向量数据库存储的历史知识。框架需要管理对话历史并能从记忆库中检索相关信息来辅助当前决策。规划器Planner复杂任务的“拆解专家”。当用户提出一个复杂请求如“帮我策划一次旅行”时规划器会指挥大脑将任务分解成一系列可执行的子任务查天气、订机票、找酒店等。执行器Executor负责调度和执行规划器产生的任务列表并管理工具调用的流程和结果。agency-agents-zh通过清晰的类定义和接口将这些模块标准化。你的工作就是选择合适的“积木”比如选用哪个模型、添加哪些工具然后把它们组装起来。这种设计极大地提升了可维护性和可扩展性。2.2 事件驱动构建灵活的工作流另一个关键设计是事件驱动架构。智能体内部的运作如“收到用户消息”、“开始规划”、“调用工具”、“返回结果”都被抽象为一个个“事件”。框架内部有一个事件总线Event Bus或消息队列来传递这些事件。这样做的好处是什么解耦各个模块之间不直接硬编码调用而是通过发布/订阅事件来通信。比如工具执行模块完成后只需发布一个“工具调用完成”事件记忆模块和响应生成模块可以独立监听并处理这个事件。可观测性你可以方便地监听所有事件从而清晰地追踪智能体的整个思考链和行动过程这对于调试和优化至关重要。灵活性你可以很容易地在事件流中插入自定义的中间件Middleware例如对所有的用户输入进行安全检查或者对所有的模型输出进行格式化处理。注意理解事件驱动模型是高效使用这类框架的关键。它意味着你的代码逻辑应该从“控制流程”转向“响应事件”。刚开始可能需要转变一下思维但一旦适应你会发现构建复杂、异步的智能体流程变得非常清晰。3. 从零开始搭建你的第一个中文智能体理论说得再多不如动手一试。我们假设要构建一个“个人助理”智能体它能回答日常问题并能调用网络搜索工具来获取实时信息。3.1 环境准备与安装首先自然是准备环境。项目通常推荐使用 Python 3.8。# 克隆项目仓库 git clone https://github.com/jnMetaCode/agency-agents-zh.git cd agency-agents-zh # 创建并激活虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装核心依赖 pip install -r requirements.txt # 通常还需要安装你计划使用的模型SDK例如OpenAI pip install openai安装完成后你需要设置API密钥。框架一般会通过环境变量来管理这些敏感信息。# 在 .env 文件中设置推荐 OPENAI_API_KEY你的sk-xxx密钥 # 或者如果是国内模型如智谱AI ZHIPUAI_API_KEY你的密钥3.2 定义核心组件大脑与工具接下来我们创建两个核心文件一个定义智能体本身一个定义它可用的工具。首先定义一个网络搜索工具search_tool.pyimport requests from agency_agents_zh.core.tool import tool # 假设框架的装饰器叫 tool tool(nameweb_search, description使用搜索引擎在互联网上搜索信息适用于获取实时新闻、最新知识或未知问题的答案。) def web_search(query: str) - str: 执行网络搜索。 Args: query: 搜索查询关键词。 Returns: 搜索结果的摘要文本。 # 这里以调用一个模拟的搜索API为例。实际中你可以接入SerperAPI、Google Custom Search等。 # 注意直接爬取搜索引擎页面可能违反其服务条款建议使用官方API。 print(f[工具调用] 正在搜索: {query}) # 模拟API调用和结果解析 # response requests.get(fhttps://api.serper.dev/search?q{query}, headers...) # 此处返回模拟数据 simulated_result f关于{query}的搜索结果近期相关讨论较多主要观点认为... return simulated_result然后创建你的智能体my_assistant.pyimport os from agency_agents_zh import Agent from agency_agents_zh.brains import OpenAIBrain # 导入OpenAI大脑 # 假设框架提供了内置的简单记忆和规划器 from agency_agents_zh.memory import SimpleConversationMemory from agency_agents_zh.planner import SimplePlanner from search_tool import web_search # 导入我们刚写的工具 def create_assistant(): # 1. 初始化大脑核心LLM brain OpenAIBrain( modelgpt-3.5-turbo, # 或 gpt-4 api_keyos.getenv(OPENAI_API_KEY) ) # 2. 初始化记忆和规划器 memory SimpleConversationMemory() planner SimplePlanner() # 3. 创建智能体实例 assistant Agent( name小智助理, description一个乐于助人的个人助理可以回答问题并使用网络搜索。, brainbrain, memorymemory, plannerplanner, tools[web_search], # 将工具注册给智能体 ) return assistant if __name__ __main__: agent create_assistant() # 启动一个简单的对话循环 print(助理已启动输入 退出 或 quit 结束对话。) while True: try: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: break response agent.process(user_input) print(f\n助理: {response}) except KeyboardInterrupt: break print(对话结束。)3.3 运行与交互运行你的智能体脚本python my_assistant.py你会看到控制台启动。尝试问它一些问题“今天天气怎么样” - 它可能会直接调用web_search工具。“圆周率的前十位是多少” - 它可能直接用知识回答。“帮我总结一下最近关于人工智能的新闻。” - 它会规划“搜索新闻”和“总结”两个步骤。在后台框架会帮你完成一系列复杂操作将你的问题连同记忆中的上下文组织成提示词发给LLMLLM判断是否需要调用工具如果需要则生成工具调用的参数框架执行工具函数将工具结果返回给LLMLLM生成最终回答。这一切都封装在agent.process()这一行简单的调用之下。实操心得在初次运行时最常见的错误是API密钥未正确设置或模型响应超时。务必检查环境变量并考虑在代码中添加简单的错误处理比如捕获openai.APIError并给出友好提示。另外工具函数的描述description至关重要LLM完全依赖这段文本来决定何时以及如何调用它所以描述要准确、具体。4. 核心功能深度解析与高级用法基础助理跑通了我们来看看agency-agents-zh更强大的能力。4.1 记忆系统的实战配置简单的对话记忆可能不够。对于需要长期记忆或知识库的智能体我们需要配置向量数据库。from agency_agents_zh.memory import VectorMemory from langchain.embeddings import OpenAIEmbeddings # 假设使用LangChain的集成 from langchain.vectorstores import Chroma def create_agent_with_vector_memory(): # 创建嵌入模型 embeddings OpenAIEmbeddings(openai_api_keyos.getenv(OPENAI_API_KEY)) # 创建或连接向量数据库 vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) # 使用向量记忆 memory VectorMemory( vectorstorevectorstore, retrieval_kwargs{k: 4} # 每次检索最相关的4条记忆 ) agent Agent( name知识库助理, brain..., memorymemory, # 使用向量记忆 tools..., ) # 你可以预先向记忆库中添加文档 # agent.memory.add_texts([文档1内容, 文档2内容]) return agent这样智能体在回答问题时会先从向量库中检索相关历史信息或知识文档将其作为上下文提供给LLM从而实现“基于知识库的问答”。4.2 多智能体协作场景搭建真正的威力在于让多个智能体协作。比如构建一个“软件团队”包含产品经理、架构师、程序员、测试员等角色。from agency_agents_zh import Agent, Team # 创建不同角色的智能体 product_manager Agent(name产品经理, description负责分析需求编写用户故事和验收标准。, brain..., tools[]) architect Agent(name系统架构师, description负责设计系统架构和技术选型。, brain..., tools[]) programmer Agent(name程序员, description负责编写代码实现功能。, brain..., tools[code_tool]) tester Agent(name测试员, description负责编写测试用例并执行测试。, brain..., tools[run_test_tool]) # 组建团队 dev_team Team( name敏捷开发团队, members[product_manager, architect, programmer, tester], # 可以指定团队协调员或工作流 workflowsequential # 例如产品经理 - 架构师 - 程序员 - 测试员 ) # 向团队派发任务 final_result dev_team.process(我们需要开发一个个人博客系统请输出设计方案和核心模块代码。) print(final_result)框架会按照定义的workflow或在LLM的协调下让智能体们依次发言、传递任务和结果共同完成一个复杂项目。你可以在控制台看到整个团队的讨论过程非常有趣。4.3 自定义工具与复杂工作流工具是智能体能力的延伸。除了简单的搜索我们可以创建更复杂的工具例如操作数据库、调用内部API、发送邮件等。一个发送邮件的工具示例import smtplib from email.mime.text import MIMEText from agency_agents_zh.core.tool import tool tool(namesend_email, description发送电子邮件到指定地址。) def send_email(to: str, subject: str, body: str) - str: 发送邮件。 Args: to: 收件人邮箱地址。 subject: 邮件主题。 body: 邮件正文。 Returns: 发送成功或失败的信息。 # 配置发件人信息应从环境变量读取 sender os.getenv(EMAIL_SENDER) password os.getenv(EMAIL_PASSWORD) # 注意可能是应用专用密码 smtp_server smtp.gmail.com port 587 msg MIMEText(body, plain, utf-8) msg[Subject] subject msg[From] sender msg[To] to try: server smtplib.SMTP(smtp_server, port) server.starttls() server.login(sender, password) server.sendmail(sender, [to], msg.as_string()) server.quit() return f邮件已成功发送至 {to} except Exception as e: return f邮件发送失败: {str(e)}将这个工具注册给智能体它就能在需要时例如在规划“通知用户”这一步自动调用该工具。你可以通过精心设计工具集让智能体融入你现有的业务系统和工作流。5. 生产环境部署与性能优化当智能体开发完成准备投入实际使用时我们需要考虑部署和性能问题。5.1 部署方案选型对于agency-agents-zh这类Python框架常见的部署方式有Web API服务推荐使用 FastAPI 或 Flask 将智能体封装成RESTful API。这是最灵活的方式可以被任何前端网页、移动端、其他服务调用。from fastapi import FastAPI, HTTPException from pydantic import BaseModel from my_assistant import create_assistant app FastAPI() agent create_assistant() # 全局初始化一个智能体实例注意并发问题 class QueryRequest(BaseModel): message: str session_id: str None # 用于区分不同会话的记忆 app.post(/chat) async def chat(request: QueryRequest): try: # 根据session_id获取或创建对应的记忆上下文 response agent.process(request.message, session_idrequest.session_id) return {response: response} except Exception as e: raise HTTPException(status_code500, detailstr(e))然后用uvicorn等ASGI服务器运行。消息队列集成对于高并发或异步任务处理场景可以让智能体监听 RabbitMQ、Kafka 或 Redis Stream 中的消息处理后再将结果发布到另一个队列。这需要编写额外的消费者/生产者代码。容器化部署使用 Docker 将你的智能体应用及其所有依赖打包成镜像。这确保了环境一致性便于在 Kubernetes 或云服务器上弹性伸缩。FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]5.2 性能优化与成本控制智能体应用的核心成本来自LLM API调用。优化性能就是优化成本。缓存Caching对频繁出现的、结果确定的查询进行缓存。例如可以将(用户问题, 对话历史)的哈希值作为键将LLM的完整响应作为值存入 Redis。下次遇到相同问题直接返回缓存结果无需调用LLM。流式响应Streaming对于生成时间较长的回答使用LLM提供的流式接口边生成边返回给前端可以极大提升用户体验感知上的速度。FastAPI 对 Server-Sent Events (SSE) 有很好的支持。超时与重试为LLM API调用设置合理的超时时间并实现带有退避策略的重试机制以应对网络波动或服务端限流。模型选择并非所有任务都需要gpt-4。对于简单的分类、提取任务使用gpt-3.5-turbo甚至更小的模型可以大幅降低成本。可以在智能体内部根据任务复杂度动态选择模型。提示词优化精心设计系统提示词System Prompt和工具描述让LLM更精准、更快速地理解意图并做出正确决策减少无效的“思考”轮次Token消耗。6. 常见问题排查与实战经验在实际开发和部署中你肯定会遇到各种问题。下面是我总结的一些典型场景和解决方案。6.1 智能体不调用工具现象你明明注册了工具但智能体总是用自身知识回答从不触发工具调用。排查思路检查工具描述这是最常见的原因。LLM完全依赖tool装饰器中的description和函数文档字符串来决定是否调用。描述必须清晰、具体说明工具的用途、适用场景和输入参数。比如“搜索网络信息”就比“搜索工具”好得多。检查系统提示词框架或你自己定义的Agent可能有一个系统提示词这个提示词需要明确鼓励或指导智能体使用工具。查看Agent初始化时是否有system_prompt参数并确保其中包含了类似“你可以使用以下工具[工具列表]”的指令。启用详细日志查看框架是否提供了调试模式打印出LLM的原始请求和响应。看看在模型返回的消息中是否包含了工具调用的请求通常是一个特定格式的JSON块。如果没有说明模型根本没想调用工具。简化测试用一个极其明确、必须用工具才能完成的指令测试比如“搜索一下今天纽约时报的头条新闻是什么”。如果这样还不调用那基本就是1或2的问题。6.2 多轮对话中记忆混乱现象在长对话中智能体忘记之前说过的话或者上下文引用错误。解决方案确认记忆后端你用的是SimpleConversationMemory还是VectorMemory前者通常有长度限制如最近的10轮对话超出部分会被丢弃。后者虽然容量大但检索可能不准确。管理会话ID在Web服务中必须为每个独立的用户会话传递唯一的session_id以确保他们的记忆隔离。前端每次请求都应携带同一个session_id。记忆窗口设置如果使用窗口记忆调整k参数增加保留的对话轮数。但注意这也会增加每次API调用的Token数量提升成本和延迟。需要在记忆完整性和成本之间权衡。总结式记忆对于超长对话一种高级策略是定期让LLM自动总结之前的对话要点然后将总结文本作为新的“记忆点”存入替代原始的冗长历史。这需要定制记忆管理逻辑。6.3 处理LLM API的速率限制和错误现象应用在高并发下频繁报错提示“Rate limit exceeded”或“Timeout”。应对策略实现客户端限流在你的应用层使用令牌桶Token Bucket或漏桶Leaky Bucket算法控制向LLM API发送请求的速率使其低于官方限制。使用重试机制对于因限流429错误或网络问题5xx错误导致的失败使用指数退避策略进行重试。import time from openai import RateLimitError def call_llm_with_retry(prompt, max_retries3): for i in range(max_retries): try: return client.chat.completions.create(modelgpt-3.5-turbo, messagesprompt) except RateLimitError: wait_time (2 ** i) 1 # 指数退避 print(f速率限制等待 {wait_time} 秒后重试...) time.sleep(wait_time) except Exception as e: # 其他错误直接抛出 raise e raise Exception(达到最大重试次数请求失败。)设置合理超时为API调用配置一个全局超时时间如30秒避免单个慢请求阻塞整个线程。考虑异步调用如果你的框架和Web服务器支持异步如 FastAPI async/await可以使用异步的LLM客户端库在高并发下更高效地管理IO等待。6.4 工具调用结果不理想现象工具被调用了但返回的结果LLM不会用或者用的不对。优化方向工具输出格式化工具函数返回的字符串应该结构清晰、信息完整。LLM需要从这段文本中提取信息。如果是结构化数据如JSON返回前最好先json.dumps()一下并附带简要说明。后处理Post-processing有时候工具返回的是原始数据如HTML、复杂JSON。可以在工具内部或工具调用后、结果返回给LLM之前加一个“后处理”步骤提取出核心信息使其更易于LLM理解。让LLM学会“放弃”在工具描述中告诉LLM如果工具返回的结果表明无法完成任务如“未找到相关信息”它应该如实告知用户而不是强行编造答案。经过以上六个部分的拆解从设计理念到基础搭建从高级功能到生产部署再到问题排查我相信你已经对jnMetaCode/agency-agents-zh这个项目以及如何用它构建实用的中文智能体有了一个全面而深入的理解。这个领域的迭代非常快框架本身也会不断更新。最好的学习方式永远是动手实践从一个简单的小想法开始逐步添加功能最终构建出能真正创造价值的智能体应用。
中文智能体开发框架实战：从模块化架构到生产部署全解析
发布时间：2026/7/26 5:50:46
1. 项目概述一个中文智能体开发框架的诞生最近在GitHub上闲逛发现了一个挺有意思的项目叫jnMetaCode/agency-agents-zh。光看名字就能猜个八九不离十这大概率是一个围绕“智能体”Agents概念构建的、面向中文开发者的开源框架或工具集。作为一名长期在AI应用开发一线摸爬滚打的从业者我立刻来了兴趣。因为“智能体”这个概念从去年开始就火得不行但真正能降低门槛、让开发者快速上手构建实用智能体的中文工具其实并不多见。这个项目在我看来瞄准的正是这个痛点。它不是一个简单的API封装而更像是一个“脚手架”或“工具箱”旨在为开发者提供一套标准化的组件、清晰的架构模式和中文友好的开发体验让大家能更专注于智能体本身的业务逻辑而不是反复折腾底层通信、任务调度这些“脏活累活”。简单说它想解决的是如何让一个具备自主规划、工具调用、记忆和协作能力的AI智能体从一个复杂的概念变成几行代码就能跑起来的现实。我花了一些时间深入研究它的代码、文档和设计理念。接下来我就从一个实践者的角度为你彻底拆解这个项目。我会聊聊它背后的核心思路、关键组件怎么用、实际搭建一个智能体的完整流程以及在这个过程中我踩过的坑和总结的经验。无论你是想快速体验AI智能体的威力还是计划将其集成到自己的产品中相信这篇深度解析都能给你带来实实在在的参考。2. 核心架构与设计哲学拆解在动手写代码之前理解一个框架的设计哲学至关重要。这决定了你用起来是顺手还是别扭。agency-agents-zh的核心思想我认为可以概括为“模块化”和“事件驱动”。2.1 模块化像搭积木一样构建智能体传统的AI应用开发往往是一个“黑盒”。你输入提示词Prompt它返回结果中间的过程难以控制和干预。而智能体框架则反其道而行之它把智能体拆解成多个可插拔的模块大脑Brain/Core这是智能体的核心通常是一个大语言模型LLM。它负责理解用户指令、进行逻辑推理、制定计划。框架会封装与不同模型如OpenAI GPT、智谱GLM、百度文心等的交互提供统一的接口。工具Tools智能体“手”和“脚”。这些是具体的函数让智能体能执行现实世界的操作比如搜索网页、查询数据库、发送邮件、执行代码等。框架需要提供一套优雅的工具注册、描述和调用机制。记忆Memory智能体的“经验”。分为短期记忆当前会话的上下文和长期记忆向量数据库存储的历史知识。框架需要管理对话历史并能从记忆库中检索相关信息来辅助当前决策。规划器Planner复杂任务的“拆解专家”。当用户提出一个复杂请求如“帮我策划一次旅行”时规划器会指挥大脑将任务分解成一系列可执行的子任务查天气、订机票、找酒店等。执行器Executor负责调度和执行规划器产生的任务列表并管理工具调用的流程和结果。agency-agents-zh通过清晰的类定义和接口将这些模块标准化。你的工作就是选择合适的“积木”比如选用哪个模型、添加哪些工具然后把它们组装起来。这种设计极大地提升了可维护性和可扩展性。2.2 事件驱动构建灵活的工作流另一个关键设计是事件驱动架构。智能体内部的运作如“收到用户消息”、“开始规划”、“调用工具”、“返回结果”都被抽象为一个个“事件”。框架内部有一个事件总线Event Bus或消息队列来传递这些事件。这样做的好处是什么解耦各个模块之间不直接硬编码调用而是通过发布/订阅事件来通信。比如工具执行模块完成后只需发布一个“工具调用完成”事件记忆模块和响应生成模块可以独立监听并处理这个事件。可观测性你可以方便地监听所有事件从而清晰地追踪智能体的整个思考链和行动过程这对于调试和优化至关重要。灵活性你可以很容易地在事件流中插入自定义的中间件Middleware例如对所有的用户输入进行安全检查或者对所有的模型输出进行格式化处理。注意理解事件驱动模型是高效使用这类框架的关键。它意味着你的代码逻辑应该从“控制流程”转向“响应事件”。刚开始可能需要转变一下思维但一旦适应你会发现构建复杂、异步的智能体流程变得非常清晰。3. 从零开始搭建你的第一个中文智能体理论说得再多不如动手一试。我们假设要构建一个“个人助理”智能体它能回答日常问题并能调用网络搜索工具来获取实时信息。3.1 环境准备与安装首先自然是准备环境。项目通常推荐使用 Python 3.8。# 克隆项目仓库 git clone https://github.com/jnMetaCode/agency-agents-zh.git cd agency-agents-zh # 创建并激活虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装核心依赖 pip install -r requirements.txt # 通常还需要安装你计划使用的模型SDK例如OpenAI pip install openai安装完成后你需要设置API密钥。框架一般会通过环境变量来管理这些敏感信息。# 在 .env 文件中设置推荐 OPENAI_API_KEY你的sk-xxx密钥 # 或者如果是国内模型如智谱AI ZHIPUAI_API_KEY你的密钥3.2 定义核心组件大脑与工具接下来我们创建两个核心文件一个定义智能体本身一个定义它可用的工具。首先定义一个网络搜索工具search_tool.pyimport requests from agency_agents_zh.core.tool import tool # 假设框架的装饰器叫 tool tool(nameweb_search, description使用搜索引擎在互联网上搜索信息适用于获取实时新闻、最新知识或未知问题的答案。) def web_search(query: str) - str: 执行网络搜索。 Args: query: 搜索查询关键词。 Returns: 搜索结果的摘要文本。 # 这里以调用一个模拟的搜索API为例。实际中你可以接入SerperAPI、Google Custom Search等。 # 注意直接爬取搜索引擎页面可能违反其服务条款建议使用官方API。 print(f[工具调用] 正在搜索: {query}) # 模拟API调用和结果解析 # response requests.get(fhttps://api.serper.dev/search?q{query}, headers...) # 此处返回模拟数据 simulated_result f关于{query}的搜索结果近期相关讨论较多主要观点认为... return simulated_result然后创建你的智能体my_assistant.pyimport os from agency_agents_zh import Agent from agency_agents_zh.brains import OpenAIBrain # 导入OpenAI大脑 # 假设框架提供了内置的简单记忆和规划器 from agency_agents_zh.memory import SimpleConversationMemory from agency_agents_zh.planner import SimplePlanner from search_tool import web_search # 导入我们刚写的工具 def create_assistant(): # 1. 初始化大脑核心LLM brain OpenAIBrain( modelgpt-3.5-turbo, # 或 gpt-4 api_keyos.getenv(OPENAI_API_KEY) ) # 2. 初始化记忆和规划器 memory SimpleConversationMemory() planner SimplePlanner() # 3. 创建智能体实例 assistant Agent( name小智助理, description一个乐于助人的个人助理可以回答问题并使用网络搜索。, brainbrain, memorymemory, plannerplanner, tools[web_search], # 将工具注册给智能体 ) return assistant if __name__ __main__: agent create_assistant() # 启动一个简单的对话循环 print(助理已启动输入 退出 或 quit 结束对话。) while True: try: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: break response agent.process(user_input) print(f\n助理: {response}) except KeyboardInterrupt: break print(对话结束。)3.3 运行与交互运行你的智能体脚本python my_assistant.py你会看到控制台启动。尝试问它一些问题“今天天气怎么样” - 它可能会直接调用web_search工具。“圆周率的前十位是多少” - 它可能直接用知识回答。“帮我总结一下最近关于人工智能的新闻。” - 它会规划“搜索新闻”和“总结”两个步骤。在后台框架会帮你完成一系列复杂操作将你的问题连同记忆中的上下文组织成提示词发给LLMLLM判断是否需要调用工具如果需要则生成工具调用的参数框架执行工具函数将工具结果返回给LLMLLM生成最终回答。这一切都封装在agent.process()这一行简单的调用之下。实操心得在初次运行时最常见的错误是API密钥未正确设置或模型响应超时。务必检查环境变量并考虑在代码中添加简单的错误处理比如捕获openai.APIError并给出友好提示。另外工具函数的描述description至关重要LLM完全依赖这段文本来决定何时以及如何调用它所以描述要准确、具体。4. 核心功能深度解析与高级用法基础助理跑通了我们来看看agency-agents-zh更强大的能力。4.1 记忆系统的实战配置简单的对话记忆可能不够。对于需要长期记忆或知识库的智能体我们需要配置向量数据库。from agency_agents_zh.memory import VectorMemory from langchain.embeddings import OpenAIEmbeddings # 假设使用LangChain的集成 from langchain.vectorstores import Chroma def create_agent_with_vector_memory(): # 创建嵌入模型 embeddings OpenAIEmbeddings(openai_api_keyos.getenv(OPENAI_API_KEY)) # 创建或连接向量数据库 vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) # 使用向量记忆 memory VectorMemory( vectorstorevectorstore, retrieval_kwargs{k: 4} # 每次检索最相关的4条记忆 ) agent Agent( name知识库助理, brain..., memorymemory, # 使用向量记忆 tools..., ) # 你可以预先向记忆库中添加文档 # agent.memory.add_texts([文档1内容, 文档2内容]) return agent这样智能体在回答问题时会先从向量库中检索相关历史信息或知识文档将其作为上下文提供给LLM从而实现“基于知识库的问答”。4.2 多智能体协作场景搭建真正的威力在于让多个智能体协作。比如构建一个“软件团队”包含产品经理、架构师、程序员、测试员等角色。from agency_agents_zh import Agent, Team # 创建不同角色的智能体 product_manager Agent(name产品经理, description负责分析需求编写用户故事和验收标准。, brain..., tools[]) architect Agent(name系统架构师, description负责设计系统架构和技术选型。, brain..., tools[]) programmer Agent(name程序员, description负责编写代码实现功能。, brain..., tools[code_tool]) tester Agent(name测试员, description负责编写测试用例并执行测试。, brain..., tools[run_test_tool]) # 组建团队 dev_team Team( name敏捷开发团队, members[product_manager, architect, programmer, tester], # 可以指定团队协调员或工作流 workflowsequential # 例如产品经理 - 架构师 - 程序员 - 测试员 ) # 向团队派发任务 final_result dev_team.process(我们需要开发一个个人博客系统请输出设计方案和核心模块代码。) print(final_result)框架会按照定义的workflow或在LLM的协调下让智能体们依次发言、传递任务和结果共同完成一个复杂项目。你可以在控制台看到整个团队的讨论过程非常有趣。4.3 自定义工具与复杂工作流工具是智能体能力的延伸。除了简单的搜索我们可以创建更复杂的工具例如操作数据库、调用内部API、发送邮件等。一个发送邮件的工具示例import smtplib from email.mime.text import MIMEText from agency_agents_zh.core.tool import tool tool(namesend_email, description发送电子邮件到指定地址。) def send_email(to: str, subject: str, body: str) - str: 发送邮件。 Args: to: 收件人邮箱地址。 subject: 邮件主题。 body: 邮件正文。 Returns: 发送成功或失败的信息。 # 配置发件人信息应从环境变量读取 sender os.getenv(EMAIL_SENDER) password os.getenv(EMAIL_PASSWORD) # 注意可能是应用专用密码 smtp_server smtp.gmail.com port 587 msg MIMEText(body, plain, utf-8) msg[Subject] subject msg[From] sender msg[To] to try: server smtplib.SMTP(smtp_server, port) server.starttls() server.login(sender, password) server.sendmail(sender, [to], msg.as_string()) server.quit() return f邮件已成功发送至 {to} except Exception as e: return f邮件发送失败: {str(e)}将这个工具注册给智能体它就能在需要时例如在规划“通知用户”这一步自动调用该工具。你可以通过精心设计工具集让智能体融入你现有的业务系统和工作流。5. 生产环境部署与性能优化当智能体开发完成准备投入实际使用时我们需要考虑部署和性能问题。5.1 部署方案选型对于agency-agents-zh这类Python框架常见的部署方式有Web API服务推荐使用 FastAPI 或 Flask 将智能体封装成RESTful API。这是最灵活的方式可以被任何前端网页、移动端、其他服务调用。from fastapi import FastAPI, HTTPException from pydantic import BaseModel from my_assistant import create_assistant app FastAPI() agent create_assistant() # 全局初始化一个智能体实例注意并发问题 class QueryRequest(BaseModel): message: str session_id: str None # 用于区分不同会话的记忆 app.post(/chat) async def chat(request: QueryRequest): try: # 根据session_id获取或创建对应的记忆上下文 response agent.process(request.message, session_idrequest.session_id) return {response: response} except Exception as e: raise HTTPException(status_code500, detailstr(e))然后用uvicorn等ASGI服务器运行。消息队列集成对于高并发或异步任务处理场景可以让智能体监听 RabbitMQ、Kafka 或 Redis Stream 中的消息处理后再将结果发布到另一个队列。这需要编写额外的消费者/生产者代码。容器化部署使用 Docker 将你的智能体应用及其所有依赖打包成镜像。这确保了环境一致性便于在 Kubernetes 或云服务器上弹性伸缩。FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]5.2 性能优化与成本控制智能体应用的核心成本来自LLM API调用。优化性能就是优化成本。缓存Caching对频繁出现的、结果确定的查询进行缓存。例如可以将(用户问题, 对话历史)的哈希值作为键将LLM的完整响应作为值存入 Redis。下次遇到相同问题直接返回缓存结果无需调用LLM。流式响应Streaming对于生成时间较长的回答使用LLM提供的流式接口边生成边返回给前端可以极大提升用户体验感知上的速度。FastAPI 对 Server-Sent Events (SSE) 有很好的支持。超时与重试为LLM API调用设置合理的超时时间并实现带有退避策略的重试机制以应对网络波动或服务端限流。模型选择并非所有任务都需要gpt-4。对于简单的分类、提取任务使用gpt-3.5-turbo甚至更小的模型可以大幅降低成本。可以在智能体内部根据任务复杂度动态选择模型。提示词优化精心设计系统提示词System Prompt和工具描述让LLM更精准、更快速地理解意图并做出正确决策减少无效的“思考”轮次Token消耗。6. 常见问题排查与实战经验在实际开发和部署中你肯定会遇到各种问题。下面是我总结的一些典型场景和解决方案。6.1 智能体不调用工具现象你明明注册了工具但智能体总是用自身知识回答从不触发工具调用。排查思路检查工具描述这是最常见的原因。LLM完全依赖tool装饰器中的description和函数文档字符串来决定是否调用。描述必须清晰、具体说明工具的用途、适用场景和输入参数。比如“搜索网络信息”就比“搜索工具”好得多。检查系统提示词框架或你自己定义的Agent可能有一个系统提示词这个提示词需要明确鼓励或指导智能体使用工具。查看Agent初始化时是否有system_prompt参数并确保其中包含了类似“你可以使用以下工具[工具列表]”的指令。启用详细日志查看框架是否提供了调试模式打印出LLM的原始请求和响应。看看在模型返回的消息中是否包含了工具调用的请求通常是一个特定格式的JSON块。如果没有说明模型根本没想调用工具。简化测试用一个极其明确、必须用工具才能完成的指令测试比如“搜索一下今天纽约时报的头条新闻是什么”。如果这样还不调用那基本就是1或2的问题。6.2 多轮对话中记忆混乱现象在长对话中智能体忘记之前说过的话或者上下文引用错误。解决方案确认记忆后端你用的是SimpleConversationMemory还是VectorMemory前者通常有长度限制如最近的10轮对话超出部分会被丢弃。后者虽然容量大但检索可能不准确。管理会话ID在Web服务中必须为每个独立的用户会话传递唯一的session_id以确保他们的记忆隔离。前端每次请求都应携带同一个session_id。记忆窗口设置如果使用窗口记忆调整k参数增加保留的对话轮数。但注意这也会增加每次API调用的Token数量提升成本和延迟。需要在记忆完整性和成本之间权衡。总结式记忆对于超长对话一种高级策略是定期让LLM自动总结之前的对话要点然后将总结文本作为新的“记忆点”存入替代原始的冗长历史。这需要定制记忆管理逻辑。6.3 处理LLM API的速率限制和错误现象应用在高并发下频繁报错提示“Rate limit exceeded”或“Timeout”。应对策略实现客户端限流在你的应用层使用令牌桶Token Bucket或漏桶Leaky Bucket算法控制向LLM API发送请求的速率使其低于官方限制。使用重试机制对于因限流429错误或网络问题5xx错误导致的失败使用指数退避策略进行重试。import time from openai import RateLimitError def call_llm_with_retry(prompt, max_retries3): for i in range(max_retries): try: return client.chat.completions.create(modelgpt-3.5-turbo, messagesprompt) except RateLimitError: wait_time (2 ** i) 1 # 指数退避 print(f速率限制等待 {wait_time} 秒后重试...) time.sleep(wait_time) except Exception as e: # 其他错误直接抛出 raise e raise Exception(达到最大重试次数请求失败。)设置合理超时为API调用配置一个全局超时时间如30秒避免单个慢请求阻塞整个线程。考虑异步调用如果你的框架和Web服务器支持异步如 FastAPI async/await可以使用异步的LLM客户端库在高并发下更高效地管理IO等待。6.4 工具调用结果不理想现象工具被调用了但返回的结果LLM不会用或者用的不对。优化方向工具输出格式化工具函数返回的字符串应该结构清晰、信息完整。LLM需要从这段文本中提取信息。如果是结构化数据如JSON返回前最好先json.dumps()一下并附带简要说明。后处理Post-processing有时候工具返回的是原始数据如HTML、复杂JSON。可以在工具内部或工具调用后、结果返回给LLM之前加一个“后处理”步骤提取出核心信息使其更易于LLM理解。让LLM学会“放弃”在工具描述中告诉LLM如果工具返回的结果表明无法完成任务如“未找到相关信息”它应该如实告知用户而不是强行编造答案。经过以上六个部分的拆解从设计理念到基础搭建从高级功能到生产部署再到问题排查我相信你已经对jnMetaCode/agency-agents-zh这个项目以及如何用它构建实用的中文智能体有了一个全面而深入的理解。这个领域的迭代非常快框架本身也会不断更新。最好的学习方式永远是动手实践从一个简单的小想法开始逐步添加功能最终构建出能真正创造价值的智能体应用。
