Notas prácticas: De patrón a pipeline: Implementación del Agentic Cortex con
Guía paso a paso operativa de las notas prácticas: De patrón a pipeline: Implementación del Agentic Cortex con contratos, verificaciones y espacios para código reutilizable para los equipos que implementan este patrón.
Fuentes: From Pattern to Pipeline: Implementing the Agentic Cortex with LangGraph and OPA
Las notas siguientes reconstruyen un camino práctico para abordar “De patrón a pipeline: Implementación del Agentic Cortex con LangGraph y OPA”. Se da énfasis en los contratos, las verificaciones y los marcadores de código reutilizables, en lugar de en un enfoque motivacional. Al trabajar en la etapa de visión general, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras adicionales realizadas posteriormente.
Visión general de la arquitectura:
La etapa de visión general de la arquitectura funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
El pipeline: seis nodos, un StateGraph
La etapa de los seis nodos de Pipeline Six funciona mejor cuando se trata como una superficie medible. Capture un transcripte ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación después de las interrupciones.
class CortexState(TypedDict, total=False):
domain_outputs: Dict[str, DomainOutput]
normalized_recommendations: List[NormalizedRecommendation]
cross_domain_conflicts: List[CrossDomainConflict]
policy_decisions: List[PolicyDecision]
resolved_conflicts: List[CrossDomainConflict]
sentinel_check: Optional[SentinelCheckResult]
final_recommendations: List[NormalizedRecommendation]
workflow = SateGraph(CortexState)
workflow.add_node("collect_domains", domain_collector_agent)
workflow.add_node("evaluate_mesh", mesh_evaluator_agent)
workflow.add_node("apply_policies", policy_engine_agent)
workflow.add_node("resolve_conflicts", conflict_resolver_agent)
workflow.add_node("sentinel_check", sentinel_loop_agent)
workflow.add_node("generate_report", report_generator_agent)workflow.set_entry_point("collect_domains")
workflow.add_conditional_edges("collect_domains",
should_continue_after_collection,
{"evaluate_mesh": "evaluate_mesh", "end": END})
Nodo 1: El recolector de dominios
La etapa Node 1 The Domain funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso. La etapa Node 1 The Domain funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.
AGENT_A_URL = "http://localhost:8001"
AGENT_B_URL = "http://localhost:8002"
Node 2: El evaluador de malla, donde surgen los conflictos
Para la etapa Node 2 The Mesh, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar una única responsabilidad y no un proceso complicado. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La conexión durante la compilación no equivale a una solución completa desde el punto de vista empresarial.
{
"conflict_type": "budget_reliability_tradeoff",
"severity": "HIGH",
"resource_id": "resource-x",
"recommendation_a": {"domain": "domain_a",
"title": "Decommission idle resource-x"},
"recommendation_b": {"domain": "domain_b",
"title": "Enable redundancy for resource-x"}
}
Puntuación Mesh = (Confianza X 100) + Bonus de Gravedad — Penalizaciones por Conflictos
Para la etapa de Confianza en la Puntuación de Malla X, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
Nodo 3: El motor de políticas OPA, gobernanza determinística
En la etapa OPA de Node 3, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el flujo pasa de entornos de demostración a entornos compartidos. Incluya la aprobación humana en aquellos pasos que generan gastos o modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial. En la etapa OPA de Node 3, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, las verificaciones humanas y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.
Arquitectura OPA Sidecar
Al trabajar en la etapa de Arquitectura OPA Sidecar, primero escribe el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiere unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado. Haz puntos de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
package cortex.recommendation
decision := result if {
_is_destructive_action(input.recommendation.title)
_is_critical_resource(input.recommendation.resource_id,
input.context)
result := {
"decision": "deny",
"reason": "Policy prevents decommissioning
of critical resource",
"rule_name": "protect_critical_resources"
}
}
package cortex.conflict
# Budget vs Reliability on critical resources gets policy override
resolution := result if {
input.conflict.conflict_type == "budget_reliability_tradeoff"
_is_critical_resource(input.conflict.resource_id, input.context)
result := {
"strategy": "policy_override",
"winner": _higher_ranked_domain(...),
"rule_name": "budget_reliability_critical_resource"
}
}# Resource Contention resolved by domain priority for unequal ranks
resolution := result if {
input.conflict.conflict_type == "resource_contention"
domain_rank[...] != domain_rank[...]
result := {
"strategy": "domain_priority",
"winner": _higher_ranked_domain(...),
"rule_name": "resource_contention_priority"
}
}# Opposing Recommendations on critical resources are escalated
resolution := result if {
input.conflict.conflict_type == "opposing_recommendations"
_is_critical_resource(...)
result := {
"strategy": "escalate",
"winner": "none",
"rule_name": "opposing_critical_escalate"
}
}
package cortex.priority
domain_rank := {
"domain_a": 1,
"domain_b": 2,
"domain_c": 3,
"domain_d": 4,
"domain_e": 5
}
services:
opa:
image: openpolicyagent/opa:latest
command: run --server --addr=0.0.0.0:8181 /policies
volumes:
- ./src/policies:/policies
Nodo 4: El resolvedor de conflictos, resolución en cuatro etapas
Al trabajar en la etapa Node 4: El conflicto, primero anote el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente una etapa posterior.
Jerarquía de resolución de conflictos en cuatro etapas
Al trabajar en la etapa de resolución de conflictos de cuatro fases, anote primero el contrato: los datos de entrada necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La reanudación del proceso no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en la etapa de resolución de conflictos de cuatro fases, anote primero el contrato: los datos de entrada necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras adicionales realizadas posteriormente.
{
"winner": "a" | "b" | "both",
"reasoning": "...",
"confidence": 0.0-1.0
}
Nodo 5: El bucle Sentinel, detectando desviaciones entre ciclos
La etapa Node 5 Sentinel funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
change_percent = (current - previous) / abs(previous) * 100
if abs(change_percent) > DRIFT_THRESHOLD_PERCENT:
drift_status = "WORSENED" if change_percent < 0
else "DRIFTED"
Nodo 6: El generador de informes
La etapa Node 6 The Report funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
El escenario completo de demostración
La etapa “The Full Demo Scenario” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso. La etapa “The Full Demo Scenario” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.
Ejecutarlo
En la fase de ejecución, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Incluya la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
git clone https://github.com/kyndryl-cto/agentic-cortex.git
cp .env.example .env
# Fill in Azure OpenAI credentials
docker-compose up
curl -X POST http://localhost:8000/assess \
-H "Content-Type: application/json" \
-d '{"subscription_ids": ["sub-001"],
"tenant_id": "tenant-001"}'
{
"node": "evaluate_mesh", "status": "processing",
"agent": "mesh_evaluator", "timestamp": "..."
}
{
"node": "apply_policies", "status": "processing",
"agent": "policy_engine", "timestamp": "..."
}
Escalar hacia la producción: agregar dominios sin tocar el pipeline
En la etapa de Escalado a Producción, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Creación de políticas Rego personalizadas para una gobernanza específica de la organización
En la fase de creación de políticas Rego personalizadas, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el flujo pasa de entornos de demostración a entornos compartidos. Incorpore la aprobación humana en aquellos casos que impliquen gastos o cambios en datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase de creación de políticas Rego personalizadas, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de políticas aplicadas posteriormente.
sh.
decision := result if {
"database" in lower(input.recommendation.resource_type)
_is_destructive_action(input.recommendation.title)
not _has_recovery_plan(input.recommendation.resource_id,
input.context)
result := {
"decision": "deny",
"reason": "Cannot decommission database without
verified recovery plan",
"rule_name": "protect_databases"
}
}
decision := result if {
input.recommendation.estimated_savings > 10000
result := {
"decision": "escalate",
"reason": sprintf("Projected savings $%.0f exceeds
threshold and requires approval",
[input.recommendation.estimated_savings]),
"rule_name": "high_impact_approval"
}
}
Operacionalización del bucle Sentinel con monitoreo en la nube
Al trabajar en la etapa de operacionalización del bucle Sentinel, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga puntos de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Integración del bucle Sentinel con monitoreo en la nube
Al trabajar en la etapa Sentinel Loop y Cloud, primero escribe el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Considera esta etapa como un contrato entre las entradas y los resultados validados. Nombra los artefactos, define las verificaciones de éxito y rechaza las completaciones parciales silenciosas. Haz una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Observabilidad: Rastreando el camino completo de resolución
Al trabajar en la fase de “Observability Tracing the Full”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando la ruta pasa de un entorno de demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en la fase de “Observability Tracing the Full”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras adicionales realizadas posteriormente.
{
"decision_id": "pd-001",
"recommendation_id": "rec-001",
"policy_name": "protect_critical_resources",
"result": "deny",
"reason": "Policy prevents decommissioning
of critical resource",
"evaluated_at": "2026-03-12T14:23:01Z"
}
{
"conflict_id": "cf-001",
"resolution_strategy": "POLICY_OVERRIDE",
"resolved_by": "policy",
"resolution_outcome": "Resolved by policy:
'protect_critical_resources'
denied 'Decommission idle resource-x'"
}
Resumen arquitectónico
La etapa de Resumen arquitectónico funciona mejor cuando se trata como una superficie medible. Capture un registro de éxito, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Mantenga el estado del gráfico simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Lista de verificación operativa
Para la etapa de Lista de verificación operativa, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto.
Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un único lugar que los operadores puedan auditar sin tener que leer todo el sistema.
Coloque la aprobación humana en las operaciones que generan gastos o modifican datos de producción. La conexión establecida en tiempo de compilación no equivale a la completitud del proceso empresarial.
Escriba un manual breve: cómo rotar claves, cómo vaciar la cola de tareas y cómo revertir la última operación de ingestión.
Documente tanto el camino óptimo como el proceso de recuperación. Las reintentos, las verificaciones humanas y el manejo de mensajes no entregados forman parte del producto, no son algo que se añada posteriormente.
Coloque la aprobación humana en las operaciones que generan gastos o modifican datos de producción. La conexión establecida en tiempo de compilación no equivale a la completitud del proceso empresarial.
Antes de promocionar el conjunto de herramientas, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos para revertir cambios. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de credenciales secretas. Prefiera una fiabilidad sólida a demostraciones ingeniosas pero puntuales.
Nota para el lote 90ddb9951707: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los archivos de prueba para que los cambios en los modelos posteriores sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: Construyendo AIOps agencial: Una plataforma de bucle cerrado con LangGraph — Guía paso a paso de las Notas prácticas: Construyendo AIOps agencial: Una plataforma de bucle cerrado con LangGraph, incluyendo contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.