/logfire-gateway

name: logfire-gateway
description: Configure an application's model calls to use the Pydantic AI Gateway. Use when the user asks to route application inference through Gateway, connect a Gateway key, or add a Gateway provider snippet. This does not configure or instrument coding agents.

Configure an Application with Pydantic AI Gateway

For observing or routing Claude Code/Codex itself, use [coding-agent setup](https://pydantic.dev/.well-known/agent-skills/logfire-coding-agents/SKILL.md) instead. Keep this application workflow separate from coding-session recording and provider setup.

Preserve the user's confirmed project, region, provider, and existing credential mechanism. An existing application Gateway key needs no CLI login or SDK write token. To create a key through the CLI, follow the [CLI Gateway credential procedure](https://pydantic.dev/.well-known/agent-skills/logfire-coding-agents/references/application-gateway.md). Use the UI's Gateway Connect flow when CLI access is unavailable.

Use this skill for model traffic, provider routing, and Gateway credentials. It is separate from `logfire-instrumentation`: a Logfire write token sends telemetry, while a Gateway key authorizes model requests. Do not substitute one for the other. Do not configure coding-agent providers, telemetry, or MCP integrations.

A prepared setup handoff may already identify the exact project and credentials. Reuse it rather than repeating authentication or selecting another project.

1. Identify the application

Before changing files, inspect the repository and identify the existing model client, model, provider, environment loader, and runnable entrypoint. If the request names an application or the repository contains a clear inference client, wire that application through Gateway. Preserve its provider protocol and model unless the user requests a change.

If there is no inference application or the target is ambiguous, ask which application the user wants to connect. Confirm a new application's purpose before scaffolding it.

A Gateway setup request authorizes routing the selected application's model calls through Gateway. Ordinary Logfire instrumentation does not imply that choice.

Continue this setup in the current agent. A prepared wizard handoff already finished account and project selection. Do not invoke the wizard again or launch another setup agent. Preserve the existing model client, provider abstraction, dependency versions, and environment conventions.

2. Handle credentials without exposing them

Reuse an existing Gateway credential provided through the repository's secret mechanism. Otherwise obtain a project-scoped Gateway key using the UI's Connect flow or the [CLI credential procedure](https://pydantic.dev/.well-known/agent-skills/logfire-coding-agents/references/application-gateway.md). Do not create a telemetry write token merely to configure an existing Gateway key. Never print the one-time secret in a recorded terminal or agent messages. Store it using the environment variable read by the selected SDK or Connect snippet: `PYDANTIC_AI_GATEWAY_API_KEY` for Pydantic AI. For other clients, keep the application's existing variable, or use `LOGFIRE_GATEWAY_API_KEY` and explicitly read it into the client's API-key option. Setting a variable alone does not make an arbitrary client consume it. Keep unrelated values intact. For a local environment file, require a gitignored regular file with user-only permissions, replace exactly one existing assignment or insert one, and write the file atomically. Never stage or commit the secret-bearing file or key to source control. Do not append duplicate assignments. If the existing secret mechanism cannot be updated safely, ask the user to install the key through their normal secret manager.

A downloaded Connect credential can use the same secret mechanism without printing or sourcing the downloaded file. Never put a key in agent messages, source code, logs, tests, or snapshots.

Use the environment variable expected by the selected SDK. Keep the key out of browser code and client-side bundles. Key creation does not activate Gateway, configure provider billing, or select a routing endpoint. If the public API rejects creation because Gateway is inactive or permission is missing, explain that specific prerequisite. Missing OAuth scope requires renewed consent with the needed permission; provider activation or billing requires Gateway settings. Do not activate paid provider access without the user's agreement. Reuse a successfully created key; do not mint another key during a configuration retry.

3. Configure the detected application

Prefer the existing client and dependency versions. Make the smallest change that preserves the application's current provider abstraction.

Pydantic AI

Use the Gateway model form when the selected provider and model are known:

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')

Set `PYDANTIC_AI_GATEWAY_BASE_URL` to the Gateway root URL supplied by Connect for the selected region or self-hosted deployment, alongside the API key. Use the Pydantic AI snippet's root URL, not a provider-specific endpoint copied from another client's snippet. Preserve an explicitly configured matching URL; do not rely on SDK region inference or a default to select the user's destination.

The normal credential is `PYDANTIC_AI_GATEWAY_API_KEY`. When the application needs an explicit key or custom route, use the installed Pydantic AI version's `gateway_provider()` and preserve the provider type and route from the Connect handoff. Do not guess a provider slug from a model name.

OpenAI-compatible clients

Use the exact Gateway base URL and route supplied by Connect, or derive the documented regional route from the handoff and existing provider protocol. Read the provider-specific examples in the Gateway doc