v2
OpenAPI 3.0.02026-08-051996591.2 MBAgents
Create agent
Creates an agent. An agent is defined by three things: the instructions it follows, the steps it executes when it receives an input, and the tools it can call. Instructions are attached to each step and determine the agent's behavior on that step.
Define the steps in the steps map. Set first_step_name to the name of the entry step. A step transitions to other steps through its next_steps conditions. The first_step field also accepts an inline entry step, but it is deprecated.
To invoke an agent, create a session and send events to it. Each event produces a response from the agent.
LLM configuration
Each agent is bound to one LLM, configured under model:
- name: the LLM to use (see GET /v2/llms).
- parameters: LLM parameters such as temperature and max tokens.
- retry_configuration: retry behavior applied to failed LLM calls.
Retry configuration
The agent retries failed LLM calls with exponential backoff:
- max_retries: maximum number of retries after the initial call. Defaults to 3.
- initial_backoff_ms: delay in milliseconds before the first retry. Defaults to 1000.
- backoff_factor: multiplier applied to the delay after each retry. Defaults to 2.0.
- max_backoff_ms: upper bound on the delay between retries. Defaults to 30000.
When retry_configuration is not set, the agent retries with the default configuration. Set enabled to false to disable retries.
post/v2/agents
Headers
Request-Timeoutinteger
The platform makes a best effort to complete the request in the specified seconds, or it times out.
Request-Timeout-Millisinteger
The platform makes a best effort to complete the request in the specified milliseconds, or it times out.
Request body
Example request
{
"key": "customer_support",
"name": "Customer Support Agent",
"description": "An AI agent specialized in handling customer support inquiries using company documentation and support tools.",
"tool_configurations": {
"customer_search": {
"type": "corpora_search",
"argument_override": {
"query": "customer support documentation"
}
}
},
"skills": {
"code_review": {
"description": "Reviews code for best practices.",
"content": "When reviewing code..."
}
},
"model": {
"name": "gpt-4",
"parameters": {
"temperature": 0.7,
"max_tokens": 1000,
"top_p": 0.9
},
"retry_configuration": {
"enabled": true,
"max_retries": 3,
"initial_backoff_ms": 1000,
"max_backoff_ms": 30000,
"backoff_factor": 2
}
},
"first_step": {
"name": "classifier",
"instructions": [
{
"id": "ins_customer_support_init",
"version": 1
}
],
"output_parser": {
"type": "default"
},
"reminders": [
{
"type": "templated",
"template_type": "velocity",
"template": "You are an expert customer support agent for $agent.name. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end",
"hooks": [
"tool_output"
],
"fire_every": 3,
"skip_first": 2
}
],
"next_steps": [
{
"condition": "get('$.output.intent') == 'sales'",
"step_name": "sales_handler"
}
],
"allowed_tools": [
"customer_search",
"web_search"
],
"allowed_skills": [
"code_review",
"debugging"
],
"reentry_step": "classifier"
},
"first_step_name": "classifier",
"steps": {
"sales_handler": {
"instructions": [
{
"type": "inline",
"template": "Handle sales inquiries"
}
],
"output_parser": {
"type": "default"
}
},
"support_handler": {
"instructions": [
{
"type": "inline",
"template": "Handle support requests"
}
],
"output_parser": {
"type": "default"
}
}
},
"metadata": {
"department": "customer_service",
"version": "1.0.0",
"owner": "support-team"
},
"enabled": true,
"compaction": {
"enabled": true,
"threshold_percent": 80,
"keep_recent_inputs": 1
},
"tool_output_offloading": {
"enabled": true,
"mode": "artifact",
"context_percentage": 0.25,
"max_threshold_bytes": 1048576,
"min_threshold_bytes": 4096,
"headroom_percentage": 0.7
}
}Response
The complete agent configuration, including the platform-generated agent key, creation timestamp, and update timestamp.
Example response
{
"key": "customer_support",
"name": "Customer Support Agent",
"description": "An AI agent specialized in handling customer support inquiries using company documentation and support tools.",
"tool_configurations": {
"customer_search": {
"type": "corpora_search",
"argument_override": {
"query": "customer support documentation"
}
}
},
"skills": {
"code_review": {
"description": "Reviews code for best practices and security issues.",
"content": "When reviewing code, focus on..."
}
},
"model": {
"name": "gpt-4",
"parameters": {
"temperature": 0.7,
"max_tokens": 1000,
"top_p": 0.9
},
"retry_configuration": {
"enabled": true,
"max_retries": 3,
"initial_backoff_ms": 1000,
"max_backoff_ms": 30000,
"backoff_factor": 2
}
},
"first_step": {
"name": "classifier",
"instructions": [
{
"id": "ins_customer_support_init",
"version": 1
}
],
"output_parser": {
"type": "default"
},
"reminders": [
{
"type": "templated",
"template_type": "velocity",
"template": "You are an expert customer support agent for $agent.name. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end",
"hooks": [
"tool_output"
],
"fire_every": 3,
"skip_first": 2
}
],
"next_steps": [
{
"condition": "get('$.output.intent') == 'sales'",
"step_name": "sales_handler"
}
],
"allowed_tools": [
"customer_search",
"web_search"
],
"allowed_skills": [
"code_review",
"debugging"
],
"reentry_step": "classifier"
},
"first_step_name": "classifier",
"steps": {
"sales_handler": {
"instructions": [
{
"type": "inline",
"template": "Handle sales inquiries"
}
],
"output_parser": {
"type": "default"
}
},
"support_handler": {
"instructions": [
{
"type": "inline",
"template": "Handle support requests"
}
],
"output_parser": {
"type": "default"
}
}
},
"metadata": {
"department": "customer_service",
"version": "1.2.0",
"owner": "support-team"
},
"enabled": true,
"compaction": {
"enabled": true,
"threshold_percent": 80,
"keep_recent_inputs": 1
},
"tool_output_offloading": {
"enabled": true,
"mode": "artifact",
"context_percentage": 0.25,
"max_threshold_bytes": 1048576,
"min_threshold_bytes": 4096,
"headroom_percentage": 0.7
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-16T14:45:00Z"
}