Construisez votre premier graphe d'agents
Créez un exemple de rédaction de réponses à cinq nœuds avec un routeur, une boucle de relecture délimitée et un relais humain. Vous apprendrez à connecter les nœuds, à publier une version et à examiner le chemin d'exécution.
Avant de commencer : vous devez disposer des autorisations nécessaires pour lire et modifier les graphes d’agents, ainsi que d’un accès aux modèles utilisés dans l’exemple. Utilisez des messages synthétiques tout au long de ce tutoriel. Prévoyez environ une heure.
Pour chaque champ de contrôle et de schéma, consultez la documentation de référence du graphe d'agent. Pour d'autres mises en page et erreurs courantes, consultez les modèles de graphe d'agent.
Décider : graphe, agent ou flux de travail
| Vous avez besoin | Utiliser | Pourquoi |
|---|---|---|
| Un personnage qui répond ou discute, éventuellement avec des outils | Un seul agent | C'est la solution la moins coûteuse à concevoir et à exploiter. Un graphe ajoute de la latence et une surface de révision sans aucun avantage. |
| Un LLM qui décide en cours d'exécution quel spécialiste appeler | Un agent avec sub_agents | Chaque sous-agent est exposé à l'agent parent en tant qu'outil. Quatre agents du catalogue initial déclarent sub_agents (par exemple clinical-workflow-orchestrator) ; ce sont des agents, et non des graphes. |
| Un flux multi-étapes fixe ou ramifié où vous devez afficher chaque étape intermédiaire, utiliser un modèle différent par étape, épingler des invites, ajouter un réviseur ou insérer des étapes déterministes entre les étapes du modèle. | Un graphe d'agents (cette page) | Une rangée par activation, versions épinglées, portes, relecture. |
| Déplacement et transformation de données sans raisonnement (ETL, HL7 vers FHIR) | Un flux de travail ou un tuyau | Ne consacrez pas de temps aux séances photo avec des mannequins pour des questions de plomberie. Voir « Créer n’importe quel flux de travail ». |
| Une fonctionnalité produit avec des rangées, des files d'attente pour la validation et des évaluations qui durent des heures. | Un graphique et un service personnalisé | La pause humaine dans le fonctionnement du moteur s'inscrit dans un processus précis (sécurité et gouvernance). Elle doit durer quelques minutes, pas plusieurs jours. |
Règle générale du guide de conception : si un clinicien ou un auditeur est susceptible de demander « pourquoi cela est-il indiqué ? », utilisez un graphique. Si une seule personne remplit cette fonction, n’en utilisez pas.
Un graphe peut toujours utiliser des nœuds de flux de travail : les gestionnaires pontés fhir.read, fhir.propose, fhir.write, notify.send et script.run exécutent des nœuds de pipeline (ou un script fixe) comme étapes déterministes (anatomie du graphe).
Tutoriel : un générateur de réponses avec routeur et boucle de révision
Vous allez construire un graphe à cinq nœuds pour une clinique : il lit un message du portail patient, achemine les messages urgents vers une infirmière, rédige une réponse pour les messages de routine, la fait vérifier par un relecteur (jusqu’à deux réécritures), et la transmet à une infirmière si le relecteur continue de refuser.
Concevoir d'abord
Notez ceci avant d'ouvrir le Studio :
| Question | Réponse pour ce graphique |
|---|---|
| Que doit absolument être vrai toute réponse ? | Pas de diagnostic, pas de posologie, pas de promesses quant au délai, en moins de 120 mots. |
| Qui décide de quoi ? | Un routeur détermine l'urgence. Un autre modèle, plus puissant, effectue un contrôle. Une personne prend en charge les urgences et les problèmes que le système ne parvient pas à résoudre. |
| Qu'est-ce que le déterminisme ? | Rien ici. Un véritable graphe clinique ajouterait un nœud fhir.read pour récupérer le contexte plutôt que de laisser un modèle le récupérer. |
| Que sont les boucles et comment sont-elles délimitées ? | Les brouillons et les révisions peuvent se répéter : max_traversals 2 sur le bord de la révision, per_node_max_visits 3, max_total_steps 12. |
| Quelle est la classe de sécurité ? | Cela a une incidence sur la communication clinique, donc affects_clinical_output est vrai. Le moteur le traite comme un élément clinique (sécurité et gouvernance). |
La définition
Téléchargez l'exemple de définition complet. L'audit du système a vérifié cette définition avec les mêmes valeurs Validate() et Lint() utilisées lors de la publication. Sélectionnez les modèles disponibles dans votre organisation et validez à nouveau avant de déployer la définition.
Afficher la définition JSON complète
{
"entry_node_id": "triage",
"exit_node_ids": [
"finalize"
],
"guards": {
"max_total_steps": 12,
"max_model_calls": 14,
"max_retry_attempts": 4,
"per_node_max_visits": {
"draft": 3,
"review": 3
}
},
"compliance": {
"regulated": false,
"affects_clinical_output": true,
"data_classification": "none"
},
"metadata": {
"owner": "Demo Hospital",
"tags": [
"tutorial",
"portal-reply"
]
},
"intended_use": {
"statement": "Drafts a reply to a patient portal message for clinic staff to review before anything is sent.",
"intended_users": [
"Clinic nurse"
]
},
"input_schema": [
{
"key": "query",
"label": "Patient message",
"type": "text",
"required": true,
"description": "The text of the portal message. Use synthetic text only."
}
],
"examples": [
{
"name": "Refill question",
"input": {
"query": "Hello, this is Test Patient A. Can I get my usual refill sent to the pharmacy on Main Street?"
}
},
{
"name": "Urgent symptom",
"input": {
"query": "Test Patient B here. Since this morning I have chest pain that spreads to my arm."
}
}
],
"nodes": [
{
"id": "triage",
"name": "Triage",
"description": "Decides whether the message is routine or urgent.",
"routing_mode": "single",
"routes": [
{
"name": "routine",
"description": "Administrative or non-urgent question that a nurse can answer in writing."
},
{
"name": "urgent",
"description": "Any symptom that could need same-day clinical attention."
}
],
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash",
"temperature": 0.1
},
"inline_prompt": {
"template": "You triage patient portal messages for Demo Hospital.\nMessage: {{.query}}\n\nReturn JSON with the key \"category\" (one short label such as refill, appointment, results, symptom) and choose the route. When in doubt, choose urgent."
},
"output_schema": {
"type": "object",
"properties": {
"route": {
"type": "string"
},
"category": {
"type": "string"
}
}
},
"retry_policy": {
"max_attempts": 2,
"backoff_ms": 500
}
},
{
"id": "draft",
"name": "Drafter",
"description": "Writes the reply, and rewrites it when the reviewer asks for changes.",
"routing_mode": "none",
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash",
"temperature": 0.3
},
"inline_prompt": {
"template": "Write a short reply (under 120 words, plain text) to this patient portal message for a nurse to review.\nMessage: {{.query}}\nCategory: {{.category}}\n{{if .feedback}}\nA reviewer rejected the previous draft.\nReviewer feedback: {{.feedback}}\nPrevious draft: {{.text}}\nRewrite the draft and fix every point.\n{{end}}\nRules: no diagnosis, no medication doses, no promises about timing."
},
"retry_policy": {
"max_attempts": 2,
"backoff_ms": 500
}
},
{
"id": "review",
"name": "Reviewer",
"description": "Checks the draft against the rules and approves it or asks for a rewrite.",
"routing_mode": "single",
"routes": [
{
"name": "approve",
"description": "The draft follows every rule."
},
{
"name": "revise",
"description": "The draft breaks a rule; explain what to fix in \"feedback\"."
}
],
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-pro",
"temperature": 0
},
"inline_prompt": {
"template": "You review a draft reply to a patient portal message.\nMessage: {{.query}}\nDraft: {{.text}}\n\nRules: no diagnosis, no medication doses, no promises about timing, under 120 words.\nReturn JSON with the keys \"route\" and \"feedback\". Put the specific problems in \"feedback\" when you choose revise, and an empty string when you choose approve."
},
"output_schema": {
"type": "object",
"properties": {
"route": {
"type": "string"
},
"feedback": {
"type": "string"
}
}
},
"retry_policy": {
"max_attempts": 2,
"backoff_ms": 500
}
},
{
"id": "escalate",
"name": "Nurse takes over",
"description": "Pauses the run until a nurse supplies the reply text.",
"routing_mode": "none",
"human_in_the_loop": true,
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash"
},
"inline_prompt": {
"template": "Human review step. The reply is supplied by a person: {{.query}}"
}
},
{
"id": "finalize",
"name": "Finalize",
"description": "Applies the clinic sign-off format to the approved text.",
"routing_mode": "none",
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash",
"temperature": 0
},
"inline_prompt": {
"template": "Return the reply below unchanged, followed on a new line by: \"Reviewed by clinic staff before sending.\"\n\n{{.text}}"
}
}
],
"edges": [
{
"id": "e1",
"source_node_id": "triage",
"target_node_id": "draft",
"kind": "route",
"route_name": "routine"
},
{
"id": "e2",
"source_node_id": "triage",
"target_node_id": "escalate",
"kind": "route",
"route_name": "urgent"
},
{
"id": "e3",
"source_node_id": "triage",
"target_node_id": "escalate",
"kind": "fallback"
},
{
"id": "e4",
"source_node_id": "draft",
"target_node_id": "review",
"kind": "deterministic"
},
{
"id": "e5",
"source_node_id": "review",
"target_node_id": "finalize",
"kind": "route",
"route_name": "approve"
},
{
"id": "e6",
"source_node_id": "review",
"target_node_id": "draft",
"kind": "route",
"route_name": "revise",
"max_traversals": 2
},
{
"id": "e7",
"source_node_id": "review",
"target_node_id": "escalate",
"kind": "fallback"
},
{
"id": "e8",
"source_node_id": "escalate",
"target_node_id": "finalize",
"kind": "deterministic"
}
]
}
Construisez-le dans le studio
- Ouvrez Tiet · Agentic, Agents, Agent Graphs et sélectionnez New graph. Nommez-le
Portal reply drafter, puis Create. Créez une version1.0.0avec New version si le Studio ne l'a pas fait. - Sur l'onglet Info définissez la description, sous Guards définissez Max Steps à
12. Ouvrez Usage et remplissez Intended use et Intended users, ajoutez une entrée d'exécutionquery(saisissez du texte, obligatoire) et deux Example presets (une question de renouvellement et un symptôme urgent). - Ajoutez cinq nœuds avec + Node, en choisissant Inline node à chaque fois :
triage,draft,review,escalate,finalize. Donnez à chacun son Display name. - Sur l'onglet
triage: Routing, modesingle, itinérairesroutineeturgentavec descriptions. Onglet Model, un petit modèle rapide. Onglet Prompt, le modèle à partir du JSON. Sur General, cliquez sur Set as entry. - Sur
draftetfinalize: modèle et invite uniquement. Surfinalizecliquez sur Mark as exit. - Sur
review: modesingle, itinérairesapproveetrevise, et un modèle plus robuste que celui du concepteur. Utilisez un modèle différent de celui du concepteur afin qu’un modèle ne valide pas son propre travail. - Sur
escalate: activer sur Human-in-the-loop. Conserver un modèle et une invite en ligne ; Studio et la vérification de publication les demandent toujours. - Tracez les arêtes avec les outils d'arête. Sélectionnez Route et faites glisser les poignées de tracé
triageversdraft(routine) etescalate(urgent). Sélectionnez Fallback et connecteztriageàescalate. Chain reliedraftàreview. Dereviewà Route.approveàfinalizeet dereviseàdraft; cliquez sur l'arêtereviseet reliez Max Traversals à2. Fallback reliereviewàescalateChainescalateàfinalize. - Cliquez sur Validate. Vous souhaitez que les options « Entrée et sortie définies », « Les 5 nœuds sont accessibles » et « Toutes les routes sont résolues », sans aucune erreur.
- Cliquez sur Save, puis Publish.
Exécutez-le
- Cliquez sur Run. Dans Run graph, choisissez le préréglage « Question de remplissage » et exécutez.
- Observez Events. Le chemin attendu est
triage(routeroutine),draft,review, puisfinalizeSi le relecteur demande une réécriture, vous verrez à nouveaudraftetreview. - Ouvrez Step Inspector sur
draft. Vérifiez Resolved prompt : le message et la catégorie sont renseignés. Lors de la première vérification, vous verrez également un événementstep.unresolved_varspourdraftqui listefeedbackettext. Ceci est normal, car le bloc{{if .feedback}}lit des clés qui n'existent qu'après un refus du réviseur. Le texte à l'intérieur du bloc n'est pas envoyé. - Exécutez le préréglage « Symptôme urgent ». L'exécution passe à l'
escalateet se met en pause avec le statutpaused. Soumettez une charge utile telle que{"text": "Synthetic review complete. Route this test message to the demonstration review queue."}dans Human Review Required. L'exécution reprend à l'finalizeet se termine. - Pour tester intentionnellement la boucle, configurez l'invite du réviseur pour qu'il rejette tout. Après deux réécritures, l'arête
reviseest épuisée, aucune route ne correspond et l'arête de repli redirige l'exécution versescalate.
Pourquoi est-il construit de cette façon ?
- Le réviseur renvoie un JSON avec
routeetfeedback.routeest consommé par le moteur ; le texte de réponse danstextest intact, doncfinalizelit toujours le texte du rédacteur. - La boucle est délimitée de trois manières : par l’arête, par le nœud et par l’ensemble du parcours. Utilisez les trois.
- Les solutions de repli garantissent qu'aucune erreur de modélisation ne peut empêcher l'exécution de se poursuivre.
escalatene nécessite aucune justification, mais les paroles de la personne deviennenttext, doncfinalizegère les deux cas de figure avec une seule invite.
Prochaines étapes
- Référence du graphe d'agents : contrôles, schéma, cycle de vie, gouvernance et inspection d'exécution.
- Modèles de graphes d'agents : routage, boucles de révision, jointures et erreurs courantes.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.