Create custom tool
curl --request POST \
--url https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-tools/ \
--header 'Content-Type: application/json' \
--data '
{
"openai_tool": {
"name": "<string>",
"description": "<string>",
"parameters": {
"properties": {},
"type": "object",
"required": [
"<string>"
],
"additionalProperties": false
}
},
"additional_tool_info": {
"api": {
"endpoint": "https://api.example.com/test",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"parameters": {
"fixed_params": {
"api_key": {
"description": "API key for authentication",
"value": "test-api-key"
}
},
"runtime_params": {}
}
},
"tool_type": "custom"
},
"tool_id": "<string>",
"tool_start_message": "<string>",
"tool_delayed_message": "<string>",
"tool_complete_message": "<string>",
"tool_failed_message": "<string>"
}
'import requests
url = "https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-tools/"
payload = {
"openai_tool": {
"name": "<string>",
"description": "<string>",
"parameters": {
"properties": {},
"type": "object",
"required": ["<string>"],
"additionalProperties": False
}
},
"additional_tool_info": {
"api": {
"endpoint": "https://api.example.com/test",
"headers": { "Content-Type": "application/json" },
"method": "POST",
"parameters": {
"fixed_params": { "api_key": {
"description": "API key for authentication",
"value": "test-api-key"
} },
"runtime_params": {}
}
},
"tool_type": "custom"
},
"tool_id": "<string>",
"tool_start_message": "<string>",
"tool_delayed_message": "<string>",
"tool_complete_message": "<string>",
"tool_failed_message": "<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({
openai_tool: {
name: '<string>',
description: '<string>',
parameters: {
properties: {},
type: 'object',
required: ['<string>'],
additionalProperties: false
}
},
additional_tool_info: {
api: {
endpoint: 'https://api.example.com/test',
headers: {'Content-Type': 'application/json'},
method: 'POST',
parameters: {
fixed_params: {api_key: {description: 'API key for authentication', value: 'test-api-key'}},
runtime_params: {}
}
},
tool_type: 'custom'
},
tool_id: '<string>',
tool_start_message: '<string>',
tool_delayed_message: '<string>',
tool_complete_message: '<string>',
tool_failed_message: '<string>'
})
};
fetch('https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-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/v2/ai-agents/{ai_agent_id}/custom-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([
'openai_tool' => [
'name' => '<string>',
'description' => '<string>',
'parameters' => [
'properties' => [
],
'type' => 'object',
'required' => [
'<string>'
],
'additionalProperties' => false
]
],
'additional_tool_info' => [
'api' => [
'endpoint' => 'https://api.example.com/test',
'headers' => [
'Content-Type' => 'application/json'
],
'method' => 'POST',
'parameters' => [
'fixed_params' => [
'api_key' => [
'description' => 'API key for authentication',
'value' => 'test-api-key'
]
],
'runtime_params' => [
]
]
],
'tool_type' => 'custom'
],
'tool_id' => '<string>',
'tool_start_message' => '<string>',
'tool_delayed_message' => '<string>',
'tool_complete_message' => '<string>',
'tool_failed_message' => '<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/v2/ai-agents/{ai_agent_id}/custom-tools/"
payload := strings.NewReader("{\n \"openai_tool\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {\n \"properties\": {},\n \"type\": \"object\",\n \"required\": [\n \"<string>\"\n ],\n \"additionalProperties\": false\n }\n },\n \"additional_tool_info\": {\n \"api\": {\n \"endpoint\": \"https://api.example.com/test\",\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"method\": \"POST\",\n \"parameters\": {\n \"fixed_params\": {\n \"api_key\": {\n \"description\": \"API key for authentication\",\n \"value\": \"test-api-key\"\n }\n },\n \"runtime_params\": {}\n }\n },\n \"tool_type\": \"custom\"\n },\n \"tool_id\": \"<string>\",\n \"tool_start_message\": \"<string>\",\n \"tool_delayed_message\": \"<string>\",\n \"tool_complete_message\": \"<string>\",\n \"tool_failed_message\": \"<string>\"\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/v2/ai-agents/{ai_agent_id}/custom-tools/")
.header("Content-Type", "application/json")
.body("{\n \"openai_tool\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {\n \"properties\": {},\n \"type\": \"object\",\n \"required\": [\n \"<string>\"\n ],\n \"additionalProperties\": false\n }\n },\n \"additional_tool_info\": {\n \"api\": {\n \"endpoint\": \"https://api.example.com/test\",\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"method\": \"POST\",\n \"parameters\": {\n \"fixed_params\": {\n \"api_key\": {\n \"description\": \"API key for authentication\",\n \"value\": \"test-api-key\"\n }\n },\n \"runtime_params\": {}\n }\n },\n \"tool_type\": \"custom\"\n },\n \"tool_id\": \"<string>\",\n \"tool_start_message\": \"<string>\",\n \"tool_delayed_message\": \"<string>\",\n \"tool_complete_message\": \"<string>\",\n \"tool_failed_message\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-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 \"openai_tool\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {\n \"properties\": {},\n \"type\": \"object\",\n \"required\": [\n \"<string>\"\n ],\n \"additionalProperties\": false\n }\n },\n \"additional_tool_info\": {\n \"api\": {\n \"endpoint\": \"https://api.example.com/test\",\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"method\": \"POST\",\n \"parameters\": {\n \"fixed_params\": {\n \"api_key\": {\n \"description\": \"API key for authentication\",\n \"value\": \"test-api-key\"\n }\n },\n \"runtime_params\": {}\n }\n },\n \"tool_type\": \"custom\"\n },\n \"tool_id\": \"<string>\",\n \"tool_start_message\": \"<string>\",\n \"tool_delayed_message\": \"<string>\",\n \"tool_complete_message\": \"<string>\",\n \"tool_failed_message\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"openai_tool": {
"name": "<string>",
"description": "<string>",
"parameters": {
"properties": {},
"type": "object",
"required": [
"<string>"
],
"additionalProperties": false
}
},
"additional_tool_info": {
"api": {
"endpoint": "https://api.example.com/test",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"parameters": {
"fixed_params": {
"api_key": {
"description": "API key for authentication",
"value": "test-api-key"
}
},
"runtime_params": {}
}
},
"tool_type": "custom"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"tool_id": "<string>",
"tool_start_message": "<string>",
"tool_delayed_message": "<string>",
"tool_complete_message": "<string>",
"tool_failed_message": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Custom Tools
Create custom tool
Create a new custom tool with the provided configuration.
POST
/
v2
/
ai-agents
/
{ai_agent_id}
/
custom-tools
/
Create custom tool
curl --request POST \
--url https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-tools/ \
--header 'Content-Type: application/json' \
--data '
{
"openai_tool": {
"name": "<string>",
"description": "<string>",
"parameters": {
"properties": {},
"type": "object",
"required": [
"<string>"
],
"additionalProperties": false
}
},
"additional_tool_info": {
"api": {
"endpoint": "https://api.example.com/test",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"parameters": {
"fixed_params": {
"api_key": {
"description": "API key for authentication",
"value": "test-api-key"
}
},
"runtime_params": {}
}
},
"tool_type": "custom"
},
"tool_id": "<string>",
"tool_start_message": "<string>",
"tool_delayed_message": "<string>",
"tool_complete_message": "<string>",
"tool_failed_message": "<string>"
}
'import requests
url = "https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-tools/"
payload = {
"openai_tool": {
"name": "<string>",
"description": "<string>",
"parameters": {
"properties": {},
"type": "object",
"required": ["<string>"],
"additionalProperties": False
}
},
"additional_tool_info": {
"api": {
"endpoint": "https://api.example.com/test",
"headers": { "Content-Type": "application/json" },
"method": "POST",
"parameters": {
"fixed_params": { "api_key": {
"description": "API key for authentication",
"value": "test-api-key"
} },
"runtime_params": {}
}
},
"tool_type": "custom"
},
"tool_id": "<string>",
"tool_start_message": "<string>",
"tool_delayed_message": "<string>",
"tool_complete_message": "<string>",
"tool_failed_message": "<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({
openai_tool: {
name: '<string>',
description: '<string>',
parameters: {
properties: {},
type: 'object',
required: ['<string>'],
additionalProperties: false
}
},
additional_tool_info: {
api: {
endpoint: 'https://api.example.com/test',
headers: {'Content-Type': 'application/json'},
method: 'POST',
parameters: {
fixed_params: {api_key: {description: 'API key for authentication', value: 'test-api-key'}},
runtime_params: {}
}
},
tool_type: 'custom'
},
tool_id: '<string>',
tool_start_message: '<string>',
tool_delayed_message: '<string>',
tool_complete_message: '<string>',
tool_failed_message: '<string>'
})
};
fetch('https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-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/v2/ai-agents/{ai_agent_id}/custom-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([
'openai_tool' => [
'name' => '<string>',
'description' => '<string>',
'parameters' => [
'properties' => [
],
'type' => 'object',
'required' => [
'<string>'
],
'additionalProperties' => false
]
],
'additional_tool_info' => [
'api' => [
'endpoint' => 'https://api.example.com/test',
'headers' => [
'Content-Type' => 'application/json'
],
'method' => 'POST',
'parameters' => [
'fixed_params' => [
'api_key' => [
'description' => 'API key for authentication',
'value' => 'test-api-key'
]
],
'runtime_params' => [
]
]
],
'tool_type' => 'custom'
],
'tool_id' => '<string>',
'tool_start_message' => '<string>',
'tool_delayed_message' => '<string>',
'tool_complete_message' => '<string>',
'tool_failed_message' => '<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/v2/ai-agents/{ai_agent_id}/custom-tools/"
payload := strings.NewReader("{\n \"openai_tool\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {\n \"properties\": {},\n \"type\": \"object\",\n \"required\": [\n \"<string>\"\n ],\n \"additionalProperties\": false\n }\n },\n \"additional_tool_info\": {\n \"api\": {\n \"endpoint\": \"https://api.example.com/test\",\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"method\": \"POST\",\n \"parameters\": {\n \"fixed_params\": {\n \"api_key\": {\n \"description\": \"API key for authentication\",\n \"value\": \"test-api-key\"\n }\n },\n \"runtime_params\": {}\n }\n },\n \"tool_type\": \"custom\"\n },\n \"tool_id\": \"<string>\",\n \"tool_start_message\": \"<string>\",\n \"tool_delayed_message\": \"<string>\",\n \"tool_complete_message\": \"<string>\",\n \"tool_failed_message\": \"<string>\"\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/v2/ai-agents/{ai_agent_id}/custom-tools/")
.header("Content-Type", "application/json")
.body("{\n \"openai_tool\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {\n \"properties\": {},\n \"type\": \"object\",\n \"required\": [\n \"<string>\"\n ],\n \"additionalProperties\": false\n }\n },\n \"additional_tool_info\": {\n \"api\": {\n \"endpoint\": \"https://api.example.com/test\",\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"method\": \"POST\",\n \"parameters\": {\n \"fixed_params\": {\n \"api_key\": {\n \"description\": \"API key for authentication\",\n \"value\": \"test-api-key\"\n }\n },\n \"runtime_params\": {}\n }\n },\n \"tool_type\": \"custom\"\n },\n \"tool_id\": \"<string>\",\n \"tool_start_message\": \"<string>\",\n \"tool_delayed_message\": \"<string>\",\n \"tool_complete_message\": \"<string>\",\n \"tool_failed_message\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v2/ai-agents/{ai_agent_id}/custom-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 \"openai_tool\": {\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"parameters\": {\n \"properties\": {},\n \"type\": \"object\",\n \"required\": [\n \"<string>\"\n ],\n \"additionalProperties\": false\n }\n },\n \"additional_tool_info\": {\n \"api\": {\n \"endpoint\": \"https://api.example.com/test\",\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"method\": \"POST\",\n \"parameters\": {\n \"fixed_params\": {\n \"api_key\": {\n \"description\": \"API key for authentication\",\n \"value\": \"test-api-key\"\n }\n },\n \"runtime_params\": {}\n }\n },\n \"tool_type\": \"custom\"\n },\n \"tool_id\": \"<string>\",\n \"tool_start_message\": \"<string>\",\n \"tool_delayed_message\": \"<string>\",\n \"tool_complete_message\": \"<string>\",\n \"tool_failed_message\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"openai_tool": {
"name": "<string>",
"description": "<string>",
"parameters": {
"properties": {},
"type": "object",
"required": [
"<string>"
],
"additionalProperties": false
}
},
"additional_tool_info": {
"api": {
"endpoint": "https://api.example.com/test",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"parameters": {
"fixed_params": {
"api_key": {
"description": "API key for authentication",
"value": "test-api-key"
}
},
"runtime_params": {}
}
},
"tool_type": "custom"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"tool_id": "<string>",
"tool_start_message": "<string>",
"tool_delayed_message": "<string>",
"tool_complete_message": "<string>",
"tool_failed_message": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Path Parameters
Body
application/json
OpenAI function definition specifying the tool's interface for AI interaction
Show child attributes
Show child attributes
Example:
{
"description": "Get the delivery date for a customer's order",
"name": "get_delivery_date",
"parameters": {
"additionalProperties": false,
"properties": {
"order_id": {
"description": "The customer's order ID",
"type": "string"
}
},
"required": ["order_id"],
"type": "object"
}
}
API configuration and other custom tool specific details needed for implementation
Show child attributes
Show child attributes
Optional message to display when the tool is started
Optional message to display when the tool is delayed
Optional message to display when the tool is completed
Optional message to display when the tool fails
Response
Successful Response
OpenAI function definition containing the tool's interface specification
Show child attributes
Show child attributes
Example:
{
"description": "Get the delivery date for a customer's order",
"name": "get_delivery_date",
"parameters": {
"additionalProperties": false,
"properties": {
"order_id": {
"description": "The customer's order ID",
"type": "string"
}
},
"required": ["order_id"],
"type": "object"
}
}
Complete configuration for the custom tool including API details
Show child attributes
Show child attributes
Timestamp indicating when this custom tool was created
Timestamp indicating when this custom tool was last modified
Unique identifier for the custom tool
Optional message to display when the tool is started
Optional message to display when the tool is delayed
Optional message to display when the tool is completed
Optional message to display when the tool fails
⌘I