Axon
Documentação

Conecte um agente, envie transcrições e leia o boletim A–F, via SDK ou REST.

Visão geral

Visão geral

A Axon é a camada de qualidade para agentes de IA. Você envia transcrições de conversas; a Axon avalia cada uma com um juiz LLM contra uma rubrica configurável e devolve um boletim A–F por dimensão, com evidência citada, causa-raiz e correção concreta.

O fluxo: conecte um agente → ingira transcrições → o juiz avalia (de forma assíncrona, numa fila durável e idempotente) → leia o boletim → corrija → trave numa suíte de regressão → monitore e receba alertas de degradação.

Início rápido

Do zero ao primeiro boletim em três passos.

  1. Gere uma chave de API em Configurações → Integração. Guarde como AXON_API_KEY.
  2. Conecte a chave do seu provedor de IA (BYOK) em Configurações → Integração → Provedor de IA. As avaliações rodam nessa chave.
  3. Instale o SDK (pnpm add @gabrielonrails/axon-sdk) ou use cURL puro.
  4. Envie uma transcrição e leia o boletim. O agente é criado na primeira ingestão.

URL base & erros

Três endpoints, todos autenticados por chave de API. A ingestão devolve 202 e avalia de forma assíncrona; faça polling do status ou leia o boletim.

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

Erros devolvem um corpo JSON '{ error, message }' com o status HTTP apropriado.

401missing_api_keySem header Authorization / chave de API.
401invalid_api_keyChave inválida ou revogada.
400no_transcriptsNenhuma transcrição válida no corpo.
413too_many_transcriptsTranscrições demais numa requisição (máx. 1000).
429rate_limitedLimite de requisições atingido: reduza o ritmo (retry após 60s).
404agent_not_foundAgente não encontrado nesta org.
404conversation_not_foundConversa (external id) não encontrada.
500internal_errorErro inesperado do servidor: re-tente com backoff.
Autenticação

Autenticação

Toda requisição autentica com uma chave de API (por org) no header Authorization: Authorization: Bearer axon_sk_….

As chaves são geradas e revogadas em Configurações → Integração. Guardamos só um hash SHA-256: a chave completa aparece uma vez. A revogação é imediata.

POSTEnvie a chave no cabeçalho Authorization (ou x-api-key):
Authorization: Bearer axon_sk_xxxxxxxxxxxxxxxxxxxxxxxx

BYOK: sua chave de IA

A avaliação roda na chave do provedor de IA que você conecta: Anthropic, OpenAI ou qualquer endpoint compatível. É obrigatória: sem ela o juiz não roda e o boletim fica vazio.

Onde conectar: no app, Configurações → Integração → Provedor de IA. Cole a chave, escolha o provedor e (opcional) o modelo. A chave é cifrada em repouso (AES-256-GCM).

Se a chave estiver inválida ou sem saldo, a conversa fica em pending/failed e nenhum boletim é gerado. Corrija a chave e reenvie a transcrição. A Axon nunca recorre a uma chave gerenciada.
Agentes & transcrições

Agentes & transcrições

O loop central: envie transcrições de conversas, consulte o status da avaliação e leia o boletim A–F do agente. Os agentes são criados sob demanda na primeira ingestão.

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

Ingerir transcrições

Envie uma ou mais transcrições de conversas para um agente. Retorna 202 imediatamente; cada conversa é avaliada de forma assíncrona numa fila durável e idempotente. Reenviar uma transcrição com a mesma id atualiza em vez de duplicar.

Chave de API Bearer. Requer uma assinatura ativa ou créditos (chave de avaliação BYOK); caso contrário, 402.

Parâmetros de path

agentstringobrigatório
Slug do agente. Criado automaticamente na primeira ingestão.

Parâmetros do corpo

transcriptsTranscript[]obrigatório
Array de transcrições. Também aceita um array simples, um único objeto ou JSONL. Máx. 1000 por requisição, corpo ≤ 6 MB.
transcripts[].idstringopcional
Chave de idempotência da conversa. Reenviar a mesma id atualiza, nunca duplica.
transcripts[].channel"chat" | "whatsapp"opcional
Canal da conversa; usado para agrupamento e para sugerir o canal padrão do agente.
transcripts[].turnsTurn[]obrigatório
Turnos ordenados. Cada turno tem role (client | agent | tool), text e toolCalls opcionais que habilitam a avaliação de trajetória.
Exemplo de corpo da requisição
{
  "transcripts": [
    {
      "id": "conv-001",
      "channel": "chat",
      "turns": [
        { "role": "client", "text": "I want a discount." },
        { "role": "agent",  "text": "I can apply 20% now." }
      ]
    }
  ]
}

Respostas

202accepted
Aceito. Corpo: { accepted, queued, agent, conversation_ids, status }. queued < accepted sob amostragem; status é "evaluating" ou "stored".
400no_transcripts
Nenhuma transcrição válida no corpo.
401missing/invalid_api_key
Chave de API ausente ou inválida.
413too_many / payload_too_large
Mais de 1000 transcrições ou corpo acima de 6 MB.
429rate_limited
Mais de 120 requisições/min por org. Retry-After: 60.
Exemplo de resposta
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}

Obter status da conversa

Consulte o status de avaliação de uma conversa ingerida pela sua id externa. Use após a ingestão para saber quando a avaliação A–F está pronta.

Chave de API Bearer.

Parâmetros de path

agentstringobrigatório
Slug do agente.
externalIdstringobrigatório
A id que você enviou na transcrição.

Respostas

200ok
Corpo: { external_id, conversation_id, status, reason, evaluation }. status ∈ pending | running | done | failed | blocked | unknown.
401missing/invalid_api_key
Chave de API ausente ou inválida.
404agent/conversation_not_found
Agente ou id externa desconhecidos para esta org.
Exemplo de resposta
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

Obter boletim do agente

O boletim atual do agente: nota geral, notas por dimensão, os principais problemas com evidência citada e a correção recomendada (causa-raiz + patches concretos de PROMPT / GUARDRAIL / EVAL). correction é null até que uma seja gerada.

Chave de API Bearer.

Parâmetros de path

agentstringobrigatório
Slug do agente.

Respostas

200ok
O boletim (veja o exemplo). Retorna os 3 problemas mais relevantes (sem paginação).
401missing/invalid_api_key
Chave de API ausente ou inválida.
404agent_not_found
Agente desconhecido, ou ainda sem boletim para esta org.
Exemplo de resposta
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"