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, 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).
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.

:::warning Ferramentas automáticas não são protegidas pela API Todo agente novo já nasce com as três ferramentas automáticas (transfer_call, transfer_to_agent, schedule_event). Esta API não impede que elas sejam renomeadas, desativadas, tenham o type alterado ou sejam excluídas via DELETE — não existe verificação server-side contra isso. 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"