Agentes e versões

Ciclo de vida

1. POST /ai/agents cria o agente e o primeiro rascunho. Ele não atende até ser ativado.
2. PUT /ai/agents/{id} altera o rascunho, sempre com a revisão lida. Sem rascunho, o PUT cria um a partir do corpo enviado.
3. POST /ai/agents/{id}/preview testa uma versão sem efeitos.
4. POST /ai/agents/{id}/publish diagnostica e publica o rascunho. A versão fica imutável e o agente passa a apontar para ela. Publicar incrementa operation_revision mas não ativa o agente.
5. POST /ai/agents/{id}/operation ativa ou pausa e escolhe o modo. Antes, libere o canal em Acesso e elegibilidade.

Há duas revisões diferentes, ambas strings decimais:

• versions[].revision: do rascunho. Vai em expected_revision no PUT e no publish, e em expected_draft_revision no restore.
• agent.operation_revision: da operação. Vai em expected_revision em operation e archive, e em expected_agent_revision ao ativar um membro de roteador.

Estado e atendimento

GET /ai/agents e GET /ai/agents/{id} trazem, em cada agente, o estado real além de paused e archived. Use serving para saber se o agente está respondendo:

Valores de lifecycle:

• draft: Nenhuma versão publicada. Não atende.
• published: Versão publicada, operação ainda não ativada. Não atende.
• active: Operação ativada. Atende se serving for true.
• paused: Tem versão publicada, mas a operação está pausada. Não atende.
• archived: Histórico preservado. Não atende.

serving só é true com lifecycle: active, credencial ativa e validada do provedor da versão, canal não revogado e fora do sandbox, e posse do canal: o vínculo do agente quando não há roteador ativo, ou a participação no roteador ativo do canal. Um agente active pode ter serving: false, por exemplo com a credencial desativada ou com um roteador ativo do qual não participa. No modo assisted, as respostas aguardam aprovação. serving não considera os contatos liberados: quem recebe resposta ainda depende da elegibilidade do canal.

Rotas

GET /ai/agents

Escopo agents:read

Query customer_id, page, per_page. Lista paginada de agentes, ordenada por nome, cada um no formato de agent abaixo, com lifecycle e serving.

POST /ai/agents

Escopo agents:write

Este exemplo é validado em teste contra o schema da rota:

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "name": "Atendimento",
  "description": "Atendimento e acompanhamento da equipe",
  "config": {
    "system_prompt": "Atenda usando os materiais autorizados e encaminhe à equipe quando precisar de uma decisão humana.",
    "provider": "openai",
    "model": "MODELO_VALIDADO_NA_CREDENCIAL",
    "credential_id": "22222222-2222-4222-8222-222222222222",
    "channel_account_id": "33333333-3333-4333-8333-333333333333",
    "tool_ids": [
      "conversations.read",
      "conversations.note",
      "knowledge.search",
      "cases.open",
      "handoff"
    ],
    "knowledge_source_ids": [
      "77777777-7777-4777-8777-777777777777"
    ],
    "skill_ids": [],
    "cases_enabled": true,
    "handoff_enabled": true
  }
}

Responde 201 com {agent_id, version_id, revision}.

GET /ai/agents/{id}

Escopo agents:read

Query customer_id. Retorna o agente e todas as versões, cada uma com o config completo.

{
  "agent": {
    "id": "44444444-4444-4444-8444-444444444444",
    "customer_id": "11111111-1111-4111-8111-111111111111",
    "name": "Atendimento",
    "description": "Atendimento e acompanhamento da equipe",
    "operation_mode": "automatic",
    "operation_revision": "4",
    "paused": false,
    "archived": false,
    "published_version_id": "55555555-5555-4555-8555-555555555555",
    "updated_at": "2026-09-25T13:00:00.000Z",
    "lifecycle": "active",
    "serving": true,
    "serving_via": "direct",
    "channel_account_id": "33333333-3333-4333-8333-333333333333"
  },
  "versions": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "agent_id": "44444444-4444-4444-8444-444444444444",
      "number": 2,
      "revision": "3",
      "status": "published",
      "config": "{ ... }",
      "created_at": "2026-09-24T18:00:00.000Z",
      "published_at": "2026-09-25T12:58:00.000Z",
      "created_by": null
    }
  ]
}

PUT /ai/agents/{id}

Escopo agents:write

Mesmo corpo da criação mais expected_revision. Com rascunho existente, a revisão é obrigatória e precisa ser a atual. Sem rascunho, omita-a: um novo rascunho é criado. Retorna {agent_id, version_id, revision}. O config enviado substitui o anterior inteiro; campos omitidos voltam ao padrão.

POST /ai/agents/{id}/preview

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "version_id": "55555555-5555-4555-8555-555555555555",
  "operation_key": "66666666-6666-4666-8666-666666666666",
  "messages": [
    {
      "role": "user",
      "content": "Qual o prazo de entrega para Manaus?"
    }
  ]
}

Retorna uma execução, no mesmo formato de Execuções. Usa o provedor real e consome a sua chave. Só conhecimento, memória e skills são consultados de verdade; as demais ferramentas, inclusive leituras, devolvem uma simulação. Nada é enviado ao contato. Com o operador ligado, operator_execution traz a revisão dele.

POST /ai/agents/{id}/publish

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "version_id": "55555555-5555-4555-8555-555555555555",
  "expected_revision": "3"
}

Retorna {version_id, number}. Antes de publicar, o servidor roda no rascunho o mesmo diagnóstico do painel. Se alguma verificação bloquear, a publicação é recusada com 422 diagnostic_blocked e error.blockers, a lista de pendências. Veja os requisitos de publicação.

{
  "error": {
    "code": "diagnostic_blocked",
    "message": "O diagnóstico do rascunho tem verificações que impedem a publicação. Resolva as pendências e publique de novo. Pendências: Elegibilidade para atender.",
    "blockers": [
      {
        "id": "eligibility",
        "title": "Elegibilidade para atender",
        "status": "blocked",
        "detail": "Somente números de teste, e nenhum número de teste foi cadastrado em Loja Centro: a IA não responde a ninguém. Cadastre um número de teste ou abra o canal em Acesso da IA."
      }
    ]
  }
}

POST /ai/agents/{id}/restore

Escopo agents:write

Corpo {customer_id, version_id, expected_draft_revision?}. Copia o config de uma versão para o rascunho. Se já existir rascunho, informe a revisão dele. Não publica nem ativa.

POST /ai/agents/{id}/duplicate

Escopo agents:write

Corpo {customer_id, name}. Cria outro agente com o rascunho (ou a versão publicada) copiado, sem canal e inativo. Retorna {agent_id, version_id, revision}.

POST /ai/agents/{id}/archive

Escopo agents:write

Corpo {customer_id, expected_revision, archived}, com operation_revision. Arquivar pausa o agente, libera o canal e preserva o histórico. Desarquivar não reativa. Retorna {id, revision, archived}.

POST /ai/agents/{id}/operation

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "expected_revision": "2",
  "mode": "assisted",
  "paused": false
}

Retorna {revision, paused, mode}. Ativar exige versão publicada, credencial ativa e válida e canal livre: outro agente vinculado ou roteador ativo no canal retorna 409 duplicate_responder. Ativar vincula o agente ao canal da versão publicada. Pausar mantém o vínculo; arquivar o libera.

O campo paused sozinho não diz se o agente atende: um agente recém-criado ou só publicado tem paused: false e ainda não foi ativado. Leia lifecycle e serving em GET /ai/agents.

GET /ai/agents/{id}/capability-usage

Escopo agents:read

Query customer_id e days (1–90, padrão 30). Compara o uso real de cada ferramenta com a versão publicada (ou o rascunho, se nada foi publicado): agent e operator com summary e items (tool, enabled, signal, recommendation, total, failures, unknown, test, last_at). Falha de leitura é 503, nunca zero.

Requisitos de publicação

A publicação pelo painel e pela API segue a mesma regra: o rascunho é diagnosticado no servidor e qualquer verificação bloqueante recusa a publicação com diagnostic_blocked. Uma verificação que não pôde ser lida também bloqueia; ela nunca conta como aprovada. A prova de geração é opcional e não bloqueia. Bloqueiam:

• system_prompt com ao menos 10 caracteres e model preenchido.
• credential_id ativa, validada e do mesmo provider. Com operador próprio, a credencial dele também.
• channel_account_id de um canal WhatsApp do Cliente.
• allowed_stage_ids, knowledge_source_ids e skill_ids existentes e ativos no Cliente; fluxos de followup.flow_ids publicados, com janela de envio compatível.
• Ferramentas que só consultam outros contatos (contacts.search, radar.read, crm.search) exigem data_access.other_contacts: true.
• Chave validada pelo provedor, com o model no catálogo dela e compatível com atendimento. Com operador próprio, a credencial e o modelo dele também.
• Canal WhatsApp ativo, do Cliente e fora do sandbox.
• Canal elegível: conta fora de exclusão e canal que aceita IA. Com o canal em pre_go_live e nenhum número em test_phone_numbers, a IA não responderia a ninguém, então a publicação é recusada. Cadastre um número de teste ou mude o modo em Acesso e elegibilidade.

Avisos não bloqueiam: outro agente ou roteador ativo no canal, ferramentas sem efeito, regras da empresa ausentes e proteções desligadas.

Schema do config

O schema é estrito: chave desconhecida gera 422. Todo campo tem padrão. Estes são os valores aplicados a um config vazio:

{
  "system_prompt": "",
  "provider": "openai",
  "model": "",
  "credential_id": null,
  "channel_account_id": null,
  "tool_ids": [],
  "operator": {
    "enabled": false,
    "provider": null,
    "model": null,
    "credential_id": null,
    "tool_ids": []
  },
  "trigger": {
    "keywords": [],
    "match": "any",
    "ignore_groups": true,
    "ignore_self": true
  },
  "time_zone": "America/Sao_Paulo",
  "business_hours": null,
  "outside_hours": "respond",
  "max_steps": 10,
  "token_budget": 50000,
  "estimated_cost_limit_usd": null,
  "history_message_window": 20,
  "history_token_window": 8000,
  "handoff_keywords": [
    "falar com humano",
    "atendente",
    "pessoa real"
  ],
  "handoff_enabled": true,
  "cases_enabled": true,
  "split_messages": false,
  "split_max_chars": 600,
  "crm_scopes": [],
  "allowed_stage_ids": [],
  "knowledge_source_ids": [],
  "skill_ids": [],
  "platform_skills": "none",
  "memory_enabled": true,
  "data_access": {
    "other_contacts": false
  },
  "accountability": {
    "enabled": false,
    "classification": false
  },
  "media": {
    "images_enabled": true,
    "documents_enabled": true,
    "video_frames_enabled": false
  },
  "followup": {
    "enabled": false,
    "flow_ids": [],
    "send_window": null
  },
  "safety": {
    "disclose_ai": true,
    "prohibited_claims": [],
    "escalation_instructions": "",
    "additional_rules": [],
    "disclosure_text": "",
    "commercial_limits": {
      "min_price_brl": null,
      "max_discount_percent": null,
      "max_installments": null
    },
    "guard_sensitivity": "standard",
    "semantic_evaluator": false
  },
  "style": {
    "tone": "friendly",
    "verbosity": "balanced",
    "use_emojis": false,
    "instructions": ""
  }
}

safety

Catálogo de ferramentas

55 valores aceitos em tool_ids e operator.tool_ids. A lista vem do código. O servidor aplica as exigências a cada chamada; uma ferramenta fora delas é recusada no turno, sem efeito.

agenda.propose só conclui quando o contato responde com CONFIRMAR XXXXXXXX, usando o código devolvido pela Agenda; o agente não confirma por conta própria. handoff tira a IA da conversa até uma pessoa devolver pelo painel ou por POST /conversations/{id}/agent-control. Enquanto ninguém assume, a conversa aparece na caixa Atendimento humano da Inbox.

Visão geral do Agente de IA · Próxima: Acesso e elegibilidade