RydanticAI

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

Learn typed output and bounded correction with a runnable offline project.

Run AI examples

Try streaming, graph checkpoints and live providers.

Connect a model

Choose Responses, Chat Completions or Messages.

Stream typed output

Work with Partial and Iterable results.

Add images and PDFs

Build ordered multimodal prompts.

Route through a gateway

Translate protocols and apply per-client budgets.

Install RydanticAI

[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 for authentication, capability selection, native history and protocol limits. Use ordered Prompt image inputs with all three providers. The development source also adds Pdf document inputs, including embedded PDF conversion across every protocol combination.

Return a validated Rust type

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.

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.

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.

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 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.

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.

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 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.

Build an agent

Multimodal inputs

Routing and decisions

Build your first agent

Run AI examples

Connect a model

Stream typed output

Add images and PDFs

Route through a gateway

Install RydanticAI

Connect an API

Return a validated Rust type

Structured output streams

Tools and execution limits

Typed graphs and checkpoints

Authenticated model gateway

Tracing and tests

TypeSafe Jev decisions

Build your first agent

Run AI examples

Connect a model

Stream typed output

Add images and PDFs

Route through a gateway

​Install RydanticAI

​Connect an API

​Return a validated Rust type

​Structured output streams

​Tools and execution limits

​Typed graphs and checkpoints

​Authenticated model gateway

​Tracing and tests

​TypeSafe Jev decisions

Install RydanticAI

Connect an API

Return a validated Rust type

Structured output streams

Tools and execution limits

Typed graphs and checkpoints

Authenticated model gateway

Tracing and tests

TypeSafe Jev decisions