Patrones gráficos de agentes
Utilice estos patrones después de completar su primer gráfico. Consulte el esquema y la gobernanza al configurar el gráfico.
Patrones de diseño
Seleccione el patrón que mejor se ajuste al flujo de información y riesgo. Descomponga por información: asigne a cada trabajador una porción delimitada de los datos, ya que la coincidencia entre agentes que vieron todo constituye una evidencia débil.
Enrutador
Úselo cuando las solicitudes se clasifiquen en varios tipos y cada una requiera instrucciones o herramientas diferentes. Mantenga el clasificador económico y proporcione una descripción precisa para cada ruta. Añada siempre un borde fallback.
Ciclo de especialista y revisor
El gráfico del tutorial. Úselo cuando un borrador tenga reglas verificables. Limite el bucle en la arista, en los nodos y en la ejecución, y asigne un destino al caso agotado. Una alternativa con el mismo efecto es una puerta verification en el borrador con una arista __verify_failed__ a un nodo de remediación.
Planificar y ejecutar (estructura centralizada)
Úselo cuando no se conozca de antemano el número y el orden de los pasos. Un planificador con routing_mode: single tiene una ruta por trabajador más una ruta done; cada trabajador tiene una arista determinista de regreso. El grafo semilla meda-clinical-encounter.json tiene esta forma: un nodo plan con ocho rutas, trabajadores que regresan a él, per_node_max_visits de 24 en plan, max_total_steps 60, y una puerta de juez en el trabajador de medicación cuya arista __verify_failed__ también regresa al planificador. Debido a que el planificador puede ejecutarse muchas veces, su límite de visitas es el guardián más importante en el grafo.
Mapear y reducir con una unión
Úselo cuando las piezas independientes se puedan analizar por separado y luego combinar. El nodo dividido tiene varios bordes deterministas salientes (con fan_out_mode: all, el valor predeterminado, todos ellos se activan). Cada trabajador devuelve JSON con sus propias claves y utiliza un borde join hacia el reductor. El reductor comienza una vez, cuando todos los bordes de unión han llegado. El handoff-icu-pause.json inicializado une seis nodos de crítica en un nodo qa de esta manera. Por defecto, la programación es serial: las ramas se ejecutan una tras otra. Establezca scheduling.mode a parallel con max_parallel_workers de al menos 2 para ejecutarlas juntas; las ramas paralelas trabajan en copias del estado y se fusionan después de que todas tienen éxito; dos ramas que escriben la misma clave con valores diferentes son un error de conflicto.
Escalada a un ser humano
Úselo cuando una verificación fallida o un caso urgente requiera la intervención de una persona. Enrute a un nodo human_in_the_loop desde una arista __verify_failed__, una arista de reserva o una arista condicional como state.urgent == true. Coloque el efecto secundario (fhir.propose o una notificación) en un nodo posterior a la persona, de modo que no se escriba nada antes de que tome una decisión.
Los diez errores más comunes
El texto de error es lo que devuelve la comprobación de publicación o Validate Los primeros nueve se reprodujeron ejecutando el validador real en el gráfico del tutorial con un cambio en cada uno.
| # | Error | Texto de error | Arreglar |
|---|---|---|---|
| 1 | Sin límite de pasos | guards.max_total_steps must be > 0 | Establecer Max Steps (por ejemplo, 12). |
| 2 | No se permite la entrada ni la salida, o la identificación es incorrecta. | entry_node_id is required, at least one exit_node_id is required, entry_node_id "nope" does not match any node | En General, Set as entry y Mark as exit. |
| 3 | Un nodo de modelo sin modelo ni mensaje. | node "draft" ("Drafter"): no model resolvable — set model_config_ref, inline_model_config, or agent_id ... y ... no prompt resolvable — set inline_prompt.template, prompt_ref.id, or agent_id ... | Configure el modelo en la pestaña Model y la solicitud en la pestaña Prompt Un nodo de interacción humana también los necesita. |
| 4 | Una puerta sin ruta de fallo | node "draft" ("Drafter") has a verification gate but no outgoing "__verify_failed__" route edge for failed verdicts | Agregue una arista de ruta llamada __verify_failed__ a un nodo de remediación. |
| 5 | Una unión rota | edge "j1": join edges require source "triage" to have routing_mode "none"; edge "j1": join edges cannot carry a condition (a false condition would deadlock the barrier); node "review" is the target of a single join edge — a barrier needs ≥2 join parents (use kind "deterministic" for a plain edge) | Unir solo desde none nodos, sin ninguna condición, con dos o más padres. |
| 6 | Configuración del modelo en un nodo determinista | node "finalize" ("Finalize"): handler_type is set — deterministic nodes must not declare model/prompt/agent config; también deterministic nodes cannot declare tool_refs | Elimine el modelo, la solicitud y la configuración de la herramienta, o elimine handler_type. |
| 7 | Una ruta sin borde, o un borde a la nada. | Lint: node "review" declares route "revise" but no route edge wires it (unwired_route); Studio: "Rutas sin resolver" | Dibuja el borde o elimina la ruta. Lint no bloquea la publicación, pero la ruta no llevaría a ninguna parte. |
| 8 | Una clave de aviso que no proporciona nada | Lint: reference "patient_age" in node "draft" field "inline_prompt.template" is not defined at this point in the flow (unresolved_prompt_reference). En tiempo de ejecución imprime <no value> y emite step.unresolved_vars. | Añádelo a input_schema, haz que un nodo anterior lo devuelva o corrige el error tipográfico. |
| 9 | Un bucle sin límite | Tiempo de ejecución: node "x" exceeded max_visits=N, o la ejecución se detiene en max_total_steps | Establezca max_traversals en el borde posterior y per_node_max_visits. Studio advierte "Se recomienda protección de bucle". |
| 10 | Límites y configuraciones incorrectas | node "draft" ("Drafter"): at most 3 fallback_models; fallback_models[0] needs an id and a version; tool_refs[0] has no tool id; pick a tool or remove the entry; max_tool_rounds must be between 1 and 20 (0 uses the default 5); scheduling.max_parallel_workers must be >= 2 in parallel mode; guards.max_active_nodes must not exceed guards.max_total_steps; compliance.data_classification must be none, pseudonymised, or phi; execution_mode "rlm" requires rlm.context_state_keys; duplicate node id "draft"; edge "e1": target_node_id "ghost" not found | Corrige el campo con nombre. |
Dos errores no producen ningún fallo: una solicitud de enrutamiento que no aclara la elección (el modelo devuelve un nombre de ruta no declarado, por lo que se activa la opción de reserva) y trabajadores que devuelven texto plano (sobrescriben text o fallan con un conflicto de estado en modo paralelo). Proporcione a las rutas descripciones claras y asigne a cada trabajador su propia clave JSON.
output_schema en un nodo no se aplica en tiempo de ejecución. Sus nombres properties indican al editor y al linter qué claves produce el nodo, por lo que se acepta un valor {{.key}} posterior. Esto no obliga al modelo a seguir el esquema; especifique lo que necesita en la solicitud.
¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..