Tutoriel

Claude Agent SDK officiel : un assistant personnel honnête et auditable (2026)

Équipe MacLogin IA 1 juin 2026 ~12 min

Le Claude Agent SDK d’Anthropic permet d’intégrer la même boucle d’outils que Claude Code dans votre application Python ou TypeScript. Règle pour débutants : démarrez en lecture seule, ajoutez un system_prompt d’honnêteté, puis élargissez allowed_tools uniquement lorsque les journaux d’audit sont corrects.

Voir aussi : Claude Code via SSH, Cursor Rules vs Skills, benchmarks agent Opus 4.8.

Divulgation : MacLogin publie ce guide. Suivez la documentation officielle Agent SDK et utilisez une clé API Claude Console — pas de revente de connexion claude.ai dans des apps tierces.

Pourquoi commencer par le SDK officiel

Les wrappers masquent souvent quels outils s’exécutent et ce qui quitte votre machine. Le SDK documente Read, Edit, Bash, permissions, hooks et sessions sur code.claude.com.

Un Mac cloud est facultatif pour des plannings 24/7 ; votre portable suffit pour un premier assistant protégé.

Structure du SDK

Couche	Rôle	Vous configurez
`query()`	Boucle agent (plan → outil → observation)	`agent.py`
Tools	Fichier, shell, recherche, web	`allowed_tools`
Permissions	Approuver / refuser / demander	`permission_mode`
Policy	Honnêteté, périmètre	`system_prompt`, `CLAUDE.md`
Audit	Journaliser l’usage des outils	`hooks`

À partir du 15 juin 2026, les abonnements comptabilisent l’Agent SDK via un pool de crédits séparé — budgétisez les boucles sans surveillance.

Runbook protégé en huit étapes

Étape 1 — Prérequis

python3 --version   # 3.10+
pip install claude-agent-sdk

Étapes 2–3 — Projet + installation

mkdir my-guarded-agent && cd my-guarded-agent
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk

Étape 4 — Clé API

# .env (gitignore this file)
ANTHROPIC_API_KEY=sk-ant-...

Étapes 5–6 — Prompt d’honnêteté + exécution lecture seule

from claude_agent_sdk import query, ClaudeAgentOptions

HONEST = """Say "I don't know" when data is missing.
Never invent paths or command output."""

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="dontAsk",
    system_prompt=HONEST,
)

Exécution : python3 agent.py — voir le quickstart.

Étapes 7–8 — Hook d’audit, puis éditions

Ajoutez des hooks PostToolUse vers audit.log avant d’activer Edit avec permission_mode="acceptEdits". Optionnel : AskUserQuestion pour clarifier.

Dépannage

Clé API introuvable

Correctif : Exportez ANTHROPIC_API_KEY dans le même shell ; ne commitez jamais .env.

pip: No matching distribution

Correctif : Utilisez Python 3.10+ ; recréez .venv.

thinking.type.enabled not supported

Correctif : Mettez à jour l’Agent SDK vers v0.2.111+ pour Opus 4.7+ ([quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart)).

Modifications de fichiers inattendues

Correctif : Revenez en arrière avec git ; repassez à dontAsk et outils lecture seule jusqu’à ce que les hooks prouvent la sécurité.

FAQ

Agent SDK vs Claude Code ?

Claude Code est l’app interactive ; le SDK est une bibliothèque intégrée via query() et ClaudeAgentOptions.

Mode permission le plus sûr ?

dontAsk avec Read, Glob, Grep uniquement.

Utiliser Opus 4.8 ?

Oui — définissez le modèle dans les options. Appliquez toujours des listes d’outils locales ; voir le guide benchmark.

Besoin de MacLogin ?

Non — clé API seulement. Mac distant facultatif pour agents toujours actifs.

vs Messages API ?

Messages API : vous implémentez la boucle d’outils. Agent SDK : boucle Anthropic + outils intégrés — v1 protégée plus rapide.

Équipe MacLogin IA

Guides Agent SDK, permissions et assistants honnêtes.

Option : Mac cloud pour agents 24/7

Le quickstart fonctionne sur portable—location Mac seulement si besoin.

Tarifs Aide