Arxi Puerta de Decisión Asset Core
Docs
Documentos de Decision Gate

Evaluación de puertas determinista, reproducible con decisiones auditables.

Documentación de Asset Core

LLM-Native Playbook

A primera vista

Qué: Flujos de trabajo optimizados para LLM para iteraciones rápidas (preverificación) y ejecuciones auditables (en vivo) Por qué: Los agentes pueden iterar hacia la satisfacción de la puerta de manera determinista Quién: Desarrolladores de agentes LLM, ingenieros de automatización Requisitos previos: evidence_flow_and_execution_model.md

Modelo Mental: Dos Caminos

Path A: Precheck (fast, asserted)
  - client supplies payload
  - data shape validates payload
  - gates evaluated, no run state mutation

Path B: Live Run (audited, verified)
  - providers fetch evidence
  - run state mutated, runpack stored

Inicio Rápido: Preverificación

Consejo de Windows: PowerShell/CMD no soportan curl en múltiples líneas al estilo bash. Usa un comando de una sola línea o cadenas de PowerShell aquí. Consejo de preajuste: Comienza con configs/presets/quickstart-dev.toml para ejecuciones locales sin fricción. Si usas el preajuste Hardened, añade Authorization: Bearer <token> a cada solicitud y utiliza un espacio de nombres no predeterminado (por ejemplo, 2).

Paso 1: Definir un Escenario

curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "scenario_define",
      "arguments": {
        "spec": {
          "scenario_id": "llm-precheck",
          "namespace_id": 1,
          "spec_version": "v1",
          "stages": [
            {
              "stage_id": "main",
              "entry_packets": [],
              "gates": [
                {
                  "gate_id": "quality",
                  "requirement": { "Condition": "report_ok" }
                }
              ],
              "advance_to": { "kind": "terminal" },
              "timeout": null,
              "on_timeout": "fail"
            }
          ],
          "conditions": [
            {
              "condition_id": "report_ok",
              "query": {
                "provider_id": "json",
                "check_id": "path",
                "params": { "file": "report.json", "jsonpath": "$.summary.failed" }
              },
              "comparator": "equals",
              "expected": 0,
              "policy_tags": []
            }
          ],
          "policies": [],
          "schemas": [],
          "default_tenant_id": 1
        }
      }
    }
  }'

Nota: La verificación previa no ejecuta consultas de proveedor. La carga útil afirmada se mapea a los ids de condición (por ejemplo, report_ok) y se evalúa directamente. La consulta del proveedor solo se utiliza durante las ejecuciones en vivo.

Paso 2: Registrar una Forma de Datos (Esquema)

curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "schemas_register",
      "arguments": {
        "record": {
          "tenant_id": 1,
          "namespace_id": 1,
          "schema_id": "llm-precheck",
          "version": "v1",
          "schema": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "report_ok": { "type": "number" }
            },
            "required": ["report_ok"]
          },
          "description": "LLM precheck payload schema",
          "created_at": { "kind": "logical", "value": 1 },
          "signing": null
        }
      }
    }
  }'

Nota: El registro del esquema está gobernado por el ACL del registro. El bypass solo local está deshabilitado por defecto; configura server.auth.principals (recomendado) o establece schema_registry.acl.allow_local_only = true para la incorporación solo en desarrollo si ves unauthorized.

Paso 3: Preverificación con Carga Útil en Línea

curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "precheck",
      "arguments": {
        "tenant_id": 1,
        "namespace_id": 1,
        "scenario_id": "llm-precheck",
        "spec": null,
        "stage_id": "main",
        "data_shape": { "schema_id": "llm-precheck", "version": "v1" },
        "payload": { "report_ok": 0 }
      }
    }
  }'

Respuesta de prechequeo (forma exacta):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "decision": {
            "kind": "complete",
            "stage_id": "main"
          },
          "gate_evaluations": [
            {
              "gate_id": "quality",
              "status": "true",
              "trace": [
                { "condition_id": "report_ok", "status": "true" }
              ]
            }
          ]
        }
      }
    ]
  }
}

Importante: precheck no devuelve valores de evidencia ni errores del proveedor.

Flujo de Ejecución en Vivo (Auditado)

# scenario_start
curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "scenario_start",
      "arguments": {
        "scenario_id": "llm-precheck",
        "run_config": {
          "tenant_id": 1,
          "namespace_id": 1,
          "run_id": "run-1",
          "scenario_id": "llm-precheck",
          "dispatch_targets": [],
          "policy_tags": []
        },
        "started_at": { "kind": "unix_millis", "value": 1710000000000 },
        "issue_entry_packets": false
      }
    }
  }'

# scenario_next
curl -s http://127.0.0.1:4000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "scenario_next",
      "arguments": {
        "scenario_id": "llm-precheck",
        "request": {
          "run_id": "run-1",
          "tenant_id": 1,
          "namespace_id": 1,
          "trigger_id": "trigger-1",
          "agent_id": "agent-1",
          "time": { "kind": "unix_millis", "value": 1710000000000 },
          "correlation_id": null
        },
        "feedback": "trace"
      }
    }
  }'

Resultado en vivo: NextResult { decision, packets, status }. Opcionalmente, feedback: "trace" puede devolver el estado de la puerta/condición cuando lo permite la política de retroalimentación del servidor; feedback: "evidence" está sujeto a las reglas de divulgación de evidencia.

Para inspeccionar evidencia y errores, llama a runpack_export o evidence_query (si la política de divulgación lo permite).

Recuperación de Errores

Los fallos de prechequeo son ya sea:

  • Errores de herramienta (esquema no encontrado, carga útil inválida), o
  • Retenciones de puerta (decisión hold), con un rastro que muestra qué condiciones son desconocidas/falsas.

Dado que el precheck no devuelve errores de evidencia:

  1. Utilice evidence_query para la depuración del proveedor (sujeto a la política de divulgación).
  2. Ejecute una evaluación en vivo y exporte el runpack para inspeccionar errores de evidencia.

Consejos para el Diseño de Esquemas

  • Utilice una carga útil de objeto con claves por ID de condición.
  • Establezca additionalProperties: false para detectar errores tipográficos.
  • Si su escenario tiene exactamente una condición, puede pasar una carga útil que no sea un objeto.

Glosario

Precheck: Evaluación de evidencia afirmada; sin mutación de estado. Live Run: Evaluación obtenida por el proveedor; runpack almacenado. Data Shape: Esquema JSON utilizado para validar las cargas útiles de precheck.