Aide-mémoire Agent SDK

Le Claude Agent SDK (claude-agent-sdk, renommé depuis « Claude Code SDK ») expose de façon programmatique le harnais d’agent de Claude Code : la boucle agentique, les outils, les hooks, les permissions, les subagents et les serveurs MCP. Vous l’hébergez — à opposer aux Managed Agents, où Anthropic héberge la boucle et le sandbox.

Installation

pip install claude-agent-sdk          # Python
npm install @anthropic-ai/claude-agent-sdk   # TypeScript

Démarrage rapide

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        model="claude-opus-5",
        system_prompt="You are a precise refactoring assistant.",
        allowed_tools=["Read", "Edit", "Bash"],
        permission_mode="acceptEdits",
        cwd="/repo",
    )
    async for message in query(prompt="Rename getUserName to getUsername repo-wide, then run tests.",
                               options=options):
        print(message)

anyio.run(main)

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const message of query({
  prompt: 'Rename getUserName to getUsername repo-wide, then run tests.',
  options: {
    model: 'claude-opus-5',
    systemPrompt: 'You are a precise refactoring assistant.',
    allowedTools: ['Read', 'Edit', 'Bash'],
    permissionMode: 'acceptEdits',
    cwd: '/repo',
  },
})) {
  console.log(message);
}

Options

Modes de permission

Callback de permission programmatique

Contrôle fin au-delà des listes allow/deny — décidez par appel :

async def can_use_tool(tool_name, tool_input, context):
    if tool_name == "Bash" and "rm -rf" in tool_input.get("command", ""):
        return {"behavior": "deny", "message": "destructive command blocked"}
    if tool_name == "Edit" and tool_input.get("file_path", "").endswith(".env"):
        return {"behavior": "deny", "message": "secrets are read-only"}
    return {"behavior": "allow"}

options = ClaudeAgentOptions(can_use_tool=can_use_tool, allowed_tools=["Read", "Edit", "Bash"])

const options = {
  allowedTools: ['Read', 'Edit', 'Bash'],
  canUseTool: async (toolName: string, input: Record<string, unknown>) => {
    if (toolName === 'Bash' && String(input.command).includes('rm -rf'))
      return { behavior: 'deny', message: 'destructive command blocked' };
    return { behavior: 'allow' };
  },
};

Hooks

Mêmes événements de cycle de vie que Claude Code (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, SubagentStop, PreCompact, Notification), enregistrés dans le code. Un hook PreToolUse renvoyant une décision de refus bloque l’outil — le mécanisme d’application déterministe.

async def block_destructive(input_data, tool_use_id, context):
    cmd = input_data.get("tool_input", {}).get("command", "")
    if any(bad in cmd for bad in ("rm -rf", "git push --force", "drop table")):
        return {"decision": "block", "reason": "destructive command"}
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [{"matcher": "Bash", "hooks": [block_destructive]}]})

Subagents

Définissez des agents délégués avec un contexte isolé, leurs propres outils et modèle :

options = ClaudeAgentOptions(
    agents={
        "security-reviewer": {
            "description": "Reviews diffs for injection, secrets, authz. Use after auth edits.",
            "prompt": "Report findings only: file:line, severity, fix. Do not edit.",
            "tools": ["Read", "Grep", "Glob"],
            "model": "claude-sonnet-5",
        }
    })

Les subagents ne reçoivent que ce que le parent transmet ; ne présumez jamais d’un héritage. Utilisez un modèle moins cher pour le travail délégué mécanique.

Serveurs MCP

options = ClaudeAgentOptions(
    mcp_servers={
        "orders": {"command": "python", "args": ["orders_server.py"]},          # stdio
        "linear": {"type": "http", "url": "https://mcp.linear.app/mcp"},        # remote
    },
    allowed_tools=["mcp__orders__get_order", "mcp__linear__list_issues"])

Les outils MCP sont dans l’espace de noms mcp__<server>__<tool> ; mettez-les explicitement en allowlist.

Événements de streaming

query() produit un flux de messages typés reflétant le flux SSE : un message system d’init, des messages assistant (blocs text/tool_use), des messages user (tool_result), et un message result final portant stop_reason, usage et le coût.

async for message in query(prompt="…", options=options):
    if message.type == "assistant":
        for block in message.content:
            if block.type == "text":
                print(block.text, end="")
    elif message.type == "result":
        print(message.stop_reason, message.usage, message.total_cost_usd)

Branchez sur le stop_reason du message result, pas sur le parsing du texte assistant.

Patterns headless

# CI gate sketch
import sys
async def review():
    async for m in query(prompt="Review the diff for security issues; output PASS or FAIL.",
                         options=ClaudeAgentOptions(permission_mode="plan",
                                                    allowed_tools=["Read", "Grep", "Bash(git diff:*)"])):
        if m.type == "result":
            sys.exit(0 if "PASS" in (m.result or "") else 1)

Agent SDK vs Managed Agents vs boucle Messages API

Idées reçues courantes

Analyse de scénario

Une équipe plateforme veut un agent CI auto-hébergé qui relit les PR pour des problèmes de sécurité, ne doit jamais éditer de fichiers, doit s’exécuter dans leur VPC (localité des données), et doit faire échouer le build sur un constat.

1. Auto-hébergé + localité des données dans le VPC → Agent SDK, pas Managed Agents (qui est hébergé). Une boucle Messages API impliquerait de reconstruire le harnais.
2. Ne doit jamais éditer → permission_mode="plan" (lecture seule) et une allowlist d’outils sans Edit/Write.
3. Focus sécurité → un subagent security-reviewer sur claude-sonnet-5 (moins cher, suffisant), outils Read, Grep, Bash(git diff:*).
4. Application → un refus PreToolUse pour toute écriture, déterministe, pas une phrase de prompt.
5. Faire échouer le build → parser le message result ; sys.exit(1) sur un constat.
6. Sécurité coût/boucle → plafonner max_turns ; journaliser total_cost_usd ; toujours brancher sur stop_reason.

Alternatives rejetées : Managed Agents (viole la localité des données), bypassPermissions (agence excessive), appliquer la lecture seule via le prompt système (prompt-comme-application), et utiliser un plafond de tours comme signal de complétion (anti-pattern de plafond d’itérations).

Points clés à retenir

• L’Agent SDK est auto-hébergé ; les Managed Agents sont hébergés par Anthropic ; choisissez selon le contrôle runtime/données vs la charge d’ops.
• La terminaison de boucle est stop_reason ; max_turns n’est qu’un garde-fou contre l’emballement.
• Appliquez les règles avec les hooks / can_use_tool, jamais avec du texte de prompt.
• Les subagents ne reçoivent que le contexte transmis explicitement ; donnez-leur leur propre modèle (souvent moins cher) et une allowlist d’outils serrée.
• Les outils MCP sont mcp__server__tool ; allowlistez-les et gardez l’ensemble petit.
• bypassPermissions est réservé au CI sandboxé.