CCA Developer M2: Production Prompting, Agents & Tool Use

messages = [
    {"role": "user", "content": "Classify this review: ..."},
    {"role": "assistant", "content": "{"}  # assistant prefill
]

2.6 Extended Thinking

Extended thinking lets the model reason explicitly before producing an answer. Enable it per-request:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 8000},
    messages=[{"role": "user", "content": "Design the optimal database schema for a multi-tenant SaaS billing system."}]
)

Thinking block in the response:

for block in response.content:
    if block.type == "thinking":
        print(f"[Reasoning] {block.thinking}")
    elif block.type == "text":
        print(f"[Answer] {block.text}")

The thinking block is for your diagnostics. Users typically see only the text block.

2.7 Tool Design

Tools are how Claude interacts with external systems. Each tool has three required fields:

{
    "name": "get_customer_orders",          # short snake_case identifier
    "description": "Retrieve all orders for a customer. Use this when you need order history, order status, or order totals for a specific customer ID.",
    "input_schema": {
        "type": "object",
        "properties": {
            "customer_id": {
                "type": "string",
                "description": "The customer's unique identifier (UUID format)"
            },
            "limit": {
                "type": "integer",
                "description": "Maximum number of orders to return. Defaults to 20.",
                "default": 20
            }
        },
        "required": ["customer_id"]
    }
}

The description is the routing signal. When the model decides which tool to call, it reads the description. A vague description ("Use this tool for orders") leads to wrong or missed tool calls. A specific description ("Use this when you need order history, order status, or order totals for a specific customer ID") reliably routes the right queries.

Description writing checklist:

• State when to use this tool (not just what it does)
• State what it returns (important for multi-tool setups where results overlap)
• Note required preconditions (e.g., "requires a valid session token")
• Keep it under 100 words; longer descriptions add noise

2.8 The Six-Step Tool-Use Loop

Tool use follows a deterministic six-step loop. Understanding every step prevents debugging confusion:

1. Application sends request → model receives messages + tool definitions
2. Model produces a tool_use block (name + input JSON)
3. stop_reason = "tool_use" — the model pauses and waits
4. Application receives the response, extracts the tool_use block
5. Application executes the tool, gets the result
6. Application appends tool_result to messages, sends again → back to step 2

Message block types in the API:

Returning tool results:

# After executing the tool, append the result and continue
messages.append({
    "role": "assistant",
    "content": response.content  # includes the tool_use block
})
messages.append({
    "role": "user",
    "content": [{
        "type": "tool_result",
        "tool_use_id": tool_use_block.id,
        "content": json.dumps({"orders": [...], "total": 3})
    }]
})

# Send again — model will continue from here
response = client.messages.create(model=model, messages=messages, tools=tools, max_tokens=1024)

Returning errors from tools. When a tool fails, return the error as a string in content and set is_error: true. The model will handle it gracefully:

{
    "type": "tool_result",
    "tool_use_id": tool_use_block.id,
    "content": "Error: customer_id not found in database",
    "is_error": True
}

2.9 Streaming

Streaming returns tokens as they are generated. The event sequence for a streaming response is:

message_start           → conversation metadata, usage counts
content_block_start     → new block begins (type: text or tool_use)
content_block_delta     → incremental content (text_delta or input_json_delta for tools)
content_block_stop      → block complete
message_delta           → final stop_reason and usage
message_stop            → stream complete

Streaming with tool use. When the model calls a tool, the content_block_start event reports type: "tool_use" and subsequent content_block_delta events deliver the input_json_delta — the JSON arguments, streamed character by character. You accumulate them and parse when the block stops.

stop_reason values:

2.10 Context Engineering

Context engineering is the active management of what lives in the context window during a long-running task. It is not optional for agents — it is the primary lever for preventing context overflow.

Four strategies:

RAG vs live tool use — the key distinction:

• Retrieval (RAG): for stable knowledge (documents, policies, reference data) that was true yesterday and will be true tomorrow. Returns text chunks injected into context.
• Live tool use: for live state (database records, API values) that a system owns and changes independently. Returns current values at call time.

The symptom of wrong choice: If your RAG chunks are returning stale data that contradicts the database, you're retrieving something that should be a live tool call.

2.11 Agent vs Workflow — The Decision

The fundamental architectural decision: should this system be a workflow (fixed sequence) or an agent (dynamic decision loop)?

Use a workflow when:

• The steps and their order are known in advance
• You want deterministic, predictable behaviour
• Cost and latency are primary constraints
• Errors need to be caught at specific known points

Use an agent when:

• The steps cannot be enumerated ahead of time
• The task requires the model to decide what to do next based on intermediate results
• Genuine unpredictability in the task requires adaptive behaviour

Three wiring paths (from lowest to highest flexibility):

Human-in-the-loop insertion points. Insert a human review gate at any step where the consequence of an error is irreversible or high-cost. Common patterns:

• Before any write operation that cannot be undone
• Before spending money (e-commerce, financial transactions)
• When the model's confidence is below a threshold
• After a fixed number of iterations (time-based escalation)

2.12 Memory Scopes

Four memory types, each with different persistence and retrieval:

Only external storage gives you true cross-session memory that you control. In-context and KV cache are session-bounded. In-weights cannot be changed without fine-tuning.

2.13 Multimodal and Batch

Images. Pass images as base64-encoded content blocks:

import base64

with open("diagram.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}},
            {"type": "text", "text": "Describe the architecture shown in this diagram."}
        ]
    }]
)

PDFs. Claude supports PDF input natively via the document block type. The model processes the document's text and visual layout:

{
    "type": "document",
    "source": {"type": "base64", "media_type": "application/pdf", "data": pdf_base64}
}

Image token cost. Images cost between 1,000–3,000 input tokens depending on resolution and detail level. For bulk image processing, use the Batches API.

M2 Checkpoint

• System prompt = operator-level constraints — not a security boundary; app code enforces authorization
• Description is the tool routing signal — vague descriptions cause wrong tool calls
• stop_reason = "max_tokens" means truncation, not completion — always check
• RAG for stable knowledge; live tools for live state — wrong choice causes stale data
• Workflow first; agent only when steps cannot be enumerated
• External storage is the only cross-session memory you control