Configure an Application with Pydantic AI Gateway

For observing or routing Claude Code/Codex itself, use coding-agent setup 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. 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. 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 documentation when needed. Preserve the client's existing API shape and load its API key from the application's selected environment variable into the client's API-key option through its normal environment loading mechanism. Do not hard-code a regional URL when the handoff already provides one. A self-hosted origin is not a hosted region: use its confirmed Gateway resource and configured route, or ask for them. A documented provider path alone does not prove that this organization has that route enabled.

Anthropic, Google, and other native clients

Use the provider-specific Gateway snippet from Connect or the linked public Gateway documentation for the selected region. Native provider paths are not interchangeable: Anthropic, OpenAI Responses, Google, Bedrock, and chat-completions routes have different URLs and request shapes. Do not translate a native request into another protocol merely to make the example compile.

4. Verify one real request

Explain that a live request sends its prompt to the selected provider through Gateway and may incur usage charges. Use one small synthetic payload with no application, customer, or secret data. An explicit request to configure and test the selected route authorizes this bounded check; otherwise ask for approval before sending it. Do not activate paid access or run production workloads as a test.

Run that request through the selected route. Check the response and the application's normal error handling. A successful import, configuration parse, or process exit is not proof that the request used the Gateway.

If the project has a read-capable Logfire login, query the exact project for a fresh Gateway request or open its Gateway activity view. Do not use the send-only SDK write token for reads. If read verification is unavailable, report the request response as verified and mark Logfire-side arrival as unverified.

Run the project's formatter, type checker, build, and focused tests. Report the exact provider, route, model, endpoint class, credential variable, request result, and any unverified Logfire-side check. Never claim that a Gateway request was observed when this session did not check it.

After setup, return the relevant project or Gateway view link. If provider activation or another prerequisite prevents the request, report that blocker and mark application inference as unverified.

References

• Pydantic AI Gateway documentation