Claude Agent SDK 接入 LiteLLM 网关通过单一代理调用任意 LLM 的实战指南【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm本文基于仓库中 cookbook/anthropic_agent_sdk 示例讲解如何把 Anthropic 的 Claude Agent SDK 指向 LiteLLM 网关让 Agent 对话不再绑定 Anthropic 直连而是通过ANTHROPIC_BASE_URL环境变量走 LiteLLM 代理从而在同一个 Agent 代码里切换 Bedrock、OpenAI、Azure 等任意模型并获得成本追踪、限流与负载均衡等网关能力。读完本文你将掌握LiteLLM 代理的启动与多模型配置、Agent SDK 的环境变量重定向原理、MCPModel Context Protocol服务器通过 HTTP 接入网关的完整配置以及交互式终端里的模型切换命令。整体思路用 ANTHROPIC_BASE_URL 把 Agent SDK 指向网关Claude Agent SDK 的客户端默认直连 Anthropic API。接入 LiteLLM 的关键只有两步把ANTHROPIC_BASE_URL指向 LiteLLM 代理地址把ANTHROPIC_API_KEY填成 LiteLLM 的 API key。LiteLLM 代理实现了 Anthropic 消息接口Anthropic Messages 兼容端点因此 SDK 发出的请求无需任何代码改造即可被网关识别和路由。示例代码中的核心逻辑如下# 指向 LiteLLM 网关而不是直连 Anthropic os.environ[ANTHROPIC_BASE_URL] http://localhost:4000 os.environ[ANTHROPIC_API_KEY] sk-1234 # 你的 LiteLLM key # 使用 LiteLLM 里配置的任意模型 options ClaudeAgentOptions( modelbedrock-claude-sonnet-4, # 也可以是 gpt-4 或任意其他模型 system_promptYou are a helpful assistant., max_turns50, )对应实现见 common.py 中的setup_litellm_env函数它先对代理地址做rstrip(/)规范化然后写入上述两个环境变量。需要注意 README 特别提醒的一点不要在 base URL 后加/anthropic之类的路径后缀——LiteLLM 会自行处理路由多拼路径反而会导致 404。快速开始1. 安装依赖pip install anthropic claude-agent-sdk litellm依赖清单 requirements.txt 里实际声明的是claude-agent-sdk和httpx0.27.0——前者提供ClaudeSDKClient、ClaudeAgentOptions等核心类后者用于示例脚本直连代理的/models端点拉取可用模型列表。2. 启动 LiteLLM 代理最简方式直接用 Claude 模型启动litellm --model claude-sonnet-4-20250514或者使用配置文件启动多模型网关litellm --config config.yaml3. 运行 Agent基础 Agent无 MCPpython main.py带 MCP 的 Agent接入 DeepWiki2 用于研究检索python agent_with_mcp.py如果 MCP 连接失败可以用环境变量关闭 MCP 降级运行USE_MCPfalse python agent_with_mcp.py启动后即可在终端与 Agent 对话。USE_MCP的读取逻辑在 agent_with_mcp.py默认值为trueMCP 服务器地址被拼接为{litellm_base_url}/mcp/deepwiki2即通过 LiteLLM 网关暴露的 MCP 端点访问而不是直连 DeepWiki。配置环境变量与默认值common.py 中的Config类定义了三个可配置项全部支持环境变量覆盖不设置时使用默认值环境变量默认值说明LITELLM_PROXY_URLhttp://localhost:4000LiteLLM 代理地址LITELLM_API_KEYsk-1234LiteLLM 的 master key 或虚拟 keyLITELLM_MODELbedrock-claude-sonnet-4.5模型名必须是 LiteLLM 配置中存在的model_nameexport LITELLM_PROXY_URLhttp://localhost:4000 export LITELLM_API_KEYsk-1234 export LITELLM_MODELbedrock-claude-sonnet-4.5其中默认 keysk-1234与仓库根目录 proxy_server_config.yaml 及 litellm/proxy/proxy_config.yaml 中general_settings.master_key的示例值一致即代理未显式配置密钥时的本地默认值。多模型代理配置config.yaml 详解示例配置 config.example.yaml 展示了如何通过model_list在同一个代理上挂载多个模型别名model_list: - model_name: bedrock-claude-sonnet-3.5 litellm_params: model: bedrock/us.anthropic.claude-3-5-sonnet-20240620-v1:0 aws_region_name: us-east-1 - model_name: bedrock-claude-sonnet-4 litellm_params: model: bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0 aws_region_name: us-east-1 - model_name: bedrock-claude-sonnet-4.5 litellm_params: model: bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0 aws_region_name: us-east-1 - model_name: bedrock-claude-opus-4.5 litellm_params: model: bedrock/us.anthropic.claude-opus-4-5-20251101-v1:0 aws_region_name: us-east-1 - model_name: bedrock-nova-premier litellm_params: model: bedrock/amazon.nova-premier-v1:0 aws_region_name: us-east-1每个条目的model_name是对 Agent 可见的别名litellm_params.model是 LiteLLM 内部使用的真实模型标识这里是 Bedrock 的完整模型 IDaws_region_name指定 Bedrock 区域。Agent 侧只需使用别名例如LITELLM_MODELbedrock-claude-sonnet-4.5。创建好config.yaml后以litellm --config config.yaml启动即可。同一文件结构在仓库的 litellm/proxy/proxy_config.yaml 中也有体现该文件还示范了 MCP 服务器与网关的集成配置# MCP Server Configuration mcp_servers: # Wikipedia MCP - reliable and works without external deps wikipedia: transport: stdio command: uvx args: [mcp-server-fetch] description: Fetch web pages and Wikipedia content deepwiki: transport: http url: https://mcp.deepwiki.com/mcp可以看到 MCP 服务器支持两种 transport本地stdio通过uvx等命令拉起和http直连远端 MCP 服务。Agent 示例中访问的/mcp/deepwiki2端点正是网关把已注册的 HTTP MCP 服务器暴露给客户端的通道。交互式聊天核心实现与对话命令基础版 main.py 的执行流程main.py 的主循环逻辑为通过Config()读取配置setup_litellm_env(config)重定向 Anthropic 环境变量调用fetch_available_models()从代理的/models端点拉取当前配置的模型列表每轮对话创建ClaudeAgentOptionsmax_turns50和ClaudeSDKClient上下文逐行读取用户输入识别命令后分发普通消息则交给stream_response()流式输出。模型列表的获取在 common.py 中实现用httpx.AsyncClient以 Bearer 鉴权请求{base_url}/models解析返回的data[].id数组。如果请求失败代理未启动或 key 错误会打印警告并降级到一份内置的默认模型列表保证 CLI 不会因此无法启动——这是一个值得借鉴的容错设计。流式输出部分stream_response通过client.query(user_input)发起查询再迭代client.receive_response()逐块处理content_block_delta增量文本与content_block_start内容块起始两类消息并即时打印最后对content字段做了兜底处理。对话命令聊天过程中支持以下命令实现在 main.py 与 common.pymodels— 列出所有可用模型当前使用的模型前带✓标记模型列表来自代理/models端点始终反映网关的最新配置model— 从列表中选择新模型并切换。由于模型在ClaudeAgentOptions创建时确定切换会结束当前会话、以新模型开启一轮对话handle_model_switch返回should_restartTrue触发外层循环重建 clientclear— 开始新会话丢弃当前上下文quit/exit— 结束聊天。带 MCP 的 agent_with_mcp.pyagent_with_mcp.py 与基础版的差异集中在ClaudeAgentOptions的mcp_servers参数上mcp_server_url f{litellm_base_url}/mcp/deepwiki2 options ClaudeAgentOptions( system_promptYou are a helpful AI assistant with access to DeepWiki for research. ..., modelcurrent_model, max_turns50, mcp_servers{ deepwiki2: { type: http, url: mcp_server_url, headers: { Authorization: fBearer {config.LITELLM_API_KEY} }, } }, )两个细节值得注意其一MCP 走 HTTP transport且鉴权头复用 LiteLLM 的 API keyAuthorization: Bearer ...与消息请求共用同一套网关鉴权其二代码做了双重降级——配置 MCP 时若抛异常则打印警告并继续无 MCP 运行创建 client 失败时则提示用户改用USE_MCPfalse或回退到python main.py。为什么通过 LiteLLM 网关调用 AgentREADME 总结了四条收益均对应网关能力而非 SDK 能力轻松切换提供商同一份 Agent 代码通过改模型名即可使用 OpenAI、Bedrock、Azure 等不同后端成本追踪LiteLLM 对每个请求做成本核算跨所有 Agent 对话统一记账限流与预算可对 key、用户、团队设置花费上限与速率限制负载均衡与 Fallback请求可分布在多个 API key 或多区域之间失败时自动回退到其他模型重试。此外因为所有流量都经过代理网关层还可以叠加防护栏guardrails、日志与观测集成这些能力对直连 Anthropic 的 SDK 是不可见的。故障排查症状排查步骤连接错误确认 LiteLLM 在运行litellm --model your-model确认 URL 正确默认http://localhost:4000认证错误校验 LiteLLM API key 是否正确确认目标模型已在 LiteLLM 配置中Model not found检查LITELLM_MODEL与配置中的model_name完全一致单独用litellm --model your-model验证模型本身可用MCP Agent 卡住或失败DeepWiki 服务可能不可用对应端点http://localhost:4000/mcp/deepwiki2用USE_MCPfalse python agent_with_mcp.py禁用 MCP或改用基础版python main.py其中 Model not found 的根因值得强调Agent 里写的是 LiteLLM 的model_name别名而不是上游的原始模型 ID。如果别名不匹配网关会直接拒绝请求这在 common.py 的注释里也有明确提示Model name as configured in LiteLLM。示例文件清单文件作用main.py无 MCP 的基础交互式 Agentagent_with_mcp.py带 MCPDeepWiki2服务器集成的 Agentcommon.py共享工具配置类、模型拉取、命令处理、流式输出config.example.yaml多模型BedrockLiteLLM 配置示例requirements.txtPython 依赖claude-agent-sdk、httpx0.27.0这套示例的最小化依赖两个包加一个代理配置文件构成了一套可复制的任意 LLM Agent SDK MCP接入模板先以环境变量重定向打通网关再按需在ClaudeAgentOptions中挂载 MCP 服务器。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Claude Agent SDK 接入 LiteLLM 网关：通过单一代理调用任意 LLM 的实战指南
Claude Agent SDK 接入 LiteLLM 网关通过单一代理调用任意 LLM 的实战指南【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm本文基于仓库中 cookbook/anthropic_agent_sdk 示例讲解如何把 Anthropic 的 Claude Agent SDK 指向 LiteLLM 网关让 Agent 对话不再绑定 Anthropic 直连而是通过ANTHROPIC_BASE_URL环境变量走 LiteLLM 代理从而在同一个 Agent 代码里切换 Bedrock、OpenAI、Azure 等任意模型并获得成本追踪、限流与负载均衡等网关能力。读完本文你将掌握LiteLLM 代理的启动与多模型配置、Agent SDK 的环境变量重定向原理、MCPModel Context Protocol服务器通过 HTTP 接入网关的完整配置以及交互式终端里的模型切换命令。整体思路用 ANTHROPIC_BASE_URL 把 Agent SDK 指向网关Claude Agent SDK 的客户端默认直连 Anthropic API。接入 LiteLLM 的关键只有两步把ANTHROPIC_BASE_URL指向 LiteLLM 代理地址把ANTHROPIC_API_KEY填成 LiteLLM 的 API key。LiteLLM 代理实现了 Anthropic 消息接口Anthropic Messages 兼容端点因此 SDK 发出的请求无需任何代码改造即可被网关识别和路由。示例代码中的核心逻辑如下# 指向 LiteLLM 网关而不是直连 Anthropic os.environ[ANTHROPIC_BASE_URL] http://localhost:4000 os.environ[ANTHROPIC_API_KEY] sk-1234 # 你的 LiteLLM key # 使用 LiteLLM 里配置的任意模型 options ClaudeAgentOptions( modelbedrock-claude-sonnet-4, # 也可以是 gpt-4 或任意其他模型 system_promptYou are a helpful assistant., max_turns50, )对应实现见 common.py 中的setup_litellm_env函数它先对代理地址做rstrip(/)规范化然后写入上述两个环境变量。需要注意 README 特别提醒的一点不要在 base URL 后加/anthropic之类的路径后缀——LiteLLM 会自行处理路由多拼路径反而会导致 404。快速开始1. 安装依赖pip install anthropic claude-agent-sdk litellm依赖清单 requirements.txt 里实际声明的是claude-agent-sdk和httpx0.27.0——前者提供ClaudeSDKClient、ClaudeAgentOptions等核心类后者用于示例脚本直连代理的/models端点拉取可用模型列表。2. 启动 LiteLLM 代理最简方式直接用 Claude 模型启动litellm --model claude-sonnet-4-20250514或者使用配置文件启动多模型网关litellm --config config.yaml3. 运行 Agent基础 Agent无 MCPpython main.py带 MCP 的 Agent接入 DeepWiki2 用于研究检索python agent_with_mcp.py如果 MCP 连接失败可以用环境变量关闭 MCP 降级运行USE_MCPfalse python agent_with_mcp.py启动后即可在终端与 Agent 对话。USE_MCP的读取逻辑在 agent_with_mcp.py默认值为trueMCP 服务器地址被拼接为{litellm_base_url}/mcp/deepwiki2即通过 LiteLLM 网关暴露的 MCP 端点访问而不是直连 DeepWiki。配置环境变量与默认值common.py 中的Config类定义了三个可配置项全部支持环境变量覆盖不设置时使用默认值环境变量默认值说明LITELLM_PROXY_URLhttp://localhost:4000LiteLLM 代理地址LITELLM_API_KEYsk-1234LiteLLM 的 master key 或虚拟 keyLITELLM_MODELbedrock-claude-sonnet-4.5模型名必须是 LiteLLM 配置中存在的model_nameexport LITELLM_PROXY_URLhttp://localhost:4000 export LITELLM_API_KEYsk-1234 export LITELLM_MODELbedrock-claude-sonnet-4.5其中默认 keysk-1234与仓库根目录 proxy_server_config.yaml 及 litellm/proxy/proxy_config.yaml 中general_settings.master_key的示例值一致即代理未显式配置密钥时的本地默认值。多模型代理配置config.yaml 详解示例配置 config.example.yaml 展示了如何通过model_list在同一个代理上挂载多个模型别名model_list: - model_name: bedrock-claude-sonnet-3.5 litellm_params: model: bedrock/us.anthropic.claude-3-5-sonnet-20240620-v1:0 aws_region_name: us-east-1 - model_name: bedrock-claude-sonnet-4 litellm_params: model: bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0 aws_region_name: us-east-1 - model_name: bedrock-claude-sonnet-4.5 litellm_params: model: bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0 aws_region_name: us-east-1 - model_name: bedrock-claude-opus-4.5 litellm_params: model: bedrock/us.anthropic.claude-opus-4-5-20251101-v1:0 aws_region_name: us-east-1 - model_name: bedrock-nova-premier litellm_params: model: bedrock/amazon.nova-premier-v1:0 aws_region_name: us-east-1每个条目的model_name是对 Agent 可见的别名litellm_params.model是 LiteLLM 内部使用的真实模型标识这里是 Bedrock 的完整模型 IDaws_region_name指定 Bedrock 区域。Agent 侧只需使用别名例如LITELLM_MODELbedrock-claude-sonnet-4.5。创建好config.yaml后以litellm --config config.yaml启动即可。同一文件结构在仓库的 litellm/proxy/proxy_config.yaml 中也有体现该文件还示范了 MCP 服务器与网关的集成配置# MCP Server Configuration mcp_servers: # Wikipedia MCP - reliable and works without external deps wikipedia: transport: stdio command: uvx args: [mcp-server-fetch] description: Fetch web pages and Wikipedia content deepwiki: transport: http url: https://mcp.deepwiki.com/mcp可以看到 MCP 服务器支持两种 transport本地stdio通过uvx等命令拉起和http直连远端 MCP 服务。Agent 示例中访问的/mcp/deepwiki2端点正是网关把已注册的 HTTP MCP 服务器暴露给客户端的通道。交互式聊天核心实现与对话命令基础版 main.py 的执行流程main.py 的主循环逻辑为通过Config()读取配置setup_litellm_env(config)重定向 Anthropic 环境变量调用fetch_available_models()从代理的/models端点拉取当前配置的模型列表每轮对话创建ClaudeAgentOptionsmax_turns50和ClaudeSDKClient上下文逐行读取用户输入识别命令后分发普通消息则交给stream_response()流式输出。模型列表的获取在 common.py 中实现用httpx.AsyncClient以 Bearer 鉴权请求{base_url}/models解析返回的data[].id数组。如果请求失败代理未启动或 key 错误会打印警告并降级到一份内置的默认模型列表保证 CLI 不会因此无法启动——这是一个值得借鉴的容错设计。流式输出部分stream_response通过client.query(user_input)发起查询再迭代client.receive_response()逐块处理content_block_delta增量文本与content_block_start内容块起始两类消息并即时打印最后对content字段做了兜底处理。对话命令聊天过程中支持以下命令实现在 main.py 与 common.pymodels— 列出所有可用模型当前使用的模型前带✓标记模型列表来自代理/models端点始终反映网关的最新配置model— 从列表中选择新模型并切换。由于模型在ClaudeAgentOptions创建时确定切换会结束当前会话、以新模型开启一轮对话handle_model_switch返回should_restartTrue触发外层循环重建 clientclear— 开始新会话丢弃当前上下文quit/exit— 结束聊天。带 MCP 的 agent_with_mcp.pyagent_with_mcp.py 与基础版的差异集中在ClaudeAgentOptions的mcp_servers参数上mcp_server_url f{litellm_base_url}/mcp/deepwiki2 options ClaudeAgentOptions( system_promptYou are a helpful AI assistant with access to DeepWiki for research. ..., modelcurrent_model, max_turns50, mcp_servers{ deepwiki2: { type: http, url: mcp_server_url, headers: { Authorization: fBearer {config.LITELLM_API_KEY} }, } }, )两个细节值得注意其一MCP 走 HTTP transport且鉴权头复用 LiteLLM 的 API keyAuthorization: Bearer ...与消息请求共用同一套网关鉴权其二代码做了双重降级——配置 MCP 时若抛异常则打印警告并继续无 MCP 运行创建 client 失败时则提示用户改用USE_MCPfalse或回退到python main.py。为什么通过 LiteLLM 网关调用 AgentREADME 总结了四条收益均对应网关能力而非 SDK 能力轻松切换提供商同一份 Agent 代码通过改模型名即可使用 OpenAI、Bedrock、Azure 等不同后端成本追踪LiteLLM 对每个请求做成本核算跨所有 Agent 对话统一记账限流与预算可对 key、用户、团队设置花费上限与速率限制负载均衡与 Fallback请求可分布在多个 API key 或多区域之间失败时自动回退到其他模型重试。此外因为所有流量都经过代理网关层还可以叠加防护栏guardrails、日志与观测集成这些能力对直连 Anthropic 的 SDK 是不可见的。故障排查症状排查步骤连接错误确认 LiteLLM 在运行litellm --model your-model确认 URL 正确默认http://localhost:4000认证错误校验 LiteLLM API key 是否正确确认目标模型已在 LiteLLM 配置中Model not found检查LITELLM_MODEL与配置中的model_name完全一致单独用litellm --model your-model验证模型本身可用MCP Agent 卡住或失败DeepWiki 服务可能不可用对应端点http://localhost:4000/mcp/deepwiki2用USE_MCPfalse python agent_with_mcp.py禁用 MCP或改用基础版python main.py其中 Model not found 的根因值得强调Agent 里写的是 LiteLLM 的model_name别名而不是上游的原始模型 ID。如果别名不匹配网关会直接拒绝请求这在 common.py 的注释里也有明确提示Model name as configured in LiteLLM。示例文件清单文件作用main.py无 MCP 的基础交互式 Agentagent_with_mcp.py带 MCPDeepWiki2服务器集成的 Agentcommon.py共享工具配置类、模型拉取、命令处理、流式输出config.example.yaml多模型BedrockLiteLLM 配置示例requirements.txtPython 依赖claude-agent-sdk、httpx0.27.0这套示例的最小化依赖两个包加一个代理配置文件构成了一套可复制的任意 LLM Agent SDK MCP接入模板先以环境变量重定向打通网关再按需在ClaudeAgentOptions中挂载 MCP 服务器。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考