Skip to main content
PUT
/
v1
/
agents
/
{agent_id}
Deploy Ai Agent
curl --request PUT \
  --url https://api.xpander.ai/v1/agents/{agent_id} \
  --header 'x-api-key: <api-key>'
{
  "name": "<string>",
  "organization_id": "<string>",
  "webhook_url": "<string>",
  "id": "<string>",
  "unique_name": "<string>",
  "origin_template": "<string>",
  "delegation_end_strategy": "return-to-start",
  "environment_id": "<string>",
  "sub_agents_continuous_thread": true,
  "deployment_type": "serverless",
  "created_by_prompt": "<string>",
  "prompts": [],
  "is_latest": false,
  "has_pending_changes": false,
  "deep_planning": false,
  "enforce_deep_planning": false,
  "connectivity_details": {},
  "framework": "agno",
  "description": "",
  "tools": [],
  "icon": "🚀",
  "avatar": "male-avatar",
  "source_nodes": [],
  "attached_tools": [],
  "access_scope": "personal",
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "oas": {},
  "graph": [],
  "llm_settings": [],
  "status": "ACTIVE",
  "knowledge_bases": [],
  "version": 1,
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "type": "manager",
  "delegation_type": "router",
  "delegation_memory_strategy": "summarization",
  "is_ai_employee": false,
  "using_nemo": false,
  "deletable": true,
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-6",
  "llm_reasoning_effort": "medium",
  "llm_api_base": "<string>",
  "output_format": "markdown",
  "voice_id": "<string>",
  "output_schema": {},
  "llm_credentials_key": "<string>",
  "llm_credentials_key_type": "xpander",
  "llm_credentials": {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>"
  },
  "llm_extra_headers": {},
  "expected_output": "",
  "agno_settings": {
    "session_storage": true,
    "learning": false,
    "agent_memories": false,
    "agentic_culture": false,
    "user_memories": false,
    "agentic_memory": false,
    "session_summaries": false,
    "num_history_runs": 10,
    "max_tool_calls_from_history": 0,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": false,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": false,
    "openai_moderation_enabled": false,
    "reasoning_tools_enabled": false,
    "tool_calls_compression": {
      "enabled": false,
      "instructions": "",
      "threshold": 3
    },
    "max_plan_retries": 15,
    "plan_retry_strategy": "tiered",
    "memory_strategy": "disabled"
  },
  "on_prem_event_streaming": true,
  "prompts_caching_enabled": false,
  "is_supervised": false,
  "orchestration_nodes": [],
  "notification_settings": {},
  "task_level_strategies": {
    "retry_strategy": {
      "enabled": false,
      "max_retries": 3
    },
    "iterative_strategy": {
      "enabled": false,
      "max_iterations": 3,
      "end_condition": {
        "type": "regex",
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "stop_strategy": {
      "enabled": false,
      "stop_on_failure": true,
      "stop_on_condition": {
        "type": "regex",
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "max_runs_per_day": 123,
    "agentic_context_enabled": false,
    "duplication_prevention": {
      "selectors": [
        "<string>"
      ],
      "enabled": false,
      "ttl_minutes": 10
    }
  },
  "use_oidc_pre_auth": false,
  "pre_auth_audiences": [],
  "use_oidc_pre_auth_token_for_llm": false,
  "oidc_pre_auth_token_llm_audience": "<string>",
  "oidc_pre_auth_token_mcp_audience": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt

Use this file to discover all available pages before exploring further.

Deploy an agent to production. This validates the configuration and makes the agent available for invocation.

​
Path Parameters

​
agent_id
string
required
Unique identifier of the agent to deploy (UUID format)

​
Response

Returns HTTP 200 with the complete agent object (same structure as Create Agent). Key response fields:
  • id: Agent identifier
  • name: Agent display name
  • status: Updated status (ACTIVE or INACTIVE)
  • deployment_type: Deployment infrastructure
  • model_provider: AI model provider
  • model_name: Specific model version
  • framework: Agent framework used
  • organization_id: UUID of the organization that owns this agent
  • description: Auto-generated from instructions if not previously set
  • has_pending_changes: Indicates whether there are unpublished changes
  • version: Current version number of the agent

​
Example Request

curl -X PUT -H "x-api-key: <your-api-key>" \
  https://api.xpander.ai/v1/agents/<agent-id>

​
Example Response

{
  "id": "<agent-id>",
  "unique_name": "customer-support-agent",
  "name": "Customer Support Agent",
  "description": "You are a customer support agent...",
  "deployment_type": "serverless",
  "framework": "agno",
  "status": "ACTIVE",
  "icon": "🎧",
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929",
  "organization_id": "<org-id>",
  "version": 2,
  "type": "manager",
  "has_pending_changes": false,
  "instructions": {
    "role": [
      "Always greet the customer warmly",
      "Search the knowledge base before answering",
      "Escalate billing issues"
    ],
    "goal": [
      "Resolve customer inquiries on first contact",
      "Maintain a friendly tone"
    ],
    "general": "You are a customer support agent..."
  }
}

​
Notes

  • Agent must have valid instructions and configuration before deployment
  • Deployment validates all configurations and dependencies
  • Previously deployed version remains active until new deployment succeeds
  • Deployment typically completes within seconds
  • After deploy, description is auto-generated from instructions if not previously set
  • has_pending_changes returns to false after successful deployment
  • Check agent status using List Agents endpoint
  • An ACTIVE status indicates the agent is ready to handle tasks

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Response

Successful Response

​
name
string
required
​
organization_id
string
required
​
webhook_url
string
required
read-only
​
id
string | null
​
unique_name
string | null
​
origin_template
string | null
​
delegation_end_strategy
enum<string> | null
default:return-to-start

Enumeration of the agent delegation end strategies.

Attributes: ReturnToStart: when last agent is finished and about to announce "finish" it will summarize and return to the first agent. FinishWithLast: finish at the last agent.

Available options:
return-to-start,
finish-with-last
​
environment_id
string | null
​
sub_agents_continuous_thread
boolean | null
default:true
​
deployment_type
enum<string> | null
default:serverless
Available options:
serverless,
container
​
created_by_prompt
string | null
​
prompts
string[] | null
​
is_latest
boolean | null
default:false
​
has_pending_changes
boolean | null
default:false
​
deep_planning
boolean | null
default:false
​
enforce_deep_planning
boolean | null
default:false
​
connectivity_details
AIAgentConnectivityDetailsA2A · object
​
framework
string | null
default:agno
​
description
string | null
default:""
​
tools
any[] | null
​
icon
string | null
default:🚀
​
avatar
string | null
default:male-avatar
​
source_nodes
AIAgentSourceNode · object[] | null
​
attached_tools
Connector · object[] | null
​
access_scope
enum<string> | null
default:personal
Available options:
personal,
organizational
​
instructions
AIAgentInstructions · object
​
oas
Oas · object
​
graph
AIAgentGraphItem · object[] | null
​
llm_settings
AIAgentGraphItemLLMSettings · object[] | null
​
status
enum<string> | null
default:ACTIVE

Enumeration of possible agent statuses.

Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.

Available options:
DRAFT,
ACTIVE,
INACTIVE
​
knowledge_bases
AgentKnowledgeBase · object[] | null
​
version
integer | null
default:1
​
created_by
string | null
​
created_at
string<date-time> | null
​
type
enum<string> | null

Enumeration of the agent types.

Attributes: Manager: marks the agent as a Managing agent. Regular: marks the agent as a regular agent. A2A: marks the agent as an external agent used via A2A protocol. Curl: marks the agent as an external agent used via a CURL. Orchestration: marks the agent as an Orchestration object.

Available options:
manager,
regular,
a2a,
curl,
orchestration
​
delegation_type
enum<string> | null
default:router

Enumeration of the agent delegation types.

Attributes: Router: Marks the agent as a router agent - xpanderAI's LLM will decide which sub-agent to trigger. Sequence: Marks the agent as a sequence agent - sub-agents will delegate to other sub-agents.

Available options:
router,
sequence
​
delegation_memory_strategy
enum<string> | null
default:summarization

Enumeration of the agent delegation memory strategies.

Attributes: Full: The memory object will be passed completely between agents. Summarization: Between each sub-agent delegation, a summarization will occur, and a new thread will be created for each agent. OriginalInput: the sub agent will get the initial task with a fresh memory thread

Available options:
full,
summarization,
original-input
​
is_ai_employee
boolean | null
default:false
​
using_nemo
boolean | null
default:false
​
deletable
boolean | null
default:true
​
model_provider
enum<string> | null
default:anthropic
Available options:
openai,
nim,
amazon_bedrock,
azure_ai_foundary,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
bytedance,
tzafon_lightcone,
open_router,
nebius,
cloudflare_ai_gw
​
model_name
string | null
default:claude-sonnet-4-6
​
llm_reasoning_effort
enum<string> | null
default:medium
Available options:
low,
medium,
high,
xhigh
​
llm_api_base
string | null
​
output_format
enum<string> | null
default:markdown
Available options:
text,
markdown,
json,
voice
​
voice_id
string | null
​
output_schema
Output Schema · object
​
llm_credentials_key
string | null
​
llm_credentials_key_type
enum<string> | null
default:xpander
Available options:
xpander,
custom
​
llm_credentials
LLMCredentials · object
​
llm_extra_headers
Llm Extra Headers · object
​
expected_output
string | null
default:""
​
agno_settings
AgnoSettings · object
​
on_prem_event_streaming
boolean | null
default:true
​
prompts_caching_enabled
boolean | null
default:false
​
is_supervised
boolean | null
default:false
​
orchestration_nodes
OrchestrationNode · object[] | null
​
notification_settings
NotificationSettings · object

Configuration for event-based notifications.

Attributes: on_success: Notifications to send when an operation succeeds. Maps notification types to a list of notification configurations. on_error: Notifications to send when an operation fails. Maps notification types to a list of notification configurations.

​
task_level_strategies
TaskLevelStrategies · object

Configuration object for task-level execution strategies.

This model groups optional strategy configurations that control how a task is executed and managed over time, including retries, iterative execution, stopping conditions, and daily run limits.

Attributes: retry_strategy: Optional retry policy configuration that defines how the task should behave when execution fails (e.g., max attempts, backoff rules).

iterative_strategy:
    Optional iterative execution configuration for tasks that may run in
    repeated cycles/steps until completion or a stop condition is met.

stop_strategy:
    Optional stopping policy configuration that defines when the task
    should stop running (e.g., timeout, max iterations, success criteria).

max_runs_per_day:
    Optional limit on how many times the task is allowed to run within a
    24-hour period. If not set, no explicit daily limit is enforced.

agentic_context_enabled:
    if agentic memory is enabled and accesible to the executor.
​
use_oidc_pre_auth
boolean | null
default:false
​
pre_auth_audiences
string[] | null
​
use_oidc_pre_auth_token_for_llm
boolean | null
default:false
​
oidc_pre_auth_token_llm_audience
string | null
​
oidc_pre_auth_token_mcp_audience
string | null