Provider for Anthropic's Claude Messages API.
Uses Req for HTTP calls. Since Anthropic's wire format uses content blocks (the most expressive format), this provider has the simplest normalization.
Config
Required:
:api_key- Anthropic API key:model- Model name (e.g., "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5")
Optional:
:max_tokens- Max output tokens, thinking included (default: 16_000). Thinking is on by default on Claude 5.x models and counts toward this limit, so a low value can cut off the answer (stop_reason: :max_tokens). Raise it for long outputs or high effort.:system_prompt- System prompt string:api_url- Base URL (default: "https://api.anthropic.com"):api_version- API version header (default: "2023-06-01"):extra_headers- Additional headers as[{name, value}]. Everyanthropic-betavalue is merged into a singleanthropic-betaheader. Alloy addscontext-management-2025-06-27itself when:extra_bodysetscontext_management; the other features it drives are GA and need no beta.:extra_body- Additional request body fields, merged last. A"tools"key here replaces every tool Alloy generates; use:server_toolsto add tools instead.:server_tools- Raw tool maps sent after Alloy's own tools, for Anthropic-run tools such as web search, web fetch, tool search or anmcp_toolset(default:[]). For example[%{"type" => "web_search_20260209", "name" => "web_search"}]. Add any request fields or beta headers they need through:extra_bodyand:extra_headers.:req_options- Additional options passed to Req (useful for testing):on_event- Streaming event callback(event -> :ok). Called for each streaming delta. When used viaAlloy.stream/3,eventis a normalized envelope map:%{v: 1, seq:, correlation_id:, turn:, ts_ms:, event: :text_delta, payload: text}%{v: 1, seq:, correlation_id:, turn:, ts_ms:, event: :thinking_delta, payload: text}Pass it as the:on_eventoption ofAlloy.stream/3. Note: direct callers ofAlloy.Provider.Anthropic.stream/4(without Turn) receive provider-native tuples (for example{:thinking_delta, text}).
:code_execution-trueadds the server-side code execution tool (code_execution_20260521)
Thinking
Claude 5.x models think by default (adaptive thinking); Claude Opus 4.6 to
4.8 and Sonnet 4.6 think once asked. Configure thinking with :extra_body:
extra_body: %{
"thinking" => %{"type" => "adaptive", "display" => "summarized"},
"output_config" => %{"effort" => "high"}
}"display" => "summarized" returns the thinking text; most current models
default to "omitted", which returns thinking blocks with an empty
thinking field and only the signature. output_config.effort ("low",
"medium", "high", and on some models "xhigh" or "max") sets how
much the model thinks. Thinking counts toward :max_tokens. Thinking
blocks come back in the message content and are sent back verbatim on
later turns, as the API requires. See
https://platform.claude.com/docs/en/build-with-claude/thinking and
https://platform.claude.com/docs/en/build-with-claude/effort.
Programmatic tool calling
With code_execution: true, Claude can call your tools from code it runs
in the sandbox. Opt a tool in with allowed_callers: [:code_execution]
(sent as "code_execution_20260120"); :human and :direct are sent as
"direct", and strings pass through unchanged. Such calls arrive as
ordinary tool calls with a :caller field, which Alloy sends back with the
history. The response's container id is kept in provider_state as
:container_id (with :container_expires_at) and sent as "container" on
the next request, which the API requires while a programmatic call is
waiting for its result. An expired container is not sent, so a session that
resumes after the container was reclaimed gets a fresh one. See
https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.
Example
Alloy.run("What is Elixir?",
provider: {Alloy.Provider.Anthropic,
api_key: System.get_env("ANTHROPIC_API_KEY"),
model: "claude-sonnet-4-6"
}
)
Summary
Functions
Stream a completion using Anthropic's SSE streaming API.
Types
@type config() :: %{ :api_key => String.t(), :model => String.t(), optional(:max_tokens) => pos_integer(), optional(:system_prompt) => String.t(), optional(:api_url) => String.t(), optional(:api_version) => String.t(), optional(:extra_headers) => [{String.t(), String.t()}], optional(:extra_body) => map(), optional(:server_tools) => [map()], optional(:req_options) => keyword(), optional(:on_event) => (term() -> :ok), optional(:cache) => boolean(), optional(:code_execution) => boolean(), optional(:provider_state) => map() }
Configuration for the Anthropic provider. See the module doc for field semantics.
Functions
@spec stream( [Alloy.Message.t()], [Alloy.Provider.tool_def()], config(), (String.t() -> :ok) ) :: {:ok, Alloy.Provider.completion_response()} | {:error, term()}
Stream a completion using Anthropic's SSE streaming API.
Calls on_chunk for each text delta as it arrives. Accumulates all
content blocks and returns the same {:ok, completion_response()} shape
as complete/3 once the stream finishes.