Criar ferramenta de uso durante a chamada
curl --request POST \
--url https://api.example.com/user/tools \
--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>"
}
]
}
'import requests
url = "https://api.example.com/user/tools"
payload = {
"name": "<string>",
"description": "<string>",
"endpoint": "<string>",
"method": "<string>",
"timeout": 123,
"headers": [
{
"name": "<string>",
"value": "<string>"
}
],
"schema": [
{
"name": "<string>",
"type": "<string>",
"description": "<string>"
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
endpoint: '<string>',
method: '<string>',
timeout: 123,
headers: [{name: '<string>', value: '<string>'}],
schema: [{name: '<string>', type: '<string>', description: '<string>'}]
})
};
fetch('https://api.example.com/user/tools', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/user/tools",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'endpoint' => '<string>',
'method' => '<string>',
'timeout' => 123,
'headers' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'schema' => [
[
'name' => '<string>',
'type' => '<string>',
'description' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/user/tools"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/user/tools")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/user/tools")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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": "ID do pedido do cliente"
},
{
"name": "order_number",
"type": "number",
"description": "Número do pedido (numérico)"
},
{
"name": "priority_order",
"type": "boolean",
"description": "Indica se este é um pedido prioritário"
}
],
"created_at": "2025-10-10T12:00:00.000000Z",
"updated_at": "2025-10-10T12:00:00.000000Z"
}
}
{
"message": "O campo name deve conter apenas letras minúsculas e underscores, e começar com uma letra.",
"errors": {
"name": [
"O nome da ferramenta deve conter apenas letras minúsculas e underscores, e começar com uma letra."
]
}
}
{
"message": "Você atingiu o limite do seu plano de 5 ferramentas de uso durante a chamada. Faça upgrade do seu plano para criar mais ferramentas."
}
Mid Call Tools
Criar ferramenta de uso durante a chamada
Cria uma nova ferramenta personalizada de uso durante a chamada, definindo nome, descrição, parâmetros e endpoint que será chamado pelo assistente.
POST
/
user
/
tools
Criar ferramenta de uso durante a chamada
curl --request POST \
--url https://api.example.com/user/tools \
--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>"
}
]
}
'import requests
url = "https://api.example.com/user/tools"
payload = {
"name": "<string>",
"description": "<string>",
"endpoint": "<string>",
"method": "<string>",
"timeout": 123,
"headers": [
{
"name": "<string>",
"value": "<string>"
}
],
"schema": [
{
"name": "<string>",
"type": "<string>",
"description": "<string>"
}
]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
endpoint: '<string>',
method: '<string>',
timeout: 123,
headers: [{name: '<string>', value: '<string>'}],
schema: [{name: '<string>', type: '<string>', description: '<string>'}]
})
};
fetch('https://api.example.com/user/tools', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/user/tools",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'endpoint' => '<string>',
'method' => '<string>',
'timeout' => 123,
'headers' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'schema' => [
[
'name' => '<string>',
'type' => '<string>',
'description' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/user/tools"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/user/tools")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/user/tools")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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": "ID do pedido do cliente"
},
{
"name": "order_number",
"type": "number",
"description": "Número do pedido (numérico)"
},
{
"name": "priority_order",
"type": "boolean",
"description": "Indica se este é um pedido prioritário"
}
],
"created_at": "2025-10-10T12:00:00.000000Z",
"updated_at": "2025-10-10T12:00:00.000000Z"
}
}
{
"message": "O campo name deve conter apenas letras minúsculas e underscores, e começar com uma letra.",
"errors": {
"name": [
"O nome da ferramenta deve conter apenas letras minúsculas e underscores, e começar com uma letra."
]
}
}
{
"message": "Você atingiu o limite do seu plano de 5 ferramentas de uso durante a chamada. Faça upgrade do seu plano para criar mais ferramentas."
}
Este endpoint permite criar uma nova ferramenta de uso durante a chamada que pode ser utilizada pelos seus assistentes de IA para interagir com APIs externas durante as ligações.
Anexando Ferramentas aos Assistentes
Após criar uma ferramenta, você precisa anexá-la a um assistente para utilizá-la durante as chamadas. As ferramentas são gerenciadas pela API de Assistentes:
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
Parâmetros do Corpo
Nome da ferramenta - deve conter apenas letras minúsculas e underscores, e começar com uma letra (ex.:
get_weather, book_appointment)Explicação detalhada de quando e como a IA deve utilizar esta ferramenta (máximo de 255 caracteres)
URL válida do endpoint de API a ser chamado
Método HTTP:
GET, POST, PUT, PATCH ou DELETETimeout da requisição em segundos (1-30, padrão: 10)
Parâmetros que a IA irá extrair da conversa e enviar para o endpoint
Show propriedades de schema
Show propriedades de schema
Campos da Resposta
Mensagem de sucesso
Objeto da ferramenta criada
Show propriedades de data
Show propriedades de data
Identificador único da ferramenta
Nome da ferramenta
Descrição da ferramenta
URL do endpoint da API
Método HTTP
Timeout da requisição em segundos
Headers HTTP
Esquema de parâmetros
Timestamp ISO 8601
Timestamp ISO 8601
{
"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": "ID do pedido do cliente"
},
{
"name": "order_number",
"type": "number",
"description": "Número do pedido (numérico)"
},
{
"name": "priority_order",
"type": "boolean",
"description": "Indica se este é um pedido prioritário"
}
],
"created_at": "2025-10-10T12:00:00.000000Z",
"updated_at": "2025-10-10T12:00:00.000000Z"
}
}
{
"message": "O campo name deve conter apenas letras minúsculas e underscores, e começar com uma letra.",
"errors": {
"name": [
"O nome da ferramenta deve conter apenas letras minúsculas e underscores, e começar com uma letra."
]
}
}
{
"message": "Você atingiu o limite do seu plano de 5 ferramentas de uso durante a chamada. Faça upgrade do seu plano para criar mais ferramentas."
}
⌘I