Anthropic

The Anthropic provider (rig::providers::anthropic) connects Rig to Anthropic’s Claude models. It supports completion models with tool use, prompt caching, and detailed token-usage reporting. Two things set it apart from other providers: it is configured through a ClientBuilder (to pin the API version and opt into beta features), and it requires max_tokens on every request.

Capabilities

Capability	Supported	Model / flag
Completion	Yes	Any Claude model id, e.g. claude-sonnet-4-5, claude-opus-4-8 — max_tokens is required
Streaming	Yes	Streaming completion and agent responses
Tools	Yes	Rig Tool trait; tool_choice supported
Structured output	Yes	Via Rig’s extractor (built on tool use); no native JSON mode
Vision / image input	Yes	Image content blocks — JPEG, PNG, GIF, WebP
Extended thinking / reasoning	Yes	Thinking and redacted-thinking blocks; enable a thinking object through additional_params
Embeddings	No	Not offered — pair Anthropic completions with OpenAI or Cohere embedding models for vector search

Basic usage

use rig::prelude::*;
use rig::providers::anthropic::{Client, completion::ANTHROPIC_VERSION_LATEST};

// Build a client, pinning the API version and opting into a beta feature
let client = Client::builder()
    .api_key("your-api-key")
    .anthropic_version(ANTHROPIC_VERSION_LATEST)
    .anthropic_beta("prompt-caching-2024-07-31")
    .build()?;

// Build an agent — max_tokens is required for Anthropic
let agent = client
    .agent("claude-sonnet-4-5")
    .preamble("You are a helpful assistant.")
    .max_tokens(1024)
    .build();

Expected output

Prompting the agent above — let reply = agent.prompt("Hello!").await?; — returns a plain-text completion:

Hello! How can I help you today?

Caution

Anthropic rejects requests without a max_tokens value. If you build a completion request or agent without one, Rig returns a CompletionError rather than sending an invalid request. Always call .max_tokens(...).

Configuring the client

Unlike most providers, the Anthropic client is created through ClientBuilder so you can set the API version and beta headers:

use rig::prelude::*;
use rig::providers::anthropic::Client;

let client = Client::builder()
    .api_key("your-api-key")
    .anthropic_version("2023-06-01")
    .anthropic_beta("prompt-caching-2024-07-31")
    .build()?;

A from_env constructor is also available for the common case of reading ANTHROPIC_API_KEY from the environment.

API versioning

Anthropic requires an explicit API version. The provider exports constants so you don’t have to hardcode the string:

• ANTHROPIC_VERSION_2023_01_01
• ANTHROPIC_VERSION_2023_06_01
• ANTHROPIC_VERSION_LATEST — currently an alias for 2023-06-01

Prefer ANTHROPIC_VERSION_LATEST unless you need to pin an older version.

Models

Pass any Claude model id as a string to agent or completion_model:

let agent = client
    .agent("claude-sonnet-4-5")
    .max_tokens(1024)
    .build();

Claude is organized into three families, from most capable to fastest: Opus, Sonnet, and Haiku.

Note

Anthropic releases new Claude versions regularly. Rather than hardcode a version here, pass the id you want as a string and check Anthropic’s model list for current options, or the crate’s exported model constants on docs.rs.

Prompt caching and token usage

With the prompt-caching beta enabled, Anthropic reports cache statistics alongside the usual token counts. Rig surfaces these on the response’s Usage:

Field	Meaning
input_tokens	Tokens processed at full price
cache_read_input_tokens	Tokens served from the prompt cache (optional)
cache_creation_input_tokens	Tokens written to the cache this request (optional)
output_tokens	Tokens generated in the response

The two cache fields are optional — they are populated only when prompt caching is active for the request.

Response content types

Claude responses can contain more than plain text. Rig models this with an untagged Content enum whose main variants are:

• Text — a text block from the model
• ToolUse — a request to call a tool, carrying an id, name, and JSON input

When you use an agent with tools, Rig interprets these variants for you: text becomes the response, and tool-use blocks are dispatched to your registered tools. You only need to work with Content directly if you consume the raw completion response.

Tool calling

Anthropic models support tool use with Anthropic’s own formatting. As with other providers, you define tools once via Rig’s Tool trait and register them on an agent — Rig converts them to Anthropic’s expected tool-definition format and parses tool-call responses back into its own types. See Tools for details.

See also

• Model Providers — vocabulary and shared configuration
• Agents and Tools
• Completions

API Reference (docs.rs)

Next steps

Model ProvidersShared provider vocabulary and configuration.

CompletionsThe request/response API behind agents.

AgentsLayer preambles, context, and tools onto a model.

EmbeddingsAnthropic has none — use OpenAI or Cohere for vector search.