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-4-8, claude-sonnet-4-6	Messages API
Extended 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
Interleaved thinking	Same	interleaved-thinking-2025-05-14 beta

Quick Start

[llm]
default_instance = "opus"

[llm.instances.opus]
type = "anthropic"
api_key = "$ANTHROPIC_API_KEY"
default_model = "claude-opus-4-8"
context_window = 200000
max_tokens = 200000
temperature = 0.3

Store your API key securely:

echo -n "sk-ant-your-anthropic-api-key" | ugent secret add --stdin anthropic_api_key

[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-4-8"
context_window = 200000      # total context (input + output)
max_tokens = 200000          # mandatory for Anthropic
temperature = 0.3

When max_tokens = 0 (auto mode), UGENT computes a concrete value from the model card. When extended thinking is active, the fallback floor is 65536 tokens so that both reasoning tokens and visible output fit.

Extended Thinking (Reasoning)

Claude models support extended thinking with configurable budget:

[llm.instances.opus.reasoning]
mode = "enabled"             # disabled | enabled | adaptive
effort = "high"              # minimal | low | medium | high | xhigh | max
budget_tokens = 10000        # optional: explicit thinking token budget

• mode = "enabled" — Thinking is always on. Use for complex coding, debugging, refactoring, and multi-step reasoning.
• mode = "adaptive" — UGENT activates thinking based on task complexity. Budget tokens are omitted (Claude decides).
• mode = "disabled" — Thinking off. Faster, lower token cost.

For Anthropic-specific display control:

[llm.instances.opus.reasoning.anthropic]
display = "expanded"         # expanded | compact (how thinking is shown)

Interleaved Thinking

When interleaved thinking is supported, 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.search]
enabled = true

[llm.instances.opus.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 a Portkey gateway), but remains a compatibility layer.

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

# 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-4-8"

AWS Bedrock

AWS Bedrock provides Claude models through Amazon's infrastructure with IAM authentication. Bedrock uses AWS SigV4 signing (not the x-api-key header), so direct integration requires a SigV4-capable proxy or gateway.

Option 1: Via Proxy / Gateway

Use a proxy that handles AWS SigV4 authentication (e.g., LiteLLM, a custom gateway, or Bedrock-compatible endpoint):

[llm.instances.bedrock]
type = "openai-compatible"
base_url = "https://your-bedrock-proxy.example.com/v1"
api_key_ref = "@bedrock_proxy_key"
default_model = "anthropic.claude-opus-4-7"
catalog_model = "claude-opus-4-7"
context_window = 200000
max_tokens = 200000

The catalog_model field maps the Bedrock model ID (anthropic.claude-opus-4-7) to UGENT's pricing and capability registry entry (claude-opus-4-7).

Option 2: 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-4-8"

Bedrock Model Naming

Bedrock uses a prefix format for model IDs:

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

Regional variants use a region prefix: us.anthropic.claude-opus-4-7.

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-4-8"
context_window = 200000
max_tokens = 200000
temperature = 0.3

# Extended thinking
[llm.instances.opus.reasoning]
mode = "enabled"
effort = "high"

[llm.instances.opus.reasoning.anthropic]
display = "expanded"

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

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

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

[llm.instances.opus.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-4-8"

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

[llm.instances.gemini]
type = "google"
api_key_ref = "@google_api_key"
default_model = "gemini-3.5-pro"

Switch with /model opus, /model gpt, or /model gemini. Cross-provider reasoning blocks are handled safely — thinking authored by Anthropic is dropped before replay to OpenAI or Google, preventing signature validation errors.