Skip to main content
GET
/
v1
/
agents
/
{agent_id}
Get Agent
curl --request GET \
  --url https://api.xpander.ai/v1/agents/{agent_id} \
  --header 'x-api-key: <api-key>'
{
  "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": [
    "<string>"
  ],
  "is_latest": true,
  "name": "<string>",
  "framework": "<string>",
  "description": "<string>",
  "tools": [
    "<any>"
  ],
  "icon": "<string>",
  "avatar": "<string>",
  "source_nodes": [
    {
      "id": "<string>",
      "type": "workbench",
      "targets": [
        "<string>"
      ],
      "metadata": {}
    }
  ],
  "attached_tools": [
    {
      "id": "<string>",
      "operation_ids": [
        "<string>"
      ]
    }
  ],
  "access_scope": "personal",
  "instructions": {
    "role": [
      "<string>"
    ],
    "goal": [
      "<string>"
    ],
    "general": "<string>"
  },
  "oas": {},
  "graph": [
    {
      "id": "<string>",
      "item_id": "<string>",
      "name": "<string>",
      "type": "source_node",
      "sub_type": "sdk",
      "targets": [
        "<string>"
      ],
      "settings": {
        "instructions": "<string>",
        "description": "<string>",
        "schemas": {
          "input": {},
          "output": {}
        },
        "advanced_filtering_options": {
          "returnables": [
            "<string>"
          ],
          "searchables": [
            "<string>"
          ],
          "globally_enabled": true
        },
        "hitl_options": {
          "title": "<string>",
          "description": "<string>",
          "recipients": [
            "<string>"
          ],
          "hitl_type": "slack",
          "slack_app": "<string>",
          "should_approve_with_current_user": true
        },
        "a2a_options": {
          "url": "<string>"
        },
        "coding_agent_settings": {
          "type": "<string>"
        },
        "mcp_settings": {
          "type": "local",
          "name": "<string>",
          "command": "<string>",
          "url": "<string>",
          "transport": "stdio",
          "auth_type": "api_key",
          "api_key": "<string>",
          "headers": {},
          "env_vars": {},
          "allowed_tools": [
            "<string>"
          ]
        },
        "use_cache": true
      },
      "llm_settings": [
        {
          "type": "before",
          "provider": "<string>",
          "model": "<string>",
          "temperature": 123
        }
      ],
      "is_first": true
    }
  ],
  "llm_settings": [
    {
      "type": "before",
      "provider": "<string>",
      "model": "<string>",
      "temperature": 123
    }
  ],
  "status": "DRAFT",
  "knowledge_bases": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "strategy": "vanilla",
      "rw": true,
      "documents": [
        "<string>"
      ]
    }
  ],
  "version": 123,
  "organization_id": "<string>",
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "type": "manager",
  "delegation_type": "router",
  "delegation_memory_strategy": "full",
  "is_ai_employee": true,
  "using_nemo": true,
  "deletable": true,
  "model_provider": "openai",
  "model_name": "<string>",
  "llm_api_base": "<string>",
  "output_format": "text",
  "output_schema": {},
  "llm_credentials_key": "<string>",
  "llm_credentials_key_type": "xpander",
  "llm_credentials": {
    "name": "<string>",
    "description": "<string>",
    "value": "<string>"
  },
  "expected_output": "<string>",
  "agno_settings": {
    "session_storage": true,
    "user_memories": true,
    "session_summaries": true,
    "num_history_runs": 123,
    "max_tool_calls_from_history": 123,
    "tool_call_limit": 123,
    "coordinate_mode": true,
    "pii_detection_enabled": true,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": true,
    "openai_moderation_enabled": true,
    "openai_moderation_categories": [
      "<string>"
    ]
  },
  "on_prem_event_streaming": true,
  "prompts_caching_enabled": true,
  "is_generalist": true,
  "webhook_url": "<string>"
}
Get complete details about an agent including configuration, deployment status, and metadata.

​
Path Parameters

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

​
Response

​
id
string
Unique identifier for the agent (UUID)
​
name
string
Display name of the agent
​
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 type: 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, gpt-4o-mini)
​
framework
string
Agent framework used (e.g., agno)
​
created_at
string
ISO 8601 timestamp of when the agent was created
​
using_nemo
boolean
Whether the agent uses Nvidia NeMo
​
is_coordinate_mode
boolean
Whether the agent operates in coordinate mode
​
origin_template
string | null
Reference to the original template used to create the agent, if any
​
delegation_end_strategy
string
Strategy for ending delegation workflows (e.g., return-to-start)
​
environment_id
string
UUID of the environment this agent operates in
​
sub_agents_continuous_thread
boolean
Whether sub-agents maintain a continuous conversation thread
​
created_by_prompt
string | null
The prompt used to create this agent, if created via prompt
​
prompts
array
Array of example prompts that demonstrate the agent’s capabilities
​
is_latest
boolean
Whether this is the latest version of the agent
​
description
string
Detailed description of the agent’s purpose and capabilities
​
tools
array
Array of tools available to the agent
​
source_nodes
array
Array of source integration nodes
​
attached_tools
array
Array of externally attached tool configurations
​
access_scope
string
Access control scope: organizational, team, private
​
expected_output
string
Description of the expected output format and content from the agent
​
version
number
Version number of the agent configuration
​
created_by
string
UUID of the user who created this agent
​
delegation_memory_strategy
string
Memory strategy for delegation: summarization, full, etc.
​
is_ai_employee
boolean
Whether this agent is configured as an AI employee
​
deletable
boolean
Whether the agent can be deleted
​
llm_api_base
string | null
Custom API base URL for LLM requests, if configured
​
output_format
string
Format of the agent’s output: markdown, json, etc.
​
output_schema
object | null
JSON schema for structured output, if configured
​
llm_credentials_key
string | null
Reference to LLM credentials, if using custom credentials
​
llm_credentials_key_type
string
Type of credentials: xpander, custom, etc.
​
llm_credentials
object | null
Custom LLM credentials object, if configured
​
agno_settings
object
Agno framework-specific settings
​
on_prem_event_streaming
boolean
Whether on-premises event streaming is enabled
​
prompts_caching_enabled
boolean
Whether prompt caching is enabled for performance
​
is_generalist
boolean
Whether this is a generalist agent (vs. specialized)
​
oas
object
OpenAPI Specification for the agent’s capabilities
​
graph
array
Visual graph representation of agent’s tool and MCP connections
​
llm_settings
array
Array of LLM configuration settings
​
webhook_url
string
Webhook URL for asynchronous notifications

​
Example Request

curl -X GET -H "x-api-key: YOUR_API_KEY" \
  https://api.xpander.ai/v1/agents/0045cf07-8af6-4c69-8d13-0a13c631a5d0

​
Example Response

{
  "id": "3496ccfc-4547-4142-8fc2-b35c9a1c201d",
  "unique_name": "bronze-condor",
  "origin_template": null,
  "delegation_end_strategy": "return-to-start",
  "environment_id": "11968157-c0ed-4b8a-a05e-be1d4bb2e922",
  "sub_agents_continuous_thread": true,
  "deployment_type": "serverless",
  "created_by_prompt": null,
  "prompts": [
    "Give me NVDA's latest earnings post-mortem with transcript highlights",
    "Create a notebook template for earnings drift analysis",
    "Decompose the last 24 hours' global risk-on/off rotation and its triggers",
    "What surprised the market this morning, not what was expected?",
    "Find sectors with consensus revisions up but prices flat",
    "List upcoming earnings in the next three days for my watchlist"
  ],
  "is_latest": true,
  "name": "Finance Agent",
  "framework": "agno",
  "description": "",
  "tools": [
    {
      "id": "XpanderDocTransformConvertMarkdownToPDF",
      "name": "Markdown to PDF Converter",
      "raw_description": "Converts Markdown content into a high-quality PDF file using advanced document transformation techniques.",
      "function_description": "Converts Markdown content into a high-quality PDF file using advanced document transformation techniques.",
      "path_params": {},
      "query_params": {},
      "body_schema": {
        "markdown_text": {
          "title": "Markdown Text",
          "type": "string",
          "example": "# Sample Markdown\n\nThis is a sample markdown text."
        }
      },
      "parameters": {
        "type": "object",
        "properties": {
          "query_params": {"type": "object", "properties": {}, "required": []},
          "path_params": {"type": "object", "properties": {}, "required": []},
          "body_params": {
            "type": "object",
            "properties": {
              "markdown_text": {"type": "string", "description": "markdown_text"}
            },
            "required": ["markdown_text"]
          },
          "headers": {
            "type": "object",
            "properties": {
              "toolcallreasoningtitle": {"type": "string"},
              "toolcallreasoningdescription": {"type": "string"}
            },
            "required": ["toolcallreasoningtitle", "toolcallreasoningdescription"]
          }
        },
        "required": ["query_params", "path_params", "body_params", "headers"]
      },
      "method": "post",
      "path": "/operation/XpanderDocTransformConvertMarkdownToPDF/transformers/markdown_to_pdf"
    }
  ],
  "icon": "🚀",
  "avatar": "male-avatar",
  "source_nodes": [
    {
      "id": "f1ad7f5b-c289-4195-bf40-d126e0205738",
      "type": "assistant",
      "targets": null,
      "metadata": {}
    },
    {
      "id": "9d0f63f5-6022-4a76-b3cd-fe6ea8cc2adf",
      "type": "sdk",
      "targets": null,
      "metadata": {}
    }
  ],
  "attached_tools": [
    {
      "id": "8904cc9f-a3f2-4e8e-8123-036dbaecb951",
      "operation_ids": ["68259fd3ff1266b1d6022ef0", "68259fd3ff1266b1d6022eef"]
    }
  ],
  "access_scope": "organizational",
  "instructions": {
    "role": [
      "Maintain a formal, concise, and professional tone at all times.",
      "Provide only evidence-backed financial analytics and explanations."
    ],
    "goal": [
      "Deliver accurate, explainable, and timely financial insights across multiple asset classes.",
      "Ensure all outputs include clear citations, assumptions, and audit trails."
    ],
    "general": "I am an institutional-grade Finance and Markets Analysis Agent."
  },
  "oas": {
    "info": {"title": "App", "version": "1.0.0"},
    "paths": {
      "/3496ccfc-4547-4142-8fc2-b35c9a1c201d": {
        "get": {
          "description": "This operation processes finance-related tasks.",
          "operationId": "XpanderProcessFinanceTasks"
        }
      }
    },
    "openapi": "3.1.0"
  },
  "graph": [
    {
      "id": "81a03e79-e8af-4862-a23e-83f6f6c62357",
      "item_id": "7128d3b3-799b-4525-847e-ed966b674ec2",
      "name": "MCP",
      "type": "mcp",
      "sub_type": null,
      "targets": [],
      "settings": {
        "mcp_settings": {
          "type": "remote",
          "name": "Alpha Vantage",
          "url": "https://mcp.alphavantage.co/mcp",
          "transport": "streamable-http"
        }
      },
      "llm_settings": [],
      "is_first": false
    }
  ],
  "llm_settings": [
    {
      "type": "before",
      "provider": "openai",
      "model": "gpt-4.1",
      "temperature": 0.0
    }
  ],
  "status": "ACTIVE",
  "knowledge_bases": [],
  "version": 24,
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "created_by": "c9b4465d-0795-4493-9a23-8fc7cf6d3283",
  "created_at": "2025-11-09T03:42:35.016813Z",
  "type": "manager",
  "delegation_type": "router",
  "delegation_memory_strategy": "summarization",
  "is_ai_employee": false,
  "using_nemo": false,
  "deletable": true,
  "model_provider": "openai",
  "model_name": "gpt-5",
  "llm_api_base": null,
  "output_format": "markdown",
  "output_schema": null,
  "llm_credentials_key": null,
  "llm_credentials_key_type": "xpander",
  "llm_credentials": null,
  "expected_output": "A concise, structured financial analysis report with evidence-backed insights.",
  "agno_settings": {
    "session_storage": true,
    "user_memories": true,
    "session_summaries": true,
    "num_history_runs": 10,
    "max_tool_calls_from_history": 0,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": true,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": true,
    "openai_moderation_enabled": false,
    "openai_moderation_categories": [""]
  },
  "on_prem_event_streaming": true,
  "prompts_caching_enabled": false,
  "is_generalist": false,
  "webhook_url": "https://webhook.xpander.ai/?agent_id=3496ccfc-4547-4142-8fc2-b35c9a1c201d&asynchronous=false"
}

​
Common Use Cases

​
Extracting Agent Configuration Details

Get comprehensive agent information including tools, settings, and webhook URLs: 
import requests

API_KEY = 'your-api-key'
BASE_URL = 'https://api.xpander.ai/v1'

def get_agent_config(agent_id: str):
  response = requests.get(
    f'{BASE_URL}/agents/{agent_id}',
    headers={'x-api-key': API_KEY}
  )

  agent = response.json()

  # Extract key configuration
  config = {
    'name': agent['name'],
    'status': agent['status'],
    'webhook_url': agent['webhook_url'],
    'model': f"{agent['model_provider']}/{agent['model_name']}",
    'framework': agent['framework'],
    'version': agent['version'],
    'tools_count': len(agent['tools']),
    'deployment': agent['deployment_type']
  }

  return config

# Example usage
config = get_agent_config('3496ccfc-4547-4142-8fc2-b35c9a1c201d')
print(config)
Example Output: 
{
  "name": "Finance Agent",
  "status": "ACTIVE",
  "webhook_url": "https://webhook.xpander.ai/?agent_id=3496ccfc-4547-4142-8fc2-b35c9a1c201d&asynchronous=false",
  "model": "openai/gpt-5",
  "version": 25
}

​
Retrieving Agent Tools and Capabilities

Inspect available tools and their configurations for integration planning: 
def list_agent_tools(agent_id: str):
  response = requests.get(
    f'{BASE_URL}/agents/{agent_id}',
    headers={'x-api-key': API_KEY}
  )

  agent = response.json()

  print(f"Agent: {agent['name']}")
  print(f"Total Tools: {len(agent['tools'])}\n")

  for tool in agent['tools']:
    print(f"📦 {tool['name']}")
    print(f"   ID: {tool['id']}")
    print(f"   Method: {tool['method'].upper()}")
    print(f"   Path: {tool['path']}")
    print(f"   Description: {tool['raw_description'][:100]}...")
    print()

# Example usage
list_agent_tools('3496ccfc-4547-4142-8fc2-b35c9a1c201d')

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
agent_id
string
required

Response

​
name
string
required
​
organization_id
string
required
​
webhook_url
string
required
​
id
string | null
​
unique_name
string | null
​
origin_template
string | null
​
delegation_end_strategy
enum<string> | null
default:return-to-start
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
​
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:organizational
Available options:
personal,
organizational
​
instructions
object | null
​
oas
object | null
​
graph
AIAgentGraphItem · object[] | null
​
llm_settings
AIAgentGraphItemLLMSettings · object[] | null
​
status
enum<string> | null
default:ACTIVE
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
Available options:
manager,
regular
​
delegation_type
enum<string> | null
default:router
Available options:
router,
sequence
​
delegation_memory_strategy
enum<string> | null
default:summarization
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:openai
Available options:
openai,
nim,
amazon_bedrock,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks
​
model_name
string | null
default:gpt-4.1
​
llm_api_base
string | null
​
output_format
enum<string> | null
default:markdown
Available options:
text,
markdown,
json
​
output_schema
object | null
​
llm_credentials_key
string | null
​
llm_credentials_key_type
enum<string> | null
default:xpander
Available options:
xpander,
custom
​
llm_credentials
object | null
​
expected_output
string | null
default:""
​
agno_settings
object | null
​
on_prem_event_streaming
boolean | null
default:true
​
prompts_caching_enabled
boolean | null
default:false
​
is_generalist
boolean | null
default:false