Claude Architect · Lesson

Agent SDK Building Blocks

The pieces that make up an SDK-based agent.

Agent SDK Building Blocks is a free Claude Architect lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What an SDK Agent Really Is

An Agent SDK agent is not a single API call. It is a loop built from a few reusable pieces that work together.

In this lesson you will learn the core building blocks: the request fields, the tools the model can call, the agentic loop that drives it, and the coordinator + subagents pattern for bigger jobs.

Master these pieces and you can reason about almost any production agent the exam throws at you.

The Request: model, messages, tools

Every turn starts with one request. Its key fields are: model, max_tokens, system, messages, tools, and tool_choice.

The single most important fact: the model keeps NO state between turns. You must send the FULL conversation history in messages on every request. There is no hidden server-side memory.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="You are a support agent.",
    messages=conversation_history,  # FULL history every turn
    tools=tools,
    tool_choice={"type": "auto"},
)

Stop Reasons Drive Everything

After each response you inspect stop_reason. It tells you what to do next:

end_turn — the model is finished.
tool_use — run the requested tool(s), append the results to history, then continue.
max_tokens — the output was truncated.
stop_sequence — a configured stop string was hit.

You decide control flow by reading stop_reason — never by scanning the text for words like "done" or "finished".

Building Block: The Agentic Loop

The agentic loop ties the request and stop reasons together:

Send the request.
Inspect stop_reason.
If tool_use: run the tools, append tool_result blocks to history, loop again.
Repeat until end_turn.

Termination is model-driven via the stop reason. An iteration cap is only a safety net, never the primary way you stop.

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=history,
        tools=tools,
    )
    if resp.stop_reason == "end_turn":
        break  # model decided it is done
    if resp.stop_reason == "tool_use":
        results = run_tools(resp.content)
        history.append({"role": "user", "content": results})

Tools: Descriptions Do the Routing

A tool is an action the model can call. The description — not the name — is the primary mechanism the model uses to pick the right tool.

A strong description states the purpose, the return values, the input formats with examples, edge cases, and applicability boundaries. Overlapping or vague descriptions cause misrouting.

tool = {
    "name": "lookup_order",
    "description": (
        "Fetch an order by its ID. Use ONLY after the "
        "customer identity is verified. Input: order_id like "
        "'ORD-10293'. Returns status, items, total_usd. "
        "Returns an empty result if the ID does not exist."
    ),
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}

Scope Tools to the Role

More tools is not better. Around 4-5 tools per agent is optimal; 18+ degrades selection reliability because descriptions start to overlap and the model misroutes.

Scope each agent's toolset to its role and follow least privilege. A support agent might carry exactly: get_customer, lookup_order, process_refund, escalate_to_human — and nothing else.

tool_choice: Forcing Structure

tool_choice controls whether and which tool runs:

"auto" — the model picks text or a tool.
"any" — the model MUST call some tool, which guarantees structured output.
{"type":"tool","name":"X"} — force one specific tool.

Pairing tool_use with a JSON Schema eliminates syntax errors and enforces required fields — the backbone of reliable structured output.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=history,
    tools=[extract_invoice_tool],
    tool_choice={"type": "any"},  # must emit structured output
)

Hooks: Deterministic Guardrails

Prompts steer behavior only probabilistically (~90%). When a failure has financial, legal, or safety consequences, you need deterministic (100%) enforcement — that is what hooks provide.

A PostToolUse hook intercepts a tool result before the model ever sees it. An outgoing-call hook can block a policy-violating action, for example a refund over $500. Reserve hard code for guarantees; let the model make the soft decisions.

def post_tool_use_hook(tool_name, tool_input, tool_result):
    if tool_name == "process_refund" and tool_input["amount"] > 500:
        # Deterministic block - the model never gets to override this
        return {"deny": True, "reason": "Refund > $500 needs a human."}
    return {"allow": True}

Multi-Agent: Coordinator + Subagents

For bigger jobs the building blocks compose into a hub-and-spoke system. A coordinator decomposes the task, delegates to subagents, aggregates results, routes, and handles errors.

Critical exam fact: subagents do NOT inherit the coordinator's conversation history. All context must be passed explicitly in each subagent prompt. The coordinator's allowedTools must include "Task", and multiple Task calls in one response run in parallel.

Defining a Subagent

Each subagent is described by an AgentDefinition: name, description, system_prompt, and allowed_tools (least privilege).

Because there is no shared memory, the coordinator embeds every fact the subagent needs directly in its prompt — the question, the constraints, and any data it must work from.

research_agent = {
    "name": "source_finder",
    "description": "Finds and quotes primary sources for one claim.",
    "system_prompt": (
        "You research ONE claim. Return source URL, exact "
        "quote, and publication date. Context is given in full "
        "because you do not see prior conversation."
    ),
    "allowed_tools": ["WebSearch", "Read"],  # least privilege
}

Structured Errors Between Blocks

The pieces only stay reliable if failures are legible. A generic "Operation failed" blocks recovery; a structured error enables intelligent routing.

Good error context includes: isError:true, an errorCategory (transient / validation / business / permission), isRetryable, a message, the attempted_query, and any partial_results. Recover transient faults locally in the subagent; escalate non-recoverable ones with partial results instead of aborting the whole workflow.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Order service timed out",
  "attempted_query": "lookup_order(ORD-10293)",
  "partial_results": null
}

Quick Check: Designing the Loop

You are building an Agent SDK customer-support agent. It must call tools, keep going across several turns, and stop reliably. Which design matches Agent SDK best practice?

Recap: The Building Blocks

The pieces of an SDK agent:

Request: model, max_tokens, system, messages, tools, tool_choice. Send the FULL history every turn — the model keeps no state.
Stop reasons: end_turn, tool_use, max_tokens, stop_sequence drive control flow — never parse text.
Agentic loop: model-driven termination; iteration caps are only a safety net.
Tools: descriptions do the routing; 4-5 per agent, least privilege. tool_choice "any" guarantees structured output.
Hooks: 100% deterministic enforcement for financial/legal/safety rules.
Coordinator + subagents: hub-and-spoke, no inherited history, pass context explicitly, structured errors for recovery.

Frequently asked questions

Is the “Agent SDK Building Blocks” lesson free?

Yes — the full text of “Agent SDK Building Blocks” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.

What will I learn in “Agent SDK Building Blocks”?

The pieces that make up an SDK-based agent. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Claude Architect?

No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Agent SDK Building Blocks” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Claude Architect lesson?

Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Claude Architect