Tools

Crie e gerencie ferramentas customizadas que seus agentes podem usar durante conversas.

Listar Tools

GET

/api/tools

Retorna todas as ferramentas do usuário

Response

[
  {
    "id": "clxyz...",
    "name": "Consultar CEP",
    "description": "Busca endereço por CEP",
    "type": "api_request",
    "method": "GET",
    "requestUrl": "https://viacep.com.br/ws/{cep}/json/",
    "isActive": true,
    "createdAt": "2026-03-01T00:00:00Z"
  }
]

Obter Tool

GET

/api/tools/:id

Retorna uma ferramenta específica

Criar Tool

POST

/api/tools

Cria uma nova ferramenta

Parameter	Type	Required	Description
`name`	string	Required	Nome da ferramenta
`description`	string	Optional	Descrição para o agente entender quando usar
`type`	string	Required	Tipo (ver tabela abaixo)
`method`	string	Optional	Método HTTP (para api_request)
`requestUrl`	string	Optional	URL da API externa
`parameters`	object	Optional	JSON Schema dos parâmetros a coletar
`headers`	object	Optional	Headers HTTP da requisição
`authorization`	object	Optional	Config de auth: { type, ... }
`body`	object	Optional	Template do body da requisição
`messages`	object	Optional	Mensagens: { start, complete, failed, delayed }

Request — Tool API Request

curl -X POST https://api.vendoria.com.br/api/tools \
  -H "X-Api-Key: vk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consultar CEP",
    "description": "Busca endereço pelo CEP",
    "type": "api_request",
    "method": "GET",
    "requestUrl": "https://viacep.com.br/ws/{cep}/json/",
    "parameters": {
      "type": "object",
      "properties": {
        "cep": { "type": "string", "description": "CEP" }
      },
      "required": ["cep"]
    }
  }'

Tipos de Tools

Tipo	Descrição
`custom`	Ferramenta customizada genérica
`api_request`	Chamada a API REST externa
`dtmf`	Envio de tons DTMF
`end_call`	Encerrar a chamada
`transfer_call`	Transferir para outro número/agente
`send_text`	Enviar SMS ou WhatsApp
`query`	Consulta a knowledge base
`google_calendar`	Integração Google Calendar
`google_sheets`	Integração Google Sheets
`slack`	Integração Slack
`mcp`	Model Context Protocol

Atualizar Tool

PATCH

/api/tools/:id

Atualiza uma ferramenta

Deletar Tool

DELETE

/api/tools/:id

Remove uma ferramenta

Vincular / Desvincular de Agente

POST

/api/tools/:id/agents/:agentId

Associa ferramenta a um agente

DELETE

/api/tools/:id/agents/:agentId

Remove associação

Tip

Uma mesma ferramenta pode ser vinculada a múltiplos agentes para reutilizar integrações.