pydantic_ai.models.anthropic
For details on how to set up authentication with this model, see model configuration for Anthropic.
Bases: Warning
Warning raised when Anthropic rejected a replayed thinking block and Pydantic AI retried without it.
Claude Fable 5.1 and 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5 bind each thinking block to the conversation prefix that produced it and reject a replay once that prefix changes — which a dynamic instructions function and a filtered toolset both do by design. Fable 5.2 and Mythos 5.2 enforce the check on every account; the other models enforce it for accounts created on or after 2026-08-31, and for older accounts record the mismatch and act on it only if the request asks it to.
Pydantic AI therefore asks for nothing by default, so an older account keeps replaying its
reasoning untouched. Where the check is enforced, the rejected request is retried once with
thinking.block_binding.prefix_mismatch_behavior='drop_block': the stale block is dropped, the
run continues, and later requests carrying that response history keep asking for the drop as
Anthropic requires. The drop is recorded on
ModelResponse.provider_details and as
an anthropic.input_transformations span event.
Bases: StreamedResponse
Implementation of StreamedResponse for Anthropic models.
Get the model name of the response.
Type: AnthropicModelName
Get the provider name.
Type: str
Get the provider base URL.
Type: str
Get the timestamp of the response.
Type: datetime
Bases: ModelSettings
Settings used for an Anthropic model request.
An object describing metadata about the request.
Contains user_id, an external identifier for the user who is associated with the request.
Type: BetaMetadataParam
Determine whether the model should generate a thinking block.
See the Anthropic docs for more information.
Type: BetaThinkingConfigParam
Whether to add cache_control to the last tool definition.
When enabled, the last tool in the tools array will have cache_control set,
allowing Anthropic to cache tool definitions and reduce costs.
If True, uses TTL=‘5m’. You can also specify ‘5m’ or ‘1h’ directly.
See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching for more information.
Type: bool | Literal[‘5m’, ‘1h’]
The service tier to use for the model request.
See https://docs.anthropic.com/en/docs/build-with-claude/latency-and-throughput for more information.
Type: Literal[‘auto’, ‘standard_only’]
Whether to add cache_control to the last system prompt block.
When enabled, the last system prompt will have cache_control set,
allowing Anthropic to cache system instructions and reduce costs.
If True, uses TTL=‘5m’. You can also specify ‘5m’ or ‘1h’ directly.
See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching for more information.
Type: bool | Literal[‘5m’, ‘1h’]
Whether to add cache_control to the last message content block.
This is an alternative to anthropic_cache for Anthropic-compatible gateways and
proxies that accept the Anthropic message format but don’t support the top-level
automatic caching parameter.
If True, uses TTL=‘5m’. You can also specify ‘5m’ or ‘1h’ directly.
Cannot be combined with anthropic_cache.
Type: bool | Literal[‘5m’, ‘1h’]
Enable prompt caching for multi-turn conversations.
Passes a top-level cache_control parameter so the server automatically applies a
cache breakpoint to the last cacheable block and moves it forward as conversations grow.
Where the model profile’s supports_auto_cache is False, such as on the legacy AsyncAnthropicBedrock
client with models not documented to support it, this falls back to per-block caching on the last user message.
If the last content block already has cache_control from an explicit CachePoint, it is preserved.
If True, uses TTL=‘5m’. You can also specify ‘5m’ or ‘1h’ directly.
This can be combined with explicit cache breakpoints (anthropic_cache_instructions,
anthropic_cache_tool_definitions, CachePoint). The automatic breakpoint counts as
1 of Anthropic’s 4 cache point slots; we automatically trim excess explicit breakpoints.
See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#automatic-caching
for more information.
Type: bool | Literal[‘5m’, ‘1h’]
Request cache diagnostics on every request.
When enabled, each request carries a diagnostics object naming the most recent Anthropic response in the
message history as previous_message_id (or null when there is none, which opts the request in so the next
one can be compared against it). Anthropic compares the two requests and reports where the prompt prefix
first diverged. The result is available in
ModelResponse.provider_details under the
'cache_diagnostics' key, as Anthropic’s diagnostics object: \{'cache_miss_reason': \{'type': ..., 'cache_missed_input_tokens': ...\}\}, or \{'cache_miss_reason': None\} when the comparison was still running.
The key is absent when Anthropic found no divergence.
Diagnostics are free and don’t affect caching, but Anthropic retains a short-lived fingerprint (hashes and
token counts, never prompt content) for each request that carries them, and HIPAA-enabled organizations have
requests using them rejected. They are only available on the Claude API, so the setting is ignored on Amazon
Bedrock, Google Cloud Vertex AI and Microsoft Foundry. Defaults to False. The ID comes from the message
history, which sanitize_messages keeps as sent, so leave this off
with history from a client; see Loading untrusted history.
Type: bool
The effort level for the model to use when generating a response.
See the Anthropic docs for more information.
Type: AnthropicEffort | None
Task budget configuration for Anthropic beta requests.
Maps to output_config.task_budget. Supported models are gated by the
anthropic_supports_task_budgets
profile flag, and Pydantic AI automatically enables Anthropic’s required task-budget beta when
this setting is present.
Omit remaining unless you are intentionally carrying a budget across compaction
or other rewritten context.
Type: AnthropicTaskBudget
Container configuration for multi-turn conversations.
By default, if previous messages contain a container_id (from a prior response),
it will be reused automatically on requests that have code execution: CodeExecutionTool,
or WebSearchTool or WebFetchTool where code execution may call them: on Anthropic’s
20260209 and 20260318 versions by default, unless citations route them to direct calls, which only happens
on the Anthropic API, and on any version when anthropic_web_tools_allowed_callers names a code
execution caller. The Anthropic API rejects a container on any other request, so
Pydantic AI doesn’t send it there. Tools passed in extra_body['tools'] aren’t read, so a
request that carries them still sends it. An id recovered from history is the only container
Pydantic AI may replace on its own: if a request carrying both that id and CodeExecutionTool
uploads comes back 500, the id is dropped and the request is sent once more so the upload
lands in a fresh container. Nothing else is replaced — not a container you set here, and not
the id used to reconnect a paused turn — so a request pinning a container the API will not
accept raises instead.
Set to False to force a fresh container (ignore any container_id from history).
Set to a container id string (e.g. 'container_xxx') to explicitly reuse a container,
or to a BetaContainerParams dict (e.g. {'skills': [...]} or
{'id': 'container_xxx', 'skills': [...]}) when passing Skills to the Anthropic
Skills beta.
Reuse from history trusts the message history for the container_id, which
sanitize_messages keeps as sent. With history from a client, set a
container id you saved on your server, or False; see
Loading untrusted history.
Type: BetaContainerParams | str | Literal[False]
Which Anthropic code execution tool version to send for CodeExecutionTool.
Defaults to 'auto', which uses the default version from the model profile:
'20260120' for Sonnet 4.5+ and Opus 4.5+, otherwise '20250825'.
Set a concrete version to force that tool version; a UserError is raised if
the selected model profile does not support that version.
Type: AnthropicCodeExecutionToolVersion | Literal[‘auto’]
Who may invoke WebSearchTool and
WebFetchTool, sent as their allowed_callers.
By default the field is omitted and Anthropic picks the caller from the tool version. The
20260209 and 20260318 versions of web search and web fetch let the model call the tools from code
execution, which gives it a server-side code execution sandbox to filter results in (“dynamic
filtering”) even when CodeExecutionTool is not
enabled. Results the model reads from code execution come back without citations, so when a request
asks for citations, with Citations and text output or, for
web fetch, enable_citations,
Pydantic AI sends ['direct'] on those versions of the cited tools on the Anthropic API, unless the
request needs code execution. See Web Tool Callers.
Set ['direct'] to have the model always call the web tools itself with no sandbox, which turns off
dynamic filtering and makes the tools eligible for Zero Data Retention. A value set here is sent
on whichever web tool version the model uses, and takes precedence over the citations default. A
code execution caller gives the model the sandbox on any version. Anthropic rejects an empty list,
code_execution_20250825, and a code execution caller on models without programmatic tool calling,
such as Claude Haiku 4.5.
See the Anthropic docs.
Tools passed as extra_body['tools'] replace the ones Pydantic AI builds, so the setting isn’t
applied to a request that has them.
Type: list[AnthropicWebToolCaller]
Whether to enable eager input streaming on tool definitions.
When enabled, all tool definitions will have eager_input_streaming set to True,
allowing Anthropic to stream tool call arguments incrementally instead of buffering
the entire JSON before streaming. This reduces latency for tool calls with large inputs.
See https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming for more information.
Type: bool
List of Anthropic beta features to enable for API requests.
Each item can be a known beta name (e.g. ‘interleaved-thinking-2025-05-14’) or a custom string.
Merged with auto-added betas (e.g. builtin tools), any betas from an anthropic-beta header in
extra_headers, however its name is capitalized, and those in the client’s default_headers, except on
AsyncAnthropicBedrock, where Bedrock ignores them. See the Anthropic docs for available beta features.
Type: list[AnthropicBetaParam]
The inference speed mode for this request.
'fast' enables high output-tokens-per-second inference for supported models (currently Claude Opus 4.6, 4.7, 4.8,
5, and 5.5, Fable 5.2, and Mythos 5.2).
On unsupported models or clients, anthropic_speed='fast' is ignored with a UserWarning.
Fast mode is only available on the direct Anthropic API (not Bedrock, Vertex, or Foundry);
see Fast mode for each model’s availability.
A response that ran in fast mode records 'speed': 'fast' in provider_details, which prices it at fast mode rates.
Note: switching between 'fast' and 'standard' invalidates the prompt cache.
Type: Literal[‘standard’, ‘fast’]
Context management configuration for automatic compaction.
When configured, Anthropic will automatically compact older context when the input token count exceeds the configured threshold. The compaction produces a summary that replaces the compacted messages.
See the Anthropic docs for more details.
Type: BetaContextManagementConfigParam
Bases: Model[AsyncAnthropicClient]
A model that uses the Anthropic API.
Internally, this uses the Anthropic Python client to interact with the API.
Apart from __init__, all methods are private or match those of the base class.
The model name.
Type: AnthropicModelName
The model provider.
Type: str
The model profile.
Anthropic web-tool availability depends on both model support and the client/platform, so the
profile’s supported_native_tools and anthropic_supports_dynamic_filtering are narrowed here
for clients that don’t support them (e.g. Bedrock, Vertex). supports_inline_system_prompts is
narrowed the same way, and for the same reason: serving a {'role': 'system'} entry is a fact
about the transport as much as about the model. Thinking-block binding is likewise narrowed, but
by client class rather than by base URL: its beta and drop-block retry are verified against
Anthropic’s Messages API, which a proxied or gateway AsyncAnthropic still reaches.
Type: AnthropicModelProfile
The effective addition mode, narrowed for transports without inline system messages.
Type: Literal[‘by_reference’] | None
def __init__(
model_name: AnthropicModelName,
*,
provider: Literal['anthropic', 'gateway'] | Provider[AsyncAnthropicClient] = 'anthropic',
profile: ModelProfileSpec | None = None,
settings: ModelSettings | None = None,
)
Initialize an Anthropic model.
The name of the Anthropic model to use. List of model names available here.
provider : Literal[‘anthropic’, ‘gateway’] | Provider[AsyncAnthropicClient] Default: 'anthropic'
The provider to use for the Anthropic API. Can be either the string ‘anthropic’ or an
instance of Provider[AsyncAnthropicClient]. Defaults to ‘anthropic’.
profile : ModelProfileSpec | None Default: None
The model profile to use. Defaults to a profile picked by the provider based on the model name.
The default ‘anthropic’ provider will use the default ..profiles.anthropic.anthropic_model_profile.
settings : ModelSettings | None Default: None
Default model settings for this model instance.
@classmethod
def supported_native_tools(cls) -> frozenset[type[AbstractNativeTool]]
The set of builtin tool types this model can handle.
frozenset[type[AbstractNativeTool]]
def unsupported_native_tool_settings(native_tool: AbstractNativeTool) -> frozenset[str]
Return native_tool’s restricting settings that Anthropic’s web tools don’t take: external_web_access=False.
@async
def compact_messages(
request_context: ModelRequestContext,
*,
instructions: str | None = None,
) -> ModelResponse
Compact messages with Anthropic’s on-demand compaction.
This sends the conversation to the Messages API with the compaction parameter, which summarizes it instead
of replying. It reads the conversation’s prompt cache, like any other request with the same prefix. The
returned ModelResponse holds a single CompactionPart with the readable summary, and its signature in
provider_details. Keep it in the message history: later requests send it back in place of the messages
before it, with the compact-2026-09-04 beta that it needs. Only Claude models that support on-demand
compaction accept the block.
The parameters Anthropic rejects on a compaction request are left out of it: stop_sequences, structured
output’s output_config.format, the remaining task budget and anthropic_context_management. A forcing
tool_choice is relaxed to auto, and the calls of a trailing response that has no tool results yet are
dropped. Images and documents in the summarized messages don’t survive compaction.
ModelResponse — A ModelResponse with a single CompactionPart containing the summary.
request_context : ModelRequestContext
The model request context containing messages, settings, and parameters.
Optional focus for the summary, such as what to keep. Anthropic replaces its whole
summarization prompt with the instructions it’s given, so the focus is sent inside a full
summarization prompt rather than on its own. On OpenAI, instructions replaces the agent’s
instructions for the compaction request instead.
UserError— If the model doesn’t support on-demand compaction, according to itsanthropic_supports_on_demand_compactionprofile flag.UnexpectedModelBehavior— If Anthropic returns no summary, for example whenmax_tokenscuts it off.
Bases: AbstractCapability[AgentDepsT]
Compaction capability for Anthropic models.
Configures automatic context management via Anthropic’s context_management
API parameter. Compaction triggers server-side when input tokens exceed
the configured threshold.
Example usage:
from pydantic_ai import Agent
from pydantic_ai.models.anthropic import AnthropicCompaction
agent = Agent(
'anthropic:claude-sonnet-4-6',
capabilities=[AnthropicCompaction(token_threshold=100_000)],
)
def __init__(
*,
token_threshold: int = 150000,
instructions: str | None = None,
pause_after_compaction: bool = False,
) -> None
Initialize the Anthropic compaction capability.
token_threshold : int Default: 150000
Compact when input tokens exceed this threshold. Minimum 50,000.
Custom instructions for the compaction summarization.
pause_after_compaction : bool Default: False
If True, the response will stop after the compaction block
with stop_reason='compaction', allowing explicit handling.
Latest Anthropic models: per line, the newest model of the newest generation and of the previous one.
Default: Literal['claude-fable-5-2', 'claude-opus-5-5', 'claude-sonnet-5-5', 'claude-haiku-5-5', 'claude-opus-4-8', 'claude-sonnet-4-6', 'claude-haiku-4-5']
Possible Anthropic model names.
The Literal lists the models to pick from, for autocomplete. Any other model id the API accepts works too, as a str.
See the Anthropic docs for a full list.
Default: str | LatestAnthropicModelNames
Models that have been retired by Anthropic but are still present in the SDK’s type definitions.
Type: frozenset[str] Default: frozenset({'claude-3-haiku-20240307', 'claude-opus-4-0', 'claude-opus-4-20250514', 'claude-sonnet-4-0', 'claude-sonnet-4-20250514'})
Anthropic task budget payload for output_config.task_budget.
Type: TypeAlias Default: BetaTokenTaskBudgetParam
Who may invoke Anthropic’s web search and web fetch tools, as sent in their allowed_callers field.
Type: TypeAlias Default: Literal['direct', 'code_execution_20250825', 'code_execution_20260120', 'code_execution_20260521']