Skip to main content
POST
/
user
/
tools
Criar ferramenta utilizadas durante a chamada
curl --request POST \
  --url https://suasofia.online/api/user/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "endpoint": "<string>",
  "method": "<string>",
  "timeout": 123,
  "headers": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "schema": [
    {
      "name": "<string>",
      "type": "<string>",
      "description": "<string>"
    }
  ]
}
'
{
  "message": "Ferramenta criada com sucesso",
  "data": {
    "id": 1,
    "name": "check_order_status",
    "description": "Use esta ferramenta para verificar o status do pedido de um cliente.",
    "endpoint": "https://api.sualoja.com/orders/status",
    "method": "GET",
    "timeout": 10,
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      },
      {
        "name": "Authorization",
        "value": "Bearer sk_..."
      }
    ],
    "schema": [
      {
        "name": "order_id",
        "type": "string",
        "description": "O ID do pedido do cliente"
      },
      {
        "name": "order_number",
        "type": "number",
        "description": "O número numérico do pedido"
      },
      {
        "name": "priority_order",
        "type": "boolean",
        "description": "Se este é um pedido prioritário"
      }
    ],
    "created_at": "2025-10-10T12:00:00.000000Z",
    "updated_at": "2025-10-10T12:00:00.000000Z"
  }
}
Este endpoint permite que você crie uma nova ferramenta utilizadas durante a chamada que pode ser usada por seus assistentes de IA para interagir com APIs externas durante as chamadas.

​
Parâmetros do Corpo

​
name
string
required
Nome da ferramenta - deve conter apenas letras minúsculas e sublinhados, e começar com uma letra (ex: get_weather, book_appointment)
​
description
string
required
Explicação detalhada de quando e como a IA deve usar esta ferramenta (máx. 255 caracteres)
​
endpoint
string
required
URL válida do endpoint da API a ser chamado
​
method
string
required
Método HTTP: GET, POST, PUT, PATCH, ou DELETE
​
timeout
integer
Timeout da solicitação em segundos (1-30, padrão: 10)
​
headers
array
Cabeçalhos HTTP para enviar com a solicitação
​
schema
array
Parâmetros que a IA extrairá da conversa e enviará para o endpoint

​
Campos de resposta

​
message
string
Mensagem de sucesso
​
data
object
O objeto da ferramenta criada
{
  "message": "Ferramenta criada com sucesso",
  "data": {
    "id": 1,
    "name": "check_order_status",
    "description": "Use esta ferramenta para verificar o status do pedido de um cliente.",
    "endpoint": "https://api.sualoja.com/orders/status",
    "method": "GET",
    "timeout": 10,
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      },
      {
        "name": "Authorization",
        "value": "Bearer sk_..."
      }
    ],
    "schema": [
      {
        "name": "order_id",
        "type": "string",
        "description": "O ID do pedido do cliente"
      },
      {
        "name": "order_number",
        "type": "number",
        "description": "O número numérico do pedido"
      },
      {
        "name": "priority_order",
        "type": "boolean",
        "description": "Se este é um pedido prioritário"
      }
    ],
    "created_at": "2025-10-10T12:00:00.000000Z",
    "updated_at": "2025-10-10T12:00:00.000000Z"
  }
}

​
Anexando Ferramentas a Assistentes

Após criar uma ferramenta, você precisa anexá-la a um assistente para usá-la durante as chamadas. As ferramentas são gerenciadas através da API de Assistente:
  • Criar Assistente - Use o parâmetro tool_ids para anexar ferramentas ao criar um assistente
  • Atualizar Assistente - Use o parâmetro tool_ids para adicionar, remover ou substituir ferramentas em um assistente existente