Arxi Decision Gate Asset Core
Docs
Decision Gate Docs

Avaluació de portes determinista, reproduïble amb decisions auditable.

Asset Core docs

LLM-Native Playbook

A Simple Vista

Què: Fluxos de treball optimitzats per LLM per a una iteració ràpida (precheck) i execucions auditable (en viu) Per què: Els agents poden iterar cap a la satisfacció de la porta de manera determinista Qui: Desenvolupadors d’agents LLM, enginyers d’automatització Prerequisits: evidence_flow_and_execution_model.md

Mental Model: Dos Camins

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

Inici ràpid: Precomprovació

Consell de Windows: PowerShell/CMD no suporten curl en múltiples línies al estil bash. Utilitzeu un comandament d’una sola línia o cadenes de PowerShell aquí. Consell de preset: Comenceu amb configs/presets/quickstart-dev.toml per a execucions locals sense friccions. Si utilitzeu el preset Hardened, afegiu Authorization: Bearer <token> a cada sol·licitud i utilitzeu un espai de noms no predeterminat (per exemple, 2).

Pas 1: Defineix un Escenari

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 prevalidació no executa consultes del proveïdor. La càrrega afirmada es mapeja a identificadors de condició (per exemple, report_ok) i s’avalua directament. La consulta del proveïdor només s’utilitza durant les execucions en viu.

Pas 2: Registrar una Forma de Dades (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 registre d’esquema està governat per l’ACL del registre. El bypass només local és desactivat per defecte; configureu server.auth.principals (recomanat) o establiu schema_registry.acl.allow_local_only = true per a la incorporació només en desenvolupament si veieu unauthorized.

Pas 3: Precomprovació amb Càrrega Inline

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 }
      }
    }
  }'

Resposta de precomprovació (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" }
              ]
            }
          ]
        }
      }
    ]
  }
}

Important: precheck no retorna valors d’evidència ni errors del proveïdor.

Flux de Funcionament en Directe (Auditat)

# 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"
      }
    }
  }'

Resultat en viu: NextResult { decisió, paquets, estat }. Opcional feedback: "trace" pot retornar l’estat de la porta/condició quan ho permet la política de retroalimentació del servidor; feedback: "evidence" està subjecte a les normes de divulgació d’evidències.

Per inspeccionar proves i errors, crida runpack_export o evidence_query (si la política de divulgació ho permet).

Recuperació d’errors

Les fallades de precomprovació són o bé:

  • Errors d’eina (esquema no trobat, càrrega útil no vàlida), o
  • Retencions de porta (decisió hold), amb un rastre que mostra quines condicions són desconegudes/falses.

Atès que la precheck no retorna errors d’evidència:

  1. Utilitzeu evidence_query per a la depuració del proveïdor (subjecte a la política de divulgació).
  2. Executa una avaluació en viu i exporta el runpack per inspeccionar errors d’evidència.

Consells per al Disseny d’Esquemes

  • Utilitzeu un objecte de càrrega clau per IDs de condició.
  • Estableix additionalProperties: false per detectar errors tipogràfics.
  • Si el teu escenari té exactament una condició, pots passar una càrrega útil que no sigui un objecte.

Glossari

Precheck: Avaluació d’evidències afirmades; sense mutació d’estat. Live Run: Avaluació obtinguda del proveïdor; runpack emmagatzemat. Data Shape: Esquema JSON utilitzat per validar les càrregues de precheck.