Anthropic (Claude)

Anthropic provides the Claude model family — Opus, Sonnet, and Haiku — for chat, extended reasoning, vision, and tool use. UGENT integrates through the native anthropic provider type, which routes to the Messages API (/v1/messages) with proper thinking objects and mandatory max_tokens.

Overview

Capability	Models	API
Chat / reasoning	claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5	Messages API
Adaptive thinking	Same	Thinking blocks in Messages API
Vision / image understanding	Same	Image content blocks
Web search (server-side tool)	Same	web-search-2025-03-05 beta
Prompt caching	Same	Per-block cache_control
Preserved thinking	claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5	thinking.block_binding

Current models at a glance:

Model	Context	Max output	Default effort	Notes
claude-opus-5-5	1M	128K	medium	Flagship. Thinking cannot be turned off.
claude-sonnet-5-5	1M	128K	high	Speed and capability. Turns thinking off with between_tools.
claude-haiku-5-5	1M	128K	medium	Lowest price. Turns thinking off with disabled.
claude-haiku-4-5	200K	64K	not supported	Previous generation; uses budget_tokens, not effort.

Opus 5.5 and Haiku 5.5 default to medium effort rather than high, so leaving effort unset there runs a level shallower than it would on the other models. UGENT warns about this at startup, and once at request time when a turn switches to one of them with no effort configured.

Haiku 5.5 bills a prompt over 100K tokens at five times its base rate; UGENT's cost estimate uses the base rate.

Quick Start

[llm]
default_instance = "opus"

[llm.instances.opus]
type = "anthropic"
api_key = "$ANTHROPIC_API_KEY"
default_model = "claude-opus-5-5"
context_window = 1000000
max_tokens = 128000

temperature on current models

On every Claude model from 4.7 on, Haiku 5.5 included, any non-default temperature, top_p or top_k returns a 400 (on Amazon Bedrock, Haiku 5.5 refuses any temperature but 1). UGENT omits temperature for these models, by catalog entry or by model generation, so a temperature line is inert on them and needs no removing. See Temperature.

Store your API key securely. Copy it to your clipboard, then pipe it in, so it never appears in your shell history:

macOS

pbpaste | ugent secret add @anthropic_api_key --provider anthropic --kind api-key --stdin

Linux X11

xclip -selection clipboard -o | ugent secret add @anthropic_api_key --provider anthropic --kind api-key --stdin

Vault & Secrets has the Wayland and Windows forms. Then reference the key with its vault handle:

[llm.instances.opus]
api_key_ref = "@anthropic_api_key"

Token Limits

Claude models require max_tokens (it is mandatory, not optional):

[llm.instances.opus]
type = "anthropic"
api_key_ref = "@anthropic_api_key"
default_model = "claude-opus-5-5"
context_window = 1000000     # total context (input + output)
max_tokens = 128000          # mandatory for Anthropic; the output cap

max_tokens is the output cap, not the context window. The current 1M-context models cap output at 128K, and a larger value is rejected: UGENT sends the value you set.

When max_tokens = 0 (auto mode), UGENT sends the model's output limit from the model catalog, and 128000 for a model the catalog does not know.

Adaptive Thinking (Reasoning)

Current Claude models use adaptive thinking: the model decides how much to think, and effort sets the depth.

[llm.instances.opus.reasoning]
mode = "adaptive"            # disabled | enabled | adaptive
effort = "high"              # low | medium | high | xhigh | max

Anthropic has no level below low. effort = "minimal" is accepted for cross-provider configs but is sent as low, so write low if that is what you mean. On models older than Opus 4.7, xhigh is sent as max.

• mode = "adaptive" — Claude decides when and how much to think. The right choice on every current model.

• mode = "enabled" — manual thinking with budget_tokens. Rejected with a 400 by every Claude model from 4.7 on, Haiku 5.5 included; UGENT upgrades it to adaptive and warns. Keep it only for Haiku 4.5 and older models.

• mode = "disabled" — turns thinking off where the model allows it. What that means on the wire differs by model, and UGENT resolves it for you:

  Model	What "disabled" sends
  claude-sonnet-5-5	thinking.type = "between_tools"
  claude-haiku-5-5, claude-opus-5, claude-sonnet-5	thinking.type = "disabled"
  claude-opus-4-8 and earlier	the field is omitted, which already means off
  claude-opus-5-5	nothing — this model cannot turn thinking off; lower effort instead

  On Sonnet 5.5, Haiku 5.5 and Opus 5, turning thinking off is rejected above high effort. UGENT clamps effort to high for those requests rather than abandoning the mode, and warns. If you wanted the deeper thinking, set mode = "adaptive".

Why this matters

On Opus 5, Sonnet 5, Sonnet 5.5 and Haiku 5.5, an absent thinking field means adaptive thinking is on. Simply omitting it — which is what "disabled" used to do — bought billed reasoning with no error. UGENT now sends the form each model actually requires.

Display

How much of the reasoning comes back:

[llm.instances.opus.reasoning]
mode = "adaptive"            # required whenever the block exists

[llm.instances.opus.reasoning.provider.anthropic]
display = "summarized"       # omitted | summarized | updates

• omitted (the API default on current models) — thinking blocks arrive with empty text. Reasoning still happens and is still billed.
• summarized — a readable summary of the reasoning. Use this if you stream thinking to users.
• updates — hides the reasoning but returns the short progress notes the model writes between tool calls. Supported on Opus 5.5, Sonnet 5.5 and the Fable family; UGENT falls back to summarized elsewhere, Haiku 5.5 included, and warns. The TUI shows these notes as a one-line status; they are never sent to channels or the web client as answer text.

Without summarized or updates, a streaming interface looks like a long pause before output.

Preserved Thinking

On claude-opus-5-5, claude-sonnet-5-5 and claude-haiku-5-5, a thinking block is valid only in the conversation that produced it. Editing the system prompt, the tool set, or any earlier message invalidates every block after the edit.

[llm.instances.opus.reasoning]
mode = "adaptive"

[llm.instances.opus.reasoning.provider.anthropic]
block_binding = "auto"       # auto | drop_block | error | off

• auto (default) — sends drop_block to endpoints UGENT recognises as speaking the Messages API, so a mismatch drops the block and is reported rather than failing the request.
• error — a mismatch returns a 400. Useful in CI to catch prefix edits.
• off — sends no control and relies on strip-and-retry recovery.

Thinking blocks are also bound to the model that produced them. Switching model mid-conversation drops the blocks the new model cannot read; the request still succeeds and the dropped blocks are not billed.

Interleaved Thinking

For manual thinking with tools on models that need it (Claude Sonnet 4.6), UGENT automatically adds the interleaved-thinking-2025-05-14 beta header. This allows thinking blocks to appear between tool calls, improving multi-step reasoning quality.

Prompt Caching

Anthropic supports prompt caching to reduce latency and cost on repeated context. UGENT injects per-block cache_control markers:

[llm.instances.opus.cache]
enabled = true

[llm.instances.opus.cache.provider.anthropic]
type = "ephemeral"           # only "ephemeral" is supported
ttl = "5m"                   # optional: "5m" or "1h" (server-side TTL)

Bedrock compatibility

Per-block cache_control is the only format AWS Bedrock accepts. UGENT always uses per-block markers (never the top-level cache_control field), so the same config works with both native Anthropic and Bedrock.

Built-in Web Search

Ground responses with real-time web search through Anthropic's server-side tool:

[llm.instances.opus.builtin_search]
enabled = true

[llm.instances.opus.builtin_search.anthropic]
max_uses = 5                 # optional: max search calls per response
allowed_domains = []         # optional: restrict to these domains
blocked_domains = []         # optional: block these domains

When enabled, UGENT adds the web-search-2025-03-05 beta header and the server-side web search tool to the request automatically.

Vision (Image Understanding)

Claude models accept images natively. No extra config needed — just attach an image in the chat and Claude will analyze it:

[llm.instances.opus]
# same config — image input is automatic when you attach an image

UGENT handles the base64 encoding and content block formatting for the Messages API.

Anthropic vs OpenAI-Compatible for Claude

For Claude models, type = "anthropic" is strongly recommended. It routes to the native Messages API with:

• Proper thinking objects (not translated from OpenAI format)
• Mandatory max_tokens handled correctly
• Native prompt caching support
• No translation-proxy edge cases

The openai-compatible path works as a fallback (e.g., through an OpenAI-compatible gateway), but remains a compatibility layer.

# Preferred:
[llm.instances.claude]
type = "anthropic"
api_key_ref = "@anthropic_api_key"
default_model = "claude-opus-5-5"

# Fallback (via proxy):
[llm.instances.claude_proxy]
type = "openai-compatible"
base_url = "https://your-proxy.example.com/v1"
api_key_ref = "@proxy_api_key"
default_model = "claude-opus-5-5"

AWS Bedrock

Bedrock serves Claude through the Anthropic Messages API, so the native anthropic provider type works directly — no proxy required.

Option 1: Bedrock API key (recommended)

Bedrock's Messages endpoints take the same request body as Anthropic's own API, with anthropic-version and anthropic-beta as HTTP headers. Point base_url at one and pass an Amazon Bedrock API key as the credential:

[llm.instances.bedrock]
type = "anthropic"
base_url = "https://bedrock-mantle.us-east-1.api.aws/anthropic"
api_key_ref = "@bedrock_api_key"
default_model = "anthropic.claude-opus-5-5"
context_window = 1000000
max_tokens = 128000

Model ids carry the anthropic. prefix on Bedrock. UGENT finds the catalog entry through it, and through a region profile (us., eu.) or a version suffix, so pricing and limits need no setting; see Gateway model ids. Set catalog_model only for a name the matching cannot see through, such as an alias of your own.

https://bedrock-runtime.{region}.amazonaws.com/anthropic works the same way. Note the /anthropic suffix: without it that host is the older InvokeModel operation, which takes betas as a body field and requires SigV4 signing — UGENT does not speak it.

Because these endpoints carry anthropic-beta headers, features that ride a beta work on Bedrock as they do on the first-party API, including the preserved-thinking block-binding control that Sonnet 5.5 needs.

Option 2: Via a SigV4 proxy

If your deployment requires IAM/SigV4 rather than a Bedrock API key, put a signing proxy in front and treat it as an OpenAI-compatible endpoint:

[llm.instances.bedrock_proxy]
type = "openai-compatible"
base_url = "https://your-bedrock-proxy.example.com/v1"
api_key_ref = "@bedrock_proxy_key"
default_model = "anthropic.claude-opus-5-5"

A proxy may strip the anthropic-beta header. UGENT withholds the block-binding control from endpoints it cannot identify for that reason, so a preserved-thinking model behind an unrecognised gateway relies on strip-and-retry recovery instead.

Option 3: Native Anthropic API

If you have direct Anthropic API access (not through Bedrock), use the native type:

[llm.instances.claude]
type = "anthropic"
api_key_ref = "@anthropic_api_key"
default_model = "claude-opus-5-5"

Bedrock Model Naming

Bedrock uses a prefix format for model IDs:

Bedrock Model ID	Standard Model Name
anthropic.claude-opus-5-5	claude-opus-5-5
anthropic.claude-sonnet-5-5	claude-sonnet-5-5
anthropic.claude-haiku-5-5	claude-haiku-5-5
anthropic.claude-haiku-4-5	claude-haiku-4-5

Regional variants use a region prefix: us.anthropic.claude-opus-5-5, eu.anthropic.claude-haiku-5-5.

TIP

UGENT automatically handles Bedrock-specific requirements: per-block cache_control format (Bedrock rejects top-level cache_control), and reasoning block signature validation. These are transparent — no extra config needed.

Complete Configuration Example

[llm]
default_instance = "opus"

[llm.instances.opus]
type = "anthropic"
api_key_ref = "@anthropic_api_key"
default_model = "claude-opus-5-5"
context_window = 1000000
max_tokens = 128000

# Adaptive thinking
[llm.instances.opus.reasoning]
mode = "adaptive"
effort = "high"

[llm.instances.opus.reasoning.provider.anthropic]
display = "summarized"

# Prompt caching
[llm.instances.opus.cache]
enabled = true

[llm.instances.opus.cache.provider.anthropic]
type = "ephemeral"

# Built-in web search
[llm.instances.opus.builtin_search]
enabled = true

[llm.instances.opus.builtin_search.anthropic]
max_uses = 5

Using Anthropic with Other Providers

[llm]
default_instance = "opus"

[llm.instances.opus]
type = "anthropic"
api_key_ref = "@anthropic_api_key"
default_model = "claude-opus-5-5"

[llm.instances.haiku]
type = "anthropic"
api_key_ref = "@anthropic_api_key"
default_model = "claude-haiku-5-5"

[llm.instances.gpt]
type = "openai"
api_key_ref = "@openai_api_key"
default_model = "gpt-6-sol"

[llm.instances.gemini]
type = "google"
api_key_ref = "@google_api_key"
default_model = "gemini-3.8-flash"

Switch with /providers use opus, /providers use gpt, or /providers use gemini, or send one message elsewhere with /with haiku <prompt>. Cross-provider reasoning blocks are handled safely — thinking authored by Anthropic is dropped before replay to OpenAI or Google, preventing signature validation errors.