Prompt engineering pour agents IA : le guide complet 2026

Le prompt engineering pour agents IA n'a rien à voir avec le prompting classique type ChatGPT. Quand vous interrogez un modèle en one-shot, le contexte se limite à votre message. Avec un agent, vous ajoutez une couche système complète : description des outils disponibles, instructions de planification, gestion de la mémoire, contraintes d'exécution.

Un prompt mal structuré ne donne pas une mauvaise réponse — il donne un agent qui ne sait pas utiliser ses propres outils.

Ce guide couvre tout ce qu'il faut pour structurer un prompt d'agent efficace :

• Les 3 niveaux de prompt (system, task, tool)
• Les 8 composants du system prompt
• Le few-shot learning adapté aux agents
• L'ingénierie des descriptions d'outils
• Le formatting des outputs

À la fin, vous disposerez d'un template prête à adapter.

Résumé rapide

Critère	Détail
Niveaux de prompt	System prompt, task prompt, tool prompt
Composants system prompt	8 éléments essentiels (rôle, objectifs, contraintes, exemples…)
Few-shot learning	2-5 exemples max, alignés sur le comportement cible
Output formatting	JSON ou markdown structuré, output parsers
Testing	A/B testing, évaluation automatisée

---

Pourquoi le prompting d'agent diffère du prompting classique

Un prompt ChatGPT classique suit le schéma : message utilisateur → réponse modèle. Interaction bornée, linéaire, sans persistances ni effets secondaires.

Un agent IA opère différemment. Il dispose d'un cycle d'exécution qui peut inclure :

1. Perception — lire et interpréter des entrées multiples (messages, fichiers, résultats d'outils)
2. Décision — déterminer quelle action prendre parmi les outils disponibles
3. Exécution — appeler un ou plusieurs outils
4. Évaluation — analyser le résultat et décider de la prochaine étape
5. Réponse — retourner un output final à l'utilisateur

Cette boucle impose trois niveaux de prompt distincts :

• System prompt — fixe le comportement global de l'agent. Chargé une seule fois en début de session.
• Task prompt — spécifique à chaque tâche utilisateur. Décrit ce qui est attendu et les contraintes de la tâche courante.
• Tool prompt — la description de chaque outil à la disposition de l'agent.

À retenir : Un system prompt trop vague donne un agent qui dérive. Un task prompt mal défini donne des réponses hors sujet. Un tool prompt mal écrit donne des appels d'outils incorrects.

---

Anatomie d'un prompt d'agent : les 6 blocs essentiels

Un prompt d'agent bien structuré contient 6 blocs dans cet ordre :

1. Role (rôle)

La première ligne définit qui est l'agent. Ce n'est pas une étiquette décorative — c'est une instruction qui influence directement le style de réponse, le niveau de détail, et les choix de comportement.

Tu es un agent de veille IA spécialisé dans la collecte et la synthèse d'articles de recherche.

Évitez les formulations génériques. "Tu es un assistant" ne dit rien. Précisez exactement quel rôle l'agent doit incarner.

2. Goals (objectifs)

Ce que l'agent doit accomplir. Un but doit être mesurable et borné.

Ton objectif : identifier les 5 avancées les plus significatives en IA générative
publiées dans les 90 derniers jours, et produire un résumé structuré par thème.

3. Backstory (contexte narratif)

Ce bloc donne à l'agent une compréhension contextuelle qui guide les décisions ambiguës. Il répond à la question : "dans quel cadre est-ce que j'opère ?"

Tu travailles pour une équipe de recherche académique qui n'a pas le temps
de suivre l'actualité IA au jour le jour. Tes synthèses doivent être
accessibles à des chercheurs non spécialisés en IA.

4. Constraints (contraintes)

Les limites explicites de l'agent. Sans ce bloc, l'agent interprète les silences du prompt comme des autorisations.

Tu ne dois jamais inventer de faits. Si une information n'est pas vérifiable,
indique-le explicitement. Tu ne génères pas de code source.

5. Tools description (descriptions d'outils)

La liste des outils disponibles avec leur signature et leur usage. Ce bloc est détaillé dans la section Ingénierie des descriptions d'outils.

6. Output format (format de sortie)

Comment l'agent doit formater sa réponse. Sans cette instruction, le formatage variera d'un appel à l'autre.

Réponds toujours en JSON avec les clés suivantes : title, summary, sources, date.
Ne renvoie jamais de texte libre en dehors de ce format.

---

Les 8 composants essentiels du system prompt

Le system prompt est le bloc le plus important de votre agent. Voici les 8 composants par ordre de priorité :

1. Rôle explicite

Définissez précisément la fonction de l'agent. Plus le rôle est spécifique, meilleurs sont les décisions de bas niveau.

2. Objectifs prioritaires

Listez les objectifs par ordre de priorité. Quand l'agent fait face à un arbitrage, cette hiérarchie guide le choix.

3. Comportement attendu

Décrivez comment l'agent doit se comporter dans les situations courantes : style de réponse, ton, niveau de détail, attitude face aux erreurs de l'utilisateur.

4. Limites et interdictions

Listez explicitement ce que l'agent ne doit jamais faire. Ce composant est critique pour la sécurité et la fiabilité.

5. Exemples de comportement (few-shot)

Insérez 2 à 5 exemples annotés qui montrent exactement le comportement attendu. La section suivante détaille le few-shot pour agents.

6. Ton et style

Indiquez le registre de langage attendu : professionnel, technique, accessible, concis. Sans cette instruction, le ton variera selon les appels.

7. Gestion de la fenêtre de contexte

Instructions explicites sur la gestion du contexte long : comment prioriser les informations récentes, quand oublier le contexte plus ancien, comment détecter les dépassements de contexte.

8. Instructions de mémoire

Si l'agent dispose d'une mémoire persistante (vector store, fichier, base de données), expliquez quand et comment l'agent doit y lire et écrire.

Exemple de system prompt complet :

system_prompt = """
Tu es un agent de recherche sémantique spécialisé en documentation technique.

## Objectifs (par ordre de priorité)
1. Identifier les sections de documentation les plus pertinentes pour la requête
2. Produire une réponse qui cite précisément les sources
3. Minimiser les hallucinations en vérifiant chaque affirmation

## Comportement attendu
- Réponds de manière concise mais complète
- Cite toujours les sources avec le titre du document et la section
- Si une information est insuffisante pour répondre, dis-le explicitement

## Limites
- Ne réinvente pas le sens d'une documentation
- Ne combine pas plusieurs affirmations de sources différentes comme si elles étaient liées
- Ne fournis pas d'opinion personnelle sur les outils

## Few-shot example
Requête: "comment configurer un webhook dans OpenClaw?"
Réponse attendue: {\{""answer": "...", "sources": [{"title": "...", "section": "..."}]}}

## Ton
Technique, précis, orienté solution. Pas de formules de politesse excessive.

## Gestion du contexte
Si le contexte dépasse 4000 tokens, privilégie les informations les plus récentes
et les sources les plus directement en lien avec la requête.

## Mémoire
Après chaque réponse, si une information importante a été découverte, note-la
dans le fichier /memory/agent_findings.md sous le format : [date] - [résumé]
"""

Prêt à créer votre premier agent ? Consultez notre guide pour créer un agent IA avec Python pour mettre en pratique ces principes.

---

Few-shot learning pour agents

Le few-shot learning dans le contexte des agents diffère de l'approche standard. L'objectif n'est pas simplement de montrer des exemples — c'est de calibrer le comportement de décision de l'agent face à des cas concrets.

Combien d'exemples ?

2 à 5 exemples suffisent. Au-delà de 5, les exemples commencent à entrer en compétition avec les instructions principales et le coût en tokens augmente significativement sans gain de performance.

Comment choisir les bons exemples ?

Vos exemples doivent couvrir trois dimensions :

• Cas heureux — le comportement standard quand tout fonctionne normalement
• Cas limites — quand l'agent doit gérer une ambiguïté ou une situation non standard
• Anti-modèles — ce que l'agent ne doit pas faire, montré par un exemple avec annotation explicite

## Example 1 — Cas standard
Requête: "résume les actualités IA de la semaine"
Comportement attendu: [output structuré standard]

## Example 2 — Cas limite
Requête: ""
Comportement attendu: L'agent détecte que la requête est vide et demande une clarification.
NE DOIT PAS: retourner un résumé basé sur des informations inventées.

## Example 3 — Anti-modèle
Requête: "quelle est la meilleure cripto à acheter?"
Comportement attendu: L'agent refuse de donner des conseils d'investissement
et indique qu'il ne fournit pas de recommandations financières.

Erreurs fréquentes en few-shot pour agents

• Trop d'exemples similaires — l'agent overfit à un pattern et échoue sur des cas légèrement différents
• Exemples sans annotations — un exemple non annoté ne dit pas à l'agent pourquoi c'est le bon comportement
• Mélanger les niveaux d'abstraction — certains exemples très concrets (code), d'autres très abstraits (concept)

---

Output formatting pour agents

Un agent qui retourne du texte libre est difficile à consommer programmatiquement. Le formatting des outputs est un composant critique de l'architecture d'un agent.

JSON vs Markdown

Format	Avantages	Inconvénients
JSON	Parsing automatique, validation de schéma, intégration CI/CD	Moins lisible pour un humain
Markdown	Lisible par un humain et une machine, structuré	Nécessite un parser Markdown dédié

Pour les agents de production, le JSON structuré est recommandé. Pour les agents orientés revue humaine, le Markdown est plus adapté.

Output parsers avec LangChain

LangChain propose des output parsers qui forcent le format de sortie :

from langchain.output_parsers import PydanticOutputParser, JsonOutputParser
from langchain.schema import HumanMessage
from pydantic import BaseModel

# Définir le schéma de sortie
class ResearchSummary(BaseModel):
    title: str
    summary: str
    sources: list[str]
    relevance_score: float

# Créer le parser
parser = PydanticOutputParser(pydantic_object=ResearchSummary)

# L'agent utilise le parser pour formater sa réponse
prompt = f"""...Réponds en suivant ce format :
{parser.get_format_instructions()}"""

Bonnes pratiques de formatting

• Définissez le format avant de lancer l'agent — modifier le format après coup nécessite de réécrire le prompt
• Validez systématiquement — utilisez un schéma Pydantic ou JSON Schema pour vérifier la conformité
• Gérez les erreurs de parsing — un agent peut retourner un JSON mal formé. Prévoyez une stratégie de retry

import json

def parse_agent_output(raw_output: str, schema: type[BaseModel]):
    try:
        data = json.loads(raw_output)
        return schema(**data)
    except json.JSONDecodeError:
        # Nettoyer le texte puis réessayer
        cleaned = raw_output.strip()
        if cleaned.startswith('```'):
            cleaned = cleaned.split('```')[1]
        return schema(**json.loads(cleaned))
    except Exception as e:
        raise ValueError(f"Output parsing failed: {e}")

Utilisez CrewAI pour orchestrer vos agents ? Notre guide complet sur CrewAI couvre comment structurer les prompts et gérer les outputs multi-agents.

---

Ingénierie des descriptions d'outils

La qualité des descriptions d'outils détermine directement le taux d'utilisation correcte des outils par l'agent. Un outil mal décrit sera soit ignoré, soit appelé avec les mauvais paramètres.

Les 4 éléments d'une bonne description d'outil

1. Nom — clair, action-oriented, sans ambiguïté
2. Description textuelle — ce que l'outil fait, pourquoi l'agent voudrait l'utiliser
3. Paramètres — chaque paramètre avec son type, ses contraintes, et un exemple
4. Sortie — ce que l'outil retourne, sous quel format

tool_spec = {
    "name": "web_search",
    "description": "Effectue une recherche sur le web. Utilisez cet outil quand "
                   "la requête nécessite des informations récentes ou des données "
                   "qui ne sont pas dans la base de connaissances.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Requête de recherche. Soyez précis et spécifique. "
                               "Évitez les questions trop longues. 5-10 mots suffisent.",
                "example": "GPT-5 release date"
            },
            "max_results": {
                "type": "integer",
                "description": "Nombre maximum de résultats à retourner (1-10).",
                "default": 5
            }
        },
        "required": ["query"]
    },
    "output": "Liste de dictionnaires avec keys: title, url, snippet"
}

Le problème des descriptions ambigües

L'ambiguïté dans une description d'outil est la cause n°1 des appels d'outils incorrects. Voici les erreurs fréquentes :

• Descriptions trop vagues : "cet outil cherche sur internet" — par rapport à "cet outil effectue une recherche web et retourne les 5 premiers résultats"
• Paramètres non typés : pas de type Python/JSON, l'agent devine le type
• Pas d'exemples : l'agent ne sait pas ce qu'un "bon" paramètre ressemble

Checklist de validation pour chaque outil

• Le nom est explicite sans ambiguïté
• La description dit quoi et pourquoi (pas seulement quoi)
• Chaque paramètre a un type JSON/Python
• Chaque paramètre a une description
• Chaque paramètre a un exemple de valeur valide
• Le format de sortie est clairement documenté

---

Testing et itération

Un prompt d'agent ne se valide pas en une passe. L'évaluation suit un cycle itératif.

A/B testing

Créez deux versions du system prompt et mesurez la performance sur un dataset de tâches représentatif. Définissez des métriques avant le test :

• Taux d'appel d'outils correct
• Précision des réponses
• Format de sortie conforme
• Temps de réponse moyen

Évaluation automatisée

Pour les agents de production, construisez un dataset de tâches annotées et utilisez un LLM comme juge pour scorer les réponses :

def evaluate_agent_response(agent_output: str, expected_output: str) -> dict:
    evaluation_prompt = f"""
    Évalue la réponse de l'agent selon ces critères (1-5) :
    - Pertinence : la réponse répond-elle à la requête ?
    - Précision : les informations sont-elles correctes ?
    - Format : le format est-il conforme aux attentes ?
    - Complétude : tous les éléments attendus sont-ils présents ?

    Réponse agent : {agent_output}
    Résultat attendu : {expected_output}

    Réponds en JSON avec les scores et une justification courte.
    """
    return judge_model.invoke(evaluation_prompt)

Checklist de test par version

Avant chaque déploiement de nouvelle version de prompt :

• Le dataset de test passe à 100% sur les cas standard
• Les cas limites sont gérés correctement
• Le format de sortie est conforme sur 20 appels minimum
• La latence n'a pas augmenté de plus de 20%
• Aucune nouvelle erreur d'appel d'outil n'apparaît

---

Conclusion et template de démarrage

Le prompt engineering pour agents IA est une discipline à part entière. Un agent bien prompté n'est pas chanceux — il est le résultat d'une ingénierie délibérée à chaque niveau : system prompt, task prompt, et tool description.

Les erreurs les plus fréquentes :

• Un system prompt trop vague
• Des exemples few-shot trop nombreux ou non annotés
• Des descriptions d'outils ambigües

Pour démarrer : définissez le rôle et les objectifs de votre agent dans le system prompt, puis itérez en ajoutant contraintes, exemples, et formatting au fil des tests.

Étape suivante : plongez dans la planification des agents IA pour comprendre comment structurer le cycle de décision de votre agent.

---

Questions fréquentes

Qu'est-ce qu'un system prompt pour un agent IA ?

Un system prompt est le bloc d'instructions chargé une seule fois au démarrage de la session de l'agent. Il définit le rôle, les objectifs, les contraintes, le style, et les instructions de gestion du contexte et de la mémoire. Contrairement à un prompt utilisateur classique, il persiste tout au long de la session.

Comment améliorer un prompt d'agent IA ?

L'amélioration suit un cycle itératif : testez l'agent sur un dataset représentatif, identifiez les cas d'échecs, affinez le system prompt avec des exemples few-shot supplémentaires ou des contraintes plus précises, puis re-tester. Les deux leviers les plus efficaces sont les exemples annotés et la qualité des descriptions d'outils.

Quelle est la différence entre few-shot et zero-shot pour un agent ?

Le zero-shot demande à l'agent de généraliser à partir d'instructions pures. Le few-shot ajoute des exemples concrets de comportement attendu directement dans le prompt. Pour un agent, le few-shot est généralement plus fiable car il donne des références comportementales, mais 2 à 5 exemples suffisent — au-delà, le prompt devient difficile à maintenir.

Comment formater la sortie d'un agent IA ?

Utilisez un format structuré (JSON ou Markdown) avec un output parser qui valide la conformité. Définissez le format attendu dans le system prompt, puis utilisez un parser comme ceux de LangChain ou Pydantic pour garantir que l'output respecte le schéma. Implémentez une stratégie de retry si le parsing échoue. Pour approfondir, consultez notre guide LangChain.

Comment décrire un outil pour un agent IA ?

Une bonne description d'outil inclut : un nom clair, une description textuelle précise, la définition complète des paramètres avec leurs types et des exemples, et le format de sortie attendu. Évitez les descriptions vagues et les paramètres non typés — ce sont les deux sources principales d'appels d'outils incorrects. Voir aussi notre sélection d'outils essentiels pour agents IA.

---

Articles liés

• Créer un agent IA avec Python — mettez en pratique le prompt engineering avec un cas concret
• Guide CrewAI : orchestrer plusieurs agents — comment structurer les prompts dans une architecture multi-agents
• La planification dans les agents IA — contrôlez le cycle de décision de vos agents
• Guide LangChain : output parsers et chain — maîtrisez le formatting des sorties
• Outils essentiels pour agents IA — le stack technique complet pour vos agents