Elementi costitutivi dell’Agent SDK

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.

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.

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".

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.

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.

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 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.

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.

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.

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.

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.

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.