Aide-mémoire API Claude

{
  "model": "claude-opus-5",
  "max_tokens": 2048,
  "system": "You are a precise assistant. Answer only from <document>.",
  "messages": [
    { "role": "user", "content": [
      { "type": "text", "text": "<document>…</document>", "cache_control": { "type": "ephemeral" } },
      { "type": "text", "text": "Summarise the termination clause." }
    ]}
  ],
  "temperature": 0.2,
  "stop_sequences": ["</answer>"],
  "thinking": { "type": "adaptive" },
  "effort": "high",
  "tools": [],
  "tool_choice": { "type": "auto" },
  "metadata": { "user_id": "hashed-id" }
}

{
  "id": "msg_01…",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    { "type": "thinking", "thinking": "…", "signature": "…" },
    { "type": "text", "text": "The notice period is 60 days." }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1200,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 18000,
    "output_tokens": 42
  }
}

// 1. Request with tools
{ "model": "claude-opus-5", "max_tokens": 1024,
  "tools": [{
    "name": "get_order",
    "description": "Look up one order by ID. Use when the user references an order number. Returns status, items and total. Does not modify anything.",
    "input_schema": { "type": "object",
      "properties": { "order_id": { "type": "string", "description": "Order ID, e.g. ORD-12345" } },
      "required": ["order_id"] },
    "strict": true
  }],
  "messages": [{ "role": "user", "content": "Where is ORD-12345?" }] }

// 2. Response: stop_reason = "tool_use"
{ "content": [{ "type": "tool_use", "id": "toolu_01", "name": "get_order", "input": { "order_id": "ORD-12345" } }],
  "stop_reason": "tool_use" }

// 3. Follow-up with tool_result (in a USER message)
{ "messages": [
  { "role": "user", "content": "Where is ORD-12345?" },
  { "role": "assistant", "content": [{ "type": "tool_use", "id": "toolu_01", "name": "get_order", "input": { "order_id": "ORD-12345" } }] },
  { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "toolu_01",
      "content": "{\"status\":\"shipped\",\"eta\":\"2026-09-17\"}" }] }
] }

// Error result – structured, never empty-success
{ "type": "tool_result", "tool_use_id": "toolu_01", "is_error": true,
  "content": "{\"category\":\"not_found\",\"retryable\":false,\"message\":\"No order ORD-12345\"}" }

def run(messages, tools, model="claude-opus-5"):
    while True:
        r = client.messages.create(model=model, max_tokens=4096, tools=tools, messages=messages)
        messages.append({"role": "assistant", "content": r.content})
        if r.stop_reason == "tool_use":
            results = []
            for block in r.content:
                if block.type == "tool_use":
                    try:
                        out = TOOLS[block.name](**block.input)
                        results.append({"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(out)})
                    except ToolError as e:
                        results.append({"type": "tool_result", "tool_use_id": block.id, "is_error": True,
                                        "content": json.dumps({"category": e.category, "retryable": e.retryable, "message": str(e)})})
            messages.append({"role": "user", "content": results})
            continue
        if r.stop_reason == "max_tokens":
            messages.append({"role": "user", "content": "Continue."}); continue
        if r.stop_reason == "pause_turn":
            continue
        if r.stop_reason == "refusal":
            return handle_refusal(r)
        return r  # end_turn / stop_sequence

{ "model": "claude-sonnet-5", "max_tokens": 1024,
  "output_config": { "format": { "type": "json_schema", "schema": {
    "type": "object",
    "properties": {
      "vendor": { "type": "string" },
      "total": { "type": "number" },
      "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] },
      "line_items": { "type": "array", "items": { "type": "object",
        "properties": { "sku": { "type": "string" }, "qty": { "type": "integer" } },
        "required": ["sku", "qty"], "additionalProperties": false } }
    },
    "required": ["vendor", "total", "currency", "line_items"],
    "additionalProperties": false } } },
  "messages": [{ "role": "user", "content": [
    { "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "…" } },
    { "type": "text", "text": "Extract the invoice." } ] }] }

{ "system": [{ "type": "text", "text": "<20k-token style guide>", "cache_control": { "type": "ephemeral" } }],
  "tools": [ … ],
  "messages": [ … dynamic content last … ] }

batch = client.messages.batches.create(requests=[
    {"custom_id": f"doc-{i}", "params": {"model": "claude-haiku-4-5", "max_tokens": 512,
     "messages": [{"role": "user", "content": doc}]}} for i, doc in enumerate(docs)])
# poll batch.processing_status until "ended", then stream results
for res in client.messages.batches.results(batch.id):
    if res.result.type == "succeeded": ...

// Vision and PDF content blocks
{ "type": "image",    "source": { "type": "url", "url": "https://example.com/chart.png" } }
{ "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "…" } }

// MCP connector
{ "mcp_servers": [{ "type": "url", "url": "https://mcp.example.com/mcp", "name": "orders" }] }

event: message_start
data: {"type":"message_start","message":{"id":"msg_01","role":"assistant","model":"claude-opus-5","content":[],"stop_reason":null,"usage":{"input_tokens":1200,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Checking the order…"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"Er8B…"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"Looking that up"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01","name":"get_order","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"input_json_delta","partial_json":"{\"order_id\":\"ORD-12345\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":57}}

event: message_stop
data: {"type":"message_stop"}

event: ping        (may arrive at any time; ignore)

{ "role": "user", "content": [
  { "type": "tool_result", "tool_use_id": "toolu_09", "content": [
    { "type": "text", "text": "Chart rendered for Q3 revenue." },
    { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo…" } }
  ] }
]}

// Assistant turn: three parallel calls (stop_reason: tool_use)
{ "role": "assistant", "content": [
  { "type": "tool_use", "id": "toolu_a", "name": "get_weather", "input": { "city": "Paris" } },
  { "type": "tool_use", "id": "toolu_b", "name": "get_weather", "input": { "city": "Tokyo" } },
  { "type": "tool_use", "id": "toolu_c", "name": "get_fx",      "input": { "pair": "EURJPY" } }
]}

// Your next user turn: all results, matched by tool_use_id, order-independent
{ "role": "user", "content": [
  { "type": "tool_result", "tool_use_id": "toolu_a", "content": "{\"c\":18}" },
  { "type": "tool_result", "tool_use_id": "toolu_b", "content": "{\"c\":26}" },
  { "type": "tool_result", "tool_use_id": "toolu_c", "content": "{\"rate\":171.2}" }
]}

import json, jsonschema
from anthropic import Anthropic

client = Anthropic()
SCHEMA = { "type": "object",
  "properties": { "vendor": {"type": "string"}, "total": {"type": "number"},
                  "currency": {"type": "string", "enum": ["USD","EUR","GBP"]} },
  "required": ["vendor","total","currency"], "additionalProperties": False }

def extract(doc_text, max_attempts=3):
    messages = [{"role": "user", "content": f"Extract the invoice.\n<doc>{doc_text}</doc>"}]
    for attempt in range(max_attempts):
        r = client.messages.create(
            model="claude-sonnet-5", max_tokens=1024,
            output_config={"format": {"type": "json_schema", "schema": SCHEMA}},
            messages=messages)
        text = r.content[0].text
        try:
            data = json.loads(text)
            jsonschema.validate(data, SCHEMA)      # schema + business rules
            if data["total"] < 0:
                raise ValueError("total must be non-negative")
            return data
        except (json.JSONDecodeError, jsonschema.ValidationError, ValueError) as e:
            messages += [{"role": "assistant", "content": text},
                         {"role": "user", "content": f"That failed validation: {e}. Return corrected JSON only."}]
    raise RuntimeError("extraction failed after retries")   # escalate, never silently return bad data

{
  "system": [
    { "type": "text", "text": "<static company style guide, 15k tokens>", "cache_control": { "type": "ephemeral" } }
  ],
  "tools": [
    { "name": "search_kb", "description": "…", "input_schema": { }, "cache_control": { "type": "ephemeral" } }
  ],
  "messages": [
    { "role": "user", "content": [
      { "type": "text", "text": "<retrieved policy docs, changes per session>", "cache_control": { "type": "ephemeral", "ttl": "1h" } },
      { "type": "text", "text": "Now: the user's current question (never cached)." }
    ]}
  ]
}

create → in_progress ──► (per request: succeeded | errored | canceled | expired)
                     └─► ended   (all requests terminal; results retrievable)
        cancel ─► canceling ─► ended

# Idempotency: safe retries for side-effecting requests
client.messages.create(**params, extra_headers={"idempotency-key": f"charge-{order_id}"})

# Upload once, reference by file_id across many requests
f = client.files.upload(file=("contract.pdf", open("contract.pdf","rb"), "application/pdf"))

r = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024,
    messages=[{"role": "user", "content": [
        {"type": "document", "source": {"type": "file", "file_id": f.id},
         "citations": {"enabled": True}},
        {"type": "text", "text": "What is the termination notice period? Cite the clause."}
    ]}])

{ "type": "text", "text": "The notice period is 60 days.",
  "citations": [{ "type": "page_location", "cited_text": "…sixty (60) days…",
                  "document_index": 0, "start_page_number": 4, "end_page_number": 4 }] }

// Context editing: clear stale tool results server-side, keep the turn valid
{ "model": "claude-opus-5", "max_tokens": 4096,
  "context_management": {
    "edits": [{ "type": "clear_tool_uses", "trigger": { "type": "input_tokens", "value": 100000 },
                "keep": { "type": "tool_uses", "value": 3 } }]
  },
  "messages": [ … ] }

// Compaction: summarise older turns while preserving the narrative
{ "context_management": {
    "edits": [{ "type": "compact", "trigger": { "type": "input_tokens", "value": 150000 } }] } }

{ "model": "claude-opus-5", "max_tokens": 2048,
  "tools": [{ "type": "memory_20250818", "name": "memory" }],
  "messages": [{ "role": "user", "content": "Remember I prefer metric units, then convert 5 miles." }] }

r = client.messages.create(
    model="claude-opus-5", max_tokens=1024,
    mcp_servers=[{ "type": "url", "url": "https://mcp.example.com/mcp", "name": "orders",
                   "authorization_token": user_scoped_token }],
    extra_headers={"anthropic-beta": "mcp-client-2025-04-04"},
    messages=[{"role": "user", "content": "Where is ORD-12345?"}])

# Agent SDK sketch – you host the harness
from claude_agent_sdk import ClaudeAgent
agent = ClaudeAgent(model="claude-opus-5", tools=[...], mcp_servers=[...],
                    permission_mode="acceptEdits")
result = agent.run("Refactor the auth module and run the tests.")