Notes pratiques : Boucles agentielles et modèles de conception
Guide pratique détaillé : Boucles agentes et modèles de conception : contrats, vérifications et emplacements de code prêts à l’emploi pour les équipes qui utilisent ce modèle.
Les notes suivantes reconstituent une approche pratique concernant les « boucles agentes et modèles de conception ». L’accent est mis sur les contrats, les vérifications et les placeholders de code interchangeables, plutôt que sur une présentation motivante. Lors de la phase d’aperçu, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût en tokens ou requêtes à côté des résultats fonctionnels. Une visibilité précoce du coût évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés.
1. Boucle Plan–Agir–Vérifier
La phase de vérification du 1 Plan Act fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du graphe. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
// Pseudo-code: Node/TypeScript orchestrating Claude as an agent
async function planActVerifyLoop(ticket) {
let iteration = 0;
const maxIterations = 5;
while (iteration < maxIterations) {
iteration++;
// 1. PLAN: ask Claude for the next step
const plan = await claude.chat({
model: "claude-3-opus",
messages: [
{
role: "user",
content: `You are a coding agent working on ticket ${ticket.id}.
Goal: Make tests pass for this ticket without changing public APIs.
Current context:
${ticket.description}
${ticket.latestFailureLog}
What is the single most useful next action?`
}
]
});
// 2. ACT: execute the suggested action if it's in the allowed action space
const action = parseAction(plan);
const result = await executeAction(action); // run tests, edit file, etc.
// 3. VERIFY: use tests as verification
const verification = await runTests(ticket.testSuite);
if (verification.allPassing) {
return { status: "done", iterations: iteration };
}
// Attach the failure output back into ticket context
ticket.latestFailureLog = verification.failureOutput;
}
return { status: "budget_exhausted" };
}
Boucle ReAct (Raison + Action)
La phase Reason Act du cycle ReAct fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de rollback avant d’élargir le périmètre. Documentez ensemble le parcours optimal et le parcours de récupération. Les tentatives répétées, les contrôles humains et le traitement des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Gardez l’état du graphe plat et typé : les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
# Pseudo-code: Python coordinator orchestrating Claude tool calls
def react_loop(incident):
iteration = 0
max_iterations = 6
while iteration < max_iterations:
iteration += 1
# REASON: Claude decides what to inspect next
reasoning = claude.chat(
model="claude-3-opus",
messages=[
{
"role": "user",
"content": f"""
You are an SRE assistant triaging a payment incident.
Incident summary:
{incident.summary}
Recent metrics:
{incident.latest_metrics}
Logs snippet:
{incident.logs_snippet}
Decide one next diagnostic action from:
- CHECK_METRICS
- CHECK_LOGS
- CHECK_DB_HEALTH
- SUMMARIZE_FINDINGS_AND_RECOMMEND_ACTION
Explain your reasoning briefly and output JSON with 'action' and 'target'.
"""
}
]
)
action = parse_json(reasoning)
if action["action"] == "SUMMARIZE_FINDINGS_AND_RECOMMEND_ACTION":
return claude.chat(... ) # final summary + recommended steps
# ACT: run the selected diagnostic
observation = run_diagnostic(action, incident)
# Update incident state for the next reasoning step
incident.update_with_observation(observation)
3. Cycle Reflect–Revise
La phase du cycle 3 Reflect Revise fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt que vers un processus embrouillé. Maintenez l’état du graphe plat et typé. Les blocs imbriqués cachent le fait que tel nœud a écrit tel champ et perturbent la reprise après interruption. La phase du cycle 3 Reflect Revise fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût en tokens ou requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés.
async function reflectReviseLoop(draftInput: string) {
// 1. GENERATE
const draft = await claude.chat({
model: "claude-3-opus",
messages: [
{
role: "user",
content: `
Write a customer-facing email explaining a declined payment due to suspected fraud.
Constraints:
- empathetic but clear
- no admission of fault
- no promises about future approvals
Context:
${draftInput}
`
}
]
});
// 2. CRITIQUE (using a cheaper model as checker)
const critique = await claude.chat({
model: "claude-3-haiku",
messages: [
{
role: "user",
content: `
You are a compliance checker.
Review the following email for:
- policy violations
- misleading statements
- over-commitments
Output a JSON with:
- issues: list of strings
- safe: boolean
Email:
${draft.content}
`
}
]
});
const review = JSON.parse(critique.content);
if (review.safe) {
return draft.content;
}
// 3. REVISE
const revised = await claude.chat({
model: "claude-3-opus",
messages: [
{
role: "user",
content: `
You wrote this email:
${draft.content}
Compliance issues:
${review.issues.join("\n")}
Rewrite the email to resolve all issues while preserving intent.
`
}
]
});
return revised.content;
}
Cycle Ébauche–Test–Correction
Pour l’étape du cycle de correction des tests préliminaires, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Imposez une approbation humaine pour les actions qui entraînent des dépenses ou modifient des données de production. Une connexion effectuée en temps de compilation ne garantit pas la complétude des processus métier.
async function draftTestFixLoop(issue: Issue) {
const maxIterations = 4;
let iteration = 0;
while (iteration < maxIterations) {
iteration++;
// DRAFT: Claude proposes code changes
const patch = await claude.chat({
model: "claude-3-opus",
messages: [
{
role: "user",
content: `
You are an autonomous coding agent.
Ticket:
${issue.title}
${issue.body}
Current failing tests:
${issue.failingTests}
Propose a minimal patch as a diff that makes tests pass
without changing public APIs.`
}
]
});
applyPatchToGitRepo(patch.content);
// TEST: run CI locally or via API
const testResult = await runCi(issue.branchName);
if (testResult.success) {
// FIX_DONE: open a PR with the diff
await openPullRequest(issue, patch.content);
return { status: "done" };
}
// FEEDBACK: update failingTests for next iteration
issue.failingTests = testResult.failureSummary;
}
return { status: "needs_human_review" };
}
Cycle Critique–Constructeur (créateur–vérificateur)
Pour l’étape de vérification du constructeur de critiques, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Imposez l’approbation humaine pour les actions qui entraînent des dépenses ou modifient des données de production. La connexion en temps de compilation ne garantit pas l’exhaustivité du fonctionnement commercial.
Boucle de tentative répétée avec mémorisation
Pour l’étape du cycle de réessai avec mémoire, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Faites approuver par un humain les actions qui entraînent des dépenses ou modifient des données de production. Une connexion en temps de compilation ne garantit pas la complétude du processus métier. Pour l’étape du cycle de réessai avec mémoire, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés.
.def retry_with_memory_loop(task, max_attempts=3):
failures = []
for attempt in range(1, max_attempts + 1):
# Ask Claude to consider past failures before deciding the next move
decision = claude.chat(
model="claude-3-opus",
messages=[
{
"role": "user",
"content": f"""
You are handling a task with a flaky external API.
Task:
{task.description}
Past failures:
{failures}
Decide whether to:
- RETRY_API
- FALLBACK_TO_CACHE
- ESCALATE_TO_HUMAN
Explain briefly and output JSON: {{ "choice": "...", "reason": "..." }}
"""
}
]
)
choice = parse_json(decision)
if choice["choice"] == "RETRY_API":
result = call_api(task)
elif choice["choice"] == "FALLBACK_TO_CACHE":
result = use_cache(task)
else:
return {"status": "escalated", "failures": failures}
if result.success:
return {"status": "success", "attempts": attempt}
failures.append(result.error_summary)
return {"status": "max_attempts_exhausted", "failures": failures}
Escalade avec intervention humaine
Lors de la phase d’escalade impliquant une intervention humaine, notez d’abord les exigences du contrat : données requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Créez des points de contrôle après les étapes coûteuses. Le mécanisme de reprise ne doit pas facturer à nouveau la même appel du LLM lorsque l’opérateur réessaie un nœud ultérieur.
async function triageLoop(ticket: Ticket) {
const autoActions = ["LABEL", "ROUTE_TO_QUEUE", "REQUEST_MORE_INFO"];
const decision = await claude.chat({
model: "claude-3-opus",
messages: [
{
role: "user",
content: `
You are a support triage agent in a payments company.
Ticket:
${ticket.body}
Decide one of:
- LABEL (low risk)
- ROUTE_TO_QUEUE (medium risk)
- ESCALATE_TO_HUMAN (high risk / unclear)
Return JSON with:
- choice
- risk_level
- rationale
`
}
]
});
const choice = JSON.parse(decision.content);
if (choice.choice === "ESCALATE_TO_HUMAN") {
await createHumanTask(ticket, choice.rationale);
return { status: "escalated" };
}
// LABEL or ROUTE_TO_QUEUE are automated but bounded
await applyAutomatedTriage(ticket, choice);
return { status: "auto_treated" };
}
Comment choisir des modèles en pratique
Lors de l’étape « Comment choisir les modèles », notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures. Faites un point après les étapes coûteuses. Le système de reprise ne doit pas facturer à nouveau la même appel d’LLM lorsque l’opérateur réessaie un nœud ultérieur.
Liste de contrôle opérationnelle
Pour l’étape de la liste de contrôle opérationnelle, définissez les entrées, le responsable de l’étape et les critères d’achèvement avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définites des vérifications de succès et refusez les terminations partielles silencieuses.
Obtenez l’approbation humaine pour les étapes qui engagent des dépenses ou modifient les données de production. La connexion en temps de compilation ne garantit pas la complétude du processus métier.
Rédigez un petit manuel d’utilisation : comment rotationner les clés, comment vider la file d’attente, comment annuler la dernière ingestion.
Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le système passe d’un environnement de démonstration à des environnements partagés.
Obtenez l’approbation humaine pour les étapes qui engagent des dépenses ou modifient les données de production. La connexion en temps de compilation ne garantit pas la complétude du processus métier.
Au préalable de promouvoir l’ensemble du système, figez les versions, conservez une version référence pour le parcours critique, et vérifiez les étapes de réversion. Les environnements partagés nécessitent des limites de débit, des contrôles d’attribution et un responsable clair pour la rotation des secrets. Préférez une fiabilité solide à de simples démonstrations temporaires.
Note de lot pour 54c3b06154e6 : ne pas inclure les clés du fournisseur dans le répertoire, fixer une limite pour les tokens par session, et stocker les transcriptions à côté des fichiers d’évaluation afin que les remplacements ultérieurs de modèles restent comparables.