Copiloto AI

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

Tres reglas que no son opcionales

Cada tool chequea el permiso de SU área. La puerta de la ruta sólo dice que podés preguntar. Si eso alcanzara, alguien con permiso de cartera y sin permiso de siniestros los leería por vía del copiloto — la peor forma de una fuga, porque no deja rastro en ninguna pantalla y el usuario nunca ve un "no tenés acceso". Cuando falta un permiso llega un tool.error con insufficient_permission, y las citations no mencionan lo que no se pudo leer.

Toda afirmación de hecho lleva citation. Un copiloto de seguros que afirme una superficie sin decir de dónde salió es un perito sin acta.

La AI propone, el humano aprueba. Las tools de mutación emiten action.proposal con applied: false. Nada de lo que el copiloto sugiere se escribe.

Reanudar

Cada evento trae id:. Si te desconectás a la mitad, mandá Last-Event-ID con el último que viste y el stream sigue desde ahí, sin volver a gastar el turno.

Lo que se rompe

• Una tool que falla degrada el run, con su tool.error en el trace. Un copiloto que contesta 500 porque una de seis tools no encontró datos es inútil justo cuando más se lo necesita.
• 429 rate_limited con Retry-After. El límite es por actor, no por organización: si fuera por tenant, un script en bucle dejaría sin copiloto a todo el equipo.
• El proveedor de LLM del sandbox es mock y es determinista. La misma pregunta sobre los mismos datos da el mismo texto, que es lo que hace que este ejemplo siga siendo correcto mañana.

Endpoints de esta guía

• POST /v1/ai/query