Patches An Agent Settings
curl --request PATCH \
--url https://api.threetone.in/v1/convai/agents/{agent_id} \
--header 'Content-Type: application/json' \
--data '
{
"name": "My agent"
}
'import requests
url = "https://api.threetone.in/v1/convai/agents/{agent_id}"
payload = { "name": "My agent" }
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({name: 'My agent'})
};
fetch('https://api.threetone.in/v1/convai/agents/{agent_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"agent_id": "agent_4m8q7z2pxn5r9vkt6d3h1c0b",
"name": "My Agent",
"workflow": {
"edges": {
"entry_to_tool_a": {
"forward_condition": {
"condition": "Tool A condition",
"type": "llm"
},
"source": "entry_node",
"target": "tool_node_a"
},
"start_to_entry": {
"forward_condition": {
"type": "unconditional"
},
"source": "start_node",
"target": "entry_node"
},
"tool_a_to_failure": {
"forward_condition": {
"successful": false,
"type": "result"
},
"source": "tool_node_a",
"target": "failure_node"
},
"tool_a_to_tool_b": {
"forward_condition": {
"successful": true,
"type": "result"
},
"source": "tool_node_a",
"target": "tool_node_b"
},
"tool_b_to_agent_transfer": {
"forward_condition": {
"type": "unconditional"
},
"source": "tool_node_b",
"target": "success_transfer"
},
"tool_b_to_conversation": {
"forward_condition": {
"condition": "Conversation condition",
"type": "llm"
},
"source": "tool_node_b",
"target": "success_conversation"
},
"tool_b_to_end": {
"forward_condition": {
"condition": "End condition",
"type": "llm"
},
"source": "tool_node_b",
"target": "success_end"
},
"tool_b_to_phone": {
"forward_condition": {
"expression": {
"children": [
{
"name": "force_phone_transfer",
"type": "dynamic_variable"
},
{
"prompt": "Phone condition",
"type": "llm",
"value_schema": {
"description": "Phone condition",
"type": "boolean"
}
},
{
"left": {
"name": "mode",
"type": "dynamic_variable"
},
"right": {
"type": "string_literal",
"value": "dev"
},
"type": "eq_operator"
}
],
"type": "or_operator"
},
"type": "expression"
},
"source": "tool_node_b",
"target": "success_phone"
}
},
"nodes": {
"entry_node": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"auto_advance_after_first_response": false,
"conversation_config": {},
"edge_order": [
"entry_to_tool_a"
],
"entry_behavior": "auto",
"label": "Entry",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"failure_node": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"auto_advance_after_first_response": false,
"conversation_config": {},
"edge_order": [],
"entry_behavior": "auto",
"label": "Failure",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"start_node": {
"edge_order": [
"start_to_entry"
],
"position": {
"x": 0,
"y": 0
},
"type": "start"
},
"success_conversation": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"auto_advance_after_first_response": false,
"conversation_config": {},
"edge_order": [],
"entry_behavior": "auto",
"label": "Success A",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"success_end": {
"edge_order": [],
"position": {
"x": 0,
"y": 0
},
"type": "end"
},
"success_phone": {
"custom_sip_headers": [],
"edge_order": [],
"position": {
"x": 0,
"y": 0
},
"require_acceptance": false,
"transfer_destination": {
"phone_number": "+1234567890",
"type": "phone"
},
"transfer_type": "conference",
"type": "phone_number"
},
"success_transfer": {
"agent_id": "success_transfer_agent",
"delay_ms": 0,
"edge_order": [],
"enable_transferred_agent_first_message": false,
"position": {
"x": 0,
"y": 0
},
"type": "standalone_agent"
},
"tool_node_a": {
"edge_order": [
"tool_a_to_failure",
"tool_a_to_tool_b"
],
"position": {
"x": 0,
"y": 0
},
"tools": [
{
"tool_id": "tool_a"
},
{
"tool_id": "tool_b"
}
],
"type": "tool"
},
"tool_node_b": {
"edge_order": [
"tool_b_to_conversation",
"tool_b_to_end",
"tool_b_to_phone",
"tool_b_to_agent_transfer"
],
"position": {
"x": 0,
"y": 0
},
"tools": [
{
"tool_id": "tool_a"
}
],
"type": "tool"
}
},
"prevent_subagent_loops": false
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Agents Platform
Patches An Agent Settings
Patches an Agent settings
PATCH
/
v1
/
convai
/
agents
/
{agent_id}
Patches An Agent Settings
curl --request PATCH \
--url https://api.threetone.in/v1/convai/agents/{agent_id} \
--header 'Content-Type: application/json' \
--data '
{
"name": "My agent"
}
'import requests
url = "https://api.threetone.in/v1/convai/agents/{agent_id}"
payload = { "name": "My agent" }
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({name: 'My agent'})
};
fetch('https://api.threetone.in/v1/convai/agents/{agent_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"agent_id": "agent_4m8q7z2pxn5r9vkt6d3h1c0b",
"name": "My Agent",
"workflow": {
"edges": {
"entry_to_tool_a": {
"forward_condition": {
"condition": "Tool A condition",
"type": "llm"
},
"source": "entry_node",
"target": "tool_node_a"
},
"start_to_entry": {
"forward_condition": {
"type": "unconditional"
},
"source": "start_node",
"target": "entry_node"
},
"tool_a_to_failure": {
"forward_condition": {
"successful": false,
"type": "result"
},
"source": "tool_node_a",
"target": "failure_node"
},
"tool_a_to_tool_b": {
"forward_condition": {
"successful": true,
"type": "result"
},
"source": "tool_node_a",
"target": "tool_node_b"
},
"tool_b_to_agent_transfer": {
"forward_condition": {
"type": "unconditional"
},
"source": "tool_node_b",
"target": "success_transfer"
},
"tool_b_to_conversation": {
"forward_condition": {
"condition": "Conversation condition",
"type": "llm"
},
"source": "tool_node_b",
"target": "success_conversation"
},
"tool_b_to_end": {
"forward_condition": {
"condition": "End condition",
"type": "llm"
},
"source": "tool_node_b",
"target": "success_end"
},
"tool_b_to_phone": {
"forward_condition": {
"expression": {
"children": [
{
"name": "force_phone_transfer",
"type": "dynamic_variable"
},
{
"prompt": "Phone condition",
"type": "llm",
"value_schema": {
"description": "Phone condition",
"type": "boolean"
}
},
{
"left": {
"name": "mode",
"type": "dynamic_variable"
},
"right": {
"type": "string_literal",
"value": "dev"
},
"type": "eq_operator"
}
],
"type": "or_operator"
},
"type": "expression"
},
"source": "tool_node_b",
"target": "success_phone"
}
},
"nodes": {
"entry_node": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"auto_advance_after_first_response": false,
"conversation_config": {},
"edge_order": [
"entry_to_tool_a"
],
"entry_behavior": "auto",
"label": "Entry",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"failure_node": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"auto_advance_after_first_response": false,
"conversation_config": {},
"edge_order": [],
"entry_behavior": "auto",
"label": "Failure",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"start_node": {
"edge_order": [
"start_to_entry"
],
"position": {
"x": 0,
"y": 0
},
"type": "start"
},
"success_conversation": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"auto_advance_after_first_response": false,
"conversation_config": {},
"edge_order": [],
"entry_behavior": "auto",
"label": "Success A",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"success_end": {
"edge_order": [],
"position": {
"x": 0,
"y": 0
},
"type": "end"
},
"success_phone": {
"custom_sip_headers": [],
"edge_order": [],
"position": {
"x": 0,
"y": 0
},
"require_acceptance": false,
"transfer_destination": {
"phone_number": "+1234567890",
"type": "phone"
},
"transfer_type": "conference",
"type": "phone_number"
},
"success_transfer": {
"agent_id": "success_transfer_agent",
"delay_ms": 0,
"edge_order": [],
"enable_transferred_agent_first_message": false,
"position": {
"x": 0,
"y": 0
},
"type": "standalone_agent"
},
"tool_node_a": {
"edge_order": [
"tool_a_to_failure",
"tool_a_to_tool_b"
],
"position": {
"x": 0,
"y": 0
},
"tools": [
{
"tool_id": "tool_a"
},
{
"tool_id": "tool_b"
}
],
"type": "tool"
},
"tool_node_b": {
"edge_order": [
"tool_b_to_conversation",
"tool_b_to_end",
"tool_b_to_phone",
"tool_b_to_agent_transfer"
],
"position": {
"x": 0,
"y": 0
},
"tools": [
{
"tool_id": "tool_a"
}
],
"type": "tool"
}
},
"prevent_subagent_loops": false
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Headers
Your API key for programmatic access. Send it in the x-api-key header; you can create and manage keys from the Developers page.
Path Parameters
The id of an agent. This is returned on agent creation.
Example:
"agent_3701k3ttaq12ewp8b7qv5rfyszkz"
Query Parameters
The ID of the branch to use
Example:
"agtbrch_0901k4aafjxxfxt93gd841r7tv5t"
Body
application/json
Conversation configuration for an agent
Show child attributes
Show child attributes
Example:
{ "agent": { "disable_first_message_interruptions": false, "dynamic_variables": { "dynamic_variable_placeholders": { "user_name": "John Doe" } }, "first_message": "Hello, how can I help you today?", "language": "en", "prompt": { "knowledge_base": [], "llm": "gemini-2.0-flash-001", "max_tokens": -1, "prompt": "You are a helpful assistant that can answer questions about the topic of the conversation.", "temperature": 0, "tool_ids": [] } }, "conversation": { "client_events": ["audio", "interruption"], "max_duration_seconds": 600 }, "tts": { "performance": "latency", "voice_id": "ME9RtCnWp5vX2LhJdF3k" }, "turn": { "interruption_ignore_term_languages": [], "interruption_ignore_terms": [], "merge_with_default_ignore_terms": false, "mode": "turn", "retranscribe_on_turn_timeout": false, "silence_end_call_timeout": -1, "soft_timeout_config": { "message": "Hhmmmm...yeah.", "timeout_seconds": -1, "use_llm_generated_message": false }, "speculative_turn": false, "spelling_patience": "auto", "transcribe_on_disabled_interruptions": false, "turn_eagerness": "normal", "turn_model": "turn_v3", "turn_timeout": 7 } }
Platform settings for the agent are all settings that aren't related to the conversation orchestration and content.
Workflow for the agent. This is used to define the flow of the conversation and how the agent interacts with tools.
Show child attributes
Show child attributes
Example:
{ "edges": { "start_to_support": { "forward_condition": { "type": "unconditional" }, "source": "start_node", "target": "support" }, "support_to_end": { "forward_condition": { "condition": "The request is resolved", "type": "llm" }, "source": "support", "target": "end" } }, "nodes": { "end": { "type": "end" }, "start_node": { "edge_order": ["start_to_support"], "type": "start" }, "support": { "edge_order": ["support_to_end"], "label": "Support", "type": "override_agent" } } }
A name to make the agent easier to find
Example:
"My agent"
Tags to help classify and filter the agent
Example:
[ "Customer Support", "Technical Help", "Three" ]
Description for this version when publishing changes (only applicable for versioned agents)
Procedure versions to publish, keyed by procedure_id. When provided, this map replaces the procedures from the current draft or branch tip. When omitted or null, unpublished procedure edits are used if present; otherwise, the branch tip's procedures are retained. Pass an empty object to remove all procedures.
Show child attributes
Show child attributes
Response
Successful Response
The ID of the agent
The name of the agent
The conversation configuration of the agent
Show child attributes
Show child attributes
The metadata of the agent
Show child attributes
Show child attributes
The platform settings of the agent
Show child attributes
Show child attributes
phone_numbers
(GetPhoneNumberManagedPSTNResponseModel · object | GetPhoneNumberSIPTrunkResponseModel · object)[]
The phone numbers of the agent
- GetPhoneNumberManagedPSTNResponseModel
- GetPhoneNumberSIPTrunkResponseModel
Show child attributes
Show child attributes
Example:
{ "fulfillment_provider": "twilio", "label": "Customer Support", "phone_number": "+1234567890", "phone_number_id": "phone_123", "source_type": "managed_pstn" }
WhatsApp accounts assigned to the agent
Show child attributes
Show child attributes
The workflow of the agent
Show child attributes
Show child attributes
Example:
{ "edges": { "start_to_support": { "forward_condition": { "type": "unconditional" }, "source": "start_node", "target": "support" }, "support_to_end": { "forward_condition": { "condition": "The request is resolved", "type": "llm" }, "source": "support", "target": "end" } }, "nodes": { "end": { "edge_order": [], "position": { "x": 0, "y": 0 }, "type": "end" }, "start_node": { "edge_order": ["start_to_support"], "position": { "x": 0, "y": 0 }, "type": "start" }, "support": { "additional_knowledge_base": [], "additional_prompt": "", "additional_tool_ids": [], "conversation_config": {}, "edge_order": ["support_to_end"], "entry_behavior": "auto", "label": "Support", "position": { "x": 0, "y": 0 }, "type": "override_agent" } }, "prevent_subagent_loops": false }
The access information of the agent for the user
Show child attributes
Show child attributes
Example:
{ "access_source": "creator", "creator_email": "john.doe@example.com", "creator_name": "John Doe", "is_creator": true, "role": "admin" }
Agent tags used to categorize the agent
The ID of the version the agent is on
The ID of the branch the agent is on
The ID of the main branch for this agent