Add or replace a tool
Saves one tool on the agent, creating it or replacing the one with this name, and leaves the agent’s other tools alone. The name comes from the URL (lowercase, 2–40 characters). Every save is a new agent revision, and calls already placed keep the version they started with.
This example is an on-call tool: the agent collects date and time from the caller, says the speak_while line, and POSTs them to your endpoint with your secret in the header. {{ vars.customer_id }} comes from the call’s variables. Replace request.url with your own HTTPS endpoint (public, port 443).
Send if_revision in the body to refuse the save if someone changed the agent since you read it. The answer is the whole agent, with every default filled in.
curl --request PUT \
--url https://sandbox.voice.miraiminds.co/v2/agents/{agent_id}/tools/{tool_name} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phase": "on_call"
}
'import requests
url = "https://sandbox.voice.miraiminds.co/v2/agents/{agent_id}/tools/{tool_name}"
payload = { "phase": "on_call" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const url = 'https://sandbox.voice.miraiminds.co/v2/agents/{agent_id}/tools/{tool_name}';
const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({phase: 'on_call'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));{
"revision": 6,
"draft": false,
"archived": false,
"analysis": {
"enabled": false
},
"id": "agt_01K2M4P7QRSTVWXYZ0A1B2C3",
"object": "agent",
"name": "सर्विस रिमाइंडर",
"system_prompt": "आप आशु हैं, मिराई मोटर्स के सर्विस एडवाइज़र. {{name}} जी की {{vehicle}} की सर्विस {{due_date}} को ड्यू है. हिंदी में बात करें, छोटे वाक्य बोलें, और ग्राहक से सर्विस की तारीख कन्फर्म करें.",
"first_message": "नमस्ते, मैं आशु बोल रहा हूं मिराई मोटर्स से. एक मिनट है आपके पास?",
"voice": {
"voice_id": "ashu",
"language": "hi"
},
"language": "hi",
"max_duration_secs": 300,
"end_call": {
"enabled": true,
"message": "धन्यवाद, आपका दिन शुभ हो.",
"confirm": true
},
"voicemail": {
"action": "hangup"
},
"background_sound": {
"sound": "off"
},
"behavior": {
"interruptions": "normal",
"adaptive_interruptions": true,
"pass_through": [],
"date_awareness": true
},
"secondary_languages": [
"en"
],
"tools": [
{
"name": "book_slot",
"phase": "on_call",
"kind": "http",
"enabled": true,
"description": "Book a service slot for the customer's car.",
"when": "Use this once the customer has agreed to a date and a time. Confirm both before booking.",
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Service date, YYYY-MM-DD."
},
"time": {
"type": "string",
"description": "Slot start time, HH:MM, 24-hour."
}
},
"required": [
"date",
"time"
]
},
"execution": "sync",
"speak_while": "एक सेकंड, मैं स्लॉट बुक कर रहा हूं.",
"request": {
"method": "POST",
"url": "https://api.example.com/service/bookings",
"headers": {
"Authorization": "Bearer {{ secrets.crm_key }}"
},
"body": {
"customer_id": "{{ vars.customer_id }}",
"date": "{{ args.date }}",
"time": "{{ args.time }}"
}
},
"response": {
"transform": "{booking_id, slot}"
},
"timeout_ms": 8000,
"retry": {
"attempts": 0,
"backoff_ms": 500
},
"on_failure": "continue"
}
],
"created_at": "2026-08-11T09:14:02Z",
"updated_at": "2026-10-09T08:42:30Z"
}{
"error": "invalid_tools",
"details": [
{
"path": "tools[0].request.headers[\"Authorization\"]",
"message": "secret \"crm_key\" does not exist in this workspace; create it with PUT /v2/secrets/crm_key first"
}
]
}{
"error": {
"code": "conflict",
"message": "agent changed; read its current revision and retry"
}
}Authorizations
Path Parameters
Response
Saved: the agent, with its tools
curl --request PUT \
--url https://sandbox.voice.miraiminds.co/v2/agents/{agent_id}/tools/{tool_name} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phase": "on_call"
}
'import requests
url = "https://sandbox.voice.miraiminds.co/v2/agents/{agent_id}/tools/{tool_name}"
payload = { "phase": "on_call" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const url = 'https://sandbox.voice.miraiminds.co/v2/agents/{agent_id}/tools/{tool_name}';
const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({phase: 'on_call'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));{
"revision": 6,
"draft": false,
"archived": false,
"analysis": {
"enabled": false
},
"id": "agt_01K2M4P7QRSTVWXYZ0A1B2C3",
"object": "agent",
"name": "सर्विस रिमाइंडर",
"system_prompt": "आप आशु हैं, मिराई मोटर्स के सर्विस एडवाइज़र. {{name}} जी की {{vehicle}} की सर्विस {{due_date}} को ड्यू है. हिंदी में बात करें, छोटे वाक्य बोलें, और ग्राहक से सर्विस की तारीख कन्फर्म करें.",
"first_message": "नमस्ते, मैं आशु बोल रहा हूं मिराई मोटर्स से. एक मिनट है आपके पास?",
"voice": {
"voice_id": "ashu",
"language": "hi"
},
"language": "hi",
"max_duration_secs": 300,
"end_call": {
"enabled": true,
"message": "धन्यवाद, आपका दिन शुभ हो.",
"confirm": true
},
"voicemail": {
"action": "hangup"
},
"background_sound": {
"sound": "off"
},
"behavior": {
"interruptions": "normal",
"adaptive_interruptions": true,
"pass_through": [],
"date_awareness": true
},
"secondary_languages": [
"en"
],
"tools": [
{
"name": "book_slot",
"phase": "on_call",
"kind": "http",
"enabled": true,
"description": "Book a service slot for the customer's car.",
"when": "Use this once the customer has agreed to a date and a time. Confirm both before booking.",
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Service date, YYYY-MM-DD."
},
"time": {
"type": "string",
"description": "Slot start time, HH:MM, 24-hour."
}
},
"required": [
"date",
"time"
]
},
"execution": "sync",
"speak_while": "एक सेकंड, मैं स्लॉट बुक कर रहा हूं.",
"request": {
"method": "POST",
"url": "https://api.example.com/service/bookings",
"headers": {
"Authorization": "Bearer {{ secrets.crm_key }}"
},
"body": {
"customer_id": "{{ vars.customer_id }}",
"date": "{{ args.date }}",
"time": "{{ args.time }}"
}
},
"response": {
"transform": "{booking_id, slot}"
},
"timeout_ms": 8000,
"retry": {
"attempts": 0,
"backoff_ms": 500
},
"on_failure": "continue"
}
],
"created_at": "2026-08-11T09:14:02Z",
"updated_at": "2026-10-09T08:42:30Z"
}{
"error": "invalid_tools",
"details": [
{
"path": "tools[0].request.headers[\"Authorization\"]",
"message": "secret \"crm_key\" does not exist in this workspace; create it with PUT /v2/secrets/crm_key first"
}
]
}{
"error": {
"code": "conflict",
"message": "agent changed; read its current revision and retry"
}
}