Get Agent

Returns the complete agent object including its tools with full schemas, the tool graph with customized input/output schemas, structured output schema, webhook URL, LLM settings, and all configuration details. This is the single source of truth for an agent’s current state.

Path Parameters

agent_id

string

required

Unique identifier of the agent (UUID format)

Response

Identity & Status

string

Agent UUID

unique_name

string

Auto-generated URL-safe slug (e.g., emerald-emu). Assigned on creation.

name

string

Display name

description

string

Auto-generated on deploy from instructions. Describes what the agent does.

icon

string

Emoji icon (e.g., 🚀)

avatar

string

Avatar identifier (e.g., male-avatar)

status

string

ACTIVE (deployed) or INACTIVE (not yet deployed)

version

integer

Increments on each deploy

deletable

boolean

Whether the agent can be deleted via the API

organization_id

string

Owning organization UUID

created_by

string | null

UUID of the user who created the agent

created_at

string

ISO 8601 timestamp

Instructions

instructions

object

System instructions that define the agent’s behavior. Divided into three sections.

Show Instructions Object

role

string[]

Array of role statements. The agent’s identity, rules, and domain knowledge.

goal

string[]

Array of goal statements. What the agent should accomplish.

general

string

Free-form general system prompt.

expected_output

string

Describes the desired output format in natural language (e.g., "Short answer, formatted in rich markdown text.").

Model Configuration

model_provider

string

LLM provider: openai, anthropic, bedrock, gemini, etc.

model_name

string

Model identifier (e.g., gpt-5.2, claude-sonnet-4-5-20250929)

llm_reasoning_effort

string

Reasoning effort level: low, medium, or high

llm_api_base

string | null

Custom LLM API base URL. null for default provider endpoints.

llm_settings

array

Model overrides. Each entry can set a different provider/model for specific pipeline stages.

Show LLM Settings Entry

type

string

Pipeline stage: before, after, etc.

provider

string

Provider name (e.g., openai, anthropic)

model

string

Model name (e.g., gpt-5.2)

temperature

number

Sampling temperature (0.0 – 2.0)

Structured Output

output_format

string

Response format: text, json, or markdown

output_schema

object | null

When output_format is json, this is a full JSON Schema that the agent’s output must conform to. Includes $schema, type, required, properties with types, descriptions, validations, and nested objects/arrays.

Show Example: Company Details Schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Registered or trading name of the company."
    },
    "industry": {
      "type": "string",
      "description": "Industry classification or sector."
    },
    "website": {
      "type": "string",
      "format": "uri",
      "description": "Company website URL."
    },
    "contact": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "phone": { "type": "string" }
      }
    },
    "status": {
      "enum": ["active", "inactive", "suspended", "closed"],
      "type": "string"
    }
  },
  "additionalProperties": false
}

Tools

tools

array

The fully-resolved tool definitions available to this agent. Each tool includes its operation ID, HTTP method, path, and complete request schemas (body_schema and parameters). These are the actual tool-calling interfaces the LLM sees at runtime.

Show Tool Object

string

Operation ID (e.g., TavilySearchServiceExecuteQueryAndReturnResults). This matches item_id in the graph.

name

string

Extended description of the tool’s purpose and workflow context.

raw_description

string

Original tool description from the toolkit source.

function_description

string

Description passed to the LLM as the function docstring.

method

string

HTTP method: get, post, put, delete, patch

path

string

Endpoint path (e.g., /operation/TavilySearchServiceExecuteQueryAndReturnResults/search)

body_schema

object

Flat map of body parameter definitions. Each key is a parameter name, value is its JSON Schema with type, description, default, enum, minimum, maximum, etc.

path_params

object

Path parameter definitions (often empty {})

query_params

object

Query parameter definitions (often empty {})

parameters

object

The structured function-calling schema sent to the LLM. Contains query_params, path_params, body_params, and headers objects.

Show Parameters Structure

body_params

object

properties map with each parameter’s type and description. required array lists mandatory fields.

headers

object

Includes toolcallreasoningtitle and toolcallreasoningdescription — metadata the LLM provides when calling the tool to explain its reasoning.

Tool Graph

graph

array

The agent’s tool graph — defines how tools are wired together, with optional custom schemas, descriptions, and routing targets. Graph items can override the default tool schemas to lock parameters, customize descriptions, or define expected output formats.

Show Graph Item

string

Graph node UUID

item_id

string

References the tool’s id in the tools array (operation ID)

name

string

Display name for this graph node (e.g., "Search Mintlify Documentation")

type

string

Node type: tool, mcp, or agent

sub_type

string | null

Sub-classification (if applicable)

targets

string[]

Array of graph node ids this tool can call next. Self-references allow looping. Empty array [] means terminal node.

is_first

boolean

Whether this is the entry-point tool in the graph

llm_settings

array

Per-node LLM overrides (same structure as top-level llm_settings)

settings

object | null

Customization layer for this graph node. null if using defaults.

Show Graph Node Settings

description

string | null

Custom description override for this tool in this graph context

instructions

string | null

Additional instructions for the LLM when using this tool

use_cache

boolean

Whether to cache tool results for repeated calls

schemas

object | null

Custom input/output schema overrides

Show Schema Overrides

input

object

Custom JSON Schema for the tool input. Can include permanentValue on fields to lock a parameter to a fixed value (e.g., always search a specific subdomain).

output

object

Custom JSON Schema describing the expected output format from this tool.

hitl_options

object | null

Human-in-the-loop configuration (approval requirements)

a2a_options

object | null

Agent-to-agent delegation options

mcp_settings

object | null

MCP-specific settings when type is mcp

Attached Tools (Toolkit References)

attached_tools

array

References to which toolkits and specific operations are attached to this agent. This maps toolkit UUIDs to the operation IDs selected from each toolkit.

Show Attached Tool Entry

string

Toolkit UUID

operation_ids

string[]

Array of operation IDs from that toolkit that are enabled for this agent

Webhook & Entry Points

webhook_url

string

Auto-generated webhook endpoint for this agent. Accepts POST requests to trigger agent tasks. Includes agent_id and asynchronous query parameters.

See the Webhook documentation for payload format, authentication, and async/sync modes.

source_nodes

array

Entry points through which this agent can be invoked.

Show Source Node

string

Node UUID

type

string

Entry point type: assistant (chat widget), sdk (Python/JS SDK), or webhook

targets

array | null

Downstream graph targets (usually null)

metadata

object

Additional metadata for this entry point

Agent Framework Settings

framework

string

Agent framework (e.g., agno)

type

string

Agent type: manager or worker

delegation_type

string

Delegation strategy: router, sequential, etc.

delegation_end_strategy

string

What happens when delegation completes: return-to-start, etc.

delegation_memory_strategy

string

How delegated context is managed: summarization, full, etc.

deployment_type

string

Infrastructure: serverless or container

agno_settings

object

Framework-level configuration for the Agno runtime.

Show Agno Settings

session_storage

boolean

Enable session persistence across turns

agent_memories

boolean

Allow agent to store long-term memories

user_memories

boolean

Allow per-user memory storage

session_summaries

boolean

Auto-summarize sessions

num_history_runs

integer

Number of previous runs to include in context

tool_call_limit

integer

Max tool calls per run (0 = unlimited)

coordinate_mode

boolean

Enable multi-agent coordination

pii_detection_enabled

boolean

PII detection on inputs

pii_detection_mask

boolean

Mask detected PII

prompt_injection_detection_enabled

boolean

Detect prompt injection attacks

openai_moderation_enabled

boolean

OpenAI content moderation

openai_moderation_categories

string[] | null

Moderation categories to check (e.g., ["hate", "harassment", "sexual", "violence"])

reasoning_tools_enabled

boolean

Enable chain-of-thought reasoning tools

tool_calls_compression

object

Compress tool call history to save context window

Show Compression Settings

enabled

boolean

Compression active

threshold

integer

Compress after N tool calls

instructions

string

Custom compression instructions

Knowledge Bases

knowledge_bases

array

Array of knowledge base IDs attached to this agent. Empty [] if none attached.

Knowledge bases and tools are attached to agents through the xpander.ai dashboard or Python SDK — not via the REST API PATCH endpoint.

Other Fields

access_scope

string

personal or organizational

is_latest

boolean

Whether this is the latest version of the agent

has_pending_changes

boolean

Whether there are undeployed changes

deep_planning

boolean

Deep planning mode enabled

sub_agents_continuous_thread

boolean

Sub-agents share the conversation thread

on_prem_event_streaming

boolean

Server-sent events for on-prem deployments

prompts_caching_enabled

boolean

LLM prompt caching

notification_settings

object

Webhook notifications on task success/error

task_level_strategies

object

Task retry, iteration, and rate-limit strategies

Example Request

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>"

Example Response

The response is the complete agent configuration. Below is a condensed example showing the key structures — a real response includes full tool schemas and may be 1000+ lines.

{
  "id": "<agent-id>",
  "unique_name": "emerald-emu",
  "name": "Product Specialist",
  "description": "Processes queries to provide comprehensive product information...",
  "icon": "🚀",
  "avatar": "male-avatar",
  "status": "ACTIVE",
  "version": 78,
  "organization_id": "<org-id>",
  "created_by": "<user-id>",
  "created_at": "2026-02-05T18:54:51.388334Z",
  "deployment_type": "serverless",
  "framework": "agno",
  "type": "manager",
  "delegation_type": "router",
  "deletable": true,

  "instructions": {
    "role": [
      "You are a product specialist assistant",
      "Search the knowledge base before answering product questions"
    ],
    "goal": [
      "Help customers understand product features",
      "Provide accurate, sourced answers"
    ],
    "general": "You are a support agent. Use tools to answer questions accurately."
  },
  "expected_output": "Short answer, formatted in rich markdown text.",

  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929",
  "llm_reasoning_effort": "medium",
  "llm_api_base": null,
  "llm_settings": [
    {
      "type": "before",
      "provider": "openai",
      "model": "gpt-5.2",
      "temperature": 0.0
    }
  ],

  "output_format": "json",
  "output_schema": {
    "type": "object",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "required": ["name"],
    "properties": {
      "name": {
        "type": "string",
        "minLength": 1,
        "description": "Company name."
      },
      "industry": {
        "type": "string",
        "description": "Industry sector."
      },
      "website": {
        "type": "string",
        "format": "uri"
      }
    },
    "additionalProperties": false
  },

  "tools": [
    {
      "id": "TavilySearchServiceExecuteQueryAndReturnResults",
      "name": "Executes a search query using Tavily AI...",
      "raw_description": "Executes a search query using Tavily AI...",
      "function_description": "Executes a search query using Tavily AI...",
      "method": "post",
      "path": "/operation/TavilySearchServiceExecuteQueryAndReturnResults/search",
      "path_params": {},
      "query_params": {},
      "body_schema": {
        "query": {
          "type": "string",
          "description": "The search query to execute.",
          "example": "who is Leo Messi?"
        },
        "max_results": {
          "type": "integer",
          "minimum": 0,
          "maximum": 20,
          "default": 5
        },
        "search_depth": {
          "type": "string",
          "enum": ["basic", "advanced"],
          "default": "basic"
        },
        "topic": {
          "type": "string",
          "enum": ["general", "news"],
          "default": "general"
        }
      },
      "parameters": {
        "type": "object",
        "properties": {
          "body_params": {
            "type": "object",
            "properties": {
              "query": { "type": "string", "description": "The search query." }
            },
            "required": ["query"]
          },
          "path_params": { "type": "object", "properties": {} },
          "query_params": { "type": "object", "properties": {} },
          "headers": {
            "type": "object",
            "properties": {
              "toolcallreasoningtitle": {
                "type": "string",
                "description": "Action title (max 5 words)"
              },
              "toolcallreasoningdescription": {
                "type": "string",
                "description": "One-sentence summary (max 100 chars)"
              }
            }
          }
        },
        "required": ["body_params", "path_params", "query_params", "headers"]
      }
    },
    {
      "id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Sends an email with HTML body content...",
      "method": "post",
      "path": "/operation/XpanderEmailServiceSendEmailWithHtmlOrTextContent/messaging/send_email",
      "body_schema": {
        "to": { "type": "array", "items": { "type": "string" } },
        "subject": { "type": "string" },
        "body_html": { "type": "string" }
      },
      "parameters": { "..." : "..." }
    }
  ],

  "graph": [
    {
      "id": "<graph-node-id>",
      "item_id": "TavilySearchServiceExecuteQueryAndReturnResults",
      "name": "Execute Search Query and Retrieve Results",
      "type": "tool",
      "sub_type": null,
      "targets": ["<self-id>"],
      "is_first": false,
      "llm_settings": [],
      "settings": {
        "description": "Search the web for relevant results...",
        "instructions": null,
        "use_cache": true,
        "schemas": {
          "input": {
            "type": "object",
            "required": ["query_params", "path_params", "body_params"],
            "properties": {
              "body_params": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string", "description": "The search query." }
                }
              }
            }
          },
          "output": {
            "type": "object",
            "properties": {
              "query": { "type": "string" },
              "results": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string" },
                    "title": { "type": "string" },
                    "content": { "type": "string" },
                    "score": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "id": "<graph-node-id>",
      "item_id": "MintlifySearchEngineSearchDocsBySubdomainAndQuery",
      "name": "Search Mintlify Documentation by Subdomain and Query",
      "type": "tool",
      "targets": ["<self-id>"],
      "settings": {
        "description": "Search in docs.xpander.ai for documentation",
        "use_cache": true,
        "schemas": {
          "input": {
            "type": "object",
            "properties": {
              "body_params": {
                "properties": {
                  "subdomain": {
                    "type": "string",
                    "permanentValue": "docs.xpander.ai"
                  },
                  "query": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    {
      "id": "<graph-node-id>",
      "item_id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "type": "tool",
      "targets": [],
      "settings": null
    }
  ],

  "attached_tools": [
    {
      "id": "<toolkit-id-1>",
      "operation_ids": ["68259fd3ff1266b1d6022eef"]
    },
    {
      "id": "<toolkit-id-2>",
      "operation_ids": ["6910a209b1c2df0f90058ca8"]
    },
    {
      "id": "<toolkit-id-3>",
      "operation_ids": [
        "68230439d76e61ed7e92e4c3",
        "68230439d76e61ed7e92e4c2"
      ]
    }
  ],

  "webhook_url": "https://webhook.xpander.ai/?agent_id=<agent-id>&asynchronous=false",

  "source_nodes": [
    { "id": "<node-id>", "type": "assistant", "targets": null, "metadata": {} },
    { "id": "<node-id>", "type": "sdk", "targets": null, "metadata": {} },
    { "id": "<node-id>", "type": "webhook", "targets": null, "metadata": {} }
  ],

  "knowledge_bases": [],

  "agno_settings": {
    "session_storage": true,
    "agent_memories": false,
    "user_memories": false,
    "session_summaries": false,
    "num_history_runs": 20,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": false,
    "prompt_injection_detection_enabled": false,
    "openai_moderation_enabled": false,
    "reasoning_tools_enabled": false,
    "tool_calls_compression": {
      "enabled": false,
      "threshold": 3,
      "instructions": ""
    }
  },

  "access_scope": "organizational",
  "is_latest": true,
  "has_pending_changes": false,
  "deep_planning": false,
  "sub_agents_continuous_thread": true,
  "on_prem_event_streaming": true,
  "notification_settings": { "on_success": {}, "on_error": {} },
  "task_level_strategies": {
    "retry_strategy": null,
    "iterative_strategy": null,
    "stop_strategy": null,
    "max_runs_per_day": null
  }
}

Common Use Cases

Quick Status Check

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '{name, status, model: .model_name, provider: .model_provider, version, tools: (.tools | length)}'

{
  "name": "Product Specialist",
  "status": "ACTIVE",
  "model": "claude-sonnet-4-5-20250929",
  "provider": "anthropic",
  "version": 78,
  "tools": 4
}

List All Tool IDs and Paths

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.tools[] | {id, method, path}'

{"id": "TavilySearchServiceExecuteQueryAndReturnResults", "method": "post", "path": "/operation/.../search"}
{"id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent", "method": "post", "path": "/operation/.../send_email"}
{"id": "MintlifySearchEngineSearchDocsBySubdomainAndQuery", "method": "post", "path": "/operation/.../mintlify_search"}
{"id": "TavilyDataExtractionExtractContentFromUrls", "method": "post", "path": "/operation/.../extract"}

Extract the Output Schema

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.output_schema'

Get the Webhook URL

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.webhook_url'

"https://webhook.xpander.ai/?agent_id=<agent-id>&asynchronous=false"

Use the webhook_url to trigger agent tasks from external systems without the SDK. See the Webhook documentation for payload format, authentication, and how to switch between sync and async modes.

Inspect Graph Wiring

See how tools are connected and which have custom schemas:

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.graph[] | {name, type, item_id, targets, has_custom_schema: (.settings.schemas != null)}'

Extract Tool Body Schema for a Specific Tool

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.tools[] | select(.id == "TavilySearchServiceExecuteQueryAndReturnResults") | .body_schema'

Check Attached Toolkit References

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.attached_tools'

[
  { "id": "<toolkit-id>", "operation_ids": ["68259fd3ff1266b1d6022eef"] },
  { "id": "<toolkit-id>", "operation_ids": ["6910a209b1c2df0f90058ca8"] },
  { "id": "<toolkit-id>", "operation_ids": ["68230439d76e61ed7e92e4c3", "68230439d76e61ed7e92e4c2"] }
]

attached_tools maps toolkit UUIDs → operation IDs. To manage which tools are attached, use the xpander.ai dashboard or the Python SDK. The REST API PATCH endpoint does not support modifying attached_tools.

Authorizations

x-api-key

string

header

required

API Key for authentication

Path Parameters

agent_id

string

required

Response

Successful Response

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

Show child attributes

graph

AIAgentGraphItem · object[] | null

Show child attributes

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

Show child attributes

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)

Show child attributes

agno_settings

AgnoSettings · object

Agno framework settings (memory, session storage, moderation, tool limits)

Show child attributes

has_pending_changes

boolean

Whether the agent has unpublished configuration changes

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

Identity & Status

Instructions

Model Configuration

Structured Output

Tools

Tool Graph

Attached Tools (Toolkit References)

Webhook & Entry Points

Agent Framework Settings

Knowledge Bases

Other Fields

Example Request

Example Response

Common Use Cases

Quick Status Check

List All Tool IDs and Paths

Extract the Output Schema

Get the Webhook URL

Inspect Graph Wiring

Extract Tool Body Schema for a Specific Tool

Check Attached Toolkit References

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

​Identity & Status

​Instructions

​Model Configuration

​Structured Output

​Tools

​Tool Graph

​Attached Tools (Toolkit References)

​Webhook & Entry Points

​Agent Framework Settings

​Knowledge Bases

​Other Fields

​Example Request

​Example Response

​Common Use Cases

​Quick Status Check

​List All Tool IDs and Paths

​Extract the Output Schema

​Get the Webhook URL

​Inspect Graph Wiring

​Extract Tool Body Schema for a Specific Tool

​Check Attached Toolkit References

Authorizations

Path Parameters

Response

Path Parameters

Response

Identity & Status

Instructions

Model Configuration

Structured Output

Tools

Tool Graph

Attached Tools (Toolkit References)

Webhook & Entry Points

Agent Framework Settings

Knowledge Bases

Other Fields

Example Request

Example Response

Common Use Cases

Quick Status Check

List All Tool IDs and Paths

Extract the Output Schema

Get the Webhook URL

Inspect Graph Wiring

Extract Tool Body Schema for a Specific Tool

Check Attached Toolkit References