Saltar al contenido principal

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​

NecesitasUsarPor qué
Una persona que responde o chatea, tal vez con herramientas.Un solo agenteEs 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 llamarUn agente con sub_agentsCada 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íaNo 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 propioLa 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.

Ciclo de revisión: del redactor al revisor, aprobación a la versión final, revisión de vuelta al redactor como máximo dos veces, luego recurrir a un humano.

Diseña primero​

Anota, antes de abrir el estudio:

PreguntaRespuesta 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.​

  1. Abre Tiet · Agentic, Agents, Agent Graphs y selecciona New graph. Nómbralo Portal reply drafter, luego Create. Crea una versión 1.0.0 con New version si Studio no lo hizo.
  2. 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 carrera query (escriba texto, obligatorio) y dos Example presets (una pregunta de recarga y un síntoma urgente).
  3. Agrega cinco nodos con + Node, eligiendo Inline node cada vez: triage, draft, review, escalate, finalize. Dale a cada uno su Display name.
  4. En la pestaña triage: Routing, modo single, rutas routine y urgent con 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.
  5. En draft y finalize: solo modelo y mensaje. En finalize haga clic Mark as exit.
  6. En review: modo single, rutas approve y revise, 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.
  7. 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.
  8. Dibuja los bordes con las herramientas de borde. Elige Route y arrastra desde los manejadores de ruta triage hasta draft (routine) y escalate (urgent). Elige Fallback y conecta triage con escalate. Chain conecta draft con review. Desde review, Route. approve hasta finalize y revise de vuelta a draft; haz clic en el borde revise y establece Max Traversals en 2. Fallback desde review hasta escalate Chain escalate a finalize.
  9. Haz clic en Validate. Quieres que "Entrada y salida definidas", "Los 5 nodos accesibles" y "Todas las rutas resueltas", sin errores.
  10. Haz clic en Save, luego Publish.

Ejecútalo​

  1. Haz clic en Run. En Run graph, elige la opción preestablecida "Rellenar pregunta" y ejecuta.
  2. Observa Events. La ruta esperada es triage (ruta routine), draft, review, luego finalize. Si el revisor pide una reescritura, verás draft y review de nuevo.
  3. 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 evento step.unresolved_vars para draft que enumera feedback y text. 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.
  4. Ejecuta el preajuste "Síntoma urgente". La ejecución va a escalate y se pausa con estado paused. 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 hasta finalize y finaliza.
  5. Para probar el bucle a propósito, configure la solicitud del revisor para que rechace todo. Después de dos reescrituras, el borde revise se utiliza, no hay coincidencias de ruta y el borde de reserva envía la ejecución a escalate.

Por qué está construido de esta manera​

  • El revisor devuelve JSON con route y feedback. El motor consume route; el texto de respuesta en text no se modifica, por lo que finalize sigue 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.
  • escalate no necesita razonamiento, pero las palabras de la persona se convierten en text, por lo que finalize maneja ambos caminos con una sola indicación.

Próximos pasos​

¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..