Create Agent
Create a new AI agent with specified configuration, tools, and knowledge bases
Request Body
serverless or container. Defaults to serverless if not specified.container deployment type is in beta and creates agents using container-based framework execution.openai (default), anthropic, etc.gpt-4o, gpt-4.1)personal (visible only to the creator) or organizational (visible to the entire organization). Defaults to organizational if not specified.low, medium, high)manager (default), regular, a2a, curltext (default) or jsonoutput_format is jsonagno)Response
Returns a completeAIAgent object:
ACTIVE or INACTIVEserverless, container, or nullpersonal or organizationalopenai)gpt-4o, gpt-4.1)agno)Example Request
Minimal create request (required fields only):Example Response
Notes
- Only
nameis required. All other fields are optional and will use platform defaults. - The
unique_nameis auto-generated as a human-friendly slug (e.g., “jade-bass”) - The
webhook_urlis auto-generated for agent invocations - Agent starts in
ACTIVEstatus immediately upon creation and is ready for invocation versionstarts at 2 and increments with each deploymenthas_pending_changesindicates whether there are unpublished configuration changes- The API may auto-upgrade
model_name(e.g., requestedgpt-4.1returnsgpt-5.2)
Next Steps
After creating an agent:- Update instructions using Update Agent
- Add tools and knowledge bases to the agent
- Deploy the agent using Deploy Agent
- Invoke the agent using the task execution endpoints
Authorizations
API Key for authentication
Body
Request model for creating a new AI agent on the xpander.ai platform.
Only name is required. All other fields have sensible defaults matching
the platform's standard agent configuration. The agent will be created
with type 'manager' by default, which supports tool use, sub-agent
delegation, and multi-step task execution.
Fields like organization_id, id, status, version, and other
system-managed properties are set automatically by the platform and
should not be provided.
Human-readable name for the agent. Must be unique within the organization. Examples: 'Customer Support Agent', 'Research Assistant'.
A brief description of what the agent does. Shown in agent listings and used by other agents when deciding delegation. Keep it concise and action-oriented.
Emoji icon displayed next to the agent name in the UI. Single emoji character.
Avatar identifier for the agent's visual representation in chat interfaces.
The agent type. 'manager' is the standard type that supports tools, sub-agents, and multi-step execution. 'regular' is a simpler agent without orchestration capabilities. 'a2a' and 'curl' are for external agent integrations. Do NOT set to 'orchestration' — use the Workflows API instead.
manager, regular, a2a, curl, orchestration User ID of the creator. Auto-populated from the API key if not provided.
The LLM provider to use for this agent's reasoning. Must match an available provider from GET /llm_providers. Common values: 'anthropic', 'openai', 'gemini'.
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 The specific model identifier within the chosen provider. Must match a model from GET /llm_providers/{provider}/models. Examples: 'claude-sonnet-4-6', 'gpt-4o', 'gemini-2.0-flash'.
Controls the depth of reasoning the LLM applies. 'low' for simple tasks, 'medium' for balanced performance, 'high' for complex reasoning, 'xhigh' for maximum reasoning depth (slower, more expensive).
low, medium, high, xhigh Custom API base URL for the LLM provider. Use this when connecting to a self-hosted or proxied LLM endpoint instead of the provider's default URL. Leave None to use the provider's standard endpoint.
Reference key to stored LLM API credentials in the xpander.ai vault. When set, the agent uses these credentials instead of the organization's default. Create credentials via the platform settings.
Type of credential storage. 'xpander' uses xpander.ai's built-in credential vault. 'custom' indicates externally managed credentials.
xpander, custom Direct LLM credentials object. Prefer using llm_credentials_key for secure credential management. Only use this for testing or when vault access is unavailable.
Additional HTTP headers to include in every LLM API request. Useful for custom authentication, routing through gateways (e.g., Helicone, Cloudflare AI Gateway), or passing metadata.
Structured instructions that define the agent's behavior. Contains 'role' (list of role descriptions), 'goal' (list of objectives), and 'general' (free-form instructions text). These are injected into the agent's system prompt.
Description of the expected output format and content. Guides the agent on what the final response should look like. Used in the system prompt to set output expectations.
The format for the agent's final response. 'markdown' for rich text, 'text' for plain text, 'json' for structured JSON output (pair with output_schema), 'voice' for speech synthesis.
text, markdown, json, voice JSON Schema defining the structure of the agent's output when output_format is 'json'. The agent will conform its response to match this schema. Must be a valid JSON Schema object.
The execution framework for this agent. 'agno' is the default xpander.ai framework with full feature support. Other options: 'langchain', 'open-ai-agents', 'google-adk', 'strands-agents'.
How this agent delegates work to sub-agents. 'router' means the LLM dynamically decides which sub-agent to invoke. 'sequence' means sub-agents execute in a predefined order, each passing results to the next.
router, sequence How conversation context is shared between sub-agents during delegation. 'full' passes the complete memory. 'summarization' creates a summary between each delegation (reduces token usage). 'original-input' gives each sub-agent only the original task input.
full, summarization, original-input What happens when the last sub-agent in a delegation chain finishes. 'return-to-start' summarizes and returns to the first agent for final response. 'finish-with-last' ends execution at the last agent.
return-to-start, finish-with-last When True, sub-agents share a continuous conversation thread. When False, each sub-agent starts with a fresh thread. Only relevant for multi-agent setups.
Enable deep planning mode where the agent creates a detailed execution plan before taking actions. Useful for complex multi-step tasks. Increases latency but improves accuracy on complex workflows.
When True, forces the agent to always use deep planning regardless of task complexity. When False (default), the agent decides when to plan based on the task.
List of connector connections with their operation IDs that this agent can use as tools. Each entry binds a connection (connector_organization) to specific operations the agent is allowed to invoke.
Structure: [{"id": "<connection_id>", "operation_ids": ["<catalog_operation_id_1>", "<catalog_operation_id_2>"]}]
- 'id' is the connection ID (connector_organization.id) from POST /connectors/{connector_id}/connect
- 'operation_ids' are the catalog operation _id values from GET /connectors/{connector_id}/{connection_id}/operations
If you provide attached_tools without corresponding graph entries, the API will automatically create graph items of type 'tool' for each operation, resolving catalog _id to operationId.
Special cases:
- Custom functions: use id="xpander-custom-functions" and operation_ids=["<custom_function_id>", ...] Custom function IDs are the function UUIDs, not catalog operation IDs.
- Sub-agents: do NOT use attached_tools. Add sub-agents directly to the 'graph' field with type='agent'.
- MCP servers: do NOT use attached_tools. Add MCP servers directly to the 'graph' field with type='mcp'.
Example (connector operations): [{"id": "770832b8-c32b-4e4c-9ca2-232fec8099a7", "operation_ids": ["694bddfcd72d937c39875cf7"]}]
Example (custom functions): [{"id": "xpander-custom-functions", "operation_ids": ["my-function-uuid-1", "my-function-uuid-2"]}]
The agent's tool graph — defines which tools are available to the LLM and their execution flow. Each graph item represents a tool the agent can call during task execution.
For connector operations (type='tool'):
- item_id: the operationId string (e.g., 'XpanderEmailServiceSendEmailWithHtmlOrTextContent')
- name: human-readable name shown to the LLM (e.g., 'Send Email')
- type: 'tool'
- targets: list of graph item IDs that should execute after this tool (empty [] for no chaining)
- NOTE: auto-created from attached_tools if not provided
For sub-agents (type='agent'):
- item_id: the agent ID (UUID) to delegate work to
- name: display name of the sub-agent
- type: 'agent'
- NO attached_tools entry needed — sub-agents are graph-only
For custom functions (type='tool', sub_type='custom_function'):
- item_id: the custom function UUID
- name: function name
- type: 'tool'
- Requires attached_tools entry with id='xpander-custom-functions'
For MCP servers (type='mcp'):
- item_id: a unique ID for this MCP server instance
- name: display name of the MCP server
- type: 'mcp'
- settings.mcp_settings: {url, transport, auth_type, name, allowed_tools, ...}
- NO attached_tools entry needed — MCP servers are graph-only
NOTE: If you provide attached_tools with operation_ids but no corresponding graph items, the API will auto-create graph items with resolved operationId and pretty_name from catalog.
Examples: Connector tool: {"item_id": "SlackPostMessage", "name": "Send Slack Message", "type": "tool", "targets": []} Sub-agent: {"item_id": "agent-uuid-here", "name": "Research Agent", "type": "agent", "targets": []} MCP server: {"item_id": "mcp-uuid", "name": "Notion", "type": "mcp", "targets": [], "settings": {"mcp_settings": {"url": "https://mcp.notion.com/sse", "transport": "sse", "name": "Notion"}}}
Per-tool LLM override settings. Allows configuring a different LLM for pre-processing ('before') or post-processing ('after') specific tool calls. Each entry specifies type, provider, model, and temperature.
Knowledge bases attached to this agent for RAG (Retrieval-Augmented Generation). Each entry references a knowledge base by ID and specifies the retrieval strategy ('vanilla' for simple retrieval, 'agentic_rag' for agent-driven retrieval).
Entry points that can trigger this agent. Defines how the agent can be invoked — via SDK, scheduled tasks, webhooks, assistant UI, MCP, A2A protocol, Telegram, or Slack.
Where the agent runs. 'serverless' runs on xpander.ai's managed infrastructure (recommended). 'container' runs on your own infrastructure as a Docker container.
serverless, container Who can access this agent. 'personal' restricts access to the creating user. 'organizational' makes it available to all organization members.
personal, organizational Target deployment environment ID. Leave None for the organization's default environment. Use this to deploy agents to specific on-premise or regional environments.
Connection details for external agent integrations (A2A protocol or CURL-based). Only relevant when type is 'a2a' or 'curl'. For standard agents, leave as empty dict.
- AIAgentConnectivityDetailsA2A
- AIAgentConnectivityDetailsCurl
- Connectivity Details
Configuration specific to the Agno framework. Controls session storage, coordinate mode (multi-agent), learning, memory strategies, guardrails (PII detection, prompt injection), tool call limits, and plan retry strategies. Only applies when framework is 'agno'.
Execution strategies applied at the task level. Configure retry behavior (max retries), iterative execution (max iterations with stop conditions), stop strategies, daily run limits, and agentic context (persistent memory across runs).
Notification configuration for task completion events. Define notifications to send on success or error via email, Slack, or webhook. Each channel supports custom subject, body, and branding.
Voice ID for text-to-speech output when output_format is 'voice'. References a voice profile in the platform's TTS service.
Enable NVIDIA NeMo guardrails integration for this agent. Provides additional safety and content filtering capabilities.
Enable LLM prompt caching to reduce latency and cost for repeated similar requests. The platform caches prompt prefixes and reuses them across invocations.
Enable supervised mode where the agent requires human approval before executing mutating operations (write/update/delete). Non-mutating operations (read/search) execute automatically.
Enable real-time event streaming for on-premise deployments. When True, task progress events are streamed to connected clients.
Enable OIDC pre-authentication for this agent. When enabled, the agent requires a valid OIDC token from the invoking user before execution. Used for user-context-aware operations.
List of allowed OIDC token audiences for pre-authentication validation. Only tokens with matching audience claims are accepted.
When True, the user's OIDC token is forwarded to the LLM provider for authenticated LLM calls. Requires use_oidc_pre_auth to be enabled.
The audience claim to request when exchanging the user's OIDC token for LLM provider access. Only used when use_oidc_pre_auth_token_for_llm is True.
The audience claim to request when exchanging the user's OIDC token for MCP server access. Enables user-context-aware MCP tool execution.
Response
Successful Response
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.
return-to-start, finish-with-last serverless, container - AIAgentConnectivityDetailsA2A
- AIAgentConnectivityDetailsCurl
- Connectivity Details
personal, organizational 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.
DRAFT, ACTIVE, INACTIVE 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.
manager, regular, a2a, curl, orchestration 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.
router, sequence 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
full, summarization, original-input 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 low, medium, high, xhigh text, markdown, json, voice xpander, custom 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.
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.