Acompanhamento do agente de IA

Execuções

Uma execução é um turno do agente (ou um teste). Status: running, waiting, completed, awaiting_approval, failed, unknown, superseded, rejected.

`GET /ai/executions`

Escopo agents:read

Query customer_id, agent_id e status opcionais, page, per_page.

`GET /ai/executions/{id}`

Escopo agents:read

Query customer_id e agent_id, ambos obrigatórios.

{
  "id": "14141414-1414-4141-8141-141414141414",
  "agent_id": "44444444-4444-4444-8444-444444444444",
  "version_id": "55555555-5555-4555-8555-555555555555",
  "source": "live",
  "mode": "assisted",
  "status": "awaiting_approval",
  "provider": "openai",
  "model": "MODELO_VALIDADO_NA_CREDENCIAL",
  "reply": "O prazo para Manaus é de 7 dias úteis.",
  "tool_trace": [
    {
      "step": 1,
      "call_id": "call_1",
      "name": "knowledge.search",
      "arguments": {
        "query": "prazo Manaus"
      },
      "output": "[...]",
      "status": "completed",
      "error_code": null
    }
  ],
  "usage": {
    "input_tokens": 1830,
    "output_tokens": 96,
    "cache_read_tokens": 0,
    "cache_write_tokens": 0,
    "reasoning_tokens": 0
  },
  "measurement_status": "measured",
  "finish_reason": "stop",
  "error_code": null,
  "created_at": "2026-09-25T13:00:00.000Z",
  "completed_at": "2026-09-25T13:00:04.000Z",
  "run_id": "15151515-1515-4151-8151-151515151515",
  "conversation_id": "99999999-9999-4999-8999-999999999999",
  "latency_ms": 4012,
  "security": {
    "summary": {
      "hold": null,
      "guard": {
        "verdict": "pass",
        "level": "none",
        "layer": "heuristic",
        "codes": []
      },
      "evaluation": {
        "verdict": "pass",
        "attempts": 1,
        "codes": []
      },
      "disclosure_version": 1
    },
    "events": [],
    "events_unavailable": false
  }
}

security é a trilha de proteção: resumo (hold, detector, avaliação e versão do aviso de IA) e events com estágio, veredito, códigos e o vínculo usado (provedor, modelo, origem), sem texto de mensagem nem chave. events_unavailable: true indica que a trilha não pôde ser lida, não que não houve verificação. Com operador, operator_execution traz a execução dele no mesmo formato.

`POST /ai/executions/{id}/decision`

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, agent_id, decision: "approve" | "reject"}. Decide uma execução em awaiting_approval no modo assistido. Aprovar executa as ações e envia a resposta; retorna a execução atualizada. Pela API, a chave precisa ter sido criada por um Administrador; no painel, qualquer membro da conta (Operador ou Administrador) aprova ou rejeita.

Casos

O agente abre um caso quando precisa de uma decisão da equipe. Status open, waiting, resolved, closed; revision numérica.

`GET /ai/cases`

Escopo agents:read

Query customer_id, page, per_page e filtros status, kind (agendamento, duvida, problema, financeiro, acesso, outro) e source (agent, guardrail, human, operator).

`GET /ai/cases/{id}`

Escopo agents:read

Query customer_id. Caso com title, summary, blocker, assigned_user_id, conversation_id, contact_id e a última decisão humana.

`PATCH /ai/cases/{id}`

Escopo agents:write · chave criada por um Administrador

Campo	Tipo e limites	Uso
`expected_revision`	inteiro	Revisão do caso.
`status`	open \| waiting \| resolved \| closed	Opcional.
`assigned_user_id`	UUID ou null	Responsável da equipe.
`message`	1–10.000	Nota no caso.
`resume_agent`	boolean	Devolve a conversa ao agente.

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "expected_revision": 4,
  "status": "resolved",
  "message": "Coleta agendada para sexta.",
  "resume_agent": true
}

`POST /ai/cases/{id}/reply`

Escopo agents:write · chave criada por um Administrador

Registra a decisão da equipe. action: resolved ou need_lead_info retomam o agente para repassar a solução ou a pergunta ao contato (no modo assistido, o envio aguarda aprovação); escalate mantém o atendimento humano. body de 1 a 4.000 caracteres.

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "expected_revision": 3,
  "operation_key": "66666666-6666-4666-8666-666666666666",
  "action": "need_lead_info",
  "body": "Peça o número do pedido e uma foto da etiqueta."
}

Retorna {case_id, revision, status, service_stale, queued, queue_reason, run_id}. Registrar a decisão não confirma o envio: confira queued e queue_reason.

`POST /ai/cases/{id}/chat`

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, operation_key, question} (question de 3 a 1.000). Consulta interna sobre o caso, com a sua chave, sem ferramentas e sem envio ao contato. Retorna o turno com reply, status, persona (o agente do caso ou, se indisponível, o assistente neutro com o provedor padrão do Cliente) e consumo. Repita a mesma operation_key para consultar uma tentativa incerta.

`GET /ai/cases/{id}/chat`

Escopo agents:read

Query customer_id, page, per_page. Histórico da consulta interna.

`GET /ai/cases/{id}/events`

Escopo agents:read

Query customer_id, page, per_page. Linha do tempo do caso, da mais antiga para a mais nova, com kind, label e autor.

`GET /ai/cases/{id}/messages`

Escopo agents:read

Query customer_id, page, per_page. Mensagens trocadas no caso.

Alertas

`GET /ai/alerts`

Escopo agents:read

Query customer_id, page, per_page e filtros status (open, acknowledged, resolved), kind e severity (info, warning, critical). Cada alerta traz kind_label, guidance e links para o caso, a conversa ou o agente.

`PATCH /ai/alerts/{id}`

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision, status} com revisão numérica e open, acknowledged ou resolved.

`POST /ai/alerts/resolve`

Escopo agents:write · chave criada por um Administrador

Resolve em lote só o que existia até created_before (ISO com fuso), com filtros opcionais {kind, severity, status: open|acknowledged}. Alertas criados depois ficam abertos. Retorna {resolved_count, remaining}.

Avisos no WhatsApp

Avisa uma pessoa da equipe, por template Utility aprovado, quando um caso é aberto. Salvar não envia mensagem.

`GET /ai/notices`

Escopo agents:read

Query customer_id. {enabled, contact_id, template_id, variable_map, revision, consent_confirmed_at, updated_at}.

`PATCH /ai/notices`

Escopo agents:write · chave criada por um Administrador

Campo	Tipo e limites	Uso
`enabled`	boolean	Liga os avisos. Exige consent_confirmed.
`contact_id · template_id`	UUID ou null	Destinatário e template (veja options).
`variable_map`	{"body:1": campo}	Chaves body:N, header:N ou button:N; valores abaixo.
`consent_confirmed`	boolean	Confirma que o destinatário autorizou receber.
`expected_revision`	inteiro ≥ 0	Revisão atual.

Campos: case_title (Título do caso), case_summary (Resumo do caso), case_url (Link do caso no BotoZap), contact_name (Nome do contato atendido), agent_name (Nome do agente).

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "enabled": true,
  "contact_id": "88888888-8888-4888-8888-888888888888",
  "template_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "variable_map": {
    "body:1": "case_title",
    "body:2": "case_url"
  },
  "consent_confirmed": true,
  "expected_revision": 0
}

`GET /ai/notices/options`

Escopo agents:read

Query customer_id. {contacts, templates, channels} elegíveis.

`GET /ai/notices/diagnostics`

Escopo agents:read

Query customer_id. Lista de verificações {id, status: ok|warning|error, message}.

`GET /ai/notices/effect`

Escopo agents:read

Query customer_id e days (1–90, padrão 30). Compara casos com e sem aviso: quantidade, respondidos e mediana de minutos.

`GET /ai/notices/jobs`

Escopo agents:read

Query customer_id, page, per_page. Envios com status (pending, claimed, sent, failed, unknown, cancelled), last_error e destino mascarado.

`POST /ai/notices/jobs/{id}/retry`

Escopo agents:write

Corpo {customer_id}. Recoloca um envio falho na fila; retorna {queued: true}. Envios com resultado incerto não são repetidos automaticamente.

`POST /ai/notices/test`

Escopo agents:write

Corpo {customer_id, operation_key, confirm_send: true}. Envia uma mensagem real ao destinatário configurado. Retorna {id} do envio.

Propostas de aprendizado

O aprendizado analisa execuções e propõe um item de instrução (playbook_bullet) ou uma memória (memory_entry). Nada é aplicado sem decisão.

`GET /ai/proposals`

Escopo agents:read

Query customer_id, status (pending, applied, rejected), agent_id, page, per_page. Cada proposta traz content, reason, evidence e revision.

`PATCH /ai/proposals/{id}`

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, expected_revision, decision: "apply" | "reject", reason?}. Aplicar uma instrução publica uma versão nova do agente e é recusado se houver rascunho em edição (409 draft_exists) ou se a versão base mudou (409 base_version_changed). Aplicar uma memória a aprova.

`POST /ai/proposals/analyze`

Escopo agents:write

Corpo {customer_id, agent_id, limit} (limit 1–100, padrão 20 execuções). Enfileira a análise e responde 202 com {queued}.

`GET /ai/proposals/settings`

Escopo agents:read

Query customer_id. {enabled, revision}.

`PATCH /ai/proposals/settings`

Escopo agents:write

Corpo {customer_id, enabled, expected_revision} com revisão numérica (0 antes da primeira gravação).

Métricas, promessas e evolução

`GET /ai/operator-metrics`

Escopo agents:read

Query customer_id, days (1–90, padrão 30) e agent_id opcional. Por agente: turnos, promessas, quem assumiu cada uma (agente, operador, pessoa), correções e ownership_rate.

`GET /ai/promises`

Escopo agents:read

Query customer_id, agent_id, status (pending, owned, unowned, dismissed) e limit (1–100, padrão 50). Promessas declaradas pelo agente no fechamento do turno (accountability.enabled). Somente leitura: correções são feitas no painel. Não confunda com os retornos avulsos.

`GET /ai/evolution`

Escopo agents:read

Query customer_id, days (7, 30 ou 90; padrão 30) e agent_id opcional. Retorna sources com learning, knowledge, skills, routing e crm, cada uma com status próprio (ok ou error). Uma fonte com erro não é zero.

Ajustes de estilo

Correções determinísticas aplicadas ao texto antes do envio. Lista fechada, desligada por padrão:

adjustment	Efeito
`sem_travessao_longo`	Sem travessão longo: Troca o travessão longo (—) por vírgula. No início ou no fim de uma linha ele é removido, sem deixar vírgula solta nem pontuação dupla. Quebras de linha são preservadas.

`GET /ai/style-adjustments`

Escopo agents:read

Query customer_id. {adjustments: [{adjustment, enabled, revision, updated_at, updated_by, updated_by_api_key}]}.

`PUT /ai/style-adjustments`

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id, adjustment, enabled, expected_revision}, com revisão string ("0" para um ajuste nunca gravado).

Controle da conversa

`POST /conversations/{id}/agent-control`

Escopo agents:write

Corpo {"action": "pause"} ou {"action": "resume"}, sem customer_id. Pausa ou devolve a conversa ao agente. Retorna {conversation_id, paused}. ID malformado ou de outra Conta: 404 not_found. Em canal atendido por roteador, o controle vale para o agente que o roteador escolheu para a conversa (ou o fallback, antes de haver roteamento); conversa sem agente responsável não muda nada.

Envios do agente com resultado incerto são conciliados no painel. Pela API, a conciliação existe para efeitos de follow-up e templates de retorno avulso, em Follow-ups e retornos.

Status	Código	Quando
403	`forbidden`	Decisão com chave que não foi criada por um Administrador.
404	`not_found`	Execução, caso ou alerta fora do Cliente (em execuções, confira também agent_id).
409	`revision_conflict`	Revisão do caso, alerta, proposta ou configuração desatualizada.
409	`case_not_open · case_not_waiting · case_stale`	Transição de caso inválida para o estado atual.
409	`dispatch_busy`	Envio em andamento ou incerto.
409	`draft_exists · base_version_changed`	Aplicar instrução com rascunho aberto ou versão base alterada.
422	`invalid`	Corpo fora do contrato, inclusive confirm_send ausente.
429	`rate_limited`	Consultas internas de caso acima do limite.

Visão geral do Agente de IA · Próxima: Propostas comerciais