AI copilot

sequenceDiagram
    participant C as Cliente
    participant S as SBOX
    C->>S: POST /v1/ai/query { question }
    S-->>C: event run.started
    S-->>C: event tool.call / tool.result (por tool)
    S-->>C: event tool.error (permiso faltante o falla)
    S-->>C: event message { text }
    S-->>C: event citations { refs }
    S-->>C: event action.proposal { applied: false }
    S-->>C: event run.completed

curl -sS -N "$SBOX/v1/ai/query" -X POST \
  -H "authorization: Bearer $TOKEN" \
  -H "idempotency-key: ai-demo-0001" \
  -H "accept: text/event-stream" \
  -H "content-type: application/json" \
  -d '{"question":"¿Cómo está la cartera después del granizo?"}'

Three rules that are not optional

Every tool checks the permission of ITS area. The route's gate only says you may ask. If that were enough, someone with portfolio permission and no claims permission would read the claims through the copilot — the worst kind of leak, because it leaves no trace on any screen and the user never sees a "you don't have access". When a permission is missing, a tool.error arrives with insufficient_permission, and the citations do not mention what could not be read.

Every statement of fact carries a citation. An insurance copilot that asserts an area without saying where it came from is an adjuster without a signed record.

The AI proposes, the human approves. Mutation tools emit action.proposal with applied: false. Nothing the copilot suggests gets written.

Resuming

Every event carries id:. If you disconnect midway, send Last-Event-ID with the last one you saw and the stream continues from there, without spending the turn again.

What breaks

• A failing tool degrades the run, with its tool.error in the trace. A copilot that answers 500 because one of six tools found no data is useless exactly when it is needed most.
• 429 rate_limited with Retry-After. The limit is per actor, not per organization: if it were per tenant, a looping script would leave the whole team without a copilot.
• The sandbox LLM provider is mock and deterministic. The same question over the same data gives the same text, which is what keeps this example correct tomorrow.

Endpoints in this guide

• POST /v1/ai/query