01 · Agents and Workflows : choisir, construire et encadrer un agent Claude

Version : 1.1 · Date : 2026-10-22 · Domaine 1 : Agents and Workflows (14,7 %)

En une phrase : on choisit la solution la plus simple qui marche (un appel, puis un workflow, puis un agent seulement si le chemin est imprévisible), on construit l'agent sur un harness qui plafonne tours et dépenses (Claude Agent SDK chez soi, Claude Managed Agents chez Anthropic), et on garantit les règles métier par du code (hooks), jamais par le seul prompt.

Ce chapitre ouvre le cours Claude Developer. Le cours voisin Claude Architect traite déjà en profondeur la boucle agentique, le coordinator, le passage de contexte, les hooks et les sessions : ici, on renvoie à ses sections et on ajoute ce qui est propre au CCDV-F (workflow ou agent, les cinq workflows, Claude Managed Agents, frameworks tiers).

Ce que l'examen demande#

Texte officiel du Claude Certified Developer – Foundations Exam Guide v1.0 (juillet 2026) :

Convention du cours : le produit évolue plus vite que le guide v1.0. Quand c'est le cas, un encadré donne d'abord la réponse d'examen (celle du guide), puis l'état actuel du produit (relevé le 22/10/2026 sur la doc officielle).

0. L'examen CCDV-F en bref#

Différence avec le CCAR-F (Architect) : l'Architect est bâti sur des scénarios d'architecture (4 tirés parmi 6) et pèse lourd sur l'orchestration (27 %). Le Developer est un examen de développeur : plus d'un tiers porte sur l'intégration applicative et les mécanismes de l'API (domaine 2, 33,1 %), et il ajoute le choix de modèle et les coûts (16,8 %) et la sécurité (8,1 %), presque absents de l'Architect. Environ 40 % des notions sont communes : ce cours y renvoie.

1. Agent Architecture (skill 1.1)#

1.1 La taxonomie : augmented LLM, workflow, agent#

Le critère de classement d'Anthropic est simple : qui décide de l'étape suivante ?

Piège classique : plusieurs appels et l'accès aux outils ne font pas un agent. Un pipeline codé en trois étapes reste un workflow, même avec un modèle très capable.

1.2 Workflow ou agent : les critères de décision#

La règle d'Anthropic : trouver la solution la plus simple possible, et n'ajouter de la complexité que si elle améliore nettement le résultat. Un système agentique échange de la latence et du coût contre de la performance sur les tâches ouvertes ; pour beaucoup d'applications, un seul appel bien optimisé (retrieval, exemples en contexte) suffit.

flowchart TD
    A["Nouvelle tâche"] --> B{"Un seul appel bien outillé<br/>(retrieval, exemples) suffit ?"}
    B -- oui --> C["Augmented LLM"]
    B -- non --> D{"Étapes connues d'avance<br/>et identiques à chaque fois ?"}
    D -- oui --> E{"Une décision de<br/>classification au départ ?"}
    E -- oui --> F["Routing"]
    E -- non --> G["Prompt chaining<br/>ou parallelization"]
    D -- non --> H{"Critères de qualité clairs<br/>et raffinement utile ?"}
    H -- oui --> I["Evaluator-optimizer"]
    H -- non --> J{"Sous-tâches découvertes<br/>en cours de route ?"}
    J -- oui --> K["Agent, ou orchestrator-workers<br/>(subagents)"]
    J -- non --> G

1.3 Manager / supervisor et subagents#

Dans une hiérarchie manager / supervisor (orchestrator-workers), un agent principal décompose la tâche, délègue à des subagents spécialisés et synthétise leurs résultats. Les règles détaillées (hub-and-spoke, quatre responsabilités du coordinator, piège de la décomposition trop étroite) sont dans Architect § 2. Ce qu'il faut retenir pour le CCDV-F :

Diagnostic d'un mauvais résultat multi-agent : commencer par le supervisor (délégation vague, périmètres qui se chevauchent, trop de subagents lancés), pas par les subagents qui ont fait ce qu'on leur a demandé.

Réponse d'examen : hub-and-spoke strict, tout passe par le supervisor.

État actuel (doc Agent SDK, relevé du 22/10/2026) : par défaut, un subagent lancé par l'agent principal tourne en arrière-plan (status: "async_launched") et son rapport arrive dans un tour suivant ; l'outil SendMessage permet d'écrire à d'autres agents nommés de la session. À l'examen, on répond hub-and-spoke.

Côté Claude Managed Agents (voir § 2.3), la délégation est encadrée par la plateforme : un seul niveau de délégation (un agent listé qui a lui-même une configuration multiagent fait échouer la requête en 400), jusqu'à 20 agents dans la liste predefined_agents, et au plus 25 child threads actifs ou inactifs par session. Tous partagent le sandbox, le système de fichiers et les credentials du vault, chacun dans son propre session thread au contexte isolé.

1.4 Quand ne pas utiliser d'agent, ni plusieurs#

• Étapes fixes : un agent coûte plus cher pour un résultat moins prévisible qu'un workflow.
• Sous-tâches couplées : plusieurs agents en parallèle sur des sous-tâches qui dépendent l'une de l'autre se marchent dessus.
• Plus de subagents ≠ meilleur résultat : chaque subagent consomme des jetons et doit être briefé.
• Règle stricte : si une règle doit être garantie (jamais la base de prod, montant maximal de remboursement), ce n'est pas une question d'architecture d'agent mais de hook ou de gate dans l'outil (§ 2.4).

2. Agent Construction with Claude (skill 1.2)#

2.1 La boucle nue et le harness#

Toute boucle d'agent a la même forme : envoyer le prompt et les définitions d'outils, exécuter les outils demandés, renvoyer les tool_result, recommencer jusqu'à une réponse sans appel d'outil. Le code complet sur la Messages API (pilotage par stop_reason, anti-patterns) est dans Architect § 1.

Le harness, c'est tout ce qui entoure la boucle en production : plafond de tours, budget, nouvelles tentatives, validation des résultats d'outils, persistance de l'état, observabilité, compaction. Ces mécanismes relèvent du code, jamais du prompt : « arrête-toi après trente appels » dans un prompt est une demande ; max_turns met fin à l'exécution.

2.2 Le Claude Agent SDK#

Le SDK (Python claude_agent_sdk, TypeScript @anthropic-ai/claude-agent-sdk) embarque la boucle de Claude Code : outils intégrés (Read, Edit, Write, Glob, Grep, Bash, WebSearch, WebFetch, Agent, Skill…), permissions, hooks, subagents, sessions avec reprise et compaction automatique.

Deux modes d'entrée :

Limites et résultat (aucune limite par défaut ; un budget est un bon défaut en production) :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    session_id = None
    try:
        async for message in query(
            prompt="Trouve et corrige le test qui échoue dans le module auth",
            options=ClaudeAgentOptions(
                allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],  # pré-approuvés, sans demande
                max_turns=30,          # tours avec outils
                max_budget_usd=2.0,    # dépense estimée, subagents compris
            ),
        ):
            if isinstance(message, ResultMessage):
                session_id = message.session_id           # présent même en cas d'erreur
                if message.subtype == "success":
                    print(message.result)                 # result n'existe que sur success
                else:
                    print(f"Arrêt : {message.subtype}, reprendre la session {session_id}")
    except Exception as error:
        # un query() en un coup lève une exception APRÈS avoir livré le ResultMessage d'erreur
        print(f"Session terminée en erreur : {error}")


asyncio.run(main())

Tous les sous-types portent total_cost_usd, usage (boucle principale seulement, sans les sous-agents : préférer model_usage pour la comptabilité), num_turns et session_id. Le champ stop_reason du résultat indique pourquoi le modèle s'est arrêté au dernier tour (end_turn, max_tokens, refusal).

Piège d'examen : error_max_turns n'est pas un échec du modèle. C'est une limite que vous avez configurée. Changer de modèle ou réécrire le prompt ne corrige pas un plafond mal dimensionné. Et max_iterations, turn_cap ou budget_limit n'existent pas dans l'Agent SDK : les noms sont max_turns / maxTurns et max_budget_usd / maxBudgetUsd.

L'option effort (low, medium, high, xhigh, max) règle la profondeur de raisonnement par session, et AgentDefinition.effort (niveau nommé ou entier) par sous-agent ; le choix des modèles et de l'effort est détaillé au chapitre 04.

2.3 Où l'agent s'exécute : self-hosted ou Anthropic-hosted#

Le guide distingue deux modèles de déploiement. Il faut séparer deux questions : qui exécute le harness, et où tourne le sandbox (outils, fichiers, trafic sortant).

Piège d'examen : Claude Managed Agents n'est pas « l'Agent SDK hébergé ». Ce sont deux produits : le SDK exécute la boucle dans votre processus ; Managed Agents expose un harness hébergé par une API.

Self-hosted SDK en conteneur : par défaut, le SDK écrit les transcripts sur le disque local (~/.claude/projects/). Un conteneur détruit perd donc la session. Pour reprendre ailleurs, passer un adaptateur session_store / sessionStore, qui réplique les transcripts vers votre stockage.

2.4 Hooks pour les actions déterministes#

Un hook est du code de votre application exécuté à un point fixe de la boucle. Il ne consomme pas de contexte et ne dépend pas du bon vouloir du modèle. La formule à retenir : « Prompts request, hooks enforce ».

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

PROD_CLI = ("psql", "prod-db")  # motifs interdits, à adapter


async def bloquer_prod(input_data, tool_use_id, context):
    commande = input_data["tool_input"].get("command", "")
    if any(motif in commande for motif in PROD_CLI):
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Accès à la base de production interdit",
            }
        }
    return {}  # objet vide : l'appel continue


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

Points d'examen :

• Le refus revient à Claude comme un résultat d'outil : il change de stratégie au lieu de planter.
• Plusieurs hooks PreToolUse en désaccord : deny l'emporte, puis defer, puis ask, puis allow.
• Un matcher porte sur le nom de l'outil (Bash, Write|Edit, ^mcp__), pas sur les arguments : filtrer le chemin ou la commande dans la fonction.
• Le détail (deux directions, normalisation des données, règle de décision) est dans Architect § 5 ; les hooks comme garde-fous de sécurité sont repris au chapitre 06.

sequenceDiagram
    participant C as Claude
    participant H as Hook PreToolUse (votre code)
    participant T as Outil Bash
    C->>H: tool_use « psql prod … »
    H-->>C: deny + permissionDecisionReason
    Note over T: l'outil n'est jamais exécuté
    C->>H: tool_use « npm test »
    H->>T: {} (autorisé)
    T-->>C: tool_result

3. Agent Patterns and Frameworks (skill 1.3)#

3.1 Les cinq workflows#

Les quatre paires à ne pas confondre :

3.2 Les patterns agentiques : boucle, subagents, mémoire, contexte#

Quatre façons de « se souvenir » :

Sécurité du memory tool : votre gestionnaire doit valider chaque chemin (rester sous /memories, résoudre la forme canonique, rejeter ../ et ses formes encodées %2e%2e%2f), plafonner la taille des fichiers et ce que view renvoie (pagination par view_range).

Frontière entre domaines : choisir l'architecture (subagent, fichier mémoire) relève du domaine 1 ; les techniques de gestion de la fenêtre (quoi élaguer, comment résumer, compaction) relèvent du domaine 6 (chapitre 05).

3.3 Frameworks tiers#

Le conseil d'Anthropic : commencer par appeler l'API directement ; beaucoup de patterns tiennent en quelques lignes. Un framework simplifie le bas niveau mais ajoute une abstraction qui masque prompts et réponses et complique le débogage ; s'il est utilisé, il faut comprendre le code qu'il exécute.

4. Labs conseillés#

Un compte Claude Console avec une clé API dans ANTHROPIC_API_KEY (jamais en dur dans le code). Les labs coûtent quelques dizaines de centimes à quelques dollars avec un petit modèle ; fixer max_budget_usd partout.

1. Workflow ou agent (30 min)
   • Prendre deux automatisations réelles : une aux étapes fixes, une dont le chemin dépend des découvertes.
   • Classer chacune (augmented LLM, workflow, agent) avec une phrase de justification.
   • Implémenter la première en prompt chaining avec une gate en code entre deux appels Messages API.
   • Attendu : le workflow donne la même séquence à chaque exécution ; noter le coût et la latence.
2. Atteindre chaque limite volontairement (30 min, Agent SDK)
   • max_turns=2 sur une tâche qui en demande plus : observer error_max_turns, sans result.
   • Capturer session_id, reprendre avec resume=session_id et une limite relevée.
   • max_budget_usd très bas sur une tâche gourmande : observer error_max_budget_usd.
   • Attendu : un tableau sous-type ↔ cause tiré de vos propres exécutions.
3. Hook de blocage (20 min)
   • Ajouter le hook PreToolUse de la § 2.4 sur Bash avec un motif inoffensif (par exemple rm -rf), puis demander à l'agent de l'exécuter.
   • Attendu : l'appel est refusé avant exécution, la raison apparaît dans le flux, l'agent change de stratégie.
4. Supervisor et subagents (40 min)
   • Définir deux subagents en lecture seule (tools=["Read", "Grep", "Glob"]) avec AgentDefinition, et un brief complet.
   • Retirer un fait du brief et observer l'erreur qui en découle.
   • Fixer CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 et max_budget_usd.
   • Attendu : le subagent sans le fait se trompe ; le coût total inclut les subagents.
5. Evaluator-optimizer (30 min, Messages API)
   • Un appel rédige, un second note selon trois critères écrits, la critique repart au rédacteur, plafond de 3 tours.
   • Attendu : la note monte puis se stabilise ; la boucle s'arrête au plafond même si les critères ne sont pas tous atteints.

Nettoyage : supprimer les clés API de test dans la Console, et les sessions Managed Agents si vous en avez créé.

5. Pièges d'examen#

6. Scénarios corrigés (QCM originaux)#

1. Une équipe traite des factures : extraction des champs, vérification d'un total, puis export comptable, toujours dans cet ordre. Le prototype est un agent avec trois outils. Que recommander ? A. Garder l'agent et ajouter un modèle plus capable B. Un workflow en prompt chaining, avec une gate en code qui vérifie le total C. Un orchestrator-workers avec trois subagents D. Un evaluator-optimizer pour fiabiliser l'export

B. Les étapes sont fixes et identiques à chaque exécution : c'est un workflow. La gate en code garantit la vérification. A et C ajoutent coût et imprévisibilité ; D sert quand il faut raffiner une sortie selon des critères.

2. Un supervisor délègue la rédaction de trois sections de rapport. Les subagents ignorent la charte de style décrite au début de la conversation avec l'utilisateur. Cause la plus probable ? A. Les subagents ont un modèle trop petit B. Le brief ne contient pas la charte : un subagent ne voit pas la conversation du parent C. La compaction a effacé la charte D. Il faut activer la mémoire partagée entre subagents

B. Seul le prompt de délégation passe. D n'existe pas comme tel ; A et C ne règlent pas un problème de transmission.

3. Un job Agent SDK nocturne s'arrête avec error_max_turns une fois sur trois. Que faire en premier ? A. Passer à un modèle plus capable B. Ajouter « termine en moins de 30 étapes » au prompt C. Reprendre la session avec resume=session_id et une limite relevée, ou découper la tâche D. Remplacer max_turns par max_iterations

C. C'est une limite de configuration, pas un échec du modèle. B est une demande non garantie ; D n'existe pas.

4. Un agent de maintenance a accès à Bash. Il ne doit jamais lancer terraform destroy, même si un fichier du dépôt le lui demande. Quel contrôle garantit la règle ? A. Une instruction dans CLAUDE.md B. Un hook PreToolUse sur Bash qui renvoie permissionDecision: "deny" pour ce motif C. Un hook PostToolUse qui journalise les commandes D. Réduire max_turns

B. Seul un hook avant l'outil bloque de façon déterministe. A est une demande ; C agit après coup ; D ne bloque rien.

5. Une société veut un agent qui tourne plusieurs heures chaque nuit, avec un sandbox, l'historique conservé côté serveur et un minimum d'infrastructure à gérer. Les données doivent rester dans son réseau. Quelle option ? A. Claude Agent SDK sur un poste développeur B. Claude Managed Agents avec un self-hosted sandbox C. Une boucle maison sur la Messages API D. Claude Managed Agents avec le cloud sandbox d'Anthropic

B. Managed Agents fournit le harness hébergé, l'état côté serveur et la planification ; le self-hosted sandbox exécute les outils et garde les fichiers sur l'infrastructure du client. D ne répond pas à l'exigence de résidence.

6. Une application route les questions de support : facturation vers un prompt spécialisé avec un outil de lecture de factures, technique vers un autre prompt avec la documentation. Quel pattern ? A. Routing B. Prompt chaining C. Voting D. Orchestrator-workers

A. Une décision de classification envoie l'entrée vers un traitement spécialisé.

7. Une revue de code lance trois analyses indépendantes et connues d'avance (style, sécurité, couverture), puis agrège. A. Orchestrator-workers B. Sectioning C. Evaluator-optimizer D. Routing

B. Sous-tâches indépendantes et énumérables d'avance. Orchestrator-workers suppose des sous-tâches découvertes à l'exécution.

8. Une équipe Python veut un agent dont la réponse finale est toujours un objet validé contre un modèle de données. Quel framework tiers correspond le mieux à ce besoin ? A. LangGraph B. Pydantic AI C. Strands Agents D. Aucun : impossible

B. Pydantic AI valide les sorties contre un type déclaré. LangGraph sert à modéliser un flux en graphe.

9. Un agent Agent SDK tourne dans un conteneur détruit après chaque requête HTTP ; le lendemain, il doit reprendre la conversation de la veille. Que faire ? (deux réponses) A. Capturer session_id et le passer à resume à la requête suivante B. Configurer un session_store qui réplique les transcripts vers un stockage externe C. Relancer avec le même prompt initial D. Augmenter max_turns

A et B. La reprise demande l'identifiant de session et un transcript qui survit au conteneur.

10. Le budget d'une requête est max_budget_usd=5. Le supervisor lance dix subagents. Que se passe-t-il quand la dépense estimée atteint 5 USD ? A. Les subagents continuent : leur budget est séparé B. Les nouveaux lancements de subagents échouent et la requête se termine en error_max_budget_usd C. Le supervisor passe automatiquement à un modèle moins cher D. Rien : le budget est indicatif

B. Le plafond couvre les subagents : un nouveau lancement échoue (« Budget limit reached ») et la requête se termine avec ce sous-type.

7. Pour aller plus loin (hors examen ou état actuel)#

• Dynamic workflows : pour des dizaines ou des centaines d'agents, l'outil Workflow (TypeScript Agent SDK) déplace l'orchestration dans un script exécuté hors du contexte de la conversation ; seul le résultat final y revient.
• Advisor (Managed Agents) : le thread principal peut consulter un modèle conseiller en cours de tour pour planifier ou relire.
• Claude Code : les mêmes notions (subagents dans .claude/agents/, hooks, sessions) sont traitées en configuration au chapitre 03 et dans Architect 03.
• Lecture de fond : Building effective agents, How we built our multi-agent research system et Effective context engineering for AI agents (Anthropic Engineering).

8. Fiche à retenir#

• Qui décide de la suite ? Le code : workflow. Le modèle : agent. Un seul appel outillé suffit souvent.
• La solution la plus simple d'abord ; un agent seulement si le chemin est imprévisible.
• Supervisor : décompose, délègue avec un brief complet, synthétise ; le subagent ne voit que son prompt (sauf fork).
• Plafonds SDK : profondeur 3, 20 subagents simultanés, max_budget_usd cumulatif.
• max_turns et max_budget_usd : aucune limite par défaut ; mettre un budget en production.
• ResultMessage.subtype avant result ; error_max_turns = reprendre la session, pas changer de modèle.
• query() pour un appel ponctuel ; ClaudeSDKClient (streaming input) pour un agent longue durée.
• Claude Managed Agents : API hébergée, beta (managed-agents-2026-04-01), Agent / Environment / Session / Events, sandbox Anthropic ou self-hosted, pas de ZDR ni BAA.
• Prompts request, hooks enforce : PreToolUse + deny bloque avant l'outil ; deny l'emporte sur tout.
• Cinq workflows : chaining, routing, parallelization (sectioning, voting), orchestrator-workers, evaluator-optimizer.
• Memory tool memory_20250818 : côté client, /memories, valider les chemins.
• LangGraph = graphe d'états ; Pydantic AI = sorties typées ; Strands = boucle pilotée par le modèle ; API directe d'abord.

Références#

Lues le 22/10/2026 :

• Claude Certified Developer – Foundations Exam Guide v1.0 (PDF officiel)
• Anthropic Partner certifications
• Building effective agents
• How we built our multi-agent research system
• Effective context engineering for AI agents
• How the agent loop works (Agent SDK)
• Agent SDK overview
• Subagents in the SDK
• Intercept and control agent behavior with hooks
• Streaming input vs single message mode
• Work with sessions
• Persist sessions to external storage
• Hosting the Agent SDK
• Claude Managed Agents overview
• Multiagent orchestration (Managed Agents)
• Self-hosted sandboxes
• Memory tool
• Compaction
• LangGraph overview
• Pydantic AI
• Strands Agents
• Cursus tiers utilisé comme base : claudecertificationguide.com, CCDV-F, domaine 1