Deep Agents 框架：从入门到精通

1. 引言在人工智能快速发展的今天智能体Agent框架已成为构建复杂 AI 应用的核心工具。Deep Agents 是一个轻量级、模块化的 Python 框架专为构建基于大语言模型LLM的智能体而设计。它提供了简洁的 API 和强大的扩展能力让开发者能够快速搭建从简单对话到复杂多智能体协作的各种应用。本文将带你从零开始通过大量代码实操逐步掌握 Deep Agents 框架的核心概念与高级用法。2. 环境准备与安装2.1 环境要求Python 3.9操作系统macOS / Linux / Windows2.2 安装 Deep Agents# 使用 pip 安装pipinstalldeep-agents# 如果需要最新开发版pipinstallgithttps://github.com/your-org/deep-agents.git2.3 验证安装importdeep_agentsasdaprint(da.__version__)# 输出示例0.1.02.4 配置 API KeyDeep Agents 默认支持 OpenAI 兼容接口。你可以通过环境变量或代码配置# 方式一环境变量exportOPENAI_API_KEYsk-your-api-keyexportOPENAI_BASE_URLhttps://api.openai.com/v1# 方式二代码配置fromdeep_agentsimportConfig configConfig(api_keysk-your-api-key,base_urlhttps://api.openai.com/v1,modelgpt-4o-mini# 默认模型)3. 核心概念速览在开始编码之前我们先了解 Deep Agents 的四个核心概念概念说明类比Agent智能体核心执行单元一个AI 员工Tool工具Agent 可调用的外部能力员工的技能Memory记忆Agent 的上下文存储员工的笔记Pipeline流水线编排多个 Agent 协作一个工作流4. 快速上手第一个 Agent4.1 最简单的对话 Agentfromdeep_agentsimportAgent# 创建一个基础 AgentagentAgent(name助手,system_prompt你是一个友好的 AI 助手请用中文回答用户问题。)# 运行一次对话responseagent.run(请介绍一下你自己)print(response)# 输出你好我是一个基于 Deep Agents 框架构建的 AI 助手...4.2 流式输出对于长文本生成流式输出能提供更好的用户体验fromdeep_agentsimportAgent agentAgent(name写作助手)# 流式输出forchunkinagent.stream(写一首关于人工智能的短诗):print(chunk,end,flushTrue)4.3 多轮对话fromdeep_agentsimportAgent agentAgent(name对话助手)# 第一轮response1agent.run(我的名字是张三)print(response1)# 第二轮Agent 会自动记住上下文response2agent.run(我叫什么名字)print(response2)# 输出你叫张三。5. 工具系统赋予 Agent 超能力工具是 Deep Agents 最强大的特性之一。通过工具Agent 可以执行代码、查询数据库、调用 API 等。5.1 内置工具fromdeep_agentsimportAgentfromdeep_agents.toolsimportPythonExecutor,WebSearch,FileReader# 创建一个带工具的 AgentagentAgent(name全能助手,tools[PythonExecutor(),# 执行 Python 代码WebSearch(),# 网页搜索FileReader(),# 读取文件])# Agent 会自动判断何时调用工具resultagent.run(计算 1 到 100 的和并用 Python 验证)print(result)5.2 自定义工具创建自己的工具非常简单fromdeep_agentsimportToolclassCalculator(Tool):一个简单的计算器工具name:strcalculatordescription:str执行数学计算支持 , -, *, /defrun(self,expression:str)-str:try:# 安全执行数学表达式resulteval(expression,{__builtins__:{}},{})returnf计算结果{result}exceptExceptionase:returnf计算错误{str(e)}# 使用自定义工具agentAgent(name数学助手,tools[Calculator()])print(agent.run(计算 (15 27) * 3 / 2 的结果))# 输出计算结果63.05.3 带参数验证的工具frompydanticimportBaseModel,Fieldfromdeep_agentsimportToolclassWeatherInput(BaseModel):city:strField(description城市名称如北京)date:strField(defaulttoday,description日期格式 YYYY-MM-DD)classWeatherTool(Tool):name:strget_weatherdescription:str查询指定城市的天气input_schema:typeWeatherInputdefrun(self,city:str,date:strtoday)-str:# 这里应该调用真实的天气 APIreturnf{city}{date}的天气晴25°CagentAgent(name天气助手,tools[WeatherTool()])print(agent.run(北京今天天气怎么样))6. 记忆系统让 Agent 拥有长期记忆6.1 对话记忆fromdeep_agentsimportAgentfromdeep_agents.memoryimportConversationMemory# 使用对话记忆agentAgent(name记忆助手,memoryConversationMemory(max_messages50)# 保留最近 50 条消息)# 多轮对话agent.run(我喜欢编程)agent.run(我最喜欢的语言是 Python)responseagent.run(根据之前的对话说说我的喜好)print(response)# 输出根据我们的对话你喜欢编程特别是 Python 语言。6.2 向量记忆长期记忆fromdeep_agentsimportAgentfromdeep_agents.memoryimportVectorMemory# 使用向量数据库实现长期记忆agentAgent(name知识助手,memoryVectorMemory(embedding_modeltext-embedding-3-small,storage_path./memory_store))# 存储知识agent.remember(用户的生日是 1990-01-01)agent.remember(用户喜欢喝美式咖啡)# 基于语义检索回忆responseagent.run(关于我的生日你知道什么)print(response)# 输出你的生日是 1990 年 1 月 1 日。7. 多 Agent 协作Pipeline 流水线7.1 顺序流水线fromdeep_agentsimportAgent,Pipeline# 创建多个 AgentwriterAgent(name写手,system_prompt你是一个专业的文章写手负责撰写文章内容。)editorAgent(name编辑,system_prompt你是一个严格的编辑负责审校和优化文章。)# 构建流水线pipelinePipeline(agents[writer,editor],modesequential# 顺序执行)# 运行流水线resultpipeline.run(写一篇关于 AI 的 200 字短文)print(result)# 输出经过写手撰写和编辑审校后的最终文章7.2 并行流水线fromdeep_agentsimportAgent,Pipeline researcherAgent(name研究员,system_prompt你负责收集和分析信息)writerAgent(name写手,system_prompt你负责撰写最终报告)reviewerAgent(name审校,system_prompt你负责检查错误)# 并行执行研究员和写手最后审校pipelinePipeline(agents[researcher,writer,reviewer],mode{parallel:[0,1],# 研究员和写手并行sequential:[2]# 最后审校})resultpipeline.run(分析 Python 和 JavaScript 的优缺点)7.3 条件分支流水线fromdeep_agentsimportAgent,Pipeline,ConditionclassLengthCheck(Condition):根据内容长度决定下一步defcheck(self,context:dict)-str:contentcontext.get(last_output,)iflen(content)500:returneditor# 长内容需要编辑returnpublisher# 短内容直接发布writerAgent(name写手)editorAgent(name编辑)publisherAgent(name发布者)pipelinePipeline(agents[writer,editor,publisher],conditions{after_writer:LengthCheck()})8. 高级特性8.1 自定义 LLM 后端fromdeep_agentsimportAgent,LLMBackend# 使用本地模型如 Ollamalocal_llmLLMBackend(providerollama,modelllama3,base_urlhttp://localhost:11434)agentAgent(name本地助手,llmlocal_llm)8.2 中间件系统fromdeep_agentsimportAgent,MiddlewareclassLoggingMiddleware(Middleware):记录所有请求和响应的中间件defbefore_request(self,messages:list)-list:print(f[LOG] 发送消息{len(messages)}条)returnmessagesdefafter_response(self,response:str)-str:print(f[LOG] 收到响应{len(response)}字符)returnresponse agentAgent(name可观测助手,middlewares[LoggingMiddleware()])8.3 错误处理与重试fromdeep_agentsimportAgent,RetryPolicy agentAgent(name可靠助手,retry_policyRetryPolicy(max_retries3,retry_delay1.0,# 秒retry_on_exceptions[TimeoutError,ConnectionError]))9. 实战项目智能客服系统让我们综合运用所学知识构建一个完整的智能客服系统fromdeep_agentsimportAgent,Pipelinefromdeep_agents.toolsimportPythonExecutor,WebSearchfromdeep_agents.memoryimportVectorMemoryfrompydanticimportBaseModel,Field# 1. 定义工具classOrderQuery(BaseModel):order_id:strField(description订单号)classOrderLookupTool(Tool):name:strquery_orderdescription:str查询订单状态input_schema:typeOrderQuerydefrun(self,order_id:str)-str:# 模拟查询数据库orders{ORD001:已发货预计明天到达,ORD002:处理中预计 3 天送达}returnorders.get(order_id,未找到该订单)# 2. 创建专业 AgentclassifierAgent(name分类器,system_prompt你是一个客服分类器。判断用户问题类型 - order: 订单相关 - product: 产品咨询 - complaint: 投诉 - other: 其他 只返回类型名称。)order_agentAgent(name订单客服,tools[OrderLookupTool()],system_prompt你是订单客服友好地帮助用户查询订单。)product_agentAgent(name产品顾问,tools[WebSearch()],system_prompt你是产品顾问为用户推荐合适的产品。)complaint_agentAgent(name投诉处理,system_prompt你是投诉处理专员耐心倾听并解决问题。)# 3. 构建客服流水线customer_servicePipeline(agents[classifier,order_agent,product_agent,complaint_agent],modeconditional,routing{order:[1],# 转到订单客服product:[2],# 转到产品顾问complaint:[3],# 转到投诉处理other:[1]# 默认转订单客服})# 4. 运行客服系统queries[我的订单 ORD001 到哪里了,推荐一款适合编程的笔记本电脑,我对你们的服务很不满意]forqueryinqueries:print(f\n用户{query})responsecustomer_service.run(query)print(f客服{response})10. 性能优化与最佳实践10.1 缓存机制fromdeep_agentsimportAgent,Cache agentAgent(name高效助手,cacheCache(ttl3600,# 缓存 1 小时max_size1000))# 相同输入会命中缓存大幅减少 API 调用agent.run(什么是机器学习)agent.run(什么是机器学习)# 命中缓存10.2 批量处理fromdeep_agentsimportAgent agentAgent(name批量处理器)# 批量处理多个请求tasks[翻译成英文你好,翻译成英文谢谢,翻译成英文再见]resultsagent.batch(tasks,max_concurrency5)fortask,resultinzip(tasks,results):print(f{task}-{result})10.3 监控与日志importloggingfromdeep_agentsimportAgent logging.basicConfig(levellogging.INFO)agentAgent(name可监控助手,enable_tracingTrue,# 开启追踪log_levelINFO)11. 常见问题与解决方案11.1 Token 限制fromdeep_agentsimportAgent# 设置最大 Token 数agentAgent(name长文助手,max_tokens4096,max_context_length8192# 上下文窗口)11.2 工具调用超时fromdeep_agentsimportAgent agentAgent(name超时控制,tool_timeout30,# 工具调用超时 30 秒max_tool_calls10# 单次最多调用 10 次工具)12. 总结与进阶方向通过本文的学习你已经掌握了 Deep Agents 框架的核心用法✅ 基础 Agent 创建与对话✅ 工具系统与自定义工具✅ 记忆系统短期 长期✅ 多 Agent 协作流水线✅ 高级特性与实战项目进阶学习建议深入源码阅读 Deep Agents 源码理解其设计模式自定义扩展开发自己的工具库和中间件性能调优针对生产环境进行缓存和并发优化多模态支持探索图像、音频等多模态 Agent部署实践使用 Docker FastAPI 部署到生产环境Deep Agents 框架的强大之处在于其灵活性和可扩展性。随着你对框架的深入理解你将能够构建出越来越复杂的 AI 应用。开始动手实践吧