Skip to main content
POST
/
v1
/
agents
Create Ai Agent
curl --request POST \
  --url https://api.xpander.ai/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Customer Support Agent",
  "deployment_type": "serverless",
  "environment_id": "11968157-c0ed-4b8a-a05e-be1d4bb2e922"
}
'
{
  "id": "new-agent-uuid-12345",
  "name": "Customer Support Agent",
  "description": "",
  "icon": "🚀",
  "status": "ACTIVE",
  "deployment_type": "serverless",
  "created_at": "2026-02-07T10:00:00.000000Z",
  "model_provider": "openai",
  "model_name": "gpt-4.1",
  "framework": "agno",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "tools": [],
  "graph": [],
  "knowledge_bases": [],
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "webhook_url": "https://webhook.xpander.ai/?agent_id=new-agent-uuid-12345&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
  }
}
Create a new AI agent with custom configuration. The agent will be created and ready for configuration and deployment.

​
Request Body

​
name
string
required
Display name for the agent
​
description
string
Description of the agent’s purpose and capabilities
​
deployment_type
string
Deployment infrastructure: serverless or container. Defaults to serverless if not specified.
container deployment type is in beta and creates agents using container-based framework execution.
​
model_provider
string
LLM provider: openai (default), anthropic, etc.
​
model_name
string
Specific model version (e.g., gpt-4o, gpt-4.1)
​
icon
string
Emoji icon for the agent (e.g., ”🚀”, ”📊”)
​
instructions
object
System instructions configuration
​
environment_id
string
Target environment ID (optional)
​
using_nemo
boolean
Use Nvidia NeMo (default: false)
​
llm_api_base
string
Custom API base URL for LLM provider (for AI Gateway configurations)
​
llm_extra_headers
object
Custom HTTP headers to include in LLM requests for gateway integration

​
Response

Returns a complete AIAgent object:
​
id
string
Unique identifier for the created agent (UUID)
​
name
string
Display name of the agent
​
description
string
Agent description
​
icon
string
Emoji icon representing the agent
​
status
string
Current deployment status: ACTIVE or INACTIVE
​
organization_id
string
UUID of the organization that owns this agent
​
deployment_type
string
Deployment infrastructure: serverless, container, or null
​
instructions
object
System instructions configuration
​
model_provider
string
AI model provider (e.g., openai)
​
model_name
string
Specific model version (e.g., gpt-4o, gpt-4.1)
​
framework
string
Agent framework used (e.g., agno)
​
unique_name
string
Auto-generated human-friendly slug identifier (e.g., “beige-swallow”)
​
version
integer
Agent version number
​
tools
array
Array of tools available to the agent
​
knowledge_bases
array
Array of knowledge bases attached to the agent
​
graph
array
Agent workflow graph configuration
​
webhook_url
string
Auto-generated webhook URL for agent invocations

​
Example Request

Minimal create request (required fields only): 
curl -X POST "https://api.xpander.ai/v1/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "name": "Customer Support Agent",
    "model_provider": "openai",
    "model_name": "gpt-5.2"
  }'
With full configuration: 
curl -X POST "https://api.xpander.ai/v1/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "name": "Customer Support Agent",
    "model_provider": "openai",
    "model_name": "gpt-5.2",
    "instructions": {
      "role": ["Customer support specialist"],
      "goal": ["Resolve customer issues efficiently"],
      "general": "Be helpful, professional, and empathetic"
    }
  }'

​
Example Response

{
  "id": "<agent-id>",
  "unique_name": "jade-bass",
  "name": "Customer Support Agent",
  "description": "",
  "deployment_type": "serverless",
  "framework": "agno",
  "status": "ACTIVE",
  "model_provider": "openai",
  "model_name": "gpt-5.2",
  "organization_id": "<org-id>",
  "version": 2,
  "has_pending_changes": false,
  "is_latest": false,
  "tools": [],
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "knowledge_bases": [],
  "icon": "🚀",
  "llm_settings": [
    {
      "provider": "openai",
      "model": "gpt-5.2",
      "temperature": 0.0
    }
  ],
  "agno_settings": {
    "session_storage": true,
    "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,
    "openai_moderation_categories": null,
    "reasoning_tools_enabled": true,
    "tool_calls_compression": {
      "enabled": false,
      "threshold": 3,
      "instructions": ""
    }
  },
  "webhook_url": "https://webhook.xpander.ai/?agent_id=<agent-id>&asynchronous=false"
}

​
Notes

  • Only name is required. All other fields are optional and will use platform defaults.
  • The unique_name is auto-generated as a human-friendly slug (e.g., “jade-bass”)
  • The webhook_url is auto-generated for agent invocations
  • Agent starts in ACTIVE status immediately upon creation and is ready for invocation
  • version starts at 2 and increments with each deployment
  • has_pending_changes indicates whether there are unpublished configuration changes
  • The API may auto-upgrade model_name (e.g., requested gpt-4.1 returns gpt-5.2)

​
Next Steps

After creating an agent:
  1. Update instructions using Update Agent
  2. Add tools and knowledge bases to the agent
  3. Deploy the agent using Deploy Agent
  4. Invoke the agent using the task execution endpoints

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Body

application/json
​
name
string
required

Display name for the agent

​
deployment_type
enum<string> | null

Deployment infrastructure: serverless (default) or container

Available options:
serverless,
container
​
environment_id
string | null

Target environment id to create the agent in

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