Aller au contenu
EN 4 QUESTIONSTrouver mon modèle
Agents et automatisation · guide nerd · 30 min de lecture

Construire un agent : la boucle, les outils et les garde-fous

Un agent est une boucle de quelques lignes : le modèle choisit un outil, le programme l'exécute, le résultat revient au modèle. Ce guide l'écrit en Python pur avec un modèle local, puis avec les SDK d'Anthropic et d'OpenAI, et pose les garde-fous.

Illustration du thème Agents et automatisation

Un agent d’IA est un programme qui confie à un modèle de langage le choix de ses prochaines actions. Anthropic distingue deux familles : les flux de travail, où le code décide de l’enchaînement des appels au modèle, et les agents, où le modèle dirige lui-même ses étapes et ses outils. Son conseil, dans son article de référence sur le sujet : chercher la solution la plus simple, et n’ajouter de la complexité que quand elle apporte quelque chose.

Ce guide écrit d’abord un agent sans aucune bibliothèque, pour voir chaque pièce, puis le réécrit avec deux SDK.

À quoi ça sert

  • Des tâches dont on ne connaît pas les étapes à l’avance : chercher une règle dans plusieurs documents, enquêter sur une panne, corriger un bogue.
  • Brancher un modèle sur vos systèmes : une base de données, un agenda, un outil interne, par des outils que vous écrivez.
  • Automatiser une suite d’actions que vous faisiez à la main, avec une validation humaine aux endroits sensibles.

Pour une tâche dont les étapes sont toujours les mêmes, un simple enchaînement d’appels écrit dans le code reste plus fiable et moins cher.

Comment ça marche

La boucle d'un agent : le modèle lit la mémoire, demande un outil ou répond. Le programme exécute l'outil dans les limites fixées et ajoute le résultat à la mémoire.

Quatre pièces suffisent :

  1. Le modèle. Il doit savoir appeler des outils : au lieu de répondre, il renvoie le nom d’un outil et ses arguments en JSON.
  2. Les outils. Des fonctions de votre programme, décrites au modèle par un nom, une phrase et un schéma de paramètres. Anthropic insiste sur ce point : soignez la description des outils autant qu’une interface destinée à un humain.
  3. La mémoire. La liste des messages : la tâche, chaque appel d’outil, chaque résultat. Elle est renvoyée en entier au modèle à chaque tour, et c’est ce qui coûte.
  4. La boucle. Tant que le modèle demande un outil, le programme l’exécute et ajoute le résultat à la mémoire. Quand il répond sans outil, la boucle s’arrête.

Un agent en Python pur

L’exemple répond à des questions sur quatre notes internes d’une entreprise fictive (les mêmes que dans le guide sur le RAG). Il tourne avec Ollama et un modèle local qui sait appeler des outils, sans aucune bibliothèque à installer.

  1. Placez vos documents dans un dossier docs/.
  2. Enregistrez le script sous agent.py :
"""Un agent minimal : une boucle, deux outils, une mémoire, des garde-fous et un compteur de jetons.
Aucune dépendance : Python 3.10 ou plus et un serveur Ollama avec un modèle qui sait appeler des outils."""
import json, sys, urllib.request
from pathlib import Path

MODELE = "gemma4:26b"
DOSSIER = Path("docs").resolve()   # le seul dossier que l'agent a le droit de lire
MAX_TOURS = 8                      # garde-fou : pas de boucle infinie
MAX_JETONS = 20_000                # garde-fou : budget de jetons pour toute la tâche


def liste_documents() -> str:
    """Liste les documents internes disponibles."""
    return ", ".join(sorted(p.name for p in DOSSIER.glob("*.md")))


def lit_document(nom: str) -> str:
    """Rend le texte d'un document interne."""
    chemin = (DOSSIER / nom).resolve()
    if chemin.parent != DOSSIER or not chemin.exists():   # garde-fou : rien hors du dossier
        return f"Erreur : document « {nom} » introuvable. Appelle liste_documents."
    return chemin.read_text(encoding="utf-8")


OUTILS = {"liste_documents": liste_documents, "lit_document": lit_document}
SCHEMAS = [
    {"type": "function", "function": {"name": "liste_documents", "description": liste_documents.__doc__,
                                      "parameters": {"type": "object", "properties": {}}}},
    {"type": "function", "function": {"name": "lit_document", "description": lit_document.__doc__,
                                      "parameters": {"type": "object", "required": ["nom"],
                                                     "properties": {"nom": {"type": "string",
                                                                            "description": "Nom du fichier, par exemple frais.md"}}}}},
]


def chat(messages):
    corps = {"model": MODELE, "messages": messages, "tools": SCHEMAS, "stream": False, "think": False,
             "options": {"temperature": 0}}
    req = urllib.request.Request("http://localhost:11434/api/chat", data=json.dumps(corps).encode(),
                                 headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=600) as r:
        return json.load(r)


def agent(tache):
    # La mémoire de l'agent : la liste des messages, renvoyée en entier à chaque tour.
    messages = [{"role": "system", "content": "Tu es l'assistant RH d'une entreprise. Tu travailles en boucle : "
                 "consulte les documents avec tes outils autant que nécessaire, puis réponds en français, "
                 "brièvement, en citant le fichier de chaque règle. N'invente aucune règle."},
                {"role": "user", "content": tache}]
    jetons = 0
    for tour in range(1, MAX_TOURS + 1):
        r = chat(messages)
        jetons += r.get("prompt_eval_count", 0) + r.get("eval_count", 0)
        msg = r["message"]
        messages.append(msg)
        appels = msg.get("tool_calls") or []
        if not appels:                                    # plus d'outil demandé : la tâche est finie
            print(f"[fin] {tour} tours, {jetons} jetons\n{msg['content'].strip()}")
            return
        for appel in appels:
            nom, args = appel["function"]["name"], appel["function"]["arguments"]
            resultat = OUTILS[nom](**args) if nom in OUTILS else f"Erreur : outil {nom} inconnu"
            print(f"[tour {tour}] {nom}({json.dumps(args, ensure_ascii=False)}) -> {len(resultat)} caractères")
            messages.append({"role": "tool", "tool_name": nom, "content": resultat})
        if jetons > MAX_JETONS:
            print(f"[arrêt] budget de {MAX_JETONS} jetons dépassé")
            return
    print(f"[arrêt] {MAX_TOURS} tours atteints sans réponse")


if __name__ == "__main__":
    agent(" ".join(sys.argv[1:]))
  1. Lancez-le avec une tâche :
python3 agent.py "Je pars trois jours en déplacement, avec un trajet en train de cinq heures et deux déjeuners avec des clients. Qu'est-ce qui m'est remboursé, et comment ?"
Terminal : agent.py reçoit une question sur un déplacement de trois jours ; tour 1, appel de liste_documents ; tour 2, appel de lit_document sur frais.md ; fin en 3 tours et 952 jetons ; la réponse cite frais.md : repas d'affaires remboursés jusqu'à 35 euros par personne, première classe permise pour un trajet de plus de quatre heures, saisie dans l'application Dépenses sous 30 jours.
Sortie réelle de agent.py sur le mini-PC Linux de QUELLE IA, le 17 novembre 2026, avec gemma4:26b servi par Ollama 0.21.1 (lignes longues repliées, gras Markdown retiré).

L’agent liste les documents, choisit frais.md, le lit et répond en trois tours. Sa réponse mérite une relecture : la note dit « seconde classe, sauf pour un trajet de plus de quatre heures », et l’agent en déduit que la première classe est permise. C’est une lecture plausible, que le document ne dit pas en toutes lettres. La citation de la source permet de vérifier ce genre de déduction.

Avec l’Agents SDK d’OpenAI

L’Agents SDK d’OpenAI (paquet openai-agents) fournit la boucle, la description automatique des outils à partir des fonctions Python, des garde-fous, des sessions et le passage d’un agent à un autre. Il se branche sur n’importe quel serveur compatible avec l’API Chat Completions, Ollama compris.

Installer OpenAI Agents SDK

Python, macOS ou Linux

source .venv/bin/activate
pip install openai-agents
export OPENAI_API_KEY=sk-...

D'après openai.github.io, lue le 3 octobre 2026.La fiche de OpenAI Agents SDK →

Le même agent tient en trente lignes. La documentation conseille de couper l’envoi des traces quand on n’a pas de clé OpenAI :

"""Le même agent avec l'Agents SDK d'OpenAI, branché sur un modèle local servi par Ollama.
pip install openai-agents"""
from pathlib import Path
from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, Runner, function_tool, set_tracing_disabled

DOSSIER = Path("docs").resolve()
set_tracing_disabled(True)   # pas de clé OpenAI : on coupe l'envoi des traces


@function_tool
def liste_documents() -> str:
    """Liste les documents internes disponibles."""
    return ", ".join(sorted(p.name for p in DOSSIER.glob("*.md")))


@function_tool
def lit_document(nom: str) -> str:
    """Rend le texte d'un document interne.

    Args:
        nom: Nom du fichier, par exemple frais.md.
    """
    chemin = (DOSSIER / nom).resolve()
    if chemin.parent != DOSSIER or not chemin.exists():
        return f"Erreur : document « {nom} » introuvable."
    return chemin.read_text(encoding="utf-8")


modele = OpenAIChatCompletionsModel(
    model="gemma4:26b",
    openai_client=AsyncOpenAI(base_url="http://localhost:11434/v1", api_key="ollama"),
)
agent = Agent(
    name="Assistant RH",
    instructions="Consulte les documents avec tes outils, puis réponds en français, brièvement, "
                 "en citant le fichier de chaque règle. N'invente aucune règle.",
    tools=[liste_documents, lit_document],
    model=modele,
)

resultat = Runner.run_sync(agent, "Combien de jours de télétravail par semaine, et quelle indemnité ?", max_turns=8)
print(resultat.final_output)
print("jetons :", resultat.context_wrapper.usage.total_tokens)

max_turns borne la boucle : au-delà, le SDK lève l’exception MaxTurnsExceeded. Pour un modèle d’OpenAI, retirez model=modele et posez la variable OPENAI_API_KEY.

Terminal : python agent_sdk.py répond que le télétravail est autorisé jusqu'à deux jours par semaine et qu'une indemnité de 2,70 euros par jour est versée dans la limite de 10 jours par mois, avec la source teletravail.md ; jetons : 1962.
Le même agent écrit avec l'Agents SDK d'OpenAI (version 0.24.0) et branché sur gemma4:26b servi en local par Ollama, exécuté sur le mini-PC de QUELLE IA le 17 novembre 2026 (gras Markdown retiré).

Avec l’Agent SDK d’Anthropic

Le Claude Agent SDK (paquet claude-agent-sdk en Python, @anthropic-ai/claude-agent-sdk en TypeScript) embarque la boucle et les outils de Claude Code : lecture et écriture de fichiers, commandes, recherche web, sous-agents, serveurs MCP, permissions. Vos propres outils s’y ajoutent sous la forme d’un serveur MCP qui tourne dans le même programme. Il demande Python 3.10 ou Node.js 18.14 au moins, et une clé d’API Claude. Sauf accord préalable, Anthropic n’autorise pas un produit tiers bâti sur ce SDK à proposer la connexion par un compte claude.ai.

Installer Claude Agent SDK

pip · Python avec pip, macOS ou Linux

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

macOS · macOS, Linux (clé d'API)

export ANTHROPIC_API_KEY=your-api-key

D'après code.claude.com, lue le 3 octobre 2026.La fiche de Claude Agent SDK →

"""Le même agent avec le Claude Agent SDK. pip install claude-agent-sdk ; variable ANTHROPIC_API_KEY."""
import asyncio
from pathlib import Path
from typing import Any
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, create_sdk_mcp_server, query, tool

DOSSIER = Path("docs").resolve()


@tool("lit_document", "Rend le texte d'un document interne (par exemple frais.md)", {"nom": str})
async def lit_document(args: dict[str, Any]) -> dict[str, Any]:
    chemin = (DOSSIER / args["nom"]).resolve()
    texte = chemin.read_text(encoding="utf-8") if chemin.parent == DOSSIER and chemin.exists() else "Document introuvable."
    return {"content": [{"type": "text", "text": texte}]}


serveur = create_sdk_mcp_server(name="rh", version="1.0.0", tools=[lit_document])


async def main():
    options = ClaudeAgentOptions(
        system_prompt="Tu réponds aux questions RH d'après les documents frais.md, conges.md, "
                      "materiel.md et teletravail.md, en citant le fichier de chaque règle.",
        mcp_servers={"rh": serveur},
        allowed_tools=["mcp__rh__lit_document"],   # seul outil autorisé sans demande
        max_turns=8,                               # garde-fou : nombre de tours
        max_budget_usd=0.50,                       # garde-fou : dépense estimée
    )
    async for message in query(prompt="Combien de jours de télétravail par semaine ?", options=options):
        if isinstance(message, ResultMessage):
            print(message.subtype, message.result)


asyncio.run(main())

Cet exemple n’a pas été exécuté sur le mini-PC de QUELLE IA, faute de clé d’API dédiée aux essais. Il suit la documentation lue le 17 novembre 2026 (version 0.2.183 du paquet Python). Quand une limite est atteinte, le dernier message porte le sous-type error_max_turns ou error_max_budget_usd. Quand le contexte approche de sa limite, le SDK résume lui-même les échanges anciens ; ce qui doit rester en toutes circonstances va dans la consigne système ou dans un fichier CLAUDE.md.

Les garde-fous

Anthropic le rappelle : l’autonomie d’un agent veut dire des coûts plus élevés et des erreurs qui s’enchaînent, d’où des essais en environnement isolé et des garde-fous.

  • Un nombre de tours maximal et un budget, en jetons ou en dollars. Sans eux, un agent qui tourne en rond vide votre crédit.
  • Des outils étroits. lit_document(nom) limité à un dossier vaut mieux qu’un execute_commande(texte) qui ouvre tout le système.
  • Une validation humaine avant toute action irréversible : envoyer un courriel, payer, supprimer, publier.
  • Des résultats d’outils traités comme des données. Une page web ou un document lu par l’agent peut contenir des instructions écrites pour le détourner (injection de consigne). Ne donnez pas à un agent qui lit du contenu extérieur les moyens d’agir sans contrôle.
  • Un journal. Gardez la trace de chaque appel d’outil et de ses arguments, comme le fait l’exemple en Python pur.

Le coût

La mémoire est renvoyée à chaque tour : le coût d’une tâche croît plus vite que le nombre de tours. L’exemple en Python pur a consommé 952 jetons en trois tours pour une question simple ; une enquête de trente tours sur des documents longs renvoie trente fois une mémoire de plus en plus lourde. Deux leviers comptent : la mise en cache du début commun des requêtes, détaillée dans le guide sur le cache et les coûts de l’API, et le choix du modèle. Voici les modèles les mieux classés pour les tâches d’agent :

Le haut du classement Agents

  1. GPT-6 AstraOpenAI100,3
  2. Claude Opus 5.5Anthropic100,1
  3. Gemini 4 ArgonGoogle DeepMind99,3
  4. Claude Fable 5.1Anthropic97,4
  5. GPT-6.1 SolOpenAI96,0

Score Agents, édition du 16 novembre 2026. Deux modèles dont les marges se recouvrent sont ex æquo.

Classement Agents des modèles de langage →

Pour aller plus loin

Pour monter son atelier d'IA à la maison, mini lab AI, du même auteur, va plus loin.

Tous les guides →

Sources

  1. anthropic.com, lue le
  2. docs.ollama.com, lue le
  3. docs.ollama.com, lue le
  4. code.claude.com, lue le
  5. code.claude.com, lue le
  6. code.claude.com, lue le
  7. code.claude.com, lue le
  8. pypi.org, lue le
  9. openai.github.io, lue le
  10. openai.github.io, lue le
  11. openai.github.io, lue le
  12. openai.github.io, lue le
  13. openai.github.io, lue le
  14. pypi.org, lue le