openai-agents-python 通过 LiteLLM 接入任意大模型LitellmModel 适配器完整指南【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonopenai-agents-python官方内置的Model实现面向 OpenAI 的 Responses API 与 Chat Completions API而 docs/ref/extensions/models/litellm_model.md 这一参考文档mkdocstrings 自动生成的模块引用桩所指向的LitellmModel则是把 OpenAI、Anthropic、Gemini、Mistral 以及大量第三方兼容端点统一收敛到同一套 Agent 编排管线中的适配器。本文以该模块为主体结合 docs/models/index.md 中 Third-party adapters 章节、examples/model_providers/ 下的可运行示例与 tests/models/ 中的测试完整讲解 LiteLLM 适配器的安装、三种接入方式、构造参数、ModelSettings对接、供应商特化处理、流式与重试机制及其边界限制读完即可在真实项目中落地一套代码、任意模型的混合多供应商工作流。一、LitellmModel 是什么一个标准的 Model 适配器实现LitellmModel继承自 SDK 的Model接口实现了get_response()、stream_response()与get_retry_advice()三个核心方法因此对Runner、Agent、工具调用、Guardrail 等上层机制完全透明——它本质上是一个把 SDK 内部表示翻译成 LiteLLM Chat Completions 请求、再把 LiteLLM 响应翻译回 SDKModelResponse的转换层。从源码 docstring 可以确认其定位src/agents/extensions/models/litellm_model.pyThis class enables using any model via LiteLLM. LiteLLM allows you to access OpenAI, Anthropic, Gemini, Mistral, and many other models.在项目文档中LiteLLM 与 Any-LLM 并列被标注为best-effort、beta 级别的第三方适配器docs/models/index.md如果只使用 OpenAI 模型应优先走内置的OpenAIResponsesModel路径而不是 LiteLLM只有在需要OpenAI 模型 非 OpenAI 供应商混用、或需要 LiteLLM 提供的供应商覆盖与路由能力时才使用本适配器适配器相当于在 SDK 与上游模型供应商之间又加了一层兼容层因此具体功能的支持程度随供应商而异上线前必须针对目标供应商做验证。二、安装与前置准备litellm属于可选依赖组未安装时导入模块会直接抛出带提示的ImportErrorsrc/agents/extensions/models/litellm_model.pypip install openai-agents[litellm]运行前还需要注意以下几点API Key 一律通过环境变量提供。LitellmProvider的 docstring 明确说明API Key 必须通过环境变量设置若模型需要额外配置如 Azure 的base与version也必须设置 LiteLLM 期望的环境变量src/agents/extensions/models/litellm_provider.py。无 OpenAI Key 时关闭 tracing。非 OpenAI 场景下建议调用set_tracing_disabled(disabledTrue)或配置自定义 tracing processor否则默认会把 trace 上传到 OpenAI 服务器而报 401。部分供应商默认不返回 usage。文档建议按需传ModelSettings(include_usageTrue)docs/models/index.md。三、三种接入方式3.1 使用litellm/前缀模型名最省事在Agent(model...)中直接写litellm/前缀的模型名Runner 会自动解析为LitellmModel。完整可运行示例见 examples/model_providers/litellm_auto.pyimport asyncio from pydantic import BaseModel from agents import Agent, ModelSettings, Runner, set_tracing_disabled from agents.decorators import tool set_tracing_disabled(disabledTrue) tool def get_weather(city: str): return fThe weather in {city} is sunny. class Result(BaseModel): output_text: str tool_results: list[str] async def main(): agent Agent( nameAssistant, instructionsYou only respond in haikus., # 前缀 litellm/ 告诉 Runner 使用 LitellmModel modellitellm/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) if __name__ __main__: asyncio.run(main())该示例通过 OpenRouter 路由运行前需设置OPENROUTER_API_KEY。模型名litellm/openrouter/openai/gpt-5.4-mini是 LiteLLM 的标准三段式命名供应商/模型LiteLLM 会根据模型名自动选择正确的 SDK 与端点格式。3.2 使用LitellmProvider作用于单次 RunLitellmProvider实现了ModelProvider接口适用于本次运行中的所有 Agent 统一走 LiteLLM的场景src/agents/extensions/models/litellm_provider.pyfrom agents import Agent, Runner, RunConfig from agents.extensions.models.litellm_provider import LitellmProvider agent Agent(nameAssistant, instructionsBe concise.) result await Runner.run( agent, Hello, run_configRunConfig(model_providerLitellmProvider()), )其内部实现极其简单get_model(model_name)直接返回LitellmModel(model_name or get_default_model())——未传模型名时回落到 SDK 的默认模型。模块中还保留了向后兼容的DEFAULT_MODEL gpt-4.1常量但注释建议优先使用get_default_model()。3.3 直接实例化LitellmModel最灵活当需要为不同 Agent 绑定不同供应商或需要显式传入base_url/api_key时直接构造模型对象并赋给Agent.model。完整示例见 examples/model_providers/litellm_provider.pyimport asyncio, os from agents import Agent, Runner, set_tracing_disabled from agents.decorators import tool from agents.extensions.models.litellm_model import LitellmModel set_tracing_disabled(disabledTrue) tool def get_weather(city: str): return fThe weather in {city} is sunny. async def main(model: str, api_key: str): agent Agent( nameAssistant, instructionsYou only respond in haikus., modelLitellmModel(modelmodel, api_keyapi_key), tools[get_weather], ) result await Runner.run(agent, Whats the weather in Tokyo?) print(result.final_output) if __name__ __main__: model os.environ.get(LITELLM_MODEL, openrouter/openai/gpt-5.4-mini) api_key os.environ.get(OPENROUTER_API_KEY, dummy) asyncio.run(main(model, api_key))命令行可直接运行uv run examples/model_providers/litellm_provider.py --model openrouter/anthropic/claude-4.5-sonnet。四、构造函数参数详解LitellmModel.__init__只接收四个参数src/agents/extensions/models/litellm_model.py参数类型说明modelstrLiteLLM 模型标识符如openrouter/openai/gpt-5.4-mini、anthropic/claude-4.5-sonnet格式取决于 LiteLLM 的供应商命名base_urlstr \| None自定义端点地址直接透传给litellm.acompletion(base_url...)适用于 OpenAI 兼容网关或自建代理api_keystr \| None显式 API Key优先于环境变量透传给 LiteLLMshould_replay_reasoning_contentShouldReplayReasoningContent \| None回调控制对话历史中推理内容reasoning content是否在后续请求中重放透传给消息转换器litellm_model.py注意LitellmModel的get_response()/stream_response()签名中previous_response_id与conversation_id参数标注为 unused——这是 Chat Completions 路径的固有限制Responses API 专属的状态续接能力在此不可用。五、与 ModelSettings 的完整对接LitellmModel._fetch_response()会把ModelSettings中的字段逐一映射到litellm.acompletion()的具名参数src/agents/extensions/models/litellm_model.pyModelSettings 字段透传目标备注temperature/top_pacompletion(temperature..., top_p...)采样控制frequency_penalty/presence_penalty同名参数频率/存在惩罚max_tokensmax_tokens输出上限tool_choicetool_choice经Converter.convert_tool_choice转换omit/NotGiven会被归一为Noneparallel_tool_callsparallel_tool_calls仅当存在已转换工具时才发送top_logprobstop_logprobs 自动补logprobsTrueChat Completions 要求设置logprobsTrue时top_logprobs才生效若用户已在extra_args中显式传logprobs则不覆盖避免重复键冲突include_usage流式时构造stream_options{include_usage: ...}控制流式响应的 usage chunkextra_bodyextra_body深拷贝供应商级请求体扩展若同时解析出reasoning_effort会先从其中弹出避免重复extra_args直接展开为acompletion的 kwargs过滤None值reasoning_effort会被弹出因为已提升为顶层参数extra_headers合并进请求头合并顺序SDK 默认头 →extra_headers→ 全局覆盖头litellm_model.pyextra_query/metadataextra_query/metadata深拷贝后透传reasoning.effort顶层reasoning_effort见下方说明timeout由外层 Runner 统一实施每次模型调用尝试的完整超时reasoning_effort 的解析优先级_get_reasoning_effort()按以下优先级解析litellm_model.pymodel_settings.reasoning.effort最高优先级model_settings.extra_body[reasoning_effort]model_settings.extra_args[reasoning_effort]。同时注意LiteLLM 的 Chat Completions 路径不会转发Reasoning.summary设置后会打印 warning 并忽略仅传递reasoning_effort。reasoning.effort支持非 OpenAI 兼容取值如none可通过上述 escape hatch 传入。另外两个值得注意的实现细节MCP 代理处理当存在已转换工具时_fetch_response会设置_skip_mcp_handlerTrue因为 SDK 工具已被转换为普通 function tool若让 LiteLLM 代理侧再做 MCP 发现会引入未处理的服务器依赖litellm_model.py。Runner 重试接管当 SDK 的 runner-managed retry 启用时should_disable_provider_managed_retries()返回 True会强制num_retries0、max_retries0把 LiteLLM 自带的供应商重试关掉保证重试只发生在 Runner 层litellm_model.py。六、请求构造与响应转换的底层实现6.1 消息与工具转换get_response()内部调用_fetch_response()核心流程litellm_model.pyConverter.items_to_messages(input, ...)把 SDK 的TResponseInputItem列表转换为 Chat Completions 消息开启 reasoning 时设置preserve_thinking_blocksTrue以支持 Claude 4 Sonnet/Opus 这类交错思维模型的思维块保留system_instructions以{role: system}插入到消息最前tool_choice与response_format结构化输出分别经Converter.convert_tool_choice/convert_response_format转换Agent 的tools与handoffs全部经Converter.tool_to_openai/Converter.convert_handoff_tool归一为 function tool 格式最终调用litellm.acompletion(...)非流式返回litellm.types.utils.ModelResponse流式返回(Response, AsyncStream[ChatCompletionChunk])。调试日志在未设置_debug.DONT_LOG_MODEL_DATA时会完整打印模型名、消息、工具与响应 JSON便于排查litellm_model.py。6.2 响应处理usage、拒绝与 logprobs拿到 LiteLLM 响应后适配器做了三件重要的事usage 统计从response.usage提取prompt_tokens/completion_tokens/total_tokens并进一步解析cached_tokens、cache_write_tokens提示词缓存与reasoning_tokens供应商未返回 usage 时仅计Usage(requests1)并打印 warningNo usage information returned from Litellmlitellm_model.py。content_filter 拒绝合成部分供应商如 Amazon Bedrock 上的 Anthropic安全拦截时只给finish_reason content_filter且消息为空若不处理会导致 Agent 循环空转重试。适配器会合成一条refusal消息写入provider_specific_fields从而触发 SDK 下游的ResponseOutputRefusal处理litellm_model.py。logprobs 附加当choice_logprobs.content存在时转换为ResponseOutputText.logprobs并附加到输出消息litellm_model.py。6.3 LitellmConverterLiteLLM 消息 → OpenAI 消息LitellmConverter.convert_message_to_openai()负责把litellm.types.utils.Message转换为 SDK 内部使用的InternalChatCompletionMessagelitellm_model.py要点包括非assistant角色直接抛ModelBehaviorError透传content、refusal来自provider_specific_fields、audio、annotationsURL 引用标注reasoning_content与thinking_blocks作为额外字段携带兼容 DeepSeek 与 Anthropic 的推理内容thinking_blocks支持 dict、__dict__对象、model_dump()对象三种形态的归一化工具调用经convert_tool_call_to_openai转换其中对 Gemini 模型会清理 LiteLLM 在tool_call.id后追加的__thought__后缀litellm_model.py并把provider_specific_fields中的 Geminithought_signature转换回extra_content{google: {...}}内部格式。七、流式输出机制stream_response()通过ChatCmplStreamHandler.handle_stream()消费 LiteLLM 流式 chunk向上层产出 SDK 的TResponseStreamEventlitellm_model.py。三个值得关注的细节span 填充时机在 yieldresponse.completed终止事件之前就填充 generation span 的 usage——因为调用方可能在收到终止事件后立即关闭生成器导致 span 永远没有 usage 数据litellm_model.py取消安全关闭收到asyncio.CancelledError时把流关闭任务调度到后台执行并重新抛出避免aclose()半途被中断正常结束时用asyncio.shield保护关闭任务防止重复关闭不可幂等的供应商流litellm_model.py流式调用同样要求include_usage通过stream_options传递测试覆盖见 tests/models/test_litellm_chatcompletions_stream.py。八、供应商特化适配Anthropic / Gemini这是适配器最有价值的部分针对不同供应商的协议差异做了显式处理8.1 工具消息排序修正Anthropic 与 Vertex AI Gemini 严格要求 conversation 历史中tool_use必须紧跟在对应的tool_result之前。_fix_tool_message_ordering()会把多工具调用的 assistant 消息按tool_call_id拆分为单条消息仅第一条保留文本/思维块/推理内容避免重复携带带签名的 thinking blocks 被 Anthropic 拒绝将tool_use → tool_result配对重排未匹配的 tool result 单独保留避免重复litellm_model.py。该逻辑仅当模型名包含anthropic、claude或gemini时启用。8.2 Gemini thought signatures 双向转换出站_convert_gemini_extra_content_to_provider_specific_fields()把内部格式extra_content{google: {thought_signature: ...}}转换为 LiteLLM 的provider_specific_fields{thought_signature: ...}仅处理最后一个 user 消息之后的 assistant 工具调用无有效签名时使用skip_thought_signature_validator占位litellm_model.py入站convert_tool_call_to_openai()反方向把thought_signature还原进extra_content供 Agent 工具调用上下文使用。配套测试包括 tests/models/test_gemini_thought_signatures.py、tests/models/test_gemini_thought_signatures_stream.py 与 tests/models/test_extended_thinking_message_order.py。8.3 推理内容保留与重放消息转换时通过preserve_thinking_blocks保留 Claude 4 系列的交错思维块should_replay_reasoning_content回调控制历史推理内容的重放策略相关行为由 tests/models/test_reasoning_content_replay_hook.py 与 tests/models/test_anthropic_thinking_blocks.py 覆盖。DeepSeek 等模型的reasoning_content处理见 tests/models/test_deepseek_reasoning_content.py。九、重试与错误处理LitellmModel.get_retry_advice()直接复用get_openai_retry_advice()litellm_model.py——因为 LiteLLM 的异常镜像了 OpenAI 风格的status/header字段可以复用同一套归一化逻辑提取retry-after与显式的重试/不重试提示。当启用 Runner 层重试时适配器会关闭 LiteLLM 自身的重试旋钮num_retries0、max_retries0把重试决策完全交给 SDK 的ModelRetrySettings与retry_policies。LiteLLM 场景的重试配置示例见 examples/basic/retry_litellm.pyprovider_suggested()策略会优先采纳来自本适配器的重试建议。十、已知限制与注意事项限制说明与应对usage 可能缺失部分经 LiteLLM 访问的供应商不填充 usage 指标需要用量统计时传ModelSettings(include_usageTrue)并对目标供应商后端单独验证结构化输出能力差异部分供应商只支持json_object而不支持json_schema可能报response_format.type : value is not one of the allowed values [text,json_object]文档建议优先选择支持 JSON Schema 输出的供应商否则易产出畸形 JSONbeta 状态LiteLLM 集成属于 best-effort beta功能支持与请求语义随供应商而异上线前需验证结构化输出、工具调用、用量上报与路由行为无 Responses API 状态续接previous_response_id/conversation_id在适配器中 unusedLiteLLM 序列化告警补丁若 LiteLLM 对响应对象发出 Pydantic serializer 警告可在导入适配器前设置export OPENAI_AGENTS_ENABLE_LITELLM_SERIALIZER_PATCHtrue开启 SDK 的兼容补丁补丁默认关闭、仅对1/true生效且依赖 LiteLLM 的私有日志辅助函数升级 LiteLLM 后需重新验证litellm_model.py禁用跟踪无 OpenAI Key 时应set_tracing_disabled(True)或配置自定义 trace processor十一、测试与验证路径适配器行为在仓库中有充分的测试保障可按需查阅用量tests/models/test_litellm_usage_requests.pyextra_body / kwargs 透传tests/models/test_litellm_extra_body.py、tests/models/test_kwargs_functionality.py流式tests/models/test_litellm_chatcompletions_stream.pylogprobstests/models/test_litellm_logprobs.py内容过滤拒绝tests/models/test_litellm_content_filter.py序列化补丁tests/models/test_litellm_logging_patch.pyUser-Agenttests/models/test_litellm_user_agent.py供应商特化tests/models/test_anthropic_thinking_blocks.py、tests/models/test_gemini_thought_signatures.py等需要系统化了解适配器在整条模型选型路径中的位置时可对照 docs/models/index.md 的 Third-party adapters 章节参考文档 docs/ref/extensions/models/litellm_model.md 本身由 docs/scripts/generate_ref_files.py 生成内容即本模块的 API 文档。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考