Agent 入门实战（下篇）：微观篇——动手构建你的第一个 Agent-平芜编程栈

宏观的“地图”看完了，现在该自己变成司机，上路跑一跑。下篇我们就用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_KEY="your-api-key" # 如果使用中转或国产模型，设置 base_url # export OPENAI_BASE_URL="https://your-endpoint/v1"

1.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: 数学表达式字符串，如 '3+5*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 超时。流式输出使用 SSE（Server-Sent Events）或 WebSocket 提升体验。