Claude Architect · Lekcja

Elementy składowe Agent SDK

Elementy, z których składa się agent oparty na SDK

Elementy składowe Agent SDK to bezpłatna lekcja Claude Architect na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Claude Architect, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Claude Architect zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

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.

Często zadawane pytania

Czy lekcja „Elementy składowe Agent SDK” jest bezpłatna?

Tak — pełny tekst „Elementy składowe Agent SDK” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Claude Architect, przejdź na CoddyKit PRO. Kurs Claude Architect zawiera 4 lekcji w sumie.

Co nauczysz się w „Elementy składowe Agent SDK”?

Elementy, z których składa się agent oparty na SDK Ćwiczysz Claude Architect z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Claude Architect?

Nie wymagamy żadnego doświadczenia. Claude Architect w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „Elementy składowe Agent SDK”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Claude Architect?

Tak. Każda lekcja Claude Architect zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Claude Architect