Ferramentas de agente (Tools)

CRUD completo para as ferramentas de um agente específico. É um recurso aninhado: toda rota parte de /api/v1/agents/{agent}/tools.

Endpoints

Método	Rota	Descrição
GET	/api/v1/agents/{agent}/tools	Lista as ferramentas do agente
POST	/api/v1/agents/{agent}/tools	Cria uma ferramenta no agente
GET	/api/v1/agents/{agent}/tools/{tool}	Exibe uma ferramenta
PUT/PATCH	/api/v1/agents/{agent}/tools/{tool}	Atualiza uma ferramenta
DELETE	/api/v1/agents/{agent}/tools/{tool}	Remove uma ferramenta

{agent} é o ID do agente dono das ferramentas; {tool} só é encontrado se pertencer a esse mesmo agente (caso contrário, 404).

Filtros de listagem

search (por nome), type, is_active.

Campos

Campo	Tipo	Obrigatório	Descrição
name	string, max 255	Sim	Nome da ferramenta.
description	string	Não	Descrição livre.
type	string	Sim	search, mcp, api_rest, database, context_action, first_message, clarification_rule, transfer_call, transfer_to_agent ou schedule_event.
is_active	boolean	Não	Padrão: conforme cadastro.
config	array	Depende do tipo	Configuração específica do tipo (veja abaixo).

agent_id nunca é aceito no corpo da requisição — a ferramenta é sempre vinculada ao agente da própria URL.

config por tipo

Tipo	Campos em config
search	engine (obrigatório: google, bing ou duckduckgo), api_key, max_results (inteiro ≥ 1).
mcp	server_url (obrigatório, URL), server_name, auth_token.
api_rest	endpoint_url (obrigatório, URL), method (GET, POST, PUT, PATCH ou DELETE), auth_type (none, bearer, basic ou api_key), auth_token (obrigatório se auth_type ≠ none), headers (objeto chave/valor).
database	driver (mysql, pgsql ou sqlsrv), host, port (1–65535), database, username, password, query — todos obrigatórios juntos quando o tipo é database.
context_action	context (obrigatório), webhook_url (obrigatório, URL), variables (obrigatório, array de {label, key, type, options, required} — veja Ação de contexto).
first_message	message — texto usado para abrir a ligação. Veja Primeira Mensagem.
clarification_rule	prompt — texto anexado às instruções do agente. Veja Indagação e Esclarecimento.
transfer_call, transfer_to_agent, schedule_event	Nenhum — são as ferramentas automáticas e não têm campos de configuração.

Em atualizações parciais (PATCH), se você não enviar config, os campos obrigatórios daquele tipo não são exigidos novamente — só são validados quando config está presente na requisição.

aviso

Ferramentas automáticas não são protegidas pela API

Todo agente novo já nasce com cinco ferramentas automáticas: as três sem configuração (transfer_call, transfer_to_agent, schedule_event) e mais first_message/clarification_rule (que têm um texto padrão editável). Esta API não impede que qualquer uma delas seja renomeada, desativada, tenha o type alterado ou seja excluída via DELETE — não existe verificação server-side contra isso. Além disso, message e prompt (de first_message/clarification_rule) não têm validação própria nesta API — diferente do que acontece no painel administrativo, onde são campos obrigatórios. Evite automatizar exclusões em massa das ferramentas de um agente sem antes filtrar por type.

Mascaramento de dados sensíveis

Os seguintes campos de config, quando presentes, nunca são retornados em texto puro — vêm mascarados com asteriscos do mesmo tamanho do valor original: api_key, auth_token e password.

Exemplo de resposta

{
  "id": 45,
  "agent_id": 12,
  "type": "api_rest",
  "name": "Consultar pedido",
  "description": "Consulta o status de um pedido pelo número",
  "is_active": true,
  "config": {
    "endpoint_url": "https://meusistema.com/api/pedidos",
    "method": "GET",
    "auth_type": "bearer",
    "auth_token": "************",
    "headers": { "X-Origem": "rouxinol" }
  },
  "created_at": "2026-08-01T12:00:00Z",
  "updated_at": "2026-08-01T12:00:00Z"
}

Exemplos com curl

Listar ferramentas de um agente

curl "$ROUXINOL_URL/api/v1/agents/12/tools?type=api_rest" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN"

Criar uma ferramenta de busca (search)

curl -X POST "$ROUXINOL_URL/api/v1/agents/12/tools" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Buscar na web",
        "type": "search",
        "config": { "engine": "google", "api_key": "SUA_CHAVE", "max_results": 5 }
      }'

Criar uma ferramenta de API REST

curl -X POST "$ROUXINOL_URL/api/v1/agents/12/tools" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Consultar pedido",
        "type": "api_rest",
        "config": {
          "endpoint_url": "https://meusistema.com/api/pedidos",
          "method": "GET",
          "auth_type": "bearer",
          "auth_token": "SEU_TOKEN"
        }
      }'

Criar uma ferramenta de banco de dados

curl -X POST "$ROUXINOL_URL/api/v1/agents/12/tools" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Consultar catálogo",
        "type": "database",
        "config": {
          "driver": "mysql",
          "host": "db.meusistema.com",
          "port": 3306,
          "database": "loja",
          "username": "rouxinol",
          "password": "senha-secreta",
          "query": "SELECT nome, preco FROM produtos WHERE ativo = 1 LIMIT 50"
        }
      }'

Criar uma ferramenta de ação de contexto

curl -X POST "$ROUXINOL_URL/api/v1/agents/12/tools" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Alertar sobre concorrente",
        "type": "context_action",
        "config": {
          "context": "Quando o cliente mencionar um concorrente",
          "webhook_url": "https://meusistema.com/webhooks/concorrente",
          "variables": [
            { "label": "Concorrente citado", "key": "concorrente", "type": "text", "required": true }
          ]
        }
      }'

Criar uma ferramenta MCP

curl -X POST "$ROUXINOL_URL/api/v1/agents/12/tools" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Servidor MCP interno",
        "type": "mcp",
        "config": { "server_name": "Interno", "server_url": "https://mcp.meusistema.com", "auth_token": "SEU_TOKEN" }
      }'

Exibir uma ferramenta

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

Atualizar uma ferramenta (atualização parcial, sem reenviar todo o config)

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

Remover uma ferramenta

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