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
Quatre pièces suffisent :
- 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.
- 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.
- 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.
- 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.
- Placez vos documents dans un dossier
docs/. - 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:]))
- 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 ?"

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/activatepip install openai-agentsexport 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.

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 .venvsource .venv/bin/activatepip install claude-agent-sdkmacOS · macOS, Linux (clé d'API)
export ANTHROPIC_API_KEY=your-api-keyD'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’unexecute_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
- GPT-6 AstraOpenAI100,3
- Claude Opus 5.5Anthropic100,1
- Gemini 4 ArgonGoogle DeepMind99,3
- Claude Fable 5.1Anthropic97,4
- GPT-6.1 SolOpenAI96,0
Score Agents, édition du 16 novembre 2026. Deux modèles dont les marges se recouvrent sont ex æquo.
Pour aller plus loin
- Claude Agent SDK
- OpenAI Agents SDK
- Classement Agents des modèles de langage
- Outils de code et agents
- Quel modèle sur ma machine
- C'est quoi un agent d'IA ? La boucle expliquéeNiveau Débutant 8 min
- Sorties structurées et appels d'outils : du JSON garantiNiveau Nerd 20 min
- Faire travailler plusieurs agents ensemble, sans casseNiveau Nerd 25 min
- MCP : brancher des outils dans Claude, ChatGPT ou un agentNiveau Amateur 15 min
- Réduire la facture d'une API d'IA : cache, lots, modèle, effortNiveau Expert 20 min
- Automatiser avec l'IA : scripts, n8n et agents personnelsNiveau Amateur 20 min
- Gemini dans Chrome et les Tâches : l'agent de GoogleNiveau Amateur 10 min
- Bien configurer Hermes Agent : modèle, Telegram, sécuritéNiveau Expert 22 min
Pour monter son atelier d'IA à la maison, mini lab AI, du même auteur, va plus loin.
Sources
- anthropic.com, lue le
- docs.ollama.com, lue le
- docs.ollama.com, lue le
- code.claude.com, lue le
- code.claude.com, lue le
- code.claude.com, lue le
- code.claude.com, lue le
- pypi.org, lue le
- openai.github.io, lue le
- openai.github.io, lue le
- openai.github.io, lue le
- openai.github.io, lue le
- openai.github.io, lue le
- pypi.org, lue le
