OpenAI Agents SDK 模板操作手册(可直接操作)

OpenAI Agents SDK 模板操作手册

1.离线替身模型驱动

配套模板默认用离线替身模型 驱动,所以不填 API Key 也能把 handoff、护栏、工具审批、会话这四套机制完整跑一遍。本文按「环境 → 安装 → 看拓扑 → 跑 demo → 跑测试 → 接真模型 → 跨进程审批 → 改造」推进,最后给出 12 个坑 与6 个高难问题。文中命令与输出均在本机(Python 3.10.11 + openai-agents 0.24.0)实测。

数据截止 2026-11-18对应模板 v0.1.09 段代码 · 10 张表 · 18 个问题解法

这份手册解决什么问题

学 SDK 最容易停在"看懂了但跑不起来":装完包发现要 Key、写了 Agent 却不知道模型下一步会不会调工具、审批停住了不知道怎么恢复。模板用替身模型把这条路铺平,本手册负责让你每一步都能验收。

0 个 Key

离线替身模型驱动全部流程,不联网

15 个测试

路由、审批、序列化恢复、护栏、会话、工具 schema

4 个场景

demo 一条命令跑完,输出可对照

12 个坑

含 3 个本次实测真实遇到的报错

| 阶段 | 做什么 | 验收 |
| 00 环境 | 确认 Python 3.10+、建虚拟环境 | python 路径含 .venv |
| 01 安装 | 装 openai-agents 与 pytest | 能 import,版本 0.24.x |
| 02 看拓扑 | inspect 打印 Agent/工具/交接 | 能看到 transfer_to_billing |
| 03 跑 demo | 四个场景一条命令 | 四处输出与文档一致 |
| 04 跑测试 | pytest -q | 15 passed |
| 05 真模型 | 换 model=None + Key | 回答随输入变化 |
| 06 跨进程审批 | RunState 序列化与恢复 | 两个进程之间能续跑 |
| 07 会话 | SQLiteSession / 裁剪 | 历史能累积、能截断 |
| 08 改造 | 加一个工具 / 一个专家 | 新用例通过、旧用例全绿 |

09 收尾 坑清单、验收清单 能解释每条坑的原因
[表 1:十个阶段与验收标准]

目录约定

下文所有命令都在模板根目录 (包含 app/、tests/、requirements.txt 的那一层)执行。Windows PowerShell 下激活脚本用 .\.venv\Scripts\Activate.ps1。

环境准备:先确认是哪一份 Python

约 2 分钟 · 验收:python --version 为 3.10+,且激活后路径含 .venv

SDK 要求 Python 3.10 及以上。机器上常有多份解释器(系统安装、IDE 自带、嵌入式),装到 A 却用 B 运行是"明明装了却 import 失败"的头号原因。

PowerShell · 建并激活虚拟环境

复制代码
# 1) 看版本与真实路径
python --version
(Get-Command python).Source

# 2) 建虚拟环境
python -m venv .venv

# 3) 激活
.\.venv\Scripts\Activate.ps1

# 4) 确认激活成功:路径必须以 .venv 开头
(Get-Command python).Source

预期输出Python 3.10.11 C:\...\openai-agents-template\.venv\Scripts\python.exe

实测遇到的第一个坑:精简版 Python 没有 venv

如果 python -m venv 报 No module named venv,说明用的是嵌入式/精简版解释器(某些 IDE 自带的就属于这类)。这不是权限问题,而是那份 Python 根本没打包 venv 模块------换系统安装的 Python(py -3.10 -m venv .venv)即可。另一个常见拦截是激活脚本被执行策略阻止:Set-ExecutionPolicy -Scope Process Bypass 后重试。

安装依赖

约 2--5 分钟 · 验收:openai-agents 版本为 0.24.x

1.PowerShell · 安装与版本确认

复制代码
pip install -r requirements.txt

python -c "import importlib.metadata as m; print('sdk', m.version('openai-agents'))"

# 国内网络慢时用镜像
# pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

预期输出(实测)sdk 0.24.0 # 另会带上 openai 3.54.0、pydantic 2.x

| 报错 | 原因 | 处理 |
| Configuration file contains invalid UTF-8 characters in ...pip.ini | pip 配置文件编码不是 UTF-8(常见于含中文注释的配置) | $env:PIP_CONFIG_FILE='NUL' 临时忽略,或把 pip.ini 另存为 UTF-8 |
| 写缓存时 Permission denied(缓存目录在别的盘) | 默认缓存路径不可写或被安全策略拦截 | $env:PIP_CACHE_DIR="$PWD\.pipcache" |

下载卡住 / 超时 默认源在国内不稳定 换镜像并加 --timeout 20;同一时间只跑一个 pip
[表 2:安装期三个真实报错与处理]

先看拓扑,再跑流程

1.约 10 秒 · 验收:能看到两个 transfer_to_* 与 draft_faq

模板里 handoff() 会把目标 Agent 包装成一个工具,工具名默认是 transfer_to_<agent 名下划线>;as_tool() 则用你给的名字。先看清这些名字,后面读 trace 和调试才不会被"模型为什么调了一个叫 transfer_to_billing 的工具"卡住。

2.PowerShell · 打印拓扑

复制代码
python -m app.cli inspect

预期输出(实测)Triage 客服前台,负责判断意图并分流。 tools : 'get_quota' handoffs : 'transfer_to_billing', 'transfer_to_tech' guardrails: 输入 1 / 输出 1 Billing 处理退款、账单、发票与会员套餐问题。不处理技术故障。 tools : 'lookup_order', 'issue_refund' handoffs : (无) guardrails: 输入 0 / 输出 1 Tech 处理登录、报错、页面白屏等技术故障。不处理退款。 tools : 'search_kb', 'draft_faq' handoffs : (无) guardrails: 输入 0 / 输出 1 KbWriter 把排查结论整理成一条 FAQ。 tools : (无) handoffs : (无) guardrails: 输入 0 / 输出 0

读这张表可以看出三件事:交接是工具 (所以模型能"调用"它)、护栏挂在哪几个 Agent 上 (输入只在 Triage,输出三个都有)、KbWriter 没有工具也没有交接 (它只被 as_tool 调用,不直接对话)。

跑 demo:四个场景一次看完

约 5 秒 · 验收:四处输出与下方一致

1.PowerShell · 离线跑通

复制代码
python -m app.cli demo

预期输出(实测,节选)场景 1:退款请求 → 路由到 Billing → 工具审批 → 完成 最后接手的 Agent:Billing 被审批的工具:'issue_refund' 最终回答:已处理:已为订单 A1001 提交退款 299.00 元,预计 1-3 个工作日到账 场景 2:技术故障 → 路由到 Tech → 检索 + FAQ(as_tool) 最后接手的 Agent:Tech 被审批的工具:(无) 最终回答:排查建议:FAQ:登录失败排查:① 确认账号未锁定;② 清除站点缓存后重试;③ 检查系统时间偏差。 场景 3:敏感输入 → 输入护栏拦截 已拦截,原因:{'matched': '身份证', 'rule': 'sensitive_input'} 场景 4:同一 Session 两轮 → 历史自动累积 Session 中累积的消息条数:6

场景 机制 可观察证据
1 handoff + 工具审批 + 恢复 last_agent = Billing;审批列表含 issue_refund
2 handoff + 函数工具 + agent-as-tool Tech 调了 search_kb 与 draft_faq;无审批
3 输入护栏 抛 InputGuardrailTripwireTriggered 并能读到原因
4 Session 同一 session_id 下消息累积到 6 条
[表 3:每个场景在验证什么]

2.这里有一个反直觉的细节

如果你直接用 run_once 跑场景 1,会看到 final_output 是 None------因为运行停在审批处,还没有最终答案。停下来不等于失败 :先看 result.interruptions,再决定批准还是拒绝。这个区别在写测试时最容易踩(把 None 当异常)。

跑测试:15 个用例固定住行为

约 2 秒 · 验收:15 passed

1.PowerShell · 全量与单文件

复制代码
pytest -q
pytest tests/test_approval.py -q
pytest tests/test_approval.py::test_reject_does_not_refund -vv

预期输出(实测)............... 100% 15 passed in 1.36s

| 文件 | 用例 | 保证的行为 |
| test_routing | refund_routes_to_billing | 退款请求确实交接给 Billing,且审批了一笔退款 |
| test_routing |
| test_routing |
|--------------------------------|------------------------------|----------------------------|
| login_issue_routes_to_tech | 故障类请求交给 Tech,且不触发审批 |
| quota_answered_without_handoff | 简单查询前台自己回答,不乱转接 |
| approve_completes | 批准后完成,订单变 refunding |
| reject_does_not_refund | 拒绝后不落账,订单保持 paid |
| output_guardrail_flags_leak | 输出含内部代号时 tripwire 为真 |
| normal_input_passes | 正常输入不被误伤 |
| sessions_are_isolated | 另一 session 为空 |
| lookup_tool_no_approval | 查询类工具不需要审批 |
| agent_as_tool_exposes_input | as_tool 暴露单个 input 字符串参数 |
[表 4:15 个用例各自保证什么]

2.为什么测试里用 asyncio.run 而不是 pytest-asyncio

少一个依赖、少一类"事件循环 fixture 配错"的问题。代价是每个用例各自建一次循环------对这个规模的模板完全够用。如果你的项目要并发跑大量异步用例,再引入 pytest-asyncio 并统一 asyncio_mode。

接真实模型

1.约 5 分钟 · 验收:回答随输入变化;退款请求仍会停在审批

模板把所有模型相关的东西都收敛在 build_agents(model=...) 一个参数上:传 None 就是 SDK 默认的 OpenAI 模型,传替身就是离线模式。所以"换真模型"不需要改任何 Agent 代码8。

2.PowerShell · 真实模型

复制代码
# 仅当前窗口有效;不要把 Key 写进代码或提交到仓库
$env:OPENAI_API_KEY="sk-..."
# $env:OPENAI_AGENTS_DISABLE_TRACING="1"   # 需要关闭追踪时再用

python -m app.cli ask "订单 A1001 我想退款"

# 换模型 / 换兼容端点(改 app/agents.py 的构造方式,见下文)
# $env:MODEL_NAME="gpt-4o-mini"

预期输出最后接手的 Agent:Billing 运行停在审批处,待批工具:'issue_refund' 审批后用 RunState 恢复,见手册阶段 06。

注意第二行:真实模型下审批依然生效 。这正是要验证的重点------替身模型验证机制,真实模型验证"它会不会正确选择工具"。若想改用兼容端点,把 Agent 构造时的 model 换成 OpenAIChatCompletionsModel(model=..., openai_client=AsyncOpenAI(base_url=...)),同时接受能力缩水。

| 能力 | Responses(默认) | Chat Completions / 兼容端点 |
| 函数工具 / handoff / 审批 | 支持 | 支持 |
| 托管工具(WebSearch / FileSearch / CodeInterpreter) | 支持 | 不支持 |
| 服务端会话(conversation_id) | 支持 | 不支持 |

结构化输出 支持 取决于供应商是否支持 json_schema
[表 5:两种模型路径的取舍 [8](#表 5:两种模型路径的取舍 [8] 能力 Responses(默认) Chat Completions / 兼容端点 函数工具 / handoff / 审批 支持 支持 托管工具(WebSearch / FileSearch / CodeInterpreter) 支持 不支持 服务端会话(conversation_id) 支持 不支持 结构化输出 支持 取决于供应商是否支持 json_schema)]

3.一个必须提前确认的坑

如果你后面想做"带联网搜索的客服",就不能换到兼容端点------托管搜索只在 Responses 下存在。这个决定要在项目初期定,否则改造成本会落在架构层。

跨进程审批:序列化 → 恢复 → 续跑

1.约 15 分钟 · 验收:test_resume.py 通过,且能说清三处必须传对的东西

审批要跨天,就一定要把运行状态挪出内存。SDK 给的载体是 RunState:to_string() 落库,from_string() 恢复,批准后继续 Runner.run(agent, state)6。

2.resume.py · 两个进程之间的完整链路

复制代码
from agents import RunState, Runner
from app.agents import build_agents

# ===== 进程 A:跑到审批处就落库 =====
result = await run_once("订单 A1001 我要退款", ctx)
payload = result.to_state().to_string()      # 字符串;to_json() 返回的是 dict
save_to_db(payload)                          # 你的存储

# ===== 进程 B:审批人点了"通过" =====
payload = load_from_db()
# 必须用与运行时一致的 Agent(含模型),否则会退回默认 OpenAI 模型
triage = build_agents(model=ScriptedModel())["triage"]
# from_string 是异步方法;context 默认反序列化成 dict,必须 context_override 传回
state = await RunState.from_string(triage, payload, context_override=ctx)
for item in state.get_interruptions():
    state.approve(item)                      # 或 state.reject(item, rejection_message=...)
result = await Runner.run(triage, state)
print(result.final_output)

| 对象 | 从哪来 | 干什么 |
| RunResult.interruptions | 第一次 Runner.run 返回 | 列出待审批项(含 tool_name、参数) |
| result.to_state() | 结果对象 | 转成可序列化、可恢复的运行状态 |
| RunState.approve / reject | 恢复出的状态 | 写入人工决策(可 always_approve=True 做粘性决策) |

Runner.run(agent, state) 恢复出的状态 从断点继续,直到完成或再次停下
[表 6:审批链路上的四个对象]

3.这三处不传对,恢复一定失败

① 字符串 vs 字典 :to_json() 返回 dict,而 from_string() 要字符串------混用会报 "Failed to parse run state JSON"。② 上下文类型 :默认反序列化后 ctx.context 变成 dict,工具里访问 .orders 立刻 AttributeError,必须 context_override=ctx。③ Agent 与模型 :恢复时若用未指定模型的 Agent,会去找 OpenAI 凭证并报 "Missing credentials"。tests/test_resume.py 就是为固定这三条而写的。

会话:从内存到 SQLite,再到裁剪

约 10 分钟 · 验收:同一 session 两轮后条数增加;加 limit 后不无限增长

1.session.py · 落盘与裁剪

复制代码
from agents import Runner, SessionSettings, SQLiteSession

# ① 默认 :memory:,进程退出即丢;给 db_path 才会落盘
session = SQLiteSession("chat-42", db_path="chat.db")

# ② 只取最近 8 条,避免长对话把 token 推爆
session = SQLiteSession("chat-42", db_path="chat.db",
                        session_settings=SessionSettings(limit=8))

await Runner.run(triage, "我想退款", context=ctx, session=session)

| 实现 | 存储 | 适用 |
| SQLiteSession | 本地文件 | 单机、原型、桌面端 |
| RedisSession | Redis | 多实例、要 TTL 的在线服务 |
| SQLAlchemySession | 关系库 | 已有数据库、统一运维 |

OpenAIConversationsSession OpenAI 服务端 不自建存储;但与 handoff 的 input_filter 不兼容
[表 7:会话实现的选型 [5](#表 7:会话实现的选型 [5] 实现 存储 适用 SQLiteSession 本地文件 单机、原型、桌面端 RedisSession Redis 多实例、要 TTL 的在线服务 SQLAlchemySession 关系库 已有数据库、统一运维 OpenAIConversationsSession OpenAI 服务端 不自建存储;但与 handoff 的 input_filter 不兼容)]

2.两个容易忽略的约束:

同一 session 不要并发跑 (历史会乱序),以及 session 与服务端会话(conversation_id)不能混用。中断恢复时也必须复用同一个 session,否则续跑看不到前面的对话。

改造:加一个"物流查询"专家

1.约 20 分钟 · 验收:新用例通过

改造顺序固定为四步:加工具 → 加 Agent → 连交接 → 补测试 。顺序反了最容易出现"Agent 写了但前台不知道怎么转给它"1。

| 步骤 | 改哪里 | 检查什么 |
| 1 · 加工具 | app/tools.py | docstring 写清"查什么、返回什么";参数用 Annotated 描述 |
| 2 · 加 Agent | app/agents.py | handoff_description 写清"负责什么、不负责什么" |
| 3 · 连交接 | Triage 的 handoffs | 是否需要 input_filter 裁剪历史 |

4 · 补测试 tests/ 路由 + 拒绝/边界各一条;跑全量回归
[表 8:四步法与每步的检查点]

2.diff · 三处改动

复制代码
# ① app/tools.py 追加
@function_tool
def track_shipping(order_id: str) -> str:
    """查询订单的物流轨迹。

    Args:
        order_id: 订单号,形如 A1001。
    """
    return f"订单 {order_id} 已揽收,预计明天送达"

# ② app/agents.py 追加一个专家
logistics = Agent[UserCtx](
    name="Logistics",
    handoff_description="查询物流轨迹与派送异常。不处理退款与技术故障。",
    instructions="用户问物流时调用 track_shipping,只回答轨迹相关。",
    tools=[track_shipping],
    model=model,
)

# ③ Triage 的 handoffs 加上它
handoffs=[
    handoff(billing, input_filter=remove_all_tools),
    handoff(tech),
    handoff(logistics),          # 物流不需要裁剪历史
],

3.为什么物流不加 input_filter

裁剪的意义是"别把无关的工具输出带进专家上下文"。物流查询往往依赖用户前一句给的单号,裁掉反而会让专家反复追问。判断标准是专家需不需要看之前的工具结果 ,而不是"历史越短越好"3。

十二个坑:现象、根因、修法

前五条是本次实测真实撞到的(不是从文档抄的),后七条来自官方语义与常见误用。按遇到概率排序。

1.十二个坑速查

| 现象 | 根因 | 修法 |
| guardrail_result.output_info 报 AttributeError | guardrail_result 是 InputGuardrailResult,原因在它的 .output 里 | 改读 exc.guardrail_result.output.output_info |
| 审批停下后 final_output 是 None | 运行还没结束,只是中断了 | 先判 result.interruptions,别把 None 当异常 |
| 恢复时报 "Failed to parse run state JSON" | to_json() 是 dict,from_string() 要字符串 | 落库用 to_string();或用 from_json(dict) |
| 恢复后工具里 ctx.context.xxx 报 AttributeError | context 默认反序列化成 dict | from_string(..., context_override=ctx) 或传 context_deserializer |
| 恢复时 "Missing credentials" | 恢复用的 Agent 没带模型,退回默认 OpenAI | 用与运行时一致的 build_agents(model=...) |
| 护栏对中间 Agent 不生效 | 输入护栏只挂链首,输出护栏只挂最终作答者 | 中间层用工具护栏,或改用 as_tool[4](#表 9:十二个坑速查 现象 根因 修法 guardrail_result.output_info 报 AttributeError guardrail_result 是 InputGuardrailResult,原因在它的 .output 里 改读 exc.guardrail_result.output.output_info 审批停下后 final_output 是 None 运行还没结束,只是中断了 先判 result.interruptions,别把 None 当异常 恢复时报 "Failed to parse run state JSON" to_json() 是 dict,from_string() 要字符串 落库用 to_string();或用 from_json(dict) 恢复后工具里 ctx.context.xxx 报 AttributeError context 默认反序列化成 dict from_string(..., context_override=ctx) 或传 context_deserializer 恢复时 "Missing credentials" 恢复用的 Agent 没带模型,退回默认 OpenAI 用与运行时一致的 build_agents(model=...) 护栏对中间 Agent 不生效 输入护栏只挂链首,输出护栏只挂最终作答者 中间层用工具护栏,或改用 as_tool[4] handoff 之后工具护栏静默 交接不走工具护栏路径 在目标 Agent 上重复声明,或统一用 as_tool 前端断流后仍在扣费 流式迭代器没消费完,运行继续 显式 result.cancel();或 cancel(mode="after_turn") FastAPI 里 run_sync 报事件循环错误 同步包装不能在已有事件循环中运行 统一改成 await Runner.run(...)[2] 模型从不调用某个工具 没写 docstring,或描述太含糊 补 Google 风格 docstring,参数加 Field(description=...)[9] 追踪默认把内容传出去了 默认开启且 trace_include_sensitive_data=True OPENAI_AGENTS_DISABLE_TRACING=1,或 set_trace_processors 改道[7] 多 Agent 后效果变差 交接丢上下文、专家工具集重叠 回到单 Agent + 工具分组;只在权限/上下文/复用三条件下拆[10]) |
| handoff 之后工具护栏静默 | 交接不走工具护栏路径 | 在目标 Agent 上重复声明,或统一用 as_tool |
| 前端断流后仍在扣费 | 流式迭代器没消费完,运行继续 | 显式 result.cancel();或 cancel(mode="after_turn") |
| FastAPI 里 run_sync 报事件循环错误 | 同步包装不能在已有事件循环中运行 | 统一改成 await Runner.run(...)[2](#表 9:十二个坑速查 现象 根因 修法 guardrail_result.output_info 报 AttributeError guardrail_result 是 InputGuardrailResult,原因在它的 .output 里 改读 exc.guardrail_result.output.output_info 审批停下后 final_output 是 None 运行还没结束,只是中断了 先判 result.interruptions,别把 None 当异常 恢复时报 "Failed to parse run state JSON" to_json() 是 dict,from_string() 要字符串 落库用 to_string();或用 from_json(dict) 恢复后工具里 ctx.context.xxx 报 AttributeError context 默认反序列化成 dict from_string(..., context_override=ctx) 或传 context_deserializer 恢复时 "Missing credentials" 恢复用的 Agent 没带模型,退回默认 OpenAI 用与运行时一致的 build_agents(model=...) 护栏对中间 Agent 不生效 输入护栏只挂链首,输出护栏只挂最终作答者 中间层用工具护栏,或改用 as_tool[4] handoff 之后工具护栏静默 交接不走工具护栏路径 在目标 Agent 上重复声明,或统一用 as_tool 前端断流后仍在扣费 流式迭代器没消费完,运行继续 显式 result.cancel();或 cancel(mode="after_turn") FastAPI 里 run_sync 报事件循环错误 同步包装不能在已有事件循环中运行 统一改成 await Runner.run(...)[2] 模型从不调用某个工具 没写 docstring,或描述太含糊 补 Google 风格 docstring,参数加 Field(description=...)[9] 追踪默认把内容传出去了 默认开启且 trace_include_sensitive_data=True OPENAI_AGENTS_DISABLE_TRACING=1,或 set_trace_processors 改道[7] 多 Agent 后效果变差 交接丢上下文、专家工具集重叠 回到单 Agent + 工具分组;只在权限/上下文/复用三条件下拆[10]) |
| 模型从不调用某个工具 | 没写 docstring,或描述太含糊 | 补 Google 风格 docstring,参数加 Field(description=...)[9](#表 9:十二个坑速查 现象 根因 修法 guardrail_result.output_info 报 AttributeError guardrail_result 是 InputGuardrailResult,原因在它的 .output 里 改读 exc.guardrail_result.output.output_info 审批停下后 final_output 是 None 运行还没结束,只是中断了 先判 result.interruptions,别把 None 当异常 恢复时报 "Failed to parse run state JSON" to_json() 是 dict,from_string() 要字符串 落库用 to_string();或用 from_json(dict) 恢复后工具里 ctx.context.xxx 报 AttributeError context 默认反序列化成 dict from_string(..., context_override=ctx) 或传 context_deserializer 恢复时 "Missing credentials" 恢复用的 Agent 没带模型,退回默认 OpenAI 用与运行时一致的 build_agents(model=...) 护栏对中间 Agent 不生效 输入护栏只挂链首,输出护栏只挂最终作答者 中间层用工具护栏,或改用 as_tool[4] handoff 之后工具护栏静默 交接不走工具护栏路径 在目标 Agent 上重复声明,或统一用 as_tool 前端断流后仍在扣费 流式迭代器没消费完,运行继续 显式 result.cancel();或 cancel(mode="after_turn") FastAPI 里 run_sync 报事件循环错误 同步包装不能在已有事件循环中运行 统一改成 await Runner.run(...)[2] 模型从不调用某个工具 没写 docstring,或描述太含糊 补 Google 风格 docstring,参数加 Field(description=...)[9] 追踪默认把内容传出去了 默认开启且 trace_include_sensitive_data=True OPENAI_AGENTS_DISABLE_TRACING=1,或 set_trace_processors 改道[7] 多 Agent 后效果变差 交接丢上下文、专家工具集重叠 回到单 Agent + 工具分组;只在权限/上下文/复用三条件下拆[10]) |
| 追踪默认把内容传出去了 | 默认开启且 trace_include_sensitive_data=True | OPENAI_AGENTS_DISABLE_TRACING=1,或 set_trace_processors 改道[7](#表 9:十二个坑速查 现象 根因 修法 guardrail_result.output_info 报 AttributeError guardrail_result 是 InputGuardrailResult,原因在它的 .output 里 改读 exc.guardrail_result.output.output_info 审批停下后 final_output 是 None 运行还没结束,只是中断了 先判 result.interruptions,别把 None 当异常 恢复时报 "Failed to parse run state JSON" to_json() 是 dict,from_string() 要字符串 落库用 to_string();或用 from_json(dict) 恢复后工具里 ctx.context.xxx 报 AttributeError context 默认反序列化成 dict from_string(..., context_override=ctx) 或传 context_deserializer 恢复时 "Missing credentials" 恢复用的 Agent 没带模型,退回默认 OpenAI 用与运行时一致的 build_agents(model=...) 护栏对中间 Agent 不生效 输入护栏只挂链首,输出护栏只挂最终作答者 中间层用工具护栏,或改用 as_tool[4] handoff 之后工具护栏静默 交接不走工具护栏路径 在目标 Agent 上重复声明,或统一用 as_tool 前端断流后仍在扣费 流式迭代器没消费完,运行继续 显式 result.cancel();或 cancel(mode="after_turn") FastAPI 里 run_sync 报事件循环错误 同步包装不能在已有事件循环中运行 统一改成 await Runner.run(...)[2] 模型从不调用某个工具 没写 docstring,或描述太含糊 补 Google 风格 docstring,参数加 Field(description=...)[9] 追踪默认把内容传出去了 默认开启且 trace_include_sensitive_data=True OPENAI_AGENTS_DISABLE_TRACING=1,或 set_trace_processors 改道[7] 多 Agent 后效果变差 交接丢上下文、专家工具集重叠 回到单 Agent + 工具分组;只在权限/上下文/复用三条件下拆[10]) |

多 Agent 后效果变差 交接丢上下文、专家工具集重叠 回到单 Agent + 工具分组;只在权限/上下文/复用三条件下拆[10](#表 9:十二个坑速查 现象 根因 修法 guardrail_result.output_info 报 AttributeError guardrail_result 是 InputGuardrailResult,原因在它的 .output 里 改读 exc.guardrail_result.output.output_info 审批停下后 final_output 是 None 运行还没结束,只是中断了 先判 result.interruptions,别把 None 当异常 恢复时报 "Failed to parse run state JSON" to_json() 是 dict,from_string() 要字符串 落库用 to_string();或用 from_json(dict) 恢复后工具里 ctx.context.xxx 报 AttributeError context 默认反序列化成 dict from_string(..., context_override=ctx) 或传 context_deserializer 恢复时 "Missing credentials" 恢复用的 Agent 没带模型,退回默认 OpenAI 用与运行时一致的 build_agents(model=...) 护栏对中间 Agent 不生效 输入护栏只挂链首,输出护栏只挂最终作答者 中间层用工具护栏,或改用 as_tool[4] handoff 之后工具护栏静默 交接不走工具护栏路径 在目标 Agent 上重复声明,或统一用 as_tool 前端断流后仍在扣费 流式迭代器没消费完,运行继续 显式 result.cancel();或 cancel(mode="after_turn") FastAPI 里 run_sync 报事件循环错误 同步包装不能在已有事件循环中运行 统一改成 await Runner.run(...)[2] 模型从不调用某个工具 没写 docstring,或描述太含糊 补 Google 风格 docstring,参数加 Field(description=...)[9] 追踪默认把内容传出去了 默认开启且 trace_include_sensitive_data=True OPENAI_AGENTS_DISABLE_TRACING=1,或 set_trace_processors 改道[7] 多 Agent 后效果变差 交接丢上下文、专家工具集重叠 回到单 Agent + 工具分组;只在权限/上下文/复用三条件下拆[10])
[表 9:十二个坑速查]

六个高难问题:需要设计,不是改参数

这些不会报错,但会上线后变成事故或成本。每一条给出"为什么难"和"落地做法"。

① 审批的幂等与并发

审批人可能连点两次"通过",也可能两个审批人同时点。若每次点击都从同一份 payload 恢复,就会退两次款 。落地要点:审批记录以 (thread_id, interrupt_id) 做唯一键,状态机只允许 pending → approved 迁移一次,恢复时用乐观锁;工具本身也要幂等(同一订单退款前先查状态)。

② 上下文爆炸

Session 默认每轮取全量历史,20 轮后 token 成本非线性上升。四个可叠加手段:SessionSettings(limit=N) 截断、session_input_callback 自定义合并、call_model_input_filter 调用前裁剪、以及压缩型会话。压缩的代价是阻塞流式收尾,低延迟场景应关闭自动压缩、改为闲时手动触发。

③ 护栏覆盖不到"中间层"

这是语义决定的,不是 bug:输入护栏保护入口、输出护栏保护出口,中间的 Billing/Tech 输出默认不过护栏。如果业务要求"每一步都不能泄露内部信息",就必须三条路选一条:在三处都挂输出护栏(本项目做法)、改用 as_tool 让专家输出先回到主管、或在工具层加工具护栏。三者的成本与误伤率不同,要按误报容忍度选。

④ 多 Agent 拓扑失控

模型能交接,就可能来回踢皮球:A 转 B、B 又转回 A。max_turns 能兜住总轮数,兜不住语义死循环。三个工程手段:每个 Agent 写清"不负责什么"、handoff_description 划边界、在 trace 上监控单次运行的交接次数并告警。

⑤ 长流程需要持久执行

SDK 没有内置 durable runtime。审批跨天、要等外部回调时,需要外部编排(官方给的是 Temporal 集成方向:模型调用变 Activity、workflow 内工具不做 I/O)。判断标准:流程是否可能跨进程重启 ------会,就必须把状态外置;不会,RunState + 数据库就够了。

⑥ 路径不固定,怎么评测

"输出等于某值"在这里几乎必然失败。可行三层:结果断言 (答案是否含关键事实)、轨迹断言 (是否调了必需工具、是否发生了不该有的交接)、护栏断言 (敏感输入是否被拦)。第三层最便宜也最该先做,因为它不依赖模型稳定性------本模板的 test_guardrails.py 就属于这一层。

六条的共同解法

都归结为三个决定:状态存在哪 (Session / RunState / 外部 workflow)、边界画在哪 (谁负责什么、什么必须审批)、怎么证明它按预期跑了(trace + 轨迹断言)。这三件事定下来,剩下的都是配置。

验收清单与命令速查

  • 虚拟环境已激活,python 路径含 .venv。
  • python -m app.cli inspect 能看到 transfer_to_billing 与 draft_faq。
  • python -m app.cli demo 四个场景输出与文档一致。
  • pytest -q 为 15 passed。
  • 能解释"为什么 run_once 跑退款会得到 final_output=None"。
  • 能说清恢复时必须传对的三样东西(字符串、context、Agent+模型)。
  • 知道输入护栏只保护链首、输出护栏只保护最终作答者。
  • 能说清 handoff 与 as_tool 在控制权和历史上差在哪。
  • 接真实模型后,退款仍会停在审批处(机制生效)。
  • 新增一个专家后,全量测试仍全绿。

| 想做什么 | 命令 |
| 看拓扑 | python -m app.cli inspect |
| 离线跑四场景 | python -m app.cli demo |
| 真实模型问一句 | python -m app.cli ask "订单 A1001 我想退款" |
| 跑全部测试 | pytest -q |
| 只验恢复链路 | pytest tests/test_resume.py -v |

关掉追踪 $env:OPENAI_AGENTS_DISABLE_TRACING="1"
[表 10:命令速查]

1.配套文件

模板源码在 openai-agents-template/(入口 app/cli.py,机制说明见 README.md);SDK 原理与更多取舍见 OpenAI Agents SDK 详细学习指南。

2.说明:

本手册的命令与输出来自本机实测(Windows 11 + Python 3.10.11 + openai-agents 0.24.0 + pytest 9.2.0);机制语义取自官方文档(访问于 2026-11-18)。离线替身模型只验证流程,不代表真实模型效果;真实模型链路未在本机跑过。

相关推荐
莪_幻尘1 小时前
AI 编程的下一场战争,不在模型,在协议
agent·ai编程·mcp
mengrennwpu2 小时前
Kynvio: 新一代办公助手
llm·agent
沉默王二3 小时前
腾讯这波上大分,Hy4-flash值得你猛蹬。
openai·agent·vibecoding
可夫小子4 小时前
OpenAI 用 Codex 修 ChatGPT 性能,1700 次调查只直接合入 15 个 PR
openai·ai编程
狂师4 小时前
太强了!三周冲到8.6k+ Star,免Root 免电脑,Mika 在后台替你操作所有App
github·agent·测试
攒了一袋星辰4 小时前
AI 求职长期记忆原理解析:从碎片经历到贝叶斯能力星图
知识图谱·agent·rag·ai工程·校招面试
九卷9 小时前
本体(Ontology)是什么?在 AI 中,本体的作用到底是什么?.md
大模型·agent
岁月宁静14 小时前
五、《从零手撸 Agent》 — 什么是 Agent:从“会聊天”到“会做事”,差的就是一个循环
python·agent
阿里云云原生19 小时前
AgentLoop × Qoder:采集自动装,审计直接问
云原生·agent