Anthropic

Use Claude through Anthropic's Messages API. BeamWeaver preserves native thinking and server-tool blocks for continuation and supports structured answers, caching, token counting and supported compaction requests.

Setup and first request

import Config
config :beam_weaver, :anthropic, api_key: System.fetch_env!("ANTHROPIC_API_KEY")

Save configuration in your runtime file, then run:

alias BeamWeaver.Core.{ChatModel, Message}
{:ok, model} = BeamWeaver.Models.init_chat_model("anthropic:claude-haiku-4-5", max_tokens: 512, timeout: 60_000)
{:ok, reply} = ChatModel.invoke(model, "Explain parcel tracking in one sentence.")
true = byte_size(Message.text(reply)) > 0
true = reply.usage_metadata.total_tokens > 0

Use the same identifier in an agent module. Set explicit output/time budgets; the provider's maximum output is usually excessive for a short application task.

Thinking and effort

Budget-based thinking and adaptive thinking are different model contracts. Haiku 4.5 and some earlier models accept enabled thinking with a token budget; newer families use adaptive thinking and supported effort levels. Some current models cannot disable thinking. Profiles expose accepted combinations.

Preserve full returned messages, including signatures and native thinking blocks, across tool rounds. Message.text/1 is for display, not lossless history. Reasoning and visible answer tokens both affect the requested output budget.

For a model with a thinking budget, configure the budget and make an actual request:

defmodule MyApp.SupportAgent do
  use BeamWeaver.Agent

  model "anthropic:claude-sonnet-4-6", thinking: %{type: :enabled, budget_tokens: 4_096}, timeout: 120_000
  system_prompt "You are Acme's support agent."
end

{:ok, result} = MyApp.SupportAgent.invoke(%{messages: ["Reply with the word ready."]})
true = byte_size(result.messages |> List.last() |> BeamWeaver.Core.Message.text()) > 0

For adaptive thinking models, choose an effort level accepted by that model:

defmodule MyApp.SupportAgent do
  use BeamWeaver.Agent

  model "anthropic:claude-opus-5-5", reasoning_effort: :high, timeout: 120_000
  system_prompt "You are Acme's support agent."
end

{:ok, result} = MyApp.SupportAgent.invoke(%{messages: ["Reply with the word ready."]})
true = byte_size(result.messages |> List.last() |> BeamWeaver.Core.Message.text()) > 0

Options

Native metadata accepts user_id rather than arbitrary application fields. Use trace metadata for your own labels. Adaptive-model sampling and manual thinking-budget restrictions are validated before HTTP execution.

Server tools

This call asks for a hosted search and checks the returned server-tool record:

{:ok, search_model} =
  BeamWeaver.Models.init_chat_model("anthropic:claude-sonnet-4-6", max_tokens: 1_024, timeout: 120_000)

{:ok, searched} =
  ChatModel.invoke(
    search_model,
    "Use web search to find the official Elixir programming language website and return its URL.",
    tools: [BeamWeaver.Anthropic.Tools.web_search()]
  )

true = byte_size(Message.text(searched)) > 0
true = Enum.any?(List.wrap(searched.content), &(Map.get(&1, :type) == :server_tool_call))

Hosted helpers include search/fetch, code execution, tool search, MCP toolsets and advisor declarations where the selected model supports them. Preserve server results unchanged for later requests.

Bash, text editor, memory and computer declarations are client tools. Your application must implement their execution loop. Computer use also requires display dimensions and a model-compatible tool revision; a declaration alone does not control a desktop. The helper defaults and current revisions are documented in BeamWeaver.Anthropic.Tools.

For BeamWeaver-managed actions, use Tools , Filesystem and Sandboxes .

Structured output

Use response_schema in an agent or direct response_format: with a supported model. The request builder closes object schemas for the native contract while preserving optional fields. Local answer validation has a narrower scope than full JSON Schema; see Structured Output . Some newer Claude models allow only auto/none tool choice, so schema-tool output cannot always be forced.

Prompt caching

Cache-control markers make eligible prefixes cacheable; provider length and expiry requirements still apply. prompt_caching true marks agent instructions. On direct requests, cache controls can mark the prefix or content blocks. Inspect actual cache reads; a short successful call is not a verified hit. Caching links the repeated-call example.

Mark a stable prefix and inspect actual cache usage over repeated provider calls. The complete policy text is inline:

alias BeamWeaver.Core.{ChatModel, ContentBlock, Message}

policy =
  String.duplicate(
    "Refunds go to the original card within five business days. Opened goods require staff review.\n",
    180
  )

messages = [
  Message.user([ContentBlock.text(policy, %{cache_control: %{type: "ephemeral"}})]),
  Message.user("How long does a refund take?")
]

model = BeamWeaver.Models.init_chat_model!("anthropic:claude-haiku-4-5", max_tokens: 256, timeout: 120_000)

usage =
  for _ <- 1..2 do
    {:ok, reply} = ChatModel.invoke(model, messages)
    true = byte_size(Message.text(reply)) > 0
    Map.get(reply.usage_metadata, :input_token_details, %{})
  end

IO.inspect(usage, label: "Provider-reported prefix cache usage")

Compaction

Supported Claude 5.5 models can return a provider-native compaction message. Keep it unchanged when continuing:

{:ok, compacting} = BeamWeaver.Models.init_chat_model("anthropic:claude-opus-5-5", max_tokens: 2_048, timeout: 120_000)
history = [Message.user("My order ID is A-1001."), Message.assistant("I will refer to order A-1001.")]

{:ok, summary} =
  ChatModel.invoke(compacting, history, compaction: %{type: :summarize, instructions: "Preserve the order ID."})

"compaction" = summary.status
{:ok, recalled} = ChatModel.invoke(compacting, [summary, Message.user("What is my order ID?")])
true = Message.text(recalled) =~ "A-1001"

Compaction cannot end on an unanswered tool call or combine incompatible forced-tool/schema requests. This native operation is separate from BeamWeaver's agent context policy and application-owned compaction engine .

Token counting

{:ok, tokens} = BeamWeaver.Anthropic.ChatModel.count_tokens(model, "Check order A-1001.")
true = is_integer(tokens) and tokens > 0

Token counting is a provider request, not inference. It does not establish that the model can complete your actual tool/answer workload.

Models

Limits are local profile data. A dash means not applicable or not recorded, not an unlimited allowance.

Sonnet 4.5 is deprecated and scheduled to retire on November 30, 2026, with Sonnet 5.5 as its recommended replacement. See Anthropic's retirement schedule .

Undated aliases can follow newer snapshots. Restricted Mythos profiles do not imply account entitlement; check Anthropic's model availability . This integration targets Anthropic's API, not Bedrock or Vertex routing. Files/managed-agent resource management is outside the wrapper.

Further reading

The official structured-output contract describes native schema constraints. Testing covers scripted behavior and replay.