Skip to main content
POST
/
v1
/
agents
/
template_import
/
{template_id}
Import Agent
curl --request POST \
  --url https://api.xpander.ai/v1/agents/template_import/{template_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Imported Agent Name",
  "environment_id": "env-prod-uuid"
}
'
{
  "id": "new-agent-from-template-uuid",
  "name": "Imported Agent",
  "description": "Agent imported from template",
  "icon": "🚀",
  "status": "ACTIVE",
  "deployment_type": "serverless",
  "created_at": "2026-02-07T10:00:00Z",
  "model_provider": "openai",
  "model_name": "gpt-4.1",
  "framework": "agno",
  "type": "manager"
}
Create a new agent instance from a template. The template can be from your organization or shared from another organization. All agent configuration, tools, sub-agents, and optionally knowledge bases will be replicated into your organization.

​
Path Parameters

​
template_id
string
required
Unique identifier of the template to import (UUID format)

​
Request Body

​
name
string
required
Display name for the new agent instance
​
description
string
Description of the agent instance (optional - can customize the template description)
​
icon
string
Emoji icon for the agent (optional - defaults to template icon)
​
with_knowledge_bases
boolean
default:true
Controls whether to import knowledge bases from the template
  • true: Imports all knowledge bases with their documents and files (if included in template)
  • false: Imports only agent configuration without knowledge bases

​
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
​
origin_template
string
UUID of the template this agent was imported from
​
deployment_type
string
Deployment infrastructure: serverless or container
​
organization_id
string
UUID of your organization
​
instructions
object
System instructions configuration inherited from template
​
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)
​
knowledge_bases
array
Array of imported knowledge bases (if with_knowledge_bases: true)
​
created_at
string
ISO 8601 timestamp of when the agent was created

​
Example Requests

​
Basic Import

curl -X POST -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Support Agent",
    "description": "Customer support agent from template",
    "icon": "🎧",
    "with_knowledge_bases": true
  }' \
  https://api.xpander.ai/v1/agents/template_import/<template-id>

​
Import Without Knowledge Bases

curl -X POST -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent Framework",
    "description": "Will add custom knowledge bases later",
    "with_knowledge_bases": false
  }' \
  https://api.xpander.ai/v1/agents/template_import/<template-id>

​
Example Response

{
  "id": "<agent-id>",
  "name": "My Support Agent",
  "description": "Customer support agent from template",
  "icon": "🎧",
  "status": "ACTIVE",
  "origin_template": "<template-id>",
  "organization_id": "<org-id>",
  "deployment_type": "serverless",
  "created_at": "2026-02-07T10:30:00.000000Z",
  "instructions": {
    "role": ["Customer support specialist"],
    "goal": ["Resolve customer issues efficiently"],
    "general": "Be helpful and professional"
  },
  "model_provider": "openai",
  "model_name": "gpt-4.1",
  "framework": "agno",
  "knowledge_bases": [
    {
      "id": "<kb-id>",
      "name": "Product Documentation",
      "description": "Product guides and FAQs"
    }
  ],
  "tools": [],
  "graph": []
}

​
Import Behavior

When importing a template:
  1. New Agent Created: A completely independent agent instance is created in your organization
  2. Configuration Copied: All agent settings, instructions, and behavior are replicated
  3. Sub-Agents Recreated: Complete agent hierarchy is maintained with new instances
  4. Knowledge Bases: Documents are copied to your organization (if included and with_knowledge_bases: true)
  5. Tools & Connectors: Tool configurations are preserved - you’ll need to provide credentials
  6. Independence: Changes to the imported agent won’t affect the source agent or template

​
Notes

  • Cross-Organization Support: Templates can be imported from any organization - share the template ID
  • Customization: You can modify the agent name, description, and icon during import
  • Tool Setup: After import, configure credentials for any tools that require authentication
  • Knowledge Bases: If the template was exported without knowledge bases, with_knowledge_bases: true has no effect
  • Origin Tracking: The origin_template field tracks which template was used for import

​
Next Steps

After importing an agent:
  1. Update agent configuration using Update Agent if needed
  2. Configure tool credentials if the agent uses external tools
  3. Deploy the agent using Deploy Agent
  4. Test the agent with sample tasks

​
See Also

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
template_id
string
required

Body

application/json
​
name
string
required
​
description
string | null
​
icon
string | null
​
with_knowledge_bases
boolean | null

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