openai-agents-python 模型提供方实战指南通过 LiteLLM / any-llm 适配层与自定义 Provider 路由任意模型【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读openai-agents-python是一个轻量级的多 Agent 工作流框架其模型层默认对接 OpenAI Responses API。但在真实项目中我们往往需要把 Agent 路由到 OpenAI 之外的大模型——例如通过 OpenRouter 一把钥匙访问各家模型、通过 LiteLLM 统一接入 Anthropic / Gemini / Mistral或者对接任意 OpenAI 兼容端点。本文以 examples/model_providers/README.md 为骨架结合仓库中的示例与源码系统讲解三种接入方式直接构造适配层 ModelAnyLLMModel/LitellmModel、通过模型名前缀自动路由any-llm/.../litellm/...、以及自定义 ModelProvider 的三级控制粒度按次调用 / 按 Agent / 全局默认。读完本文你将能在不修改框架源码的前提下用一套代码无缝切换任意模型提供方。一、示例总览一条 API Key 跑通四套适配器examples/model_providers/目录下的示例全部围绕模型提供方适配这一主题默认走 OpenRouter 聚合网关因此你只需要一个OPENROUTER_API_KEYexport OPENROUTER_API_KEY...配置好密钥后直接运行四个适配器示例中的任意一个uv run examples/model_providers/any_llm_provider.py uv run examples/model_providers/any_llm_auto.py uv run examples/model_providers/litellm_provider.py uv run examples/model_providers/litellm_auto.py其中*_provider.py两个示例采用显式构造 Model 对象的接入方式*_auto.py两个示例采用模型名前缀自动路由的接入方式。所有示例都演示了带工具调用get_weather的 Agent 运行并统一使用俳句风格的指令You only respond in haikus.以方便观察输出差异。此外目录下还有三个自定义 Provider 示例custom_example_provider.py、custom_example_agent.py、custom_example_global.py覆盖从单次调用到全局默认的三种自定义接入粒度详见第五节。1.1 直接模型示例命令行覆盖目标模型any_llm_provider.py与litellm_provider.py都支持用--model参数覆盖默认模型方便你在不修改代码的情况下快速切换目标模型uv run examples/model_providers/any_llm_provider.py --model openrouter/openai/gpt-5.4-mini uv run examples/model_providers/litellm_provider.py --model openrouter/openai/gpt-5.4-mini也可切换为 Anthropic 模型如openrouter/anthropic/claude-4.5-sonnet演示 OpenRouter 上多厂商模型的自由路由。两个脚本还接受--api-key参数未显式传入时从环境变量读取。二、方式一显式构造适配层 Model2.1 使用AnyLLMModel直接接入any_llm_provider.py 演示了最直白的用法把AnyLLMModel实例直接作为Agent的model传入。from agents import Agent, Runner, set_tracing_disabled from agents.decorators import tool from agents.extensions.models.any_llm_model import AnyLLMModel set_tracing_disabled(disabledTrue) tool def get_weather(city: str): print(f[debug] getting weather for {city}) return fThe weather in {city} is sunny. async def main(model: str, api_key: str): agent Agent( nameAssistant, instructionsYou only respond in haikus., modelAnyLLMModel(modelmodel, api_keyapi_key), tools[get_weather], ) result await Runner.run(agent, Whats the weather in Tokyo?) print(result.final_output)脚本的命令行入口if __name__ __main__展示了参数解析与默认值回退逻辑这是实际可复制使用的模式parser.add_argument(--model, typestr, requiredFalse) parser.add_argument(--api-key, typestr, requiredFalse) model args.model or os.environ.get(ANY_LLM_MODEL, openrouter/openai/gpt-5.4-mini) api_key args.api_key or os.environ.get(OPENROUTER_API_KEY, dummy)即命令行参数优先其次回退到ANY_LLM_MODEL/OPENROUTER_API_KEY环境变量最后使用占位值。当 API Key 为占位值dummy时脚本会打印提示并直接跳过运行避免因缺失密钥而报错。从源码看AnyLLMModel定义于 src/agents/extensions/models/any_llm_model.py其构造签名支持四个参数参数类型说明modelstr完整模型标识如openrouter/openai/gpt-5.4-minibase_urlstr \| None可选覆盖提供方默认端点api_keystr \| None可选覆盖提供方默认密钥apiresponses \| chat_completions \| None可选指定走 Responses API 还是 Chat Completions API缺省时自动探测AnyLLMModel内部会把model字符串按第一个/拆分为提供方名 模型名_split_model_name并缓存已初始化的提供方客户端get_response/stream_response会根据所选 API 分派到_get_response_via_responses或_get_response_via_chat两条路径见 any_llm_model.py即同一套 Agent 代码既可走原生 Responses也可走 Chat Completions。需要注意的是any-llm-sdk是可选依赖未安装时会抛出明确的ImportError提示any-llm-sdk is required to use the AnyLLMModel. Install it via the optional dependency group: pip install openai-agents[any-llm]. any-llm-sdk currently requires Python 3.11.因此使用该路径前需先执行pip install openai-agents[any-llm]并确保 Python 版本为 3.11 及以上。2.2 使用LitellmModel直接接入litellm_provider.py 与上面几乎同构区别仅在于使用LitellmModel并回退到LITELLM_MODEL环境变量from agents.extensions.models.litellm_model import LitellmModel model args.model or os.environ.get(LITELLM_MODEL, openrouter/openai/gpt-5.4-mini) api_key args.api_key or os.environ.get(OPENROUTER_API_KEY, dummy) agent Agent( nameAssistant, instructionsYou only respond in haikus., modelLitellmModel(modelmodel, api_keyapi_key), tools[get_weather], )LitellmModel定义于 src/agents/extensions/models/litellm_model.py构造签名同样支持model、base_url、api_key另有一个should_replay_reasoning_content选项用于控制推理内容重放。它的依赖同样为可选组pip install openai-agents[litellm]。从源码实现看LitellmModel._fetch_response最终调用litellm.acompletion(...)并把ModelSettings中的temperature、top_p、max_tokens、tool_choice、response_format、parallel_tool_calls、reasoning_effort、top_logprobs等字段透传给 LiteLLM见 litellm_model.pyextra_headers、api_key、base_url也会一并传入ModelSettings.extra_body/extra_args则作为提供方专属参数的逃生舱口。值得注意的几点实现细节针对 Anthropic / Claude / Gemini 等要求工具调用必须先于工具结果的 API源码会执行_fix_tool_message_ordering重排消息顺序litellm_model.py针对 Gemini 的 thought signature会做extra_content→provider_specific_fields的格式转换litellm_model.py当提供方以finish_reason content_filter但空消息返回时会合成一条 refusal避免 Agent 陷入无意义的空轮重试。三、方式二模型名前缀自动路由零样板代码如果不想手动构造 Model 对象可以直接把模型名写成带前缀的字符串传给Agent由框架内置的MultiProvider根据前缀自动选择对应的 ModelProvider。这正是两个*_auto.py示例的做法也是日常使用中最简洁的接入方式。3.1any-llm/前缀自动路由any_llm_auto.py 的核心代码from pydantic import BaseModel from agents import Agent, ModelSettings, Runner, set_tracing_disabled from agents.decorators import tool class Result(BaseModel): output_text: str tool_results: list[str] async def main(): agent Agent( nameAssistant, instructionsYou only respond in haikus., modelany-llm/openrouter/openai/gpt-5.4-mini, tools[get_weather], model_settingsModelSettings(tool_choicerequired), output_typeResult, ) result await Runner.run(agent, Whats the weather in Tokyo?) print(result.final_output)模型字符串any-llm/openrouter/openai/gpt-5.4-mini中any-llm/是路由前缀openrouter/openai/gpt-5.4-mini是交给 any-llm 适配层解析的完整模型标识。脚本在入口处强制校验OPENROUTER_API_KEY环境变量未设置时直接抛出ValueError而非静默占位。该示例还演示了两个与路由机制正交的框架能力ModelSettings(tool_choicerequired)强制模型必须调用工具output_typeResult让最终输出解析为 Pydantic 结构体结构化输出与工具调用结果一起返回。3.2litellm/前缀自动路由litellm_auto.py 与上面唯一的实质差异是模型字符串# We prefix with litellm/ to tell the Runner to use the LitellmModel modellitellm/openrouter/openai/gpt-5.4-mini,注释清楚地说明litellm/前缀告诉 Runner 使用LitellmModel。其余结构Result输出类型、tool_choicerequired、OPENROUTER_API_KEY强制校验完全一致可作为同一套 Agent 代码在 any-llm 与 LiteLLM 两条适配层之间切换的直接对照样本。脚本中还保留了一段被注释的logging.basicConfig(levellogging.DEBUG)需要观察 LiteLLM 底层调用细节时可以取消注释启用。3.3 前缀路由的底层机制自动路由由 src/agents/models/multi_provider.py 中的MultiProvider实现。其默认映射规则类 docstring 明确记载为openai/前缀或无前缀→OpenAIProvider例如openai/gpt-4.1、gpt-4.1litellm/前缀 →LitellmProvider例如litellm/openai/gpt-4.1any-llm/前缀 →AnyLLMProvider例如any-llm/openrouter/openai/gpt-4.1。路由解析流程在get_model中完成multi_provider.py先按第一个/切出前缀与剩余模型名再按显式provider_map 内置litellm/any-llm回退 openai别名 未知前缀策略的顺序解析。两个值得了解的扩展点provider_map可以注入自定义的前缀 →ModelProvider映射优先级最高openai_prefix_modealias/model_id与unknown_prefix_modeerror/model_id前者决定openai/...字符串是剥掉前缀按别名处理还是保留完整字符串直通 OpenAI 兼容端点后者决定未知前缀是抛UserError还是原样透传给 OpenAI 提供方——这对openrouter/openai/gpt-4o这类命名空间化模型 ID 很有用multi_provider.py。四、参数优先级与密钥管理小结综合两个*_provider.py示例的命令行解析逻辑可以得到一套可复用的参数优先级约定优先级来源示例值1最高命令行--model/--api-keyopenrouter/anthropic/claude-4.5-sonnet2环境变量ANY_LLM_MODEL/LITELLM_MODEL/OPENROUTER_API_KEY3兜底脚本内默认值openrouter/openai/gpt-5.4-mini、dummy两个*_auto.py示例则选择更严格的策略OPENROUTER_API_KEY未设置即抛错避免带病运行。两种策略分别适用于演示友好与生产严谨两种场景可按需取舍。五、方式三自定义 ModelProvider 的三级控制粒度当 LiteLLM / any-llm 适配层仍不满足需求例如需要对接私有化的 OpenAI 兼容端点时仓库提供了三个自定义 Provider 示例对应三种控制粒度。三者都通过环境变量EXAMPLE_BASE_URL、EXAMPLE_API_KEY、EXAMPLE_MODEL_NAME配置自定义端点任一缺失即抛出ValueError提示。5.1 按次调用RunConfig(model_provider...)custom_example_provider.py 演示把自定义ModelProvider挂在某一次Runner.run调用上其他调用仍走默认提供方from openai import AsyncOpenAI from agents import Agent, Model, ModelProvider, OpenAIChatCompletionsModel, RunConfig, Runner client AsyncOpenAI(base_urlBASE_URL, api_keyAPI_KEY) class CustomModelProvider(ModelProvider): def get_model(self, model_name: str | None) - Model: return OpenAIChatCompletionsModel(modelmodel_name or MODEL_NAME, openai_clientclient) CUSTOM_MODEL_PROVIDER CustomModelProvider() async def main(): agent Agent(nameAssistant, instructionsYou only respond in haikus., tools[get_weather]) # This will use the custom model provider result await Runner.run( agent, Whats the weather in Tokyo?, run_configRunConfig(model_providerCUSTOM_MODEL_PROVIDER), ) print(result.final_output)关键点是实现ModelProvider抽象基类只需实现get_model(model_name)一个方法返回一个Model实例接口定义见 src/agents/models/interface.py。这里返回的OpenAIChatCompletionsModel配合自定义AsyncOpenAI客户端即可把 Agent 指向任意 OpenAI 兼容端点本地 vLLM、Ollama、第三方网关等。5.2 按 Agentmodel参数直接挂 Modelcustom_example_agent.py 把控制粒度缩小到单个 Agent不为整个调用链换 Provider而是让这一个 Agent 使用自定义模型其余 Agent 不受影响from agents import OpenAIChatCompletionsModel agent Agent( nameAssistant, instructionsYou only respond in haikus., modelOpenAIChatCompletionsModel(modelMODEL_NAME, openai_clientclient), tools[get_weather], )脚本注释中还给出了一个等效的备选方案用OpenAIProvider(openai_clientclient)构造 Provider配合Runner.run(..., run_configRunConfig(model_providerPROVIDER))使用。两种写法殊途同归可按代码风格偏好选择。5.3 全局默认set_default_openai_clientset_default_openai_apicustom_example_global.py 把自定义端点和 API 协议设为进程级默认之后创建的所有 Agent 无需任何额外参数即走自定义提供方from agents import ( Agent, Runner, set_default_openai_api, set_default_openai_client, set_tracing_disabled, ) client AsyncOpenAI(base_urlBASE_URL, api_keyAPI_KEY) set_default_openai_client(clientclient, use_for_tracingFalse) set_default_openai_api(chat_completions) set_tracing_disabled(disabledTrue) async def main(): agent Agent( nameAssistant, instructionsYou only respond in haikus., modelMODEL_NAME, # 普通模型名字符串即可 tools[get_weather], ) result await Runner.run(agent, Whats the weather in Tokyo?) print(result.final_output)两个全局设置的含义脚本 docstring 有明确说明set_default_openai_client(clientclient, use_for_tracingFalse)把自定义客户端设为默认 OpenAI 客户端且不用于 tracing避免把自定义端点的流量误报给平台追踪服务set_default_openai_api(chat_completions)把默认 API 协议设为 Chat Completions——因为大多数非 OpenAI 提供方尚未支持 Responses API这是接入第三方端点时的关键一步。三个自定义示例都默认调用set_tracing_disabled(disabledTrue)。注释解释这是在假设你没有 platform.openai.com API Key 的前提下关闭追踪如果你有 Key可通过设置OPENAI_API_KEY环境变量或调用set_tracing_export_api_key()单独配置追踪密钥从而保留追踪能力。六、三种接入方式的选择建议综合 README 与源码可按以下维度做技术选型接入方式代表示例适合场景代码侵入显式构造 Modelany_llm_provider.py/litellm_provider.py单个 Agent 绑定特定适配层需细粒度控制api/base_url低构造时传入前缀自动路由any_llm_auto.py/litellm_auto.py多 Agent 混用多种提供方靠模型名字符串切换最低仅改字符串自定义 Providercustom_example_{provider,agent,global}.py对接 OpenAI 兼容端点 / 私有化网关中需实现get_model实践中三者可以混用默认链路用litellm/前缀走 LiteLLM个别敏感 Agent 显式传入AnyLLMModel走另一条通道而某个只调一次的批处理任务通过RunConfig(model_provider...)指向本地端点。所有方案都不需要修改框架源码这正体现了openai-agents-python模型层接口抽象 前缀路由 适配器的可插拔设计核心接口见 src/agents/models/interface.py路由实现见 src/agents/models/multi_provider.py。七、运行前置条件Python 环境使用uv run运行示例仓库通过 pyproject.toml 与 uv.lock 管理依赖any-llm 路径额外要求 Python 3.11密钥export OPENROUTER_API_KEY...README 明确说明这是唯一必需的密钥自定义示例需要EXAMPLE_BASE_URL、EXAMPLE_API_KEY、EXAMPLE_MODEL_NAME三个环境变量可选依赖按需安装pip install openai-agents[any-llm]或pip install openai-agents[litellm]模型标识格式OpenRouter 模型形如openrouter/厂商/模型名如openrouter/openai/gpt-5.4-mini、openrouter/anthropic/claude-4.5-sonnetLiteLLM 支持的更多提供方格式可参考其官方文档但本仓库示例一律以 OpenRouter 为默认目标。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
openai-agents-python 模型提供方实战指南通过 LiteLLM / any-llm 适配层与自定义 Provider 路由任意模型【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读openai-agents-python是一个轻量级的多 Agent 工作流框架其模型层默认对接 OpenAI Responses API。但在真实项目中我们往往需要把 Agent 路由到 OpenAI 之外的大模型——例如通过 OpenRouter 一把钥匙访问各家模型、通过 LiteLLM 统一接入 Anthropic / Gemini / Mistral或者对接任意 OpenAI 兼容端点。本文以 examples/model_providers/README.md 为骨架结合仓库中的示例与源码系统讲解三种接入方式直接构造适配层 ModelAnyLLMModel/LitellmModel、通过模型名前缀自动路由any-llm/.../litellm/...、以及自定义 ModelProvider 的三级控制粒度按次调用 / 按 Agent / 全局默认。读完本文你将能在不修改框架源码的前提下用一套代码无缝切换任意模型提供方。一、示例总览一条 API Key 跑通四套适配器examples/model_providers/目录下的示例全部围绕模型提供方适配这一主题默认走 OpenRouter 聚合网关因此你只需要一个OPENROUTER_API_KEYexport OPENROUTER_API_KEY...配置好密钥后直接运行四个适配器示例中的任意一个uv run examples/model_providers/any_llm_provider.py uv run examples/model_providers/any_llm_auto.py uv run examples/model_providers/litellm_provider.py uv run examples/model_providers/litellm_auto.py其中*_provider.py两个示例采用显式构造 Model 对象的接入方式*_auto.py两个示例采用模型名前缀自动路由的接入方式。所有示例都演示了带工具调用get_weather的 Agent 运行并统一使用俳句风格的指令You only respond in haikus.以方便观察输出差异。此外目录下还有三个自定义 Provider 示例custom_example_provider.py、custom_example_agent.py、custom_example_global.py覆盖从单次调用到全局默认的三种自定义接入粒度详见第五节。1.1 直接模型示例命令行覆盖目标模型any_llm_provider.py与litellm_provider.py都支持用--model参数覆盖默认模型方便你在不修改代码的情况下快速切换目标模型uv run examples/model_providers/any_llm_provider.py --model openrouter/openai/gpt-5.4-mini uv run examples/model_providers/litellm_provider.py --model openrouter/openai/gpt-5.4-mini也可切换为 Anthropic 模型如openrouter/anthropic/claude-4.5-sonnet演示 OpenRouter 上多厂商模型的自由路由。两个脚本还接受--api-key参数未显式传入时从环境变量读取。二、方式一显式构造适配层 Model2.1 使用AnyLLMModel直接接入any_llm_provider.py 演示了最直白的用法把AnyLLMModel实例直接作为Agent的model传入。from agents import Agent, Runner, set_tracing_disabled from agents.decorators import tool from agents.extensions.models.any_llm_model import AnyLLMModel set_tracing_disabled(disabledTrue) tool def get_weather(city: str): print(f[debug] getting weather for {city}) return fThe weather in {city} is sunny. async def main(model: str, api_key: str): agent Agent( nameAssistant, instructionsYou only respond in haikus., modelAnyLLMModel(modelmodel, api_keyapi_key), tools[get_weather], ) result await Runner.run(agent, Whats the weather in Tokyo?) print(result.final_output)脚本的命令行入口if __name__ __main__展示了参数解析与默认值回退逻辑这是实际可复制使用的模式parser.add_argument(--model, typestr, requiredFalse) parser.add_argument(--api-key, typestr, requiredFalse) model args.model or os.environ.get(ANY_LLM_MODEL, openrouter/openai/gpt-5.4-mini) api_key args.api_key or os.environ.get(OPENROUTER_API_KEY, dummy)即命令行参数优先其次回退到ANY_LLM_MODEL/OPENROUTER_API_KEY环境变量最后使用占位值。当 API Key 为占位值dummy时脚本会打印提示并直接跳过运行避免因缺失密钥而报错。从源码看AnyLLMModel定义于 src/agents/extensions/models/any_llm_model.py其构造签名支持四个参数参数类型说明modelstr完整模型标识如openrouter/openai/gpt-5.4-minibase_urlstr \| None可选覆盖提供方默认端点api_keystr \| None可选覆盖提供方默认密钥apiresponses \| chat_completions \| None可选指定走 Responses API 还是 Chat Completions API缺省时自动探测AnyLLMModel内部会把model字符串按第一个/拆分为提供方名 模型名_split_model_name并缓存已初始化的提供方客户端get_response/stream_response会根据所选 API 分派到_get_response_via_responses或_get_response_via_chat两条路径见 any_llm_model.py即同一套 Agent 代码既可走原生 Responses也可走 Chat Completions。需要注意的是any-llm-sdk是可选依赖未安装时会抛出明确的ImportError提示any-llm-sdk is required to use the AnyLLMModel. Install it via the optional dependency group: pip install openai-agents[any-llm]. any-llm-sdk currently requires Python 3.11.因此使用该路径前需先执行pip install openai-agents[any-llm]并确保 Python 版本为 3.11 及以上。2.2 使用LitellmModel直接接入litellm_provider.py 与上面几乎同构区别仅在于使用LitellmModel并回退到LITELLM_MODEL环境变量from agents.extensions.models.litellm_model import LitellmModel model args.model or os.environ.get(LITELLM_MODEL, openrouter/openai/gpt-5.4-mini) api_key args.api_key or os.environ.get(OPENROUTER_API_KEY, dummy) agent Agent( nameAssistant, instructionsYou only respond in haikus., modelLitellmModel(modelmodel, api_keyapi_key), tools[get_weather], )LitellmModel定义于 src/agents/extensions/models/litellm_model.py构造签名同样支持model、base_url、api_key另有一个should_replay_reasoning_content选项用于控制推理内容重放。它的依赖同样为可选组pip install openai-agents[litellm]。从源码实现看LitellmModel._fetch_response最终调用litellm.acompletion(...)并把ModelSettings中的temperature、top_p、max_tokens、tool_choice、response_format、parallel_tool_calls、reasoning_effort、top_logprobs等字段透传给 LiteLLM见 litellm_model.pyextra_headers、api_key、base_url也会一并传入ModelSettings.extra_body/extra_args则作为提供方专属参数的逃生舱口。值得注意的几点实现细节针对 Anthropic / Claude / Gemini 等要求工具调用必须先于工具结果的 API源码会执行_fix_tool_message_ordering重排消息顺序litellm_model.py针对 Gemini 的 thought signature会做extra_content→provider_specific_fields的格式转换litellm_model.py当提供方以finish_reason content_filter但空消息返回时会合成一条 refusal避免 Agent 陷入无意义的空轮重试。三、方式二模型名前缀自动路由零样板代码如果不想手动构造 Model 对象可以直接把模型名写成带前缀的字符串传给Agent由框架内置的MultiProvider根据前缀自动选择对应的 ModelProvider。这正是两个*_auto.py示例的做法也是日常使用中最简洁的接入方式。3.1any-llm/前缀自动路由any_llm_auto.py 的核心代码from pydantic import BaseModel from agents import Agent, ModelSettings, Runner, set_tracing_disabled from agents.decorators import tool class Result(BaseModel): output_text: str tool_results: list[str] async def main(): agent Agent( nameAssistant, instructionsYou only respond in haikus., modelany-llm/openrouter/openai/gpt-5.4-mini, tools[get_weather], model_settingsModelSettings(tool_choicerequired), output_typeResult, ) result await Runner.run(agent, Whats the weather in Tokyo?) print(result.final_output)模型字符串any-llm/openrouter/openai/gpt-5.4-mini中any-llm/是路由前缀openrouter/openai/gpt-5.4-mini是交给 any-llm 适配层解析的完整模型标识。脚本在入口处强制校验OPENROUTER_API_KEY环境变量未设置时直接抛出ValueError而非静默占位。该示例还演示了两个与路由机制正交的框架能力ModelSettings(tool_choicerequired)强制模型必须调用工具output_typeResult让最终输出解析为 Pydantic 结构体结构化输出与工具调用结果一起返回。3.2litellm/前缀自动路由litellm_auto.py 与上面唯一的实质差异是模型字符串# We prefix with litellm/ to tell the Runner to use the LitellmModel modellitellm/openrouter/openai/gpt-5.4-mini,注释清楚地说明litellm/前缀告诉 Runner 使用LitellmModel。其余结构Result输出类型、tool_choicerequired、OPENROUTER_API_KEY强制校验完全一致可作为同一套 Agent 代码在 any-llm 与 LiteLLM 两条适配层之间切换的直接对照样本。脚本中还保留了一段被注释的logging.basicConfig(levellogging.DEBUG)需要观察 LiteLLM 底层调用细节时可以取消注释启用。3.3 前缀路由的底层机制自动路由由 src/agents/models/multi_provider.py 中的MultiProvider实现。其默认映射规则类 docstring 明确记载为openai/前缀或无前缀→OpenAIProvider例如openai/gpt-4.1、gpt-4.1litellm/前缀 →LitellmProvider例如litellm/openai/gpt-4.1any-llm/前缀 →AnyLLMProvider例如any-llm/openrouter/openai/gpt-4.1。路由解析流程在get_model中完成multi_provider.py先按第一个/切出前缀与剩余模型名再按显式provider_map 内置litellm/any-llm回退 openai别名 未知前缀策略的顺序解析。两个值得了解的扩展点provider_map可以注入自定义的前缀 →ModelProvider映射优先级最高openai_prefix_modealias/model_id与unknown_prefix_modeerror/model_id前者决定openai/...字符串是剥掉前缀按别名处理还是保留完整字符串直通 OpenAI 兼容端点后者决定未知前缀是抛UserError还是原样透传给 OpenAI 提供方——这对openrouter/openai/gpt-4o这类命名空间化模型 ID 很有用multi_provider.py。四、参数优先级与密钥管理小结综合两个*_provider.py示例的命令行解析逻辑可以得到一套可复用的参数优先级约定优先级来源示例值1最高命令行--model/--api-keyopenrouter/anthropic/claude-4.5-sonnet2环境变量ANY_LLM_MODEL/LITELLM_MODEL/OPENROUTER_API_KEY3兜底脚本内默认值openrouter/openai/gpt-5.4-mini、dummy两个*_auto.py示例则选择更严格的策略OPENROUTER_API_KEY未设置即抛错避免带病运行。两种策略分别适用于演示友好与生产严谨两种场景可按需取舍。五、方式三自定义 ModelProvider 的三级控制粒度当 LiteLLM / any-llm 适配层仍不满足需求例如需要对接私有化的 OpenAI 兼容端点时仓库提供了三个自定义 Provider 示例对应三种控制粒度。三者都通过环境变量EXAMPLE_BASE_URL、EXAMPLE_API_KEY、EXAMPLE_MODEL_NAME配置自定义端点任一缺失即抛出ValueError提示。5.1 按次调用RunConfig(model_provider...)custom_example_provider.py 演示把自定义ModelProvider挂在某一次Runner.run调用上其他调用仍走默认提供方from openai import AsyncOpenAI from agents import Agent, Model, ModelProvider, OpenAIChatCompletionsModel, RunConfig, Runner client AsyncOpenAI(base_urlBASE_URL, api_keyAPI_KEY) class CustomModelProvider(ModelProvider): def get_model(self, model_name: str | None) - Model: return OpenAIChatCompletionsModel(modelmodel_name or MODEL_NAME, openai_clientclient) CUSTOM_MODEL_PROVIDER CustomModelProvider() async def main(): agent Agent(nameAssistant, instructionsYou only respond in haikus., tools[get_weather]) # This will use the custom model provider result await Runner.run( agent, Whats the weather in Tokyo?, run_configRunConfig(model_providerCUSTOM_MODEL_PROVIDER), ) print(result.final_output)关键点是实现ModelProvider抽象基类只需实现get_model(model_name)一个方法返回一个Model实例接口定义见 src/agents/models/interface.py。这里返回的OpenAIChatCompletionsModel配合自定义AsyncOpenAI客户端即可把 Agent 指向任意 OpenAI 兼容端点本地 vLLM、Ollama、第三方网关等。5.2 按 Agentmodel参数直接挂 Modelcustom_example_agent.py 把控制粒度缩小到单个 Agent不为整个调用链换 Provider而是让这一个 Agent 使用自定义模型其余 Agent 不受影响from agents import OpenAIChatCompletionsModel agent Agent( nameAssistant, instructionsYou only respond in haikus., modelOpenAIChatCompletionsModel(modelMODEL_NAME, openai_clientclient), tools[get_weather], )脚本注释中还给出了一个等效的备选方案用OpenAIProvider(openai_clientclient)构造 Provider配合Runner.run(..., run_configRunConfig(model_providerPROVIDER))使用。两种写法殊途同归可按代码风格偏好选择。5.3 全局默认set_default_openai_clientset_default_openai_apicustom_example_global.py 把自定义端点和 API 协议设为进程级默认之后创建的所有 Agent 无需任何额外参数即走自定义提供方from agents import ( Agent, Runner, set_default_openai_api, set_default_openai_client, set_tracing_disabled, ) client AsyncOpenAI(base_urlBASE_URL, api_keyAPI_KEY) set_default_openai_client(clientclient, use_for_tracingFalse) set_default_openai_api(chat_completions) set_tracing_disabled(disabledTrue) async def main(): agent Agent( nameAssistant, instructionsYou only respond in haikus., modelMODEL_NAME, # 普通模型名字符串即可 tools[get_weather], ) result await Runner.run(agent, Whats the weather in Tokyo?) print(result.final_output)两个全局设置的含义脚本 docstring 有明确说明set_default_openai_client(clientclient, use_for_tracingFalse)把自定义客户端设为默认 OpenAI 客户端且不用于 tracing避免把自定义端点的流量误报给平台追踪服务set_default_openai_api(chat_completions)把默认 API 协议设为 Chat Completions——因为大多数非 OpenAI 提供方尚未支持 Responses API这是接入第三方端点时的关键一步。三个自定义示例都默认调用set_tracing_disabled(disabledTrue)。注释解释这是在假设你没有 platform.openai.com API Key 的前提下关闭追踪如果你有 Key可通过设置OPENAI_API_KEY环境变量或调用set_tracing_export_api_key()单独配置追踪密钥从而保留追踪能力。六、三种接入方式的选择建议综合 README 与源码可按以下维度做技术选型接入方式代表示例适合场景代码侵入显式构造 Modelany_llm_provider.py/litellm_provider.py单个 Agent 绑定特定适配层需细粒度控制api/base_url低构造时传入前缀自动路由any_llm_auto.py/litellm_auto.py多 Agent 混用多种提供方靠模型名字符串切换最低仅改字符串自定义 Providercustom_example_{provider,agent,global}.py对接 OpenAI 兼容端点 / 私有化网关中需实现get_model实践中三者可以混用默认链路用litellm/前缀走 LiteLLM个别敏感 Agent 显式传入AnyLLMModel走另一条通道而某个只调一次的批处理任务通过RunConfig(model_provider...)指向本地端点。所有方案都不需要修改框架源码这正体现了openai-agents-python模型层接口抽象 前缀路由 适配器的可插拔设计核心接口见 src/agents/models/interface.py路由实现见 src/agents/models/multi_provider.py。七、运行前置条件Python 环境使用uv run运行示例仓库通过 pyproject.toml 与 uv.lock 管理依赖any-llm 路径额外要求 Python 3.11密钥export OPENROUTER_API_KEY...README 明确说明这是唯一必需的密钥自定义示例需要EXAMPLE_BASE_URL、EXAMPLE_API_KEY、EXAMPLE_MODEL_NAME三个环境变量可选依赖按需安装pip install openai-agents[any-llm]或pip install openai-agents[litellm]模型标识格式OpenRouter 模型形如openrouter/厂商/模型名如openrouter/openai/gpt-5.4-mini、openrouter/anthropic/claude-4.5-sonnetLiteLLM 支持的更多提供方格式可参考其官方文档但本仓库示例一律以 OpenRouter 为默认目标。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
