openai-agents-python 内部机制解析AgentBindings 双身份绑定与执行 Agent 分离原理【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读本文深入解析 openai-agents-python 运行内部run_internal的AgentBindings机制它如何在一轮turn执行中同时携带对外可见的公开 Agent与实际执行逻辑的执行 Agent两个身份以及bind_public_agent/bind_execution_agent两个工厂函数分别服务于哪些场景。读完本文你将理解沙箱sandbox场景下执行前克隆的底层设计、运行循环中绑定对象的流转路径并能读懂相关源码与测试的调用关系。一、从参考文档到源码一个面向 Agent 双身份的绑定对象本文对应的官方参考文档位于 docs/ref/run_internal/agent_bindings.md它通过 mkdocstrings 指令::: agents.run_internal.agent_bindings自动渲染源码模块的 docstring 与签名真实内容即模块 src/agents/run_internal/agent_bindings.py。该模块体量极小但承担着运行期一个关键职责为每一轮执行携带公开身份与执行身份两组 Agent 引用。dataclass(frozenTrue) class AgentBindings(Generic[TContext]): Carry the public and execution agent identities for a turn. public_agent: Agent[TContext] execution_agent: Agent[TContext]从源码看AgentBindings是一个冻结frozen数据类且以TContext为泛型参数——与Agent[TContext]保持一致确保绑定对象携带的 Agent 与其共享相同的上下文类型。两个字段语义分明public_agent本轮对外可见的 Agent用户配置、钩子hooks、护栏guardrails等面向用户语义的身份execution_agent本轮真正执行模型调用、工具调用等逻辑的身份可以是一个被改写过的克隆体。二、两个工厂函数何时绑定同一身份何时分离身份模块对外暴露两个构造函数__all__中列出它们代表了两种截然不同的执行形态1.bind_public_agent常规路径双身份合一def bind_public_agent(agent: Agent[TContext]) - AgentBindings[TContext]: Build bindings for non-rewritten execution where both identities are the same. return AgentBindings(public_agentagent, execution_agentagent)其 docstring 明确指出适用于 non-rewritten execution无改写执行当 Agent 不需要被预先改写时公开身份与执行身份指向同一个对象。这是绝大多数普通运行的默认形态。2.bind_execution_agent执行专用克隆双身份分离def bind_execution_agent( *, public_agent: Agent[TContext], execution_agent: Agent[TContext], ) - AgentBindings[TContext]: Build bindings for execution-only clones such as sandbox-prepared agents. return AgentBindings( public_agentpublic_agent, execution_agentexecution_agent, )该函数使用关键字-only 参数明确要求调用方同时给出两个身份。docstring 中的典型场景是 sandbox-prepared agents——即经过沙箱准备sandbox preparation流程改写出来的执行克隆。此时公开身份仍是用户传入的原始 Agent而执行身份则指向被克隆、注入能力capabilities后的执行专用 Agent。三、绑定对象的生命周期绑定在哪里产生、在哪里消费通过检索仓库可以发现AgentBindings在整个运行链路中被广泛传递是run_internal各模块间共享的核心数据结构之一。3.1 普通运行入口与主循环在顶层入口 src/agents/run.py 中运行循环对当前 Agent 调用bind_public_agent(current_agent)生成绑定流式主循环 src/agents/run_internal/run_loop.py 同样在每一轮开始时执行current_bindings bind_public_agent(current_agent)随后从中取出execution_agent用于实际执行。可以推断普通 Agent 在每一轮都会被重新绑定绑定对象是每轮turn级别的临时结构而非跨轮持久化的状态——这与数据类 docstring 中 for a turn 的定位完全吻合。3.2 回合解析绑定驱动工具、审批与护栏的执行在 src/agents/run_internal/turn_resolution.py 中execute_tools_and_side_effects(bindingsbindings, ...)在执行工具与副作用工具调用、审批、护栏、交接时首先取public_agent bindings.public_agentresolve_interrupted_turn(bindingsbindings, ...)在恢复被审批中断的回合时同时取出public_agent与execution_agent并用execution_agent计算输出 schemaget_output_schema(execution_agent)get_single_step_result_from_response(bindingsbindings, ...)则以public_agent作为item_agent参与模型响应处理。同理工具规划模块 src/agents/run_internal/tool_planning.py 的_execute_tool_plan也接收bindings并从中取出public_agent执行工具计划。可以看出一个清晰的分工模式面向模型响应与用户语义的加工使用public_agent而涉及 schema 求解、真正执行步骤的环节既可能使用public_agent也可能使用execution_agent。四、沙箱场景双身份绑定的核心用武之地双身份绑定之所以存在关键在于沙箱运行时会预先改写 Agent 以注入沙箱能力但又必须保留用户对原始 Agent 的语义引用。在 src/agents/sandbox/runtime.py 的SandboxRuntime中可以看到两条绑定路径缓存命中路径当某 Agent 已按(agent, session, run_as_name)三元组缓存过准备结果时直接复用缓存的prepared_agent然后return _SandboxPreparedAgent( bindingsbind_execution_agent( public_agentcurrent_agent, execution_agentprepared_agent, ), inputprepared_input, )首次准备路径调用prepare_sandbox_agent(...)生成执行克隆绑定能力capability.bind(session)、bind_workspace_scope(...)与 run-as 身份后同样以bind_execution_agent(public_agentcurrent_agent, execution_agentprepared_agent)构造绑定。关键点在于public_agent始终是current_agent用户视角的原始 Agent而execution_agent是经prepare_sandbox_agent改写、挂载了沙箱会话与工作区作用域的克隆。这样用户配置的钩子、护栏等语义仍以原始 Agent 为准而模型调用、工具执行则发生在具备沙箱能力的克隆体上实现了语义身份与执行身份的解耦。五、测试层面的印证测试代码同样直接引用了这两个工厂函数印证了它们是面向内部使用的稳定 APItests/test_run_step_execution.py导入bind_execution_agent, bind_public_agent并以bind_public_agent(agent)构造大量bindings参数用于单步执行测试tests/test_hitl_error_scenarios.py封装了一个按条件二选一的辅助函数——需要执行克隆时用bind_execution_agent否则回退bind_public_agent直接复刻了沙箱场景的双路径决策此外 tests/test_server_conversation_tracker.py、tests/test_tool_origin.py、tests/test_run_impl_resume_paths.py、tests/test_agent_runner.py 等均在构造运行环境时使用bind_public_agent。从测试用法可以推断AgentBindings是run_internal各内部函数约定俗成的标准参数开发者如需直接调用execute_tools_and_side_effects、get_single_step_result_from_response等内部接口必须自行构造绑定对象。六、设计意义与使用要点总结维度bind_public_agentbind_execution_agent适用场景无改写执行的普通运行执行前克隆如沙箱准备的 Agent参数形式单个agent关键字参数public_agentexecution_agent双身份关系指向同一 Agent公开身份与执行克隆分离典型调用方run.py、run_loop.py、tool_execution.pysandbox/runtime.py要点归纳AgentBindings是冻结数据类绑定对象一旦构造不可修改保证一轮执行内身份引用稳定绑定对象按轮turn产生普通路径每轮通过bind_public_agent重建不跨轮持久化沙箱运行时通过bind_execution_agent将用户原始 Agent与注入能力的执行克隆打包传递是理解沙箱 Agent 能力注入机制的入口若要深入阅读相关实现建议沿着 agent_bindings.py → run_loop.py → turn_resolution.py → sandbox/runtime.py 的调用链逐层追踪。需要说明的是AgentBindings属于run_internal内部模块位于 src/agents/run_internal/ 目录其命名即表明它面向框架内部运行机制而非公开 API普通业务代码通常不需要直接使用但理解这一层抽象对于排查沙箱执行差异、编写内部工具或深入定制运行行为有直接帮助。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考