Claude Agent SDK

Slide 2 — Session Objectives

At the end of the 2 hours, you will know:

1. Describe the SDK architecture: Agent, Runner, tools, handoffs, guardrails, hooks, context
2. Implement typed tools with @tool
3. Design handoffs and justify the choice vs. tool call
4. Install entry/exit guardrails
5. Orchestrate coordinator, pipeline, parallel execution
6. Manage errors, timeouts, fallbacks

SDK = Software Development Kit

Slide 3 — Why a dedicated SDK?

Calling the API (Application Programming Interface) “by hand” requires rewriting:

• the sending loop → tool call detection → execution → reinjection → iteration
• serialization of tool diagrams
• management of errors, retries, timeouts
• multi-agent orchestration

The SDK is not magic: it is the agentic loop from session 1, packaged and equipped for production.

Slide 4 — The 7 bricks of the SDK

Slide 5 — The class Agent

from claude_agent_sdk import Agent

agent_support = Agent(
    name="support-client",           # routing, logs, handoffs
    model="claude-sonnet-4-5",       #  volatile identifier
    instructions=(
        "You are Acme's support agent. Reply in English. "
        "Always cite the internal source you used."
    ),
    tools=[search_kb, creer_ticket],
)

instructions = the behavioral contract. Anything not there is left to interpretation of the model.

Slide 6 — The Runner: the agentic loop

from claude_agent_sdk import Runner

res = Runner.run(agent_support, "Billed twice this month.")
print(res.final_output)

What Runner.run() does:

1. Send message + instructions + tool diagrams
2. The model responds: final text or tool calls
3. Runs tools, returns results
4. Loop until final response, handoff, or max_turns

Slide 7 — The complete flow

        User → [Guardrail input] → Agent (model)
                                     │
                   ┌── tool call ────┤── handoff ──→ Other agent
                   ▼                 │
              Tool execution         ▼
                   │           Final response
                   └── result ──→ (loop)
                                     │
                             [Guardrail output] → User

The hooks observe each arrow. The typed context circulates everywhere — never in the prompt.

Slide 8 — Certification trap: sync vs async

• Runner.run() — synchronous, simple scripts
• Runner.run_async() — asyncio, mandatory for parallel

Typical question: “Five independent analyzes to be launched simultaneously — which method?” → run_async + asyncio.gather

Slide 9 — Tools: the decorator @tool

@tool
def search_kb(query: str, max_results: int = 5) -> str:
    """Search the internal knowledge base.

    Use for any product or procedure question.

    Args:
        query: natural-language search terms.
        max_results: maximum number of documents.
    """
    ...

• Docstring → description sent to model
• Type hints → JSON schema (JavaScript Object Notation)
• Default value → optional parameter

Slide 10 — The docstring is prompt engineering

"""Searches for stuff."""

Tells when to use the tool, describes each parameter, specifies the limits

The docstring is not a comment for your colleagues. This is an instruction for the pattern.

Slide 11 — Tool errors: business vs. technical

Actionable text allows the model to self-correct (rephrase, reask).

Slide 12 — Good tool practices

• One tool = one responsibility (no do_everything(action))
• Naming from a model perspective (query, not q)
• Always limited: max_results, timeouts, pagination
• Concise and structured feedback — not a 50 KB JSON dump

Slide 13 — Handoffs: the concept

A handoff = transfer of control: agent A passes the conversation to agent B.

Slide 14 — Handoffs: implementation

from claude_agent_sdk import Agent, handoff

agent_triage = Agent(
    name="triage",
    model="claude-haiku-4-5",   #  router = simple task → light model
    instructions="Route to the right specialist. "
                 "NEVER solve it yourself.",
    handoffs=[handoff(agent_facturation),
              handoff(agent_conformite)],
)

The model sees each handoff as a pseudo-tool transfer_to_X — it is he who decides to route.

Slide 15 — Handoffs: three architectural points

1. Target agent inherits history — a specialist who re-questions = poorly configured handoff
2. Handoff return possible (target → source) → risk of ping-pong → bound with max_turns
3. Circular reference: wire the return handoff after the instantiation of the agents

Slide 16 — Anti-pattern: the amnesic subagent

Bad

Runner.run(agent_redacteur, "Write section 2.")

Good

Runner.run(agent_redacteur, f"""
Mission: write section 2 of the report "{titre}".
Overall outline: {plan}
Sections already written (summary): {resume}
Tone: formal. Audience: finance leadership. 400-600 words.
Deliverable: Markdown, no preamble.
""")

A subagent does not share your working memory. #1 cause of multi-agent failure in production.

Slide 17 — Guardrails: hard validation

@input_guardrail
def bloquer_pan(ctx, agent, message: str):
    """Reject any bank card number."""
    if PAN_RE.search(message):
        return GuardrailTripwire(triggered=True,
            message="Please use the secure portal.")
    return GuardrailTripwire(triggered=False)

• Input guardrail: before the model · Output guardrail: after
• Tripwire triggered → run interrupted + dedicated exception to catch

Slide 18 — Guardrails: rules vs LLM-as-judge

	Rules/regex	Light LLM Judge
Latency	~0ms	+200–800ms
Cost	0	1 call/answer
False negatives	High (paraphrases)	Weak

Production: defense in depth — rules in 1st line, judge in 2nd line.

Slide 19 — Instructions vs guardrails

“Where to put: never disclose personal data?”

Both:

• instructions → orients the model (probabilistic)
• guardrail → blocking code (deterministic)

Regulatory compliance requires the deterministic layer.

Slide 20 — Hooks: lifecycle observability

class HooksAudit(RunHooks):
    async def on_tool_start(self, ctx, agent, tool):
        logger.info("agent=%s tool=%s", agent.name, tool.name)
    async def on_handoff(self, ctx, source, cible):
        logger.info("handoff %s → %s", source.name, cible.name)

Runner.run(agent, msg, hooks=HooksAudit())

Uses: regulatory audit, latency/cost metrics, kill-switch.

Examination distinction: hook = observe · guardrail = block. The main safety goes into the guardrails.

Slide 21 — Context variables: shared typed state

@dataclass
class ContexteClient:
    client_id: str
    tier: str

@tool
def consulter_factures(ctx: RunContextWrapper[ContexteClient]) -> str:
    """List the invoices of the authenticated client."""
    return api.factures(ctx.context.client_id)  # never asked of the model

agent = Agent[ContexteClient](name="support", ...)
Runner.run(agent, msg, context=ContexteClient("C-4812", "premium"))

Slide 22 — Safety rule (exam classic)

The identity of the user comes from the application context (authenticated session), NEVER from a parameter filled by the model.

Otherwise: a prompt injection reads other people's invoices.

The context is never serialized in the prompt — only what the tools return reaches the model.

Slide 23 — Pattern 1: coordinator + sub-agents

The coordinator breaks down, delegates, aggregates.

options_coordinateur = {
    "allowedTools": ["Read", "Grep", "Task"],  #  "Task" = right to delegate
    "maxTurns": 40,
}

Examination pitfall: without "Task" in allowedTools, no subagents — the coordinator tries everything himself, silently. Symptom: “My multi-agent only uses one agent”.

Slide 24 — Pattern 2: pipeline

brut    = Runner.run(agent_extracteur, document).final_output
analyse = Runner.run(agent_analyste,  f"Data:\n{brut}").final_output
rapport = Runner.run(agent_redacteur, f"Analysis:\n{analyse}").final_output

Steps testable in isolation, model sized per step
Cumulative latency, upstream error propagated
→ exit guardrail between stages

Slide 25 — Pattern 3: parallel

taches = [Runner.run_async(agent_analyste, c) for c in chunks]
resultats = await asyncio.gather(*taches, return_exceptions=True)
ok     = [r.final_output for r in resultats if not isinstance(r, Exception)]
echecs = [r for r in resultats if isinstance(r, Exception)]

• return_exceptions=True: a failure does not cancel the N−1 successes
• Latency ÷ N, but simultaneous tokens × N → be careful of rate limits

Slide 26 — Pattern choice grid

Slide 27 — Error management: three families

1. Tool error → try/except in tool, actionable text returned to model
2. Agent failure → max_turns (loops), output guardrail + controlled restart, then fallback
3. Timeout → asyncio.wait_for(..., timeout=120) + idempotence of edge effect tools

try:
    res = await asyncio.wait_for(Runner.run_async(agent, msg), timeout=120)
except asyncio.TimeoutError:
    res = reponse_degradee(...)
except OutputGuardrailTripwireTriggered:
    res = escalade_humaine(msg)

Slide 28 — Idempotence: the case of reimbursement

A initier_remboursement tool retried after timeout does not have to pay twice.

Solution: idempotence key — the second call with the same key is ignored on the server side.

Summary sentence: In production, the question is not if an agent fails, but what next. A certifiable architecture defines the behavior of each failure.

Slide 29 — Summary: the 8 reflexes of the architect

1. Tool Docstring = prompt engineering
2. Business error in text, technical error in exception
3. Handoff = transfer of control + history
4. Full context in each delegation prompt
5. Identity via typed context, never via model parameter
6. Guardrails = deterministic · instructions = probabilistic · hooks = observation
7. "Task" in allowedTools to delegate
8. return_exceptions=True, max_turns, timeouts, idempotence