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>'
{
  "id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
  "name": "Product Specialist",
  "description": "Answers product questions using web search and documentation",
  "icon": "🚀",
  "status": "ACTIVE",
  "deployment_type": "serverless",
  "created_at": "2026-02-05T18:54:51.388334Z",
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929",
  "framework": "agno",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "tools": [
    {
      "id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "method": "post",
      "path": "/operation/XpanderEmailServiceSendEmailWithHtmlOrTextContent/messaging/send_email"
    }
  ],
  "graph": [
    {
      "id": "124fe641-c1dc-4a2a-89d0-36f9bda2df75",
      "item_id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "type": "tool",
      "targets": [],
      "is_first": false
    }
  ],
  "knowledge_bases": [],
  "instructions": {
    "role": [
      "AI support agent for xpander.ai"
    ],
    "goal": [
      "Be helpful and accurate"
    ],
    "general": "You are the official xpander.ai support agent."
  },
  "output_format": "text",
  "expected_output": "Short answer, formatted in rich markdown text.",
  "webhook_url": "https://webhook.xpander.ai/?agent_id=93a1cd50-2af0-452a-99a0-6e1f1b14fb29&asynchronous=false",
  "unique_name": "emerald-emu",
  "llm_api_base": null,
  "has_pending_changes": false,
  "llm_settings": [
    {
      "type": "before",
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250929",
      "temperature": 0
    }
  ],
  "agno_settings": {
    "session_storage": true,
    "agent_memories": false,
    "coordinate_mode": true,
    "num_history_runs": 20,
    "tool_call_limit": 0
  }
}
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

​
id
string | null
​
deployment_type
enum<string> | null
Available options:
serverless,
container
​
name
string

Display name of the agent

​
framework
string | null

Agent framework used (e.g., agno)

​
description
string | null

Description of the agent's purpose and capabilities

​
tools
any[] | null

Array of tools available to the agent

​
icon
string | null

Emoji icon representing the agent

​
instructions
AIAgentInstructions · object
​
graph
AIAgentGraphItem · object[] | null
​
status
enum<string> | null

Current deployment status: ACTIVE or INACTIVE

Available options:
DRAFT,
ACTIVE,
INACTIVE
​
knowledge_bases
AgentKnowledgeBase · object[] | null

Array of knowledge bases attached to the agent

​
organization_id
string

UUID of the organization that owns this agent

​
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.

Available options:
manager,
regular,
a2a,
curl
​
model_provider
enum<string> | null

AI model provider (e.g., openai, anthropic)

Available options:
openai,
nim,
amazon_bedrock,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
open_router,
nebius
​
model_name
string | null

Specific model version (e.g., gpt-4o, gpt-4.1, claude-sonnet-4-5-20250929)

​
output_format
enum<string> | null

Output format: markdown or json

Available options:
text,
markdown,
json
​
output_schema
Output Schema · object

JSON schema for structured output when output_format is json

​
expected_output
string | null

Natural-language description of the desired output (e.g., "A bulleted list of key findings")

​
webhook_url
string

Auto-generated webhook URL for agent invocations

​
unique_name
string

Auto-generated unique identifier for the agent (e.g. 'emerald-emu')

​
llm_api_base
string | null

Custom LLM API base URL for self-hosted or proxied model endpoints

​
llm_settings
AIAgentGraphItemLLMSettings · object[]

LLM configuration per graph node (provider, model, temperature)

​
agno_settings
AgnoSettings · object

Agno framework settings (memory, session storage, moderation, tool limits)

​
has_pending_changes
boolean

Whether the agent has unpublished configuration changes