---
name: "anthropic-claude"
description: 'Implement production applications with Anthropic Claude models -- Messages API, tool use, prompt caching, adaptive thinking, vision, computer use, and the Claude Agent SDK. Use when coding directly against Anthropic APIs, Claude via AWS Bedrock, or Claude via GCP Vertex AI rather than a higher-level framework.'
metadata:
 author: "Frontier"
 version: "1.0.0"
 created: "2026-04-22"
 updated: "2026-04-22"
compatibility:
 frameworks: ["anthropic-sdk", "claude-agent-sdk", "aws-bedrock", "gcp-vertex-ai", "langchain", "microsoft-agent-framework"]
 languages: ["python", "typescript", "csharp", "java", "go"]
 platforms: ["windows", "linux", "macos"]
prerequisites: ["Anthropic API key OR Bedrock/Vertex access", "anthropic SDK 0.39+ (Python) or 0.30+ (TS)", "Claude Agent SDK optional for agentic loops"]
---

# Anthropic Claude

> WHEN: Writing implementation code against Anthropic Claude models directly via the Messages API, or via Amazon Bedrock / GCP Vertex AI, or via the Claude Agent SDK.

## When to Use

- Calling Claude models directly with the Anthropic Messages API
- Deploying Claude on AWS Bedrock or GCP Vertex AI
- Building tool-using Claude agents with the Claude Agent SDK
- Adding prompt caching, adaptive thinking, or vision to a Claude app
- Migrating from another LLM provider to Claude and preserving behavior

## Decision Tree

```
Need Claude in production?
+- Direct Anthropic API?
|  - Use anthropic SDK (python or typescript)
+- AWS-hosted workload?
|  - Use Claude on Amazon Bedrock via boto3 / AWS SDK
+- GCP-hosted workload?
|  - Use Claude on Vertex AI via google-cloud-aiplatform
+- Agentic loop with tools, files, shell?
|  - Use Claude Agent SDK
+- Framework already chosen (LangChain, MAF, LangGraph)?
   - Use the provider adapter rather than raw SDK
```

## Core Rules

1. Always send a `system` prompt separately from the `messages` array -- Claude separates system instruction from the turn history.
2. Pin model IDs explicitly (for example `claude-opus-5-5`, `claude-haiku-4.5`). Do not rely on aliases in production.
3. Reserve output tokens deliberately. `max_tokens` covers thinking plus answer on Opus 5.5; treat it as a required cost and latency lever.
4. Use prompt caching for any prompt prefix reused across turns -- system prompt, tool schemas, long docs, few-shot examples.
5. Prefer structured tool use over freeform JSON in prose. Let Claude emit tool_use blocks and validate on the server side.

## Model Selection (September 2026)

| Model | Best For | Context / Output | Notes |
|---|---|---|---|
| `claude-opus-5-5` | Agentic coding, code review, knowledge work, computer use | 1M / 128K | Frontier default Claude model; thinking always on |
| `claude-opus-4.8` | Pinned prior-Opus deployments | 200K / 64K | Allows disabled or budgeted thinking |
| `claude-haiku-4.5` | High-volume, low-latency, simple classification | 200K / 8K | Cheapest, fastest |

## Minimal Pattern (Python)

```python
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    system="You are a concise technical assistant.",
    messages=[
        {"role": "user", "content": "Summarize the Frontier workflow in 3 bullets."}
    ],
)

print(next(b.text for b in response.content if b.type == "text"))
```

## Tool Use Pattern

```python
tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    tools=tools,
    messages=[{"role": "user", "content": "Weather in Seattle?"}],
)

# On "tool_use": append response.content as-is (thinking included), then tool_result.
```

## Prompt Caching

Cache static prefix content (system prompts, tool schemas, long docs) with `cache_control`:

```python
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    system=[
        {"type": "text", "text": LONG_SYSTEM_PROMPT,
         "cache_control": {"type": "ephemeral"}}
    ],
    messages=[{"role": "user", "content": "Apply the policy above to case X."}],
)
```

- Cached tokens cost ~10% of standard input on cache hit.
- Cache TTL is 5 minutes by default, extendable.
- Minimum cacheable length applies -- short prefixes will not cache.

## Thinking and Effort

Opus 5.5 always uses adaptive thinking. Control depth with `output_config.effort`
(`low`, `medium` default, `high`, `xhigh`, `max`); its `medium` matches Opus 5 at
`high`. Disabled thinking, `budget_tokens`, non-default `temperature`/`top_p`/`top_k`,
forced `tool_choice` and assistant prefill return 400 errors. Do not prompt for
written-out reasoning: it can be refused as `reasoning_extraction`; request
`thinking.display: "summarized"` when you need a reasoning summary.

## Deployment Targets

| Target | SDK / Client | When |
|---|---|---|
| Anthropic API | `anthropic` (python/ts) | Default -- simplest path |
| Amazon Bedrock | `boto3` with `bedrock-runtime` | AWS-resident workload, IAM-based auth |
| GCP Vertex AI | `anthropic[vertex]` or Vertex SDK | GCP-resident workload, service-account auth |

Model IDs and feature parity differ per target. Check feature availability (caching, adaptive thinking, computer use) per cloud before committing.

## Migrating To Claude

- Map `system` role messages from OpenAI-style to Claude's separate `system` parameter.
- Replace function calling JSON with Claude `tool_use` blocks and `tool_result` turn responses.
- Re-tune few-shot examples. Claude responds well to XML-tagged structure in prompts.

## Design Guidance

- Put durable task instructions in `system`. Keep `messages` focused on the current user turn plus tool/result loop.
- Use XML tags (`<context>`, `<instructions>`, `<examples>`) in large prompts -- Claude follows tagged structure reliably.
- Prefer structured output via tool_use with a schema over "respond in JSON" prose.
- Stream long responses to reduce perceived latency and enable early cancellation.

## Safety And Guardrails

- Claude has strong native refusal behavior; do not double-stack safety instructions unnecessarily -- it hurts quality.
- For regulated domains, use `system` to scope the assistant's role and allowed outputs precisely.
- Validate tool inputs on the server before execution. Claude can and will call tools with unexpected parameters.
- Log refusals with enough metadata to tune the system prompt without leaking user data.

## Anti-Patterns

- **Role Confusion**: Embedding system instructions inside `messages` -> Use the separate `system` parameter.
- **Unpinned Models**: Depending on provider aliases in production -> Pin explicit model IDs such as `claude-opus-5-5`.
- **Uncached Prefixes**: Sending the same 20K-token system prompt every turn -> Use prompt caching.
- **Prose JSON**: Asking Claude to "respond with JSON" -> Use tool_use with an input schema.
- **Over-Provisioned Effort**: Running every call at `high` or above -> Start at `medium` and raise only where evals show a gain.
- **Cross-Cloud Assumption**: Assuming Bedrock or Vertex supports every API-only feature -> Check per-target feature parity.

## Checklist

- [ ] Model ID is pinned (no bare aliases)
- [ ] System prompt is in the `system` parameter, not in `messages`
- [ ] `max_tokens` is set deliberately based on expected output
- [ ] Prompt caching is enabled for any stable prefix > ~1K tokens
- [ ] Tool definitions use `input_schema` with strict types
- [ ] Effort is set explicitly and raised only where it measurably helps
- [ ] Deployment target (API / Bedrock / Vertex) is documented per environment
- [ ] Traces capture model ID, prompt version, cache-hit status, and stop_reason

## References

- [Anthropic API Reference](https://docs.anthropic.com/en/api/overview)
- [Claude Models Overview](https://docs.anthropic.com/en/docs/about-claude/models/overview)
- [Prompt Caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)
- [Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview)
- [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)
- [Claude on Amazon Bedrock](https://docs.anthropic.com/en/api/claude-on-amazon-bedrock)
- [Claude on Vertex AI](https://docs.anthropic.com/en/api/claude-on-vertex-ai)
- [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-agent-sdk)

## Troubleshooting

| Symptom | Resolution |
|---|---|
| `401 unauthorized` | Confirm `ANTHROPIC_API_KEY` or cloud credential path; Bedrock/Vertex use IAM/service-account, not API key |
| Output truncated mid-sentence | `max_tokens` too low -- Claude hard-stops at the limit; raise or stream |
| Tool call never fires | Check tool schema types; Claude is strict about required fields and enum constraints |
| Cache miss every turn | Prefix is below minimum cache length or drifts across turns -- stabilize the prefix |
| Feature missing on Bedrock/Vertex | Not all API features ship on every cloud -- fall back to direct Anthropic API or accept gap |
| Thinking latency too high | Lower `effort`; Opus 5.5 cannot disable thinking |