Agentes

CRUD completo para os agentes de IA da conta.

Endpoints

Método	Rota	Descrição
GET	/api/v1/agents	Lista agentes
POST	/api/v1/agents	Cria um agente
GET	/api/v1/agents/{agent}	Exibe um agente
PUT/PATCH	/api/v1/agents/{agent}	Atualiza um agente
DELETE	/api/v1/agents/{agent}	Remove um agente

Filtros de listagem

search (por nome), is_active, ai_connection_id.

Campos

Campo	Tipo	Obrigatório	Descrição
name	string, max 255	Sim	Nome do agente.
description	string	Não	Resumo do propósito do agente.
instructions	string	Sim	Prompt do sistema — define o comportamento do agente.
ai_connection_id	integer	Sim	ID de uma conexão de IA ativa da mesma conta.
voice	string	Sim	Uma das vozes disponíveis: marin, cedar, alloy, ash, ballad, coral, echo, sage, shimmer, verse.
is_active	boolean	Não	Padrão: conforme cadastro.
avatar	string, max 255	Não	Caminho/URL do avatar.

Exemplo de resposta

{
  "id": 12,
  "name": "Atendimento Comercial",
  "description": "Agente responsável por triagem e agendamentos",
  "instructions": "Você é um assistente...",
  "ai_connection_id": 3,
  "voice": "marin",
  "avatar": null,
  "is_active": true,
  "created_at": "2026-08-01T12:00:00Z",
  "updated_at": "2026-08-01T12:00:00Z"
}

note

As ferramentas (tools) de um agente têm sua própria API — veja Ferramentas de agente.

Exemplos com curl

Listar agentes

curl "$ROUXINOL_URL/api/v1/agents?is_active=true" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN"

Criar um agente

curl -X POST "$ROUXINOL_URL/api/v1/agents" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Atendimento Comercial",
        "description": "Agente responsável por triagem e agendamentos",
        "instructions": "Você é um assistente comercial simpático e objetivo.",
        "ai_connection_id": 3,
        "voice": "marin",
        "is_active": true
      }'

Exibir um agente

curl "$ROUXINOL_URL/api/v1/agents/12" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN"

Atualizar um agente

curl -X PATCH "$ROUXINOL_URL/api/v1/agents/12" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "voice": "cedar" }'

Remover um agente

curl -X DELETE "$ROUXINOL_URL/api/v1/agents/12" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN"