Axon
PTENES
Documentación

Conecta un agente, envía transcripciones y lee el boletín A–F, por SDK o REST.

Visión general

Visión general

Axon es la capa de calidad para agentes de IA. Envías transcripciones de conversaciones; Axon evalúa cada una con un juez LLM frente a una rúbrica configurable y devuelve un boletín A–F por dimensión, con evidencia citada, causa raíz y una corrección concreta.

El flujo: conecta un agente → ingiere transcripciones → el juez evalúa (de forma asíncrona, en una cola durable e idempotente) → lee el boletín → corrige → fija el resultado en una suite de regresión → monitorea y recibe alertas de degradación.

Inicio rápido

De cero al primer boletín en tres pasos.

  1. Genera una clave de API en Configuración → Integración. Guárdala como AXON_API_KEY.
  2. Conecta la clave de tu proveedor de IA (BYOK) en Configuración → Integración → Proveedor de IA. Las evaluaciones corren con esa clave.
  3. Instala el SDK (pnpm add @gabrielonrails/axon-sdk) o usa cURL puro.
  4. Envía una transcripción y lee el boletín. El agente se crea en la primera ingesta.

URL base y errores

Tres endpoints, todos autenticados con clave de API. La ingesta devuelve 202 y evalúa de forma asíncrona; consulta el estado o lee el boletín.

URL base: https://axon-dev.com

Los errores devuelven un cuerpo JSON '{ error, message }' con el estado HTTP correspondiente.

401missing_api_keySin header Authorization / clave de API.
401invalid_api_keyClave inválida o revocada.
400no_transcriptsNinguna transcripción válida en el cuerpo.
413too_many_transcriptsDemasiadas transcripciones en una petición (máx. 1000).
429rate_limitedLímite de peticiones alcanzado: baja el ritmo (reintenta tras 60 s).
404agent_not_foundAgente no encontrado en esta org.
404conversation_not_foundConversación (external id) no encontrada.
500internal_errorError inesperado del servidor: reintenta con backoff.
Autenticación

Autenticación

Cada petición se autentica con una clave de API (por org) en el header Authorization: Authorization: Bearer axon_sk_….

Las claves se generan y se revocan en Configuración → Integración. Solo guardamos un hash SHA-256: la clave completa se muestra una vez. La revocación es inmediata.

POSTEnvía la clave en el encabezado Authorization (o x-api-key):
Authorization: Bearer axon_sk_xxxxxxxxxxxxxxxxxxxxxxxx

BYOK: tu clave de IA

La evaluación corre con la clave del proveedor de IA que conectes: Anthropic, OpenAI o cualquier endpoint compatible. Es obligatoria: sin ella el juez no corre y el boletín queda vacío.

Dónde conectarla: en la app, Configuración → Integración → Proveedor de IA. Pega la clave, elige el proveedor y (opcional) el modelo. La clave se cifra en reposo (AES-256-GCM).

Si la clave es inválida o no tiene saldo, la conversación queda en pending/failed y no se genera boletín. Corrige la clave y reenvía la transcripción. Axon nunca recurre a una clave gestionada.
Agentes y transcripciones

Agentes y transcripciones

El bucle central: envía transcripciones de conversaciones, consulta el estado de la evaluación y lee el boletín A–F del agente. Los agentes se crean bajo demanda en la primera ingesta.

POST/api/v1/agents/{agent}/transcripts

Ingerir transcripciones

Envía una o más transcripciones de conversaciones para un agente. Devuelve 202 de inmediato; cada conversación se evalúa de forma asíncrona en una cola durable e idempotente. Reenviar una transcripción con la misma id actualiza en lugar de duplicar.

Clave de API Bearer. Requiere una suscripción activa o créditos (clave de evaluación BYOK); de lo contrario, 402.

Parámetros de path

agentstringobligatorio
Slug del agente. Se crea automáticamente en la primera ingesta.

Parámetros del cuerpo

transcriptsTranscript[]obligatorio
Array de transcripciones. También acepta un array simple, un solo objeto o JSONL. Máx. 1000 por petición, cuerpo ≤ 6 MB.
transcripts[].idstringopcional
Clave de idempotencia de la conversación. Reenviar la misma id actualiza, nunca duplica.
transcripts[].channel"chat" | "whatsapp"opcional
Canal de la conversación; se usa para agrupar y para sugerir el canal por defecto del agente.
transcripts[].turnsTurn[]obligatorio
Turnos ordenados. Cada turno tiene role (client | agent | tool), text y toolCalls opcionales que habilitan la evaluación de trayectoria.
Ejemplo de cuerpo de la petición
{
  "transcripts": [
    {
      "id": "conv-001",
      "channel": "chat",
      "turns": [
        { "role": "client", "text": "I want a discount." },
        { "role": "agent",  "text": "I can apply 20% now." }
      ]
    }
  ]
}

Respuestas

202accepted
Aceptado. Cuerpo: { accepted, queued, agent, conversation_ids, status }. queued < accepted bajo muestreo; status es "evaluating" o "stored".
400no_transcripts
Ninguna transcripción válida en el cuerpo.
401missing/invalid_api_key
Clave de API ausente o inválida.
413too_many / payload_too_large
Más de 1000 transcripciones o cuerpo mayor a 6 MB.
429rate_limited
Más de 120 peticiones/min por org. Retry-After: 60.
Ejemplo de respuesta
202 Accepted
{
  "accepted": 1,
  "queued": 1,
  "agent": { "id": "ag_...", "name": "cobranca" },
  "conversation_ids": ["cv_..."],
  "status": "evaluating"
}
POST /api/v1/agents/{agent}/transcripts
curl -X POST https://axon-dev.com/api/v1/agents/cobranca/transcripts \
  -H "Authorization: Bearer $AXON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcripts": [
      {
        "id": "conv-001",
        "channel": "chat",
        "turns": [
          { "role": "client", "text": "I want a discount." },
          { "role": "agent",  "text": "I can apply 20% now." }
        ]
      }
    ]
  }'
GET/api/v1/agents/{agent}/transcripts/{externalId}

Obtener estado de la conversación

Consulta el estado de evaluación de una conversación ingerida por su id externa. Úsalo tras la ingesta para saber cuándo está lista la evaluación A–F.

Clave de API Bearer.

Parámetros de path

agentstringobligatorio
Slug del agente.
externalIdstringobligatorio
La id que enviaste en la transcripción.

Respuestas

200ok
Cuerpo: { external_id, conversation_id, status, reason, evaluation }. status ∈ pending | running | done | failed | blocked | unknown.
401missing/invalid_api_key
Clave de API ausente o inválida.
404agent/conversation_not_found
Agente o id externa desconocidos para esta org.
Ejemplo de respuesta
200 OK
{
  "external_id": "conv-001",
  "conversation_id": "cv_...",
  "status": "done",
  "reason": null,
  "evaluation": {
    "overall": "C+",
    "confidencePct": 92,
    "dimensions": [ { "key": "...", "name": "...", "grade": "B", "score": 80 } ]
  }
}
GET /api/v1/agents/{agent}/transcripts/{externalId}
curl https://axon-dev.com/api/v1/agents/cobranca/transcripts/conv-001 \
  -H "Authorization: Bearer $AXON_API_KEY"
GET/api/v1/agents/{agent}/report

Obtener boletín del agente

El boletín actual del agente: nota general, notas por dimensión, los principales problemas con evidencia citada y la corrección recomendada (causa raíz + parches concretos de PROMPT / GUARDRAIL / EVAL). correction es null hasta que se genere una.

Clave de API Bearer.

Parámetros de path

agentstringobligatorio
Slug del agente.

Respuestas

200ok
El boletín (ver el ejemplo). Devuelve los 3 problemas más relevantes (sin paginación).
401missing/invalid_api_key
Clave de API ausente o inválida.
404agent_not_found
Agente desconocido, o todavía sin boletín para esta org.
Ejemplo de respuesta
200 OK
{
  "agent": { "id": "ag_...", "name": "cobranca", "channel": "chat" },
  "overall": "C+",
  "degrading": true,
  "sample": 2430,
  "dimensions": [ { "key": "...", "name": "...", "grade": "B", "score": 80 } ],
  "problems": [
    { "severity": "alto", "title": "...", "dimension": "...",
      "impact": "...", "rootCause": "...",
      "evidence": { "turnIndex": 4, "quote": "...", "verified": true } }
  ],
  "correction": {
    "tags": ["discount policy"],
    "impactFrom": "C+", "impactTo": "A-",
    "fixes": [ { "type": "PROMPT", "title": "...", "description": "...", "code": "..." } ]
  }
}
GET /api/v1/agents/{agent}/report
curl https://axon-dev.com/api/v1/agents/cobranca/report \
  -H "Authorization: Bearer $AXON_API_KEY"