PydanticAI SDK

DeepIntShield 2.8.3 supplies a native PydanticAI model connected to the gateway. PydanticAI owns the Agent, output validation, tools, dependencies, and execution loop. Use a configured provider/model ID to select the upstream provider while keeping its credentials on the gateway.

Install and configure

pip install "deepintshield[pydanticai]==2.8.3"
export DEEPINTSHIELD_VIRTUAL_KEY="sk-ds-your-virtual-key"
export DEEPINTSHIELD_BASE_URL="https://app.deepintshield.com"

The extra installs PydanticAI’s OpenAI integration. A separate Anthropic or Google client is not required for common inference through the gateway. The selected model must support the requested endpoint and output/tool features.

A live SDK client also enables supported Agentic framework hooks. Configure the workload identity and registration described under governed execution before running the SDK’s native Agent examples; inference credentials alone do not complete that setup.

Bind a model and keep the native Agent

import asyncio

from deepintshield import DeepintShield
from pydantic_ai import Agent

async def main():
    with DeepintShield.from_env() as shield:
        async with shield.async_openai() as client:
            model = shield.bind("pydanticai").model(
                "anthropic/claude-sonnet-4-5",
                api="chat_completions",
                openai_client=client,
            )
            agent = Agent(model, instructions="Be concise and helpful.")
            result = await agent.run("Explain what an API gateway does.")
            print(result.output)

asyncio.run(main())

The example explicitly owns and closes the native asynchronous client. You can omit openai_client to let the binder construct one from shield.openai_config(); native clients have a separate lifecycle from the parent DeepintShield client. Supplied clients retain their own connection and request settings, so configure them for the gateway yourself.

The binder supports these exact api values:

Value	Native PydanticAI model	Gateway operation
chat_completions (default)	OpenAIChatModel	Chat Completions
responses	OpenAIResponsesModel	Responses

For a model with Responses support, change api="responses". Preserve native PydanticAI message history, tool results, and continuation behavior; support for stored response IDs and other provider-native resources varies by provider. See protocol operations.

Structured output and streaming

PydanticAI continues to validate its native output type:

from pydantic import BaseModel
from pydantic_ai import Agent

class Summary(BaseModel):
    topic: str
    summary: str

agent = Agent(model, output_type=Summary)
result = await agent.run("Summarize how virtual keys work.")
print(result.output.summary)

Use this in the async function while the model’s client is open. Select a model whose tool or structured-output behavior matches your PydanticAI configuration. For ordinary text streaming:

agent = Agent(model)
async with agent.run_stream("Write a short welcome message.") as result:
    async for text in result.stream_text(delta=True):
        print(text, end="", flush=True)

These are native PydanticAI operations. Gateway output inspection remains incremental for streams; use nonstreaming inference or buffering if the whole answer must be approved before any text reaches the user. See streaming responses.

Native tools and governed execution

Define tools through PydanticAI’s existing public API:

agent = Agent(model)

@agent.tool_plain
def add_numbers(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

A live DeepintShield client installs supported PydanticAI enforcement hooks. Before running governed agents, configure the workload’s Agentic identity, registration, and grants. Set agent_name or DEEPINTSHIELD_AGENT_NAME unless the Virtual Key already resolves to a server-issued agent subject. Policy checks authorize the validated tool and arguments at the supported execution boundary; a denied or unapproved call does not execute.

These governance requirements are additional to the two inference connection variables. PydanticAI still chooses and executes tools, and native model binding alone is not a tool authorization policy. Follow Agents and Agentic governance for setup, approvals, obligations, and supported runtime boundaries.

Existing native PydanticAI code

Applications without the DeepIntShield package can configure OpenAIProvider directly:

import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

provider = OpenAIProvider(
    base_url="https://app.deepintshield.com/v1",
    api_key=os.environ["DEEPINTSHIELD_VIRTUAL_KEY"],
)
model = OpenAIChatModel("anthropic/claude-sonnet-4-5", provider=provider)
agent = Agent(model)
print(agent.run_sync("Hello!").output)

This configures inference routing. Configure separate framework/service controls for any tool execution in that application.

Compatibility helper and native provider features

shield.pydanticai(model=..., instructions=...) remains a whole-agent compatibility shortcut. It constructs a native Agent with an OpenAI-compatible model under /pydanticai/v1. Prefer the model binder when your application owns Agent construction or needs explicit Chat Completions/Responses selection.

The /pydanticai compatibility prefix also exposes selected provider-native formats. If a feature needs native Anthropic or GenAI semantics, install and configure the corresponding native dependencies and use the matching provider adapter. Do not assume its constructor has the same options as OpenAIProvider. See the Anthropic and GenAI integrations for protocol details.

See providers and frameworks for binder settings and SDK error codes for direct SDK and governance failures.