Construye tu primer grafo de agentes
Crea un ejemplo de redacción de respuestas con cinco nodos, que incluya un enrutador, un bucle de revisión con límite y una transferencia humana. Aprenderás a conectar nodos, publicar una versión e inspeccionar la ruta de ejecución.
Antes de comenzar: necesitas permiso para leer y editar los gráficos de los agentes y acceso a los modelos utilizados en el ejemplo. Utiliza mensajes sintéticos a lo largo de este tutorial. Calcula aproximadamente una hora.
Para cada control y campo de esquema, consulte la referencia del gráfico de agentes. Para otros diseños y errores comunes, consulte los patrones del gráfico de agentes.
Decide: gráfico, agente o flujo de trabajo
| Necesitas | Usar | Por qué |
|---|---|---|
| Una persona que responde o chatea, tal vez con herramientas. | Un solo agente | Es más económico de construir y ejecutar. Un gráfico añade latencia y superficie de revisión sin obtener ninguna ventaja. |
| Un LLM que decide en tiempo de ejecución a qué especialista llamar | Un agente con sub_agents | Cada subagente se expone al padre como una herramienta. Cuatro agentes en el catálogo inicial declaran sub_agents (por ejemplo, clinical-workflow-orchestrator); son agentes, no grafos. |
| Un flujo multietapa fijo o ramificado donde debe mostrar cada paso intermedio, usar un modelo diferente por etapa, fijar indicaciones, agregar un revisor o colocar pasos deterministas entre los pasos del modelo. | Un gráfico de agentes (esta página) | Una fila de pasos por activación, versiones fijas, puertas, repetición. |
| Movimiento y transformación de datos sin razonamiento (ETL, HL7 a FHIR) | Un flujo de trabajo o tubería | No dedique tiempo a realizar llamadas al modelo en tareas de fontanería. Consulte Crear cualquier flujo de trabajo. |
| Una función del producto con filas, colas de aprobación y revisiones de varias horas. | Un gráfico más un servicio propio | La pausa humana del motor reside en un único proceso (seguridad y gobernanza). Úsela durante minutos, no días. |
Regla general de la guía de diseño: si un médico o auditor pregunta alguna vez "¿por qué dice eso?", utilice un gráfico. Si un solo agente cumple la función, no lo haga.
Un gráfico aún puede usar nodos de flujo de trabajo: los manejadores puenteados fhir.read, fhir.propose, fhir.write, notify.send y script.run ejecutan nodos de canalización (o un script fijo) como pasos deterministas (anatomía del gráfico).
Tutorial: un redactor de respuestas con un enrutador y un bucle de revisión.
Construirás un grafo de cinco nodos para una clínica: lee los mensajes del portal del paciente, dirige los urgentes a una enfermera, redacta una respuesta para los rutinarios, la revisa un evaluador (con hasta dos revisiones) y, si el evaluador se niega repetidamente, la entrega a una enfermera.
Diseña primero
Anota, antes de abrir el estudio:
| Pregunta | Respuesta para este gráfico |
|---|---|
| ¿Qué debe ser cierto en cada respuesta? | Sin diagnóstico, sin dosis de medicamentos, sin promesas sobre plazos, menos de 120 palabras. |
| ¿Quién decide qué? | Un enrutador determina la urgencia. Un modelo diferente y más potente realiza la revisión. Una persona se encarga de todo lo urgente o de todo lo que el sistema no pueda resolver. |
| ¿Qué es determinista? | Aquí no hay nada. Un grafo clínico real agregaría un nodo fhir.read para obtener el contexto en lugar de dejar que un modelo lo obtenga. |
| ¿Qué son los bucles y cómo se delimitan? | El borrador y la revisión pueden repetirse: max_traversals 2 en el borde de revisión, per_node_max_visits 3, max_total_steps 12. |
| ¿Cuál es la clase de seguridad? | Afecta a la comunicación clínica, por lo que affects_clinical_output es verdadero. El motor lo trata como clínico (seguridad y gobernanza). |
La definición
Descargue la definición de ejemplo completa. La auditoría de backend retenida verificó esta definición con los mismos valores Validate() y Lint() utilizados en el momento de la publicación. Seleccione los modelos disponibles en su organización y vuelva a validarlos antes de publicarlos en su implementación.
Ver la definición JSON completa
{
"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"
}
]
}
Construyelo en el estudio.
- Abre Tiet · Agentic, Agents, Agent Graphs y selecciona New graph. Nómbralo
Portal reply drafter, luego Create. Crea una versión1.0.0con New version si Studio no lo hizo. - En la pestaña Info, configure la descripción; debajo de Guards, configure Max Steps a
12. Abra Usage y complete Intended use y Intended users, agregue una entrada de carreraquery(escriba texto, obligatorio) y dos Example presets (una pregunta de recarga y un síntoma urgente). - Agrega cinco nodos con + Node, eligiendo Inline node cada vez:
triage,draft,review,escalate,finalize. Dale a cada uno su Display name. - En la pestaña
triage: Routing, modosingle, rutasroutineyurgentcon descripciones. Pestaña Model, un modelo pequeño y rápido. Pestaña Prompt, la plantilla del JSON. En la General, haga clic en Set as entry. - En
draftyfinalize: solo modelo y mensaje. Enfinalizehaga clic Mark as exit. - En
review: modosingle, rutasapproveyrevise, y un modelo más fuerte que el del redactor. Utilice un modelo diferente al del redactor para que un modelo no apruebe su propio trabajo. - En
escalate: encender en Human-in-the-loop. Mantener un modelo en línea y una solicitud; Studio y la comprobación de publicación aún los solicitan. - Dibuja los bordes con las herramientas de borde. Elige Route y arrastra desde los manejadores de ruta
triagehastadraft(routine) yescalate(urgent). Elige Fallback y conectatriageconescalate. Chain conectadraftconreview. Desdereview, Route.approvehastafinalizeyrevisede vuelta adraft; haz clic en el borderevisey establece Max Traversals en2. Fallback desdereviewhastaescalateChainescalateafinalize. - Haz clic en Validate. Quieres que "Entrada y salida definidas", "Los 5 nodos accesibles" y "Todas las rutas resueltas", sin errores.
- Haz clic en Save, luego Publish.
Ejecútalo
- Haz clic en Run. En Run graph, elige la opción preestablecida "Rellenar pregunta" y ejecuta.
- Observa Events. La ruta esperada es
triage(rutaroutine),draft,review, luegofinalize. Si el revisor pide una reescritura, verásdraftyreviewde nuevo. - Abrir Step Inspector en
draft. Comprobar Resolved prompt: el mensaje y la categoría están completos. En la primera pasada también verá un eventostep.unresolved_varsparadraftque enumerafeedbackytext. Esto es lo esperado, ya que el bloque{{if .feedback}}lee claves que solo existen después de un rechazo del revisor. El texto dentro del bloque no se envía. - Ejecuta el preajuste "Síntoma urgente". La ejecución va a
escalatey se pausa con estadopaused. Envía una carga útil como{"text": "Synthetic review complete. Route this test message to the demonstration review queue."}en Human Review Required. La ejecución continúa hastafinalizey finaliza. - Para probar el bucle a propósito, configure la solicitud del revisor para que rechace todo. Después de dos reescrituras, el borde
revisese utiliza, no hay coincidencias de ruta y el borde de reserva envía la ejecución aescalate.
Por qué está construido de esta manera
- El revisor devuelve JSON con
routeyfeedback. El motor consumeroute; el texto de respuesta entextno se modifica, por lo quefinalizesigue leyendo el texto del redactor. - El bucle está delimitado de tres maneras: por la arista, por el nodo y por todo el recorrido. Utilice las tres.
- Los mecanismos de reserva impiden que cualquier error del modelo provoque que la ejecución se quede sin opciones.
escalateno necesita razonamiento, pero las palabras de la persona se convierten entext, por lo quefinalizemaneja ambos caminos con una sola indicación.
Próximos pasos
- Referencia del gráfico de agentes: controles, esquema, ciclo de vida, gobernanza e inspección de la ejecución.
- Patrones de grafos de agentes: enrutamiento, bucles de revisión, uniones y errores comunes.
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..