Agentes — API

Veja o guia conceitual em Agentes.

Registrar

POST /api/v1/agents admin

A IA cria automaticamente as solicitações de acesso para as ferramentas relevantes.

Requisição

{
  "name": "Assistente de Faturas",
  "description": "Assistente que responde dúvidas de clientes sobre faturas e histórico de pagamentos.",
  "owner_email": "operacoes@empresa.com",
  "review_period_days": 30
}

Resposta 201

{
  "agent": {
    "id": 3,
    "name": "Assistente de Faturas",
    "status": "pending_approval",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2026-05-20T10:00:00Z"
  },
  "access_requests": [
    {
      "id": 7,
      "tool_id": 5,
      "tool_name": "consultar_fatura",
      "reason": "O agente precisa consultar faturas para responder dúvidas de cobrança.",
      "status": "pending"
    }
  ]
}

Listar e obter

Endpoint	Papel	Descrição
GET /api/v1/agents	leitor	Lista os agentes.
GET /api/v1/agents/{id}	leitor	Detalha o agente e suas ferramentas aprovadas.
GET /api/v1/agents/{id}/access-requests	leitor	Solicitações de acesso do agente.

Atualizar e expor como ferramenta

PUT /api/v1/agents/{id} admin

Atualização parcial. Definir expose_as_tool: true registra o agente como ferramenta para outros agentes (multiagente).

Requisição

{ "expose_as_tool": true }

Ao ativar, a resposta inclui uma única vez o expose_secret (a credencial que outros agentes usam para chamá-lo). Ele não é recuperável depois.

Excluir

DELETE /api/v1/agents/{id} admin

Remove o agente e os dados relacionados. Resposta 204.

Conversar

POST /api/v1/agents/{id}/chat client_secret

Autentica com o client_secret (ou expose_secret), não com o token de usuário.

Requisição

{ "message": "Qual o status da fatura INV-2024-001?", "session_id": "opcional" }

Resposta 200

{
  "response": "A fatura INV-2024-001 está PAGA. Valor: R$ 1.250,00. Paga em 2026-04-15.",
  "tools_used": ["consultar_fatura"],
  "session_id": "a3f8c1d2-…"
}

Erros comuns

Código	Motivo
401	client_secret inválido ou ausente.
403	Agente suspenso ou pendente de aprovação.
403	Agente tentou chamar uma ferramenta não aprovada (bloqueado e auditado).
429	Limite de mensagens do mês atingido.