Agents : le SDK agent, les agents managés et la planification

Un agent, c'est simplement Claude dans une boucle avec des outils, qui tourne jusqu'à ce qu'une tâche soit réellement terminée. Cette seule idée résume toute la leçon. Un appel APIAPIApplication Programming Interface : une interface standardisée qui permet aux applications de communiquer et d'échanger des données sans connaître leur fonctionnement interne respectif.Voir la définition complète → normal donne à Claude un tour pour répondre ; un agent donne à Claude la capacité d'appeler un outil, voir le résultat, décider quoi faire ensuite, appeler un autre outil, et continuer jusqu'à ce qu'il juge le travail terminé ou que vous l'arrarrL'Annual Recurring Revenue (ARR) est le revenu normalisé et prévisible qu'une entreprise par abonnement attend de ses contrats actifs sur une année.Voir la définition complète →êtiez.

Vous connaissez déjà les briques (tool use, MCPMCPUn standard ouvert qui permet aux assistants IA de se connecter aux outils et données de l'entreprise de façon cohérente et gouvernée, sans intégration sur mesure à chaque fois.Voir la définition complète →, la Messages API). Cette leçon porte sur leur assemblage en quelque chose qui tourne en autonomie, et sur le point de production que personne n'évoque dans les tutoriels : comment faire tourner un agent selon une planification sans avoir à le surveiller.

Quand un agent vaut mieux qu'un appel unique

Optez pour un simple appel à la Messages API quand la tâche est one-shot et autoportante : résumer ce texte, classer ce ticket, rédiger cet email. Une entrée, une sortie, terminé.

Optez pour un agent quand la tâche exige de la découverte, de l'itération ou du branchement que vous ne pouvez pas scripter à l'avance. Le signe, c'est quand vous ne pouvez pas écrire la séquence exacte des étapes en amont parce que les étapes dépendent de ce que Claude trouve en chemin.

Exemples concrets où un agent se justifie :

• « Cherche pourquoi notre taux d'erreur a grimpé cette nuit » (Claude doit interroger les logs, repérer un motif, interroger à nouveau, corréler avec un déploiement).
• « Réconcilie les paiements Stripe d'hier avec notre table de commandes et signale les écarts » (nombre de requêtes variable, dépend des données).
• « Relis cette PR, lance les tests et corrige ce qui échoue » (les corrections dépendent des tests qui échouent).

Si vous vous retrouvez à écrire un arbre de if/else géant autour d'appels de modèle, c'est probablement un agent qu'il vous faut. Si un seul prompt avec du bon contexte fait le travail, ne surdimensionnez pas.

Le Claude Agent SDK, en clair

Le Claude Agent SDK est la boîte à outils officielle pour construire des agents sur le même harnais que celui qui fait tourner Claude Code. Il gère la boucle pour vous : il gère la conversation, expose les outils à Claude, exécute les appels d'outils que Claude demande, réinjecte les résultats, et répète jusqu'à l'achèvement.

Le changement mental clé : avec la Messages API brute, vous écrivez la boucle vous-même (appel, vérification de tool_use, exécution de l'outil, ajout du résultat, nouvel appel). L'Agent SDK possède cette boucle, vous vous concentrez donc sur les outils dont dispose l'agent et sur ce que vous voulez obtenir.

Trois choses que le SDK vous donne d'emblée :

• La boucle d'agent, y compris la gestion du contexte à mesure que la conversation s'allonge.
• Les outils, y compris des outils intégrés comme les opérations sur fichiers et les commandes shell, plus tout ce que vous exposez via MCP (Model Context Protocol, le standard ouvert pour connecter Claude à des systèmes et des données externes).
• Les permissions et les garde-fous, pour décider ce que l'agent a le droit de toucher.

Il existe en TypeScript et en Python. Comme il partage ses fondations avec Claude Code, un agent que vous construisez avec lui peut lire des fichiers, lancer des commandes et éditer du code avec la même compétence que celle que vous avez vue dans Claude Code, mais pointée sur *votre* tâche au lieu d'une session de terminal interactive.

Agents managés ou exécution par vous-même

Il y a deux façons d'opérer un agent, et la distinction compte pour la planification.

Auto-hébergé : vous faites tourner l'Agent SDK dans votre propre processus, sur votre machine, votre conteneur ou votre fonction serverless. Vous possédez le runtime, les secrets et la planification. Contrôle maximal, plus de travail d'ops.

Agents managés : Anthropic fait tourner la boucle d'agent sur son infrastructure. Vous définissez l'agent (ses outils, ses instructions, ses permissions) et Anthropic l'exécute, en prenant en charge l'orchestration, les retries et le scaling. Vous déléguez la charge opérationnelle.

La recommandation pratique : prototypez en auto-hébergé parce que la boucle de feedback est rapide et que vous pouvez tout logger. Passez aux agents managés quand vous avez besoin de fiabilité, d'isolation, et que vous préférez ne pas maintenir de serveur. Pour la planification en particulier, un agent managé associé à un déclencheur de type cron supprime presque toutes les pièces mobiles.

Note de vocabulaire : un agent est ici une boucle Claude-plus-outils configurée. Un connecteur (des applications Claude et de la marketplace de connecteurs) est une intégration packagée qui expose un service à Claude via MCP. Une Skill est une capacité packagée et réutilisable. Les agents peuvent *utiliser* des connecteurs et des Skills comme outils.

Un exemple concret : l'agent de rapport nocturne

Construisons le cas canonique : un agent qui tourne chaque nuit, récupère les chiffres de la veille, écrit un rapport court et le poste sur Slack.

Pourquoi un agent et pas un script ? Parce que « écrire un rapport court » est exactement l'étape floue, chargée de jugement, qu'un script ne peut pas faire et pour laquelle un appel API unique ne peut pas *collecter les données* de façon fiable. L'agent interroge la base (peut-être plusieurs fois selon ce qu'il voit), interprète les chiffres, décide ce qui mérite d'être mis en avant, et met en forme le message.

Voici une esquisse Python propre avec l'Agent SDK. L'agent reçoit deux outils (un outil de requête base de données et un outil de publication Slack) et une instruction. Notez le peu de code d'orchestration : la boucle vit à l'intérieur de query.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, tool, create_sdk_mcp_server

@tool("run_sql", "Run a read-only SQL query against the analytics DB", {"sql": str})
async def run_sql(args):
    rows = await analytics_db.fetch(args["sql"])
    return {"content": [{"type": "text", "text": str(rows)}]}

@tool("post_to_slack", "Post a message to the #metrics channel", {"text": str})
async def post_to_slack(args):
    await slack.post(channel="#metrics", text=args["text"])
    return {"content": [{"type": "text", "text": "posted"}]}

tools = create_sdk_mcp_server(name="report-tools", tools=[run_sql, post_to_slack])

PROMPT = """Pull yesterday's signups, revenue, and active users from the
analytics DB. Compare each to the prior day. Write a 5-line report that
leads with anything unusual, then post it to Slack."""

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"report": tools},
        allowed_tools=["mcp__report__run_sql", "mcp__report__post_to_slack"],
        system_prompt="You are a careful analytics assistant. Query before you conclude.",
    )
    async for message in query(prompt=PROMPT, options=options):
        print(message)

asyncio.run(main())

Quelques points à remarquer :

• allowed_tools est votre garde-fou. L'outil SQLSQLSales Qualified Lead : un prospect que l'équipe commerciale a validé comme prêt pour une prise de contact directe et une proposition, après avoir passé des critères de qualification explicites.Voir la définition complète → est en lecture seule par construction ; l'agent ne peut littéralement pas supprimer une table parce que vous ne lui en avez jamais donné la capacité.
• L'instruction dit « Query before you conclude. » Cela pousse l'agent à réellement regarder les données plutôt qu'à halluciner des chiffres, ce qui est l'habitude la plus importante pour un agent de reporting.
• La boucle est invisible. Claude décide combien d'appels run_sql il lui faut. Si les inscriptions semblent bizarres, il peut creuser avant d'écrire le rapport.

Planification : le faire tourner à une cadence

Un agent que vous déclenchez à la main est une démo. Un agent qui tourne chaque nuit à 2h pendant que vous dormez est un produit. La planification fait la différence.

Il n'y a rien de magique ici, et c'est une bonne nouvelle : une exécution d'agent n'est qu'un processus que vous pouvez invoquer. Choisissez le mécanisme de déclenchement qui correspond à l'endroit où vit l'agent.

Option 1 : cron système (auto-hébergé). Si l'agent tourne sur un serveur que vous contrôlez, un cron classique suffit. Une ligne dans votre crontab :

0 2 * * * cd /opt/nightly-report && /usr/bin/python3 agent.py >> /var/log/report.log 2>&1

Cela lance `agent.py` à 02:00 chaque jour et ajoute la sortie à un log. Simple, durable, et vous pouvez lire le log quand quelque chose cloche.

Option 2 : une fonction serverless planifiée. Un scheduler cloud (un Lambda planifié, un job Cloud Run, un déclencheur schedule GitHub Actions) invoque l'agent sur une expression cron sans que vous gardiez un serveur en vie. Vous ne payez que quand il tourne. C'est le point d'équilibre pour la plupart des jobs nocturnes.

Voici la version GitHub Actions, qui est honnêtement la plus simple si votre code vit déjà dans un repo :

name: nightly-report
on:
  schedule:
    - cron: "0 2 * * *"
  workflow_dispatch: {}   # vous permet aussi de le déclencher manuellement
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install claude-agent-sdk
      - run: python agent.py
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

La ligne workflow_dispatch est une petite habitude mais importante : elle vous donne un bouton manuel « lancer maintenant » pour tester sans attendre 2h du matin. Stockez votre clé comme secret de dépôt, jamais dans le fichier.

Option 3 : agents managés avec une planification. Quand vous faites tourner l'agent sur l'infrastructure managée d'Anthropic, vous attachez une planification à la définition de l'agent plutôt que de câbler votre propre cron. La boucle d'agent, les retries et l'environnement d'exécution sont pris en charge ; vous fournissez la cadence et le déclencheur. Consultez la documentation de l'Agent SDK à jour pour la configuration exacte, la surface managée évoluant vite au fil de 2025 et 2026.

Ce qui change dès qu'il tourne sans surveillance

Un agent planifié est autonome, ce qui soulève trois préoccupations qu'un appel ponctuel n'a jamais eues. Concevez pour elles dès le premier jour.

Idempotence et échec partiel. Si l'agent poste sur Slack puis que l'exécution plante ensuite, l'exécution de demain va-t-elle poster en double ? Pour un rapport c'est sans conséquence, mais pour tout ce qui écrit des données, rendez les actions d'outils sûres à réexécuter ou vérifiez si le travail a déjà été fait avant de le faire.

Observabilité. Vous ne regardez pas. Loggez chaque appel d'outil et le résultat final, et faites en sorte que l'agent lui-même signale son succès ou son échec à un endroit que vous verrez (un thread Slack, une ligne de statut). Si le rapport nocturne cesse d'apparaître, cette absence doit être bruyante.

Coût et boucles qui s'emballent. Un agent dans une boucle peut, dans des cas pathologiques, appeler des outils bien plus souvent que prévu. Fixez une limite de tours ou de budget pour qu'un agent perdu s'arrête au lieu de tourner pendant une heure. L'Agent SDK vous permet de plafonner cela ; utilisez-le.

Moindre privilège. Cela mérite d'être répété parce que c'est l'assurance la moins chère à votre disposition. L'agent nocturne obtient un rôle base de données en lecture seule et un seul canal Slack. Rien de plus. Un agent sans surveillance ne devrait jamais détenir des permissions dont il n'a pas strictement besoin pour son unique travail.

Points clés

• Utilisez un agent quand les étapes dépendent de ce que Claude découvre. Si vous pouvez scripter la séquence exacte, un simple appel à la Messages API est plus simple et moins cher. Si vous ne pouvez pas, la boucle se justifie.
• Laissez l'Agent SDK posséder la boucle. Votre travail consiste à définir les outils (souvent via MCP), écrire une instruction claire et régler les permissions. Prototypez en auto-hébergé, puis passez aux agents managés quand vous voulez qu'Anthropic gère le runtime.
• La planification n'est qu'un déclencheur sur un processus normal. Cron système pour un serveur que vous possédez, un job serverless planifié ou un schedule GitHub Actions dans la plupart des cas, ou une planification attachée directement à un agent managé.
• Concevez explicitement pour un fonctionnement sans surveillance : rendez les actions d'écriture idempotentes, loggez chaque appel d'outil pour que les échecs soient bruyants, plafonnez les tours pour éviter les boucles qui s'emballent, et accordez le moindre privilège pour que l'agent ne puisse toucher qu'à son unique travail.
• Prévoyez toujours un déclencheur manuel (workflow_dispatch, un chemin « lancer maintenant ») pour tester l'agent sans attendre le déclenchement de la planification.