千笔-AIWritePaper · https://www.aiwritepaper.com把专科 agent 做成工具agent.as_tool时最容易踩的坑不是「调用语法」而是控制权与状态边界manager 仍掌握回合但嵌套 run不会自动继承父对话状态若把session乱共享、把needs_approval绕开、或把嵌套final_output当成已审计真相账单与合规会一起炸。官方 Tools · Agents as tools 写清相对 handoffas_tool 让中心 agent 编排专科网络而不交出控制as_tool支持max_turns/run_config/session/needs_approval/parameters/custom_output_extractor/is_enabled/on_stream等。本文按工程笔记钉死对照表、可跑 smoke 与生产禁区。示例模型名写作gpt-4o以你账号可用快照与官方文档为准。图上方 as_tool vs handoff中部嵌套选项与状态不继承下方生产禁区与 fail smoke。目标说明读完你应能独立完成五件事用一句话说清as_tool 时manager 保持控制handoff 会交出对话控制权。列出as_tool常用选项max_turns、run_config、session、needs_approval、parameters、custom_output_extractor、is_enabled、on_stream。写出可跑片段orchestrator specialist.as_tool并说明嵌套 run不继承父 conversation state。钉死生产禁区静默嵌套花费、错误共享 session、审批旁路、把嵌套 final_output 当审计真理。留下 fail smoke 笔记无 key 至少能构造工具有 key 时验证嵌套输出与审批中断路径可观测。规格钉死对照官方 Agents as tools控制权as_tool 中心 agent 编排handoff 移交控制。状态嵌套 agent 的 state 选项配置该次嵌套 run父 run 会话状态不自动继承。共享历史要共享 client-managed 历史须显式把同一session传给父与嵌套并与previous_response_id/conversation_id三选一策略勿混用。审批needs_approval与 function_tool 同流中断进result.interruptions经to_state()approve/reject再 resume。输出默认把嵌套 final 回给 manager可用custom_output_extractor抽取/校验。条件启用is_enabled可为 bool 或(ctx, agent)-bool禁用则对 LLM 完全隐藏。适用边界适合用 as_tool需要中心编排多个专科翻译、检索、计费问答且回合后仍要由 manager 汇总。希望专科失败时 manager 仍可换工具或降级而不是整段对话被 handoff 带走。需要在专科入口挂needs_approval或结构化parameters。更适合 handoff或单独 Runner.run专科必须接管后续多轮用户对话客服转专家坐席。你其实要「换一个 agent 成为当前对话主体」而不是「调一次工具拿结果」。不该指望 as_tool 单独搞定嵌套自动继承父消息历史默认不继承要共享须显式 session/continuation。嵌套 final_output 已审计业务事实只是模型产物除非你另有核验与审批。is_enabledFalse 等于鉴权它管可见性/调度不替代工具内授权与资源级检查。on_stream 开了 已记账清晰流式事件便于观察不自动产生成本审计表。风险提示嵌套 run 会单独消耗 turns 与 tokensmanager 若在循环里反复调贵专科成本呈乘法。把同一可变 session 在无隔离场景乱传可能串话。审批工具若在测试里永远approve等于没测拒绝路径。把 extractor 写成「缺失则编造默认 JSON」会把空结果洗成成功。步骤与机制1. as_tool vs handoff 对照维度as_toolhandoff控制权manager 保持交给目标 agent典型用途编排专科、汇总答案转交会话主体状态继承嵌套不自动继承父会话按 handoff/会话策略走审批挂载needs_approval可挂工具入口另见 HITL/中断模式失败后manager 可继续选工具对话已在专科侧2. as_tool 选项速查选项做什么不做什么tool_name/tool_description暴露给模型的工具面不改专科内部 instructionsmax_turns限制嵌套回合不限制父 runrun_config嵌套 RunConfig不自动合并父 config 全部字段以官方为准实测session嵌套 client-managed 历史不隐式等于父 sessionneeds_approval调用前可暂停不替代工具内鉴权parameters结构化入参 schema默认仍是{input: str}custom_output_extractor改写回传内容不自动校验业务真伪is_enabled运行时显隐不是授权系统on_stream监听嵌套流事件不代替成本账本3. 可跑 smokeorchestrator specialist.as_tool先pip install openai-agents并导出OPENAI_API_KEY无 key 时至少应能 import 与构造as_tool。importasynciofromagentsimportAgent,Runner# 专科短指令便于观察嵌套输出specialistAgent(nameCitationCheck,instructions(你只做一件事根据输入指出引用核验要点。不要编造 DOI不确定就写「需人工打开核验」。),modelgpt-4o,# 占位以账号可用快照为准)orchestratorAgent(namePaperOrchestrator,instructions(你是论文助手编排者。需要引用核验时必须调用 citation_check 工具工具失败或不确定时向用户披露禁止把猜测写成已核验。),modelgpt-4o,tools[specialist.as_tool(tool_namecitation_check,tool_description对给定引用片段做核验要点检查,max_turns4,# 嵌套默认不继承父会话此处故意不传 session便于对照)],)asyncdefmain()-None:resultawaitRunner.run(orchestrator,请核验Smith 2021 JournalX 卷3 页12-20DOI 未提供。,)print(final:,result.final_output)# 观察嵌套痕迹new_items / raw_responses以 SDK 版本为准print(items:,len(getattr(result,new_items,[])or[]))if__name____main__:asyncio.run(main())验收进程可构造工具有 key 时最终输出应承认「需人工打开」类不确定性而不是伪造「DOI 已验证通过」。把一次成功日志路径写入_w/as-tool-smoke-checklist.md。4. Fail smoke误共享 session / 审批旁路笔记Fail A — 误以为嵌套继承父历史# 反例说明不要当最佳实践# 父 run 已有多轮上下文但 as_tool 未传 session / continuation。# 期望专科「记得」刚才用户纠正过的主张编号。# 实际嵌套从自己的输入起步可能丢掉纠正 → 输出漂移。# 记 failnested_state_inheritfailFail B — 审批永远自动通过# 若 as_tool(..., needs_approvalTrue) 却在测试夹具里无条件 approve# 则从未验证 reject / 超时未审批路径。# 门禁至少 1 次 reject 样本落盘否则 approval_pathfailFail C — extractor 把空结果洗成成功asyncdefunsafe_extract(run_result):# 反例缺失时返回伪造 JSONreturn{status:ok,verified:true}# 正确方向缺失则返回明确失败标记让 manager 降级asyncdefsafe_extract(run_result):textstr(getattr(run_result,final_output,)or).strip()ifnottext:return{status:empty,verified:false}returntext把 A/B/C 三行 fail 记入 checklist零 fail 样本不得宣称生产禁区已测。5. 结构化 parameters 与输出抽取可选加强frompydanticimportBaseModel,FieldclassCheckInput(BaseModel):cite_key:strField(description正文引用键如 [12])snippet:strField(description待核验片段)toolspecialist.as_tool(tool_namecitation_check_struct,tool_description结构化引用核验,parametersCheckInput,include_input_schemaTrue,custom_output_extractorsafe_extract,)门禁结构化入参仍要在专科 instructions 里禁止编造schema 合法 ≠ 事实正确。生产禁区对标 90/91禁区为什么危险替代静默嵌套花费专科×循环账单乘法max_turns 成本审计 调用次数上限以为嵌套继承父会话纠正丢失、串话显式 session 或声明无共享同一 session 无隔离乱传用户/租户串数据按请求隔离写清策略审批夹具永远 approve拒绝路径未测强制 reject smoke把嵌套 final_output 当真理幻觉进入业务抽检/二次核验/人工闸extractor 缺失即「成功 JSON」空失败被洗白空失败标记is_enabled 当鉴权仍可能被错误装配工具内授权 guardrail与 handoff 混用却无 runbookoncall 无法判断控制权对照表进仓库可验证清单能用一句话区分 as_tool 与 handoff 的控制权orchestrator specialist.as_tool smoke 可跑或可构造文档写明嵌套不自动继承父 conversation state至少 1 条 fail无共享却期望继承 / 或错误共享若启用 needs_approvalapprove 与 reject 各 ≥1 样本成本记录嵌套调用次数与 max_turns禁止把嵌套 final_output 直接写入「已核验」业务字段踩坑把 handoff 示例代码改两个字就当 as_tool导致控制权误解。父 instructions 写「你记得全部历史」却给嵌套空 input。on_stream只打印不落盘排障时只剩 final 字符串。生产用贵模型做专科却在 smoke 用极短 prompt 掩盖超时与花费。多专科并行时假设「一个失败全体停」——须对照 runner 取消与工具错误策略实测。与 sessions / RunConfig / HITL 的分工面管什么不管什么as_tool嵌套调用面与选项自动继承父历史sessionclient-managed 历史策略替代审批run_config嵌套追踪/模型等配置自动合并父全部语义needs_approval人机闸工具内业务鉴权custom_output_extractor回传整形事实核验常见误配只开 tracing 观察嵌套很忙却不设max_turns或只设审批却在 resume 时无条件放行。当天最小实验30–40 分钟复制 orchestrator smoke无 key 验证可构造有 key 跑通一次。造 Fail A期望继承却不传 session记 nested_state_inheritfail。若启用审批造一次 reject。给 extractor 空结果确认不会洗成 verifiedtrue。把四行结果写入_w/as-tool-smoke-checklist.md。没有第 5 步落盘不得自称「as_tool 生产禁区已钉死」。多服务落地建议只读专科格式检查、提纲可 as_tool 短 max_turns。写操作/发信/扣费默认 needs_approval 或外层事务嵌套成功 ≠ 已提交。长对话专家坐席优先 handoff而不是假装 as_tool 能接管多轮。多租户session 与日志按租户隔离禁止全局单例 session。失败含义速查现象含义下一步专科「忘了」用户纠正状态未共享或 input 未带纠正显式传入或改 handoff账单陡增嵌套循环/无 max_turns限次 审计final 很顺但业务未核验把模型输出当真理加抽检闸审批日志全是 approve拒绝未测补 reject smokeis_enabled 关了仍被调用装配/缓存旧 tools查构建时 tools 列表Runbook 片段可直接贴进仓库[as-tool-policy] control manager_keeps_control nested_inherits_parent_conversation false session_strategy explicit_only max_turns_default 4 approval_write_tools required extractor_empty fail_not_ok smoke_required construct_or_run, nested_no_inherit_fail, reject_once发版检查官只问三句嵌套是否声明了状态策略写操作有没有拒绝样本嵌套输出进业务前有没有第二道核验对照编排观感 vs 生产应有行为场景编排观感生产应有行为翻译专科「调一下工具」max_turns 输出语言抽检引用核验专科「已经 check 过了」空 DOI→需人工禁 verified 洗白计费问答「答案很完整」金额字段二次校验多轮专家「再 as_tool 一次」评估是否该 handoff嵌套花费审计字段建议落盘嵌套 run 至少记录parent_run_id/nested_tool_name/nested_max_turnsnested_turns_used若可从结果推断session_strategynone|shared_explicit|server_continuationapproval_decisionn/a|approve|reject|timeoutextractor_statuspassthrough|empty_fail|custom_ok把五行打进_w/as-tool-smoke-checklist.md。没有花费与审批列只写「调用成功」等于没做生产验收。条件启用 is_enabled 的正确用法is_enabled适合环境开关预发关计费专科、租户能力包、A/B 工具面。不适合把「用户是否有权扣款」塞进可见性函数却不在工具内校验参数。用法可接受危险预发隐藏写操作专科是生产仍靠隐藏当鉴权按语言偏好显隐翻译专科是把偏好当安全边界异步函数查配额再显隐可配额通过后不再校验参数门禁工具实现内仍要做资源级授权is_enabled只减暴露面。与多 agent 模式文档的对齐提示官方多 agent 模式常并列 handoff、agents-as-tools、LLM-as-router。工程验收上要求写清本服务默认哪一种控制权模型切换时变更记录在哪。本文不复述全部模式图但 runbook 必须能回答「失败时谁还握着对话」。流式 on_stream 最小约定若传入on_stream事件类型对齐raw_response_event/run_item_stream_event/agent_updated_stream_event以 SDK 为准。处理器同步或异步均可但应有序处理。生产建议采样写入日志避免把全量 token 明文塞进无加密存储。打开on_stream会走嵌套 streaming 并在返回 final 前排空流——延迟与费用预期要写入容量计划。对照handoff 误用 as_tool 的症状症状可能误用纠正用户后续问题「专科不接话」本该 handoff 却 as_tool改 handoff 或显式多轮 session专科答完 manager 又改口as_tool 正常用 extractor/指令约束改口账单暴涨循环 as_toolmax_turns 断路器审批从未出现未设 needs_approval写操作强制挂闸当天加强结构化失败注入在预发造三条专科 instructions 故意要求编造 DOI → 看 manager 是否照抄进 final。max_turns1逼出截断 → 看是否被叙述成「已完整核验」。needs_approvalTrue后 reject → 看业务是否仍写入「已通过」。三条日志路径进 checklist缺一则 as-tool 闸门未完整。安全笔记短嵌套 agent 的 tools 列表应最小权限不要把生产写库工具挂到「只读核验」专科。custom_output_extractor里不要执行未校验代码路径。日志中的tool_call参数可能含 PII与 tracing 敏感开关一并治理。总结as_tool的工程核心不是语法糖而是控制权仍在 manager状态与花费在嵌套边界重新结算。相对 handoff它适合编排相对「嵌套自动记得一切」它默认不继承。可跑 smoke fail 样本 审批拒绝路径 禁止把嵌套 final 当审计真理才对得起 tool 超时/guardrails 91、RunConfig/sessions 90 那一档强度。参考ToolsAgents as toolshttps://openai.github.io/openai-agents-python/tools/质量要点/workspace/csdn-posts/quality/LATEST.md