logfire-gateway

使用 Pydantic AI Gateway 配置应用程序

如果要观察或路由 Claude Code/Codex 本身，请改用 coding-agent setup。请将此应用程序工作流与编码会话记录和提供商配置分开。

保留用户已确认的项目、区域、提供商和现有凭据机制。已有的应用程序 Gateway 密钥无需 CLI 登录或 SDK 写入令牌。若要通过 CLI 创建密钥，请遵循 CLI Gateway 凭据流程。 CLI 不可用时，请使用 UI 中的 Gateway Connect 流程。

将此技能用于模型流量、提供商路由和 Gateway 凭据。它与 logfire-instrumentation 分开：Logfire 写入令牌用于发送遥测数据，而 Gateway 密钥用于授权模型请求。不要互相替代。不要配置编码 Agent 提供商、遥测数据或 MCP 集成。

准备好的设置交接可能已经确定了准确的项目和凭据。请复用这些信息，而不是重复身份验证或选择其他项目。

1. 确认应用程序

更改文件前，请检查代码库并确定现有的模型客户端、模型、提供商、环境加载器和可运行入口。如果请求中指定了应用程序，或者代码库中存在明确的推理客户端，请将该应用程序接入 Gateway。除非用户要求更改，否则请保留其提供商协议和模型。

如果没有推理应用程序，或目标不明确，请询问用户想要接入哪个应用程序。搭建新应用程序前，请先确认其用途。

请求配置 Gateway 即表示授权将所选应用程序的模型调用路由至 Gateway。常规的 Logfire 插桩并不意味着用户做出了这一选择。

请在当前 Agent 中继续此配置。准备好的向导交接已完成账户和项目选择。不要再次调用向导，也不要启动另一个设置 Agent。请保留现有模型客户端、提供商抽象、依赖版本和环境约定。

2. 处理凭据，避免暴露

复用通过仓库的密钥机制提供的现有 Gateway 凭据。否则，通过 UI 的 Connect 流程或 CLI 凭据操作流程获取项目范围的 Gateway 密钥。 不要仅为配置现有 Gateway 密钥而创建遥测写入令牌。 切勿在录制的终端或 Agent 消息中打印一次性密钥。 使用所选 SDK 或 Connect 代码片段读取的环境变量存储密钥：Pydantic AI 使用 PYDANTIC_AI_GATEWAY_API_KEY。对于其他客户端，保留应用程序现有的变量，或使用 LOGFIRE_GATEWAY_API_KEY，并将其明确读取到客户端的 API 密钥选项中。仅设置变量 并不能让任意客户端读取它。 保留无关值。对于本地环境文件，必须使用被 git 忽略的普通文件，并设置仅用户可读写的权限；精确替换一个现有赋值或插入一个赋值，并以原子方式写入文件。切勿将包含密钥的文件或密钥暂存或提交到源代码管理中。不要追加重复的赋值。如果无法安全更新现有密钥机制，请让用户通过其常规密钥管理器安装密钥。

下载的 Connect 凭据可以使用同一密钥机制，无需打印或加载下载的文件。切勿在 Agent 消息、 源代码、日志、测试或快照中放入密钥。

使用所选 SDK 预期的环境变量。不要将密钥放入浏览器代码或客户端代码包中。创建密钥不会激活 Gateway、配置提供商计费或选择路由端点。如果公共 API 因 Gateway 未激活或缺少权限而拒绝创建，请说明具体的前置条件。缺少 OAuth 范围时，需要重新征求同意并获取所需权限；激活提供商或配置计费则需要在 Gateway 设置中完成。未经用户同意，不要激活付费提供商访问权限。成功创建的密钥应重复使用；配置重试时不要再创建另一个密钥。

3. 配置检测到的应用程序

优先使用现有客户端和依赖项版本。尽可能少地修改，同时保留应用程序当前的提供商抽象。

Pydantic AI

当所选提供商和模型已知时，使用 Gateway 模型形式：

from pydantic_ai import Agent

# Set PYDANTIC_AI_GATEWAY_API_KEY and PYDANTIC_AI_GATEWAY_BASE_URL from Connect.
agent = Agent('gateway/openai:gpt-5.2')

将 PYDANTIC_AI_GATEWAY_BASE_URL 设置为 Connect 针对所选区域或可自托管部署提供的 Gateway 根 URL，并同时设置 API 密钥。使用 Pydantic AI 代码片段中的根 URL，而不要使用从其他客户端代码片段复制来的特定于提供商的端点。保留明确配置的匹配 URL；不要依赖 SDK 推断区域或使用默认值来选择用户的目标位置。

常规凭据为 PYDANTIC_AI_GATEWAY_API_KEY。如果应用程序需要显式密钥或自定义路由，请使用已安装的 Pydantic AI 版本中的 gateway_provider()，并保留 Connect 交接信息中的提供商类型和路由。不要根据模型名称猜测提供商标识。

OpenAI 兼容客户端

使用 Connect 提供的确切 Gateway 基础 URL 和路由，或者根据交接信息和现有提供商协议推导文档中说明的区域路由。必要时，参阅 Gateway 文档中的特定于提供商的示例。保留客户端现有的 API 形式，并通过常规环境变量加载机制，将 API 密钥从应用程序选定的环境变量加载到客户端的 API 密钥选项中。如果交接信息已提供区域 URL，不要硬编码区域 URL。自托管源站并非托管区域：请使用已确认的 Gateway 资源和配置的路由，否则请询问用户。文档中说明了提供商路径，并不能证明该组织已启用该路由。

Anthropic、Google 和其他原生客户端

使用 Connect 中针对提供商的 Gateway 代码片段，或所选区域对应的公开 Gateway 文档。原生提供商路径不可互换：Anthropic、OpenAI Responses、Google、 Bedrock 和 chat-completions 路由具有不同的 URL 和请求格式。 不要仅为了让示例通过编译，就把原生请求转换为另一种协议。

4. 验证一个真实请求

说明实时请求会将提示词通过 Gateway 发送给所选提供商，且可能产生使用费用。使用一份不含应用、客户或机密数据的小型合成载荷。明确要求配置并测试所选路由，即表示授权进行这项范围有限的检查；否则，发送前请先征求批准。不要为了测试而启用付费访问或运行生产工作负载。

通过所选路由运行该请求。检查响应以及应用的常规错误处理。成功导入、解析配置或进程退出，并不能证明请求使用了 Gateway。

如果项目有可读取数据的 Logfire 登录权限，请查询确切的项目，查找刚发出的 Gateway 请求，或打开其 Gateway 活动视图。不要使用仅限发送的 SDK 写入令牌进行读取。如果无法进行读取验证，请报告请求响应已验证，并注明 Logfire 侧的到达情况尚未验证。

运行项目的格式化工具、类型检查器、构建和针对性测试。报告确切的提供商、路由、模型、端点类别、凭据变量、请求结果，以及任何尚未验证的 Logfire 侧检查。如果本次会话没有检查，就绝不要声称观察到了 Gateway 请求。

设置完成后，返回相关的项目或 Gateway 视图链接。如果提供商启用或其他前置条件阻止了请求，请报告该阻碍，并注明应用推理尚未验证。

参考资料

• Pydantic AI Gateway 文档