Alloy.Provider.Anthropic (alloy v0.13.0)

Copy Markdown View Source

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}]. Every anthropic-beta value is merged into a single anthropic-beta header. Alloy adds context-management-2025-06-27 itself when :extra_body sets context_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_tools to 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 an mcp_toolset (default: []). For example [%{"type" => "web_search_20260209", "name" => "web_search"}]. Add any request fields or beta headers they need through :extra_body and :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 via Alloy.stream/3, event is 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_event option of Alloy.stream/3. Note: direct callers of Alloy.Provider.Anthropic.stream/4 (without Turn) receive provider-native tuples (for example {:thinking_delta, text}).
  • :code_execution - true adds 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

Types

Configuration for the Anthropic provider. See the module doc for field semantics.

Functions

Stream a completion using Anthropic's SSE streaming API.

Types

config()

@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

stream(messages, tool_defs, config, on_chunk)

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