宏观的“地图”看完了现在该自己变成司机上路跑一跑。下篇我们就用OpenAI Agents SDK来动手构建一个 Agent同时穿插对比其他框架的习惯帮你建立“手感”。看完这篇你就能写出一个可运行的 Agent并对它的核心机制了然于胸。一、环境准备与核心概念1.1 选型为什么先用 OpenAI Agents SDK极其轻量核心概念极少学习曲线平缓。Python 原生装饰器风格定义工具易于测试和部署。开源且与模型解耦虽然名叫 OpenAI但通过 SDK 的 Runner 你可以在底层接入任何兼容 OpenAI API 的模型包括 DeepSeek、Qwen 等只需提供base_url。非常适合入门理解 Agent 的工具调用Tool、交接Handoff、护栏Guardrails三大件。当然如果你想在企业场景设计更复杂的状态图LangGraph 是更好的选择如果团队无代码诉求强可以直接用 Coze 或 Dify。但原理是相通的。1.2 安装与环境确保 Python 3.10安装依赖pip install openai-agents # OpenAI Agents SDK pip install python-dotenv设置 API Key可以直接用 OpenAI 的 Key也可以用兼容服务export OPENAI_API_KEYyour-api-key # 如果使用中转或国产模型设置 base_url # export OPENAI_BASE_URLhttps://your-endpoint/v11.3 三大核心概念速览Agent具有名称、指令instructions和一组工具tools的智能体。指令告诉它角色和任务工具赋予它行动能力。Tool一个被function_tool装饰的 Python 函数Agent 会自主决定何时调用。你只需把函数写好、文档字符串docstring写清楚模型就会自动生成正确的调用参数。Handoff把一个 Agent 的对话控制权移交给另一个 Agent用于多 Agent 协作例如前台接待 Agent 把用户转接给技术支持 Agent。此外还有Guardrails对输入/输出进行校验和过滤和Tracing调试追踪。二、从零构建一个带工具的“生活助手”Agent我们将做一个能查天气和算数学题的简单 Agent。任务用户问“北京今天天气怎么样” → Agent 调用天气工具模拟返回信息。用户问“123 * 456 等于多少” → Agent 调用计算器工具。用户闲聊 → Agent 正常回复。2.1 定义工具import asyncio from agents import Agent, Runner, function_tool function_tool def get_weather(city: str) - str: 获取指定城市的实时天气情况。 Args: city: 城市名称如 Beijing 或 Shanghai # 模拟天气数据实际项目中可调用天气 API mock_weather_db { beijing: 北京晴25°C微风, shanghai: 上海小雨22°C东南风3级, } return mock_weather_db.get(city.lower(), f抱歉暂无{city}的天气数据。) function_tool def calculator(expression: str) - str: 执行数学运算支持加减乘除和括号。 Args: expression: 数学表达式字符串如 35*2 try: # 安全计算仅允许数字和基本运算符 allowed_chars set(0123456789-*/(). ) if not set(expression).issubset(allowed_chars): return 错误表达式包含不允许的字符 result eval(expression) return f计算结果{result} except Exception as e: return f计算出错{str(e)}关键在于docstring 写清楚功能、参数和返回值——模型就是通过读取这些描述来决定何时调用、传什么参数。2.2 创建 Agent 并运行# 创建 Agent life_assistant Agent( name生活助手, instructions你是一个友好的生活助手。你可以帮用户查询天气和执行数学计算。 如果用户的问题超出你的能力范围请礼貌地告诉他们。, tools[get_weather, calculator], ) async def main(): # 运行对话 result await Runner.run( life_assistant, input北京今天天气如何另外帮我算一下 456 * 789 ) print(result.final_output) asyncio.run(main())输出会类似北京今天天气晴朗25°C微风。456 * 789 的计算结果是 359784。有其它需要帮你的吗你不需要写任何 if-else 判断意图Agent 自己规划了步骤先调用get_weather(Beijing)再调用calculator(456*789)最后汇总生成回复。这就是ReAct 循环的实际体现。2.3 查看 Agent 思考过程调试利器在实际开发中我们经常需要知道 Agent “脑子里”发生了什么。Runner 支持流式输出和追踪result await Runner.run( life_assistant, input上海天气怎么样, ) # 打印出每一步的工具调用和推理 for step in result.to_input_list(): print(step)你会看到类似tool_call事件的字典包含调用的工具名和参数。这能快速定位“为什么 Agent 没按预期调用工具”等问题。三、升级引入第二个 Agent 和 Handoff多 Agent 交接真实场景中单个 Agent 难以应对所有问题。我们再加一个“技术支持”Agent当用户遇到报错、代码问题时生活助手可以把对话转交给它。tech_agent Agent( name技术支持, instructions你是技术专家解决编程、服务器、软件相关问题。请用专业但易懂的语言回答。, tools[], # 也可以加入代码执行等工具 ) # 修改生活助手的指令告知它可以转接 life_assistant_v2 Agent( name生活助手Pro, instructions你是生活助手可以查天气、计算数学。 当用户提问涉及编程、技术故障、报错代码等问题时 立即使用 transfer_to_tech 将对话交给技术支持专家。, tools[get_weather, calculator], handoffs[tech_agent], # 注册可交接的 Agent )这里的handoffs是传递给Agent构造函数的参数SDK 会自动生成一个名为transfer_to_tech的工具。当大模型判断用户问题属于技术支持范畴时它会调用这个工具Runner 就会无缝地把当前对话上下文移交给tech_agent由它继续回复。测试一下async def test_handoff(): result await Runner.run( life_assistant_v2, input我部署服务时遇到 502 Bad Gateway 错误怎么办 ) print(result.final_output)你会看到最终回复是技术 Agent 给出的详细排查步骤而不是生活助手强答。无需额外编写路由逻辑整个交接由模型驱动——这就是 Handoff 的优雅。四、从玩具到生产必须考虑的四个维度上面的 Demo 可爱但在真实环境远远不够。要让 Agent 稳定落地需要升级以下四个维度4.1 工具安全与鲁棒性真实工具会操作数据库、发送邮件、修改文件。你必须校验输入参数不仅是类型还有取值范围加入 Human-in-the-loop敏感操作需人工确认设置超时和重试机制错误标准化抛出带有可读信息的异常而非让 Agent 去猜在 OpenAI Agents SDK 中可以给 Agent 设置guardrails比如input_guardrails检查用户输入是否包含注入攻击output_guardrails校验输出是否符合预设格式。4.2 记忆与上下文管理Demo 中每次Runner.run都是无状态的。生产系统需要会话管理维护session_id把历史对话存储在 Redis/数据库中。长记忆超出上下文窗口时自动做摘要或滑动窗口截断。用户画像从对话中抽取偏好存入长期记忆下次对话加载。你可以在 Agent 的instructions中注入“你正在和用户小明对话他偏好简洁回答”实现轻量个性化。4.3 评估与可观测性不能靠“感觉”来判断 Agent 好不好。建立评估体系合成评估集根据真实业务场景人工编写 100 条指令和预期结果每次修改后自动回归。LLM 裁判用更强模型如 GPT-4o对 Agent 输出的准确性、完整性、安全性打分。轨迹分析接入 Langfuse 或 Braintrust 等平台查看每一步的延迟、token 消耗、工具调用成功率。OpenAI Agents SDK 自带Tracing功能能导出至 OpenAI Dashboard 或自定义 Collector看每一轮的工具调用、耗时。4.4 部署架构简单的 Agent 可以封装成 FastAPI 服务放入 Docker再用 Kubernetes 编排。对于需要长时间运行、多步骤的 Agent要考虑异步任务队列如 Celery避免 HTTP 超时。流式输出使用 SSEServer-Sent Events或 WebSocket 提升体验。五、Agent 工程师的进阶学习路线图完成以上实战你已是一名“入门级 Agent 工程师”。如果想在这个领域持续精进推荐按以下路径爬升深入框架源码阅读 LangGraph 或 AutoGen 的源码理解图状态管理、检查点、人机回环的真正实现。规划与推理优化研究 Tree-of-Thoughts、Reflexion自我反思、LLM Compiler 等论文并在框架中复现。Agentic RAG让 Agent 决定检索什么、何时检索、怎么切分构建主动型知识助手。多 Agent 系统设计设计合理的分工拓扑处理 Agent 间的共识、冲突和资源竞争。参考 CAMEL、ChatDev 等研究。安全与对齐提示注入防御、内容安全、基于 RLHF 的行为对齐都是企业级 Agent 的必修课。紧跟协议演进MCP 和 A2A 协议正在成为行业标准熟悉它们能让你构建的 Agent 融入更大的生态。六、写在最后Agent 不是一个魔法盒子它的本质是“大模型作为推理引擎 工程化的控制逻辑 确定性的工具衔接”。入门 Agent 开发关键不在于跑通某个 Demo而在于建立起“AI 的思维方式”你需要预判模型会做什么、何时会犯错、如何为它编织一张安全的网。从今天起把你平时在命令行敲的脚本、在网页上手动查询的操作试着抽象成一个个 Tool然后交给 Agent 去调度。你会慢慢发现自己正在从一个“代码的搬运工”转变成“智能系统的导演”。当某一天你构建的 Agent 独立完成了一项原本需要团队半天才能搞定的复杂任务时你可能会心一笑——这个世界真的开始变了。