> ## Documentation Index
> Fetch the complete documentation index at: https://rydantic.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# RydanticAI

> Build typed agents, resumable graphs and a three-protocol gateway with the independent rydantic-ai crate.

`rydantic-ai` lives in the same workspace with its own `0.6.0` version and publishing lifecycle. The core Rydantic model crate remains independent of AI transport dependencies.

Prompt & toolsAgentValidated Rust output

> **[Build your first agent](/tutorials/typed-agent.md)**
>
> Learn typed output and bounded correction with a runnable offline project.

> **[Run AI examples](/examples/agents.md)**
>
> Try streaming, graph checkpoints and live providers.

> **[Connect a model](/integrations/api-providers.md)**
>
> Choose Responses, Chat Completions or Messages.

> **[Stream typed output](/integrations/structured-output.md)**
>
> Work with Partial and Iterable results.

> **[Add images and PDFs](/integrations/images.md)**
>
> Build ordered multimodal prompts.

> **[Route through a gateway](/integrations/gateway-protocols.md)**
>
> Translate protocols and apply per-client budgets.

## Install RydanticAI

```toml theme={"system"}
[dependencies]
rydantic = "0.7.0-beta.3"
rydantic-ai = "0.6.0"
```

## Connect an API

Configure `BASEURL`, `MODEL` and optional `APIKEY`. Select `ResponsesProvider`, `ChatCompletionsProvider` or `AnthropicMessagesProvider`, or use `HttpProvider::from_env(Api::ChatCompletions)` to select a protocol at runtime. Each provider integrates with the same Agent, typed tools and structured output streams.

`BASEURL` includes the API prefix, such as `https://api.openai.com/v1` or `https://api.anthropic.com/v1`. The provider appends `/responses`, `/chat/completions` or `/messages`. See [API providers](/integrations/api-providers.md) for authentication, capability selection, native history and protocol limits.

Use ordered [`Prompt` image inputs](/integrations/images) with all three providers. The development source also adds [`Pdf` document inputs](/integrations/pdf), including embedded PDF conversion across every protocol combination.

## Return a validated Rust type

```rust theme={"system"}
use rydantic::Model;
use rydantic_ai::{Agent, ResponsesProvider, RunContext};
use std::sync::Arc;

#[derive(Model)]
struct Answer {
    answer: String,
}

// Inside an async function:
let provider = Arc::new(ResponsesProvider::from_env()?);
let model = std::env::var("MODEL")?;
let agent = Agent::<(), Answer>::new(provider, model);
let result = agent.run("What is 19 + 23?", Arc::new(()), RunContext::default()).await?;
println!("{}", result.output.answer);
```

Responses and Chat Completions request native JSON Schema by default. Messages uses schema instructions and runtime validation, with optional native schema support for compatible models. Override `Capabilities` explicitly for endpoints with different features. Rydantic validates the final output in every mode.

## Structured output streams

Use `Agent::stream_partial()` and `Agent::stream_iterable()` for structured output. `Partial<T>` emits provisional JSON field snapshots and returns a fully validated final `T`. `Iterable<T>` validates complete elements before emission and can collect the accepted attempt into `Vec<T>`, with no `Clone` requirement. Both modes preserve validation correction, tool execution, usage, cancellation and bounded backpressure. See the [structured output guide](/integrations/structured-output.md).

## Tools and execution limits

`TypedTool<Dependencies, Arguments, Output, Handler>` derives its argument schema from a Rydantic model. Arguments are validated before execution. The handler receives typed arguments, `Arc<Dependencies>` and a `RunContext`; its output is validated before returning to the model. Async validators are supported for arguments and final outputs.

Agent limits cover model calls, tool calls, correction retries and observed token usage. A shared cancellation token and absolute deadline cover provider requests, validation and handlers. Tool execution errors stop the run; executed handlers are never automatically replayed. Retain transactional or idempotency controls for external side effects in the handler.

Provider schemas resolve root references and normalize definition names. Numeric constraints beyond JavaScript's safe integer range become textual descriptions and are recorded in `schema::prepare_model_schema::<T>().runtime_constraints`; Rydantic still enforces the original numeric constraints at runtime. This preserves Rust integer constraints across JSON-based providers.

```sh theme={"system"}
cargo run -p rydantic-ai --example provider
```

## Typed graphs and checkpoints

`Graph<State, Dependencies, NodeKey, Output>` uses typed state, dependencies and node keys, including application enums. Implement `Node` and declare allowed outgoing edges while building the graph. Each node returns `Transition::Next`, `Transition::Pause` or `Transition::End`.

A pause returns `Checkpoint { state, next, steps }`. Serialize the checkpoint with Serde, persist it in application storage, and pass it to `Graph::resume` with fresh dependencies and context. Step limits apply across resumes. Unknown nodes and undeclared transitions fail explicitly.

```sh theme={"system"}
cargo run -p rydantic-ai --example graph
```

Checkpoints are boundaries between nodes. Applications own durable storage, checkpoint authenticity and external side-effect recovery.

## Authenticated model gateway

The gateway exposes `GET /v1/models`, `POST /v1/responses`, `POST /v1/chat/completions` and `POST /v1/messages`, including JSON and SSE. Each upstream selects `api`: `responses`, `chat_completions` or `anthropic_messages`. Frontend and upstream protocols are independent; all nine combinations support text, tools, JSON Schema mappings and usage. See [gateway protocols](/integrations/gateway-protocols.md) for authentication, SDK configuration and bounded native replay. Each client has a bearer key and an explicit model allowlist. Configuration files contain environment-variable names for keys, and route definitions identify upstream URLs and models.

```sh theme={"system"}
cargo run -p rydantic-ai --bin rydantic-ai-gateway -- crates/rydantic-ai/examples/gateway.json
```

Set `RYDANTIC_GATEWAY_KEY` to a private random value of at least 16 bytes before running the example configuration. Keys supplied by gateway clients remain separate from upstream provider credentials. SSE disconnects cancel the upstream request. Ordered failover applies to HTTP 429/502/503/504 before any stream events; partially delivered responses and transport/protocol failures are not replayed.

The executable serves HTTP. For network clients, terminate HTTPS at a reverse proxy and keep the gateway listener on loopback. An off-host proxy-to-gateway hop also needs encrypted transport and restricted access. Upstream API keys are configured separately from client bearer keys.

Per-client and global ledgers atomically reserve capacity before each attempt. They track attempts, tokens and optional operator-maintained prices using integer micro-USD. Actual completion reconciles usage; unknown or cancelled outcomes consume reservations conservatively. Usage exceeding a reservation can overdraw the ledger and block subsequent admission. These controls govern admission and observed accounting; an upstream billing ceiling requires provider-side enforcement. Dollar limits require prices on every allowed route. Routes without configured prices can use request and token controls. Ledgers are in memory and reset on restart.

Each ledger applies its own configured token/cost reservation. Admission is atomic across client and global policies; completion or cancellation reconciles each hold separately.

## Tracing and tests

Agent runs, tools, graph nodes and gateway attempts emit standard Rust `tracing` spans. Usage and retry counts are recorded without logging prompts or credential values. Configure a subscriber and an OpenTelemetry exporter in your application as needed.

```sh theme={"system"}
cargo test -p rydantic-ai --all-features
cargo check -p rydantic-ai --no-default-features
```

Normal tests use local fake providers and native HTTP/SSE fixtures. Live Responses tests are ignored by default and require explicit `BASEURL`, `MODEL` and optional `APIKEY`. Set `NATIVE_JSON_SCHEMA=false` or `OUTPUT_TOKEN_LIMIT=false` when needed for endpoint capabilities.

## TypeSafe Jev decisions

The [TypeSafe Jev SDK](/integrations/jev.md) adds typed Noul, Choice and Score judgments. Configure `TYPESAFE_BASEURL` and `TYPESAFE_APIKEY`, retain the native confidence/distribution metadata, and parse primary answers into a Rydantic model for a tool or graph node.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.