Notes pratiques : De la récupération à la réflexion : création d’agents prêts à l’emploi
Guide pratique pas à pas : Des opérations de récupération au raisonnement : création d’agents prêts à l’emploi, avec des contrats, des vérifications et des blocs de code intégrables pour les équipes qui mettent en œuvre ce modèle.
Utilisez ceci comme une version révisée destinée aux opérateurs des idées présentées dans « From Retrieval to Reasoning: Building Production-Ready Agentic AI Systems with Knowledge Graphs » : étapes claires, emplacements de code ordonnés et notes de récupération permettant de continuer en cas de transfert. L’étape « Aperçu » fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Conservez les configurations 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.
from neo4j import GraphDatabase
import json
def get_grounded_context(user_query: str, entity_extractor, driver) -> str:
# Step 1: Extract entities from the user query
entities = entity_extractor(user_query) # e.g., ["Product X", "Supplier Y"]
# Step 2: Pull a relevant subgraph from Neo4j
with driver.session() as session:
result = session.run(
"""
MATCH (e)-[r]-(connected)
WHERE e.name IN $entities
RETURN e.name AS entity,
type(r) AS relationship,
connected.name AS related_entity,
connected.attributes AS attributes
LIMIT 50
""",
entities=entities
)
subgraph = [record.data() for record in result]
# Step 3: Format subgraph as structured context
context_str = json.dumps(subgraph, indent=2)
grounded_prompt = f"""
You are a reasoning agent. Use ONLY the following structured knowledge to answer.
If the answer isn't derivable from this context, say so explicitly.
KNOWLEDGE GRAPH CONTEXT:
{context_str}
USER QUERY: {user_query}
"""
return grounded_prompt
def plan_with_graph(goal: str, graph_schema: dict, llm) -> list[dict]:
schema_str = json.dumps(graph_schema, indent=2)
planning_prompt = f"""
You are a planning agent. Given the goal below, decompose it into steps.
Each step must reference a valid entity type or relationship from the schema.
Do not invent steps that require knowledge outside this schema.
GRAPH SCHEMA:
{schema_str}
GOAL: {goal}
Return a JSON list of steps. Each step must include:
- "action": what to do
- "graph_query": the Cypher query to retrieve required context
- "depends_on": list of prior step indices this step requires
"""
raw_plan = llm.complete(planning_prompt)
plan = json.loads(raw_plan)
return plan
def execute_with_validation(step: dict, intermediate_result: str, driver, llm) -> dict:
# Extract claims from the intermediate result
claim_extraction_prompt = f"""
Extract all factual claims from this text as a list of (subject, predicate, object) triples.
TEXT: {intermediate_result}
Return as JSON array.
"""
claims = json.loads(llm.complete(claim_extraction_prompt))
validation_results = []
with driver.session() as session:
for claim in claims:
result = session.run(
"""
MATCH (s {name: $subject})-[r]-(o {name: $object})
WHERE type(r) = $predicate OR $predicate IN r.aliases
RETURN count(r) AS match_count
""",
subject=claim["subject"],
predicate=claim["predicate"],
object=claim["object"]
)
record = result.single()
validation_results.append({
"claim": claim,
"validated": record["match_count"] > 0
})
unvalidated = [v for v in validation_results if not v["validated"]]
return {
"result": intermediate_result,
"validated": len(unvalidated) == 0,
"flagged_claims": unvalidated
}
Checklist opérationnelle
Lorsque vous travaillez sur l’étape de la checklist opérationnelle, notez d’abord les exigences : entrées requises, signal de succès et ce qui se passe en cas d’échec partiel. Cette checklist garantit que les modifications ultérieures du code restent transparentes.
Enregistrez les temps d’exécution ainsi que le coût des jetons ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce du coût permet d’éviter des factures inattendues lorsque le chemin passe de l’environnement de démonstration à des environnements partagés.
Mémorisez les instructions système stables et les schémas des outils. L’envoi répété d’un préambule identique est une cause fréquente de gaspillage.
Séparez la politique de segmentation des données de la politique de récupération. Modifier l’une ne doit pas obliger à réécrire l’autre lorsque les métriques de qualité changent.
Obtenez l’approbation humaine pour les opérations qui entraînent des dépenses ou modifient des données de production. Une configuration en temps de compilation ne garantit pas une couverture complète des besoins métier.
Suivez le coût et la latence en même temps que la qualité. Une réponse légèrement moins bonne mais coûtant 10 fois moins peut être le meilleur compromis en environnement de production.
Au préalable de promouvoir le stack, figez les versions, créez un enregistrement d’or pour le chemin critique et confirmez les étapes de rollback. Les environnements partagés nécessitent des limites de débit, des vérifications de location ainsi qu’un responsable clair pour la rotation des secrets. Préférez une fiabilité banale à des démonstrations ingénieuses ponctuelles.
Note de lot pour 7e5e1dbfc22b : gardez les clés du fournisseur hors du répertoire, fixez un plafond pour les tokens par session et stockez les enregistrements à côté des fichiers de configuration d’évaluation afin que les remplacements ultérieurs de modèles restent comparables.
La note de renforcement de niveau 0 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement d’or, un cas de défaillance et la note de rollback avant d’élargir le périmètre. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, la défaillance doit pointer vers une seule responsabilité plutôt que vers un processus embrouillé.
Détail de renforcement 0/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des observations anecdotiques.
Pour la première étape de la note de renforcement, définir 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é. Enregistrer les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts permet d’éviter des factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés.
Détail de renforcement 1/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des observations anecdotiques.
Lors de la réalisation de l’étape 2 des notes de renforcement, notez d’abord les conditions contractuelles : entrées requises, 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 apportées ultérieurement.
Détail de renforcement 2/956 : mesurez le temps d’exécution, la classe de l’erreur et l’utilisation des tokens pour cette note, puis décidez si vous souhaitez conserver la modification en vous basant sur un ensemble de questions prédéfini plutôt que sur des observations subjectives.
L’étape 3 des notes de renforcement fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Recueillez un exemple idéal de fonctionnement, un cas d’échec et une note de réversion avant d’élargir le périmètre. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès et refusez les terminations partielles silencieuses.
Détail de renforcement 3/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des anecdotes.
Pour la phase 4 de la note de renforcement, définir 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é. Conserver 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 avoir à lire l’ensemble du système.
Détail de renforcement 4/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des anecdotes.
Lors de l’étape 5 des notes de renforcement, notez d’abord les éléments essentiels : 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. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une responsabilité précise plutôt qu’un processus embrouillé.
Détail de renforcement 5/956 : mesurez le temps d’exécution, la classe de l’erreur et la consommation de tokens pour cette note, puis décidez si vous souhaitez conserver la modification en vous basant sur un ensemble de critères prédéfinis plutôt que sur des observations subjectives.
L’étape 6 des notes de renforcement fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Recueillez un exemple idéal de fonctionnement, un cas d’échec et des notes de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des surprises lors du passage de l’environnement de démonstration à des environnements partagés.
Détail de renforcement 6/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des anecdotes.
Pour l’étape 7 de la note de renforcement, définir 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é. Documenter 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 du produit, et non d’une mise en forme ultérieure.
Détail de renforcement 7/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des anecdotes.
Lors de l’étape 8 des notes de renforcement, 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. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès et refusez les terminaisons partielles silencieuses.
Détail de renforcement 8/956 : mesurez le temps d’exécution, la classe de l’erreur et la consommation de tokens pour cette note, puis décidez si vous souhaitez conserver la modification en vous basant sur un ensemble de questions prédéfini plutôt que sur des observations subjectives.
L’étape 9 des notes de renforcement fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les stocks de secrets et les flags fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système.
Détail de renforcement 9/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des anecdotes.
Pour l’étape 10 du processus de renforcement, définir 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é. Préférer des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé.
Détail de renforcement 10/956 : mesurer le temps d’exécution, la classe d’erreur et la consommation de tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble de questions prédéfini plutôt que sur des anecdotes.
Lors de l’exécution de l’étape 11 des notes de renforcement, notez d’abord les éléments essentiels : les entrées requises, le signal de succès, ainsi que 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 des jetons 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 de l’environnement de démonstration à des environnements partagés.
Détail 11/956 du renforcement : mesurez le temps d’exécution réel, la catégorie de l’erreur et la consommation de jetons pour cette note, puis décidez si vous souhaitez conserver la modification en vous basant sur un ensemble de critères prédéfinis plutôt que sur des observations subjectives.
L’étape 12 des notes de renforcement fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple idéal de fonctionnement, un cas d’échec et la note de réversion avant d’élargir le périmètre.
Dokumentez ensemble le parcours normal et celui de récupération. Les tentatives de répétition, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations apportées ultérieurement.
Détail de renforcement 12/956 : mesurer le temps d’exécution, la classe d’erreur et l’utilisation des tokens pour cette note, puis décider de conserver ou non le changement en se basant sur un ensemble fixe de questions plutôt que sur des anecdotes.