Building LLM-Powered Applications with Claude
Choose the right surface, detect the project language, read the relevant docs.
What You Get
- Language-detected SDK examples (Python, TypeScript, Go, Elixir, Rust, Lua, cURL)
- Decision tree: single call vs workflow vs agent vs Agent SDK
- Current model IDs, thinking/effort config, caching patterns
- Tool use patterns (tool runner, manual loop, code execution)
- Error taxonomy and live documentation URLs
Top Pitfalls (quick reference)
| Mistake |
Fix |
Using budget_tokens on Opus 4.6 / Sonnet 4.6 |
Use thinking: {type: "adaptive"} -- budget_tokens is deprecated |
Lowballing max_tokens |
Default ~16K non-streaming, ~64K streaming. Truncation = wasted retry |
| Prefilling assistant message on Opus 4.6 |
Returns 400. Use structured outputs or system prompt instead |
| Silent cache invalidation |
Check usage.cache_read_input_tokens. Common culprit: datetime.now() in system prompt |
| Redefining SDK types |
Use Anthropic.MessageParam, Anthropic.Tool, etc. -- don't roll your own |
Full list: shared/pitfalls.md
Defaults
Use Claude Opus 4.6 (claude-opus-4-6) unless the user names a different model. Use adaptive thinking (thinking: {type: "adaptive"}) for anything remotely complicated. Use streaming for long input/output -- .get_final_message() / .finalMessage() if you don't need individual events.
Language Detection
Infer from project files:
*.py, pyproject.toml, requirements.txt -> Python -- read from python/*.ts, *.tsx, package.json, tsconfig.json -> TypeScript -- read from typescript/*.js, *.jsx (no .ts present) -> TypeScript -- JS uses the same SDK*.go, go.mod -> Go -- read from go/*.ex, *.exs, mix.exs -> Elixir -- read from elixir/*.rs, Cargo.toml -> Rust -- read from rust/*.lua, .luarc.json -> Lua -- read from lua/
If ambiguous, ask. If unsupported language, suggest curl/ examples.
Which Surface?
| Use Case |
Surface |
| Single call (classify, summarize) |
Claude API |
| Multi-step pipeline, your tools |
Claude API + tool use |
| Agent needing file/web/terminal |
Agent SDK |
| Custom agent, your own tools |
Claude API agentic loop |
Decision tree and "Should I Build an Agent?" criteria: shared/surfaces.md
Reading Guide
| Task |
Read |
| Single call (classify/summarize/extract) |
{lang}/claude-api/README.md |
| Chat UI / streaming |
+ {lang}/claude-api/streaming.md |
| Long conversations (context overflow) |
+ Compaction section; details: shared/thinking-effort.md |
| Prompt caching / cache optimization |
shared/prompt-caching.md + {lang}/claude-api/README.md |
| Tool use / function calling / agents |
+ shared/tool-use-concepts.md + {lang}/claude-api/tool-use.md |
| Batch processing |
+ {lang}/claude-api/batches.md |
| File uploads across requests |
+ {lang}/claude-api/files-api.md |
| Agent with built-in tools |
{lang}/agent-sdk/README.md + {lang}/agent-sdk/patterns.md |
| Model selection / capabilities |
shared/models.md |
| Thinking, effort, compaction |
shared/thinking-effort.md |
| Error handling |
shared/error-codes.md |
Go, Elixir, Rust, Lua, cURL: single file covers all basics. Read that plus shared/ files as needed.
When to Use WebFetch
Use when user asks for "latest" info, cached data seems wrong, or features aren't covered here. URLs: shared/live-sources.md.
1---2name: claude-api3description: Build apps with the Claude API or Anthropic SDK. TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude API, Anthropic SDKs, or Agent SDK. DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks.4---56# Building LLM-Powered Applications with Claude78Choose the right surface, detect the project language, read the relevant docs.910## What You Get1112- Language-detected SDK examples (Python, TypeScript, Go, Elixir, Rust, Lua, cURL)13- Decision tree: single call vs workflow vs agent vs Agent SDK14- Current model IDs, thinking/effort config, caching patterns15- Tool use patterns (tool runner, manual loop, code execution)16- Error taxonomy and live documentation URLs1718## Top Pitfalls (quick reference)1920| Mistake | Fix |21| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |22| Using `budget_tokens` on Opus 4.6 / Sonnet 4.6 | Use `thinking: {type: "adaptive"}` -- budget_tokens is deprecated |23| Lowballing `max_tokens` | Default ~16K non-streaming, ~64K streaming. Truncation = wasted retry |24| Prefilling assistant message on Opus 4.6 | Returns 400. Use structured outputs or system prompt instead |25| Silent cache invalidation | Check `usage.cache_read_input_tokens`. Common culprit: `datetime.now()` in system prompt |26| Redefining SDK types | Use `Anthropic.MessageParam`, `Anthropic.Tool`, etc. -- don't roll your own |2728Full list: `shared/pitfalls.md`2930## Defaults3132Use **Claude Opus 4.6** (`claude-opus-4-6`) unless the user names a different model. Use **adaptive thinking** (`thinking: {type: "adaptive"}`) for anything remotely complicated. Use **streaming** for long input/output -- `.get_final_message()` / `.finalMessage()` if you don't need individual events.3334## Language Detection3536Infer from project files:3738- `*.py`, `pyproject.toml`, `requirements.txt` -> **Python** -- read from `python/`39- `*.ts`, `*.tsx`, `package.json`, `tsconfig.json` -> **TypeScript** -- read from `typescript/`40- `*.js`, `*.jsx` (no `.ts` present) -> **TypeScript** -- JS uses the same SDK41- `*.go`, `go.mod` -> **Go** -- read from `go/`42- `*.ex`, `*.exs`, `mix.exs` -> **Elixir** -- read from `elixir/`43- `*.rs`, `Cargo.toml` -> **Rust** -- read from `rust/`44- `*.lua`, `.luarc.json` -> **Lua** -- read from `lua/`4546If ambiguous, ask. If unsupported language, suggest `curl/` examples.4748## Which Surface?4950| Use Case | Surface |51| --------------------------------- | ------------------------- |52| Single call (classify, summarize) | Claude API |53| Multi-step pipeline, your tools | Claude API + tool use |54| Agent needing file/web/terminal | Agent SDK |55| Custom agent, your own tools | Claude API agentic loop |5657Decision tree and "Should I Build an Agent?" criteria: `shared/surfaces.md`5859## Reading Guide6061| Task | Read |62| ---- | ---- |63| Single call (classify/summarize/extract) | `{lang}/claude-api/README.md` |64| Chat UI / streaming | + `{lang}/claude-api/streaming.md` |65| Long conversations (context overflow) | + Compaction section; details: `shared/thinking-effort.md` |66| Prompt caching / cache optimization | `shared/prompt-caching.md` + `{lang}/claude-api/README.md` |67| Tool use / function calling / agents | + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md` |68| Batch processing | + `{lang}/claude-api/batches.md` |69| File uploads across requests | + `{lang}/claude-api/files-api.md` |70| Agent with built-in tools | `{lang}/agent-sdk/README.md` + `{lang}/agent-sdk/patterns.md` |71| Model selection / capabilities | `shared/models.md` |72| Thinking, effort, compaction | `shared/thinking-effort.md` |73| Error handling | `shared/error-codes.md` |7475> Go, Elixir, Rust, Lua, cURL: single file covers all basics. Read that plus `shared/` files as needed.7677## When to Use WebFetch7879Use when user asks for "latest" info, cached data seems wrong, or features aren't covered here. URLs: `shared/live-sources.md`.
DROOdotFOO