Get Agent

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

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

Show Instructions Object

role

array

Array of role descriptions

goal

array

Array of goal descriptions

general

string

General instructions text

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

Show Tool Object

string

Unique identifier for the tool

name

string

Display name of the tool

raw_description

string

Detailed description of the tool’s functionality

function_description

string

Description of what the function does

method

string

HTTP method (e.g., post, get)

path

string

API endpoint path for the tool

path_params

object

Path parameters schema

query_params

object

Query parameters schema

body_schema

object

Request body schema

parameters

object

Complete parameters definition including query, path, body, and headers

source_nodes

array

Array of source integration nodes

Show Source Node Object

string

UUID of the source node

type

string

Type of source: assistant, sdk, webhook, etc.

targets

array | null

Target nodes for this source

metadata

object

Additional metadata for the source node

attached_tools

array

Array of externally attached tool configurations

Show Attached Tool Object

string

UUID of the attached tool configuration

operation_ids

array

Array of operation IDs associated with this tool

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

Show Agno Settings

session_storage

boolean

Enable session storage

user_memories

boolean

Enable user memory persistence

session_summaries

boolean

Enable session summarization

num_history_runs

number

Number of historical runs to maintain

max_tool_calls_from_history

number

Maximum tool calls to retrieve from history

tool_call_limit

number

Limit on tool calls per session

coordinate_mode

boolean

Enable coordinate mode

pii_detection_enabled

boolean

Enable PII detection

pii_detection_mask

boolean

Mask detected PII

prompt_injection_detection_enabled

boolean

Enable prompt injection detection

openai_moderation_enabled

boolean

Enable OpenAI content moderation

openai_moderation_categories

array

Specific moderation categories to enforce

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

Show OAS Object

openapi

string

OpenAPI version (e.g., 3.1.0)

info

object

API metadata (title, version)

paths

object

API paths and operations

graph

array

Visual graph representation of agent’s tool and MCP connections

Show Graph Node Object

string

UUID of the graph node

item_id

string

Reference to the tool or MCP item

name

string

Display name of the node

type

string

Node type: tool, mcp, etc.

sub_type

string | null

Sub-type classification if applicable

targets

array

Connected target nodes

settings

object

Node-specific configuration settings

llm_settings

array

LLM configuration for this node

is_first

boolean

Whether this is the first node in execution

llm_settings

array

Array of LLM configuration settings

Show LLM Settings Object

type

string

Settings type: before, after, etc.

provider

string

LLM provider (e.g., openai)

model

string

Model identifier

temperature

number

Temperature parameter for generation

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

API Key for authentication

Path Parameters

agent_id

string

required

Response

Successful Response

name

string

required

organization_id

string

required

webhook_url

string

required

string | null

unique_name

string | null

origin_template

string | null

delegation_end_strategy

enum<string> | null

default:return-to-start

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.

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

Whether this is the latest version of the agent

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

Show child attributes

attached_tools

Connector · object[] | null

Show child attributes

access_scope

enum<string> | null

default:organizational

Available options:

personal,

organizational

instructions

object | null

Show child attributes

oas

object | null

graph

AIAgentGraphItem · object[] | null

Show child attributes

llm_settings

AIAgentGraphItemLLMSettings · object[] | null

Show child attributes

status

enum<string> | null

default:ACTIVE

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.

Available options:

DRAFT,

ACTIVE,

INACTIVE

knowledge_bases

AgentKnowledgeBase · object[] | null

Show child attributes

version

integer | null

default:1

created_by

string | null

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.

Available options:

manager,

regular

delegation_type

enum<string> | null

default:router

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.

Available options:

router,

sequence

delegation_memory_strategy

enum<string> | null

default:summarization

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

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

Show child attributes

expected_output

string | null

default:""

agno_settings

object | null

Show child attributes

on_prem_event_streaming

boolean | null

default:true

prompts_caching_enabled

boolean | null

default:false

is_generalist

boolean | null

default:false

Overview

REST API - Agents

REST API - Tasks

REST API - Knowledge

REST API - Toolkits

REST API - Misc

Python SDK - Core Modules

Python SDK - API Reference

CLI Reference

Path Parameters

Response

Example Request

Example Response

Common Use Cases

Extracting Agent Configuration Details

Retrieving Agent Tools and Capabilities

Authorizations

Path Parameters

Response

Overview

REST API - Agents

REST API - Tasks

REST API - Knowledge

REST API - Toolkits

REST API - Misc

Python SDK - Core Modules

Python SDK - API Reference

CLI Reference

​Path Parameters

​Response

​Example Request

​Example Response

​Common Use Cases

​Extracting Agent Configuration Details

​Retrieving Agent Tools and Capabilities

Authorizations

Path Parameters

Response

Path Parameters

Response

Example Request

Example Response

Common Use Cases

Extracting Agent Configuration Details

Retrieving Agent Tools and Capabilities