Claude Architect · レッスン

Agent SDKの構成要素

SDKベースのエージェントを構成する要素を学びます

レッスン 1/413 ステップ

「Agent SDKの構成要素」はCoddyKit上の無料Claude Architectレッスンです。これはレッスン1/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはClaude Architect学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Claude Architectコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

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.

無料で開始

AI チューターと学ぶ Python — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース: 26
レッスン: 104

無料で学習を始めるコース全体を表示

よくある質問

「Agent SDKの構成要素」レッスンは無料ですか？

はい。「Agent SDKの構成要素」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Claude Architectコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Claude Architectコースには全4レッスンが含まれています。

「Agent SDKの構成要素」で何を学びますか？

SDKベースのエージェントを構成する要素を学びますブラウザで直接実行するハンズオンコードでClaude Architectを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Claude Architectを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのClaude Architectは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン1/4です。

「Agent SDKの構成要素」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このClaude Architectレッスンでコードを書いて実行できますか？

はい。すべてのClaude Architectレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← Claude Architectに戻る