Agent - xpander.ai

Agent Class

The Agent class is the central component of the xpander SDK, representing an AI agent with capabilities for task execution, tool usage, and state management.

Retrieving an Agent

# Get an agent by ID
agent = client.agents.get(agent_id="agent-id-123")

Parameter	Type	Required	Description
`agent_id`	string	Yes	ID of the agent

Returns: Agent instance

Agent Properties

Core Properties

Property	Type	Description	Availability
`id`	string	Unique identifier for the agent	Always available
`name`	string	Name of the agent	Always available
`instructions`	object	System instructions for the agent	Always available
`metadata`	object	Contains metadata like description	Always available
`execution`	Execution	Current execution context	After adding a task
`messages`	List[Dict]	Conversation messages array	After initialization
`graph`	Graph	Workflow graph system	Always available
`tool_choice`	string	Setting for tool selection behavior	Always available

Configuration Properties

Property	Type	Description
`memory_type`	MemoryType	Type of memory (e.g., SHORT_TERM)
`memory_strategy`	MemoryStrategy	Strategy for memory management (e.g., FULL)
`end_tool_enabled`	boolean	Whether the xpfinish-agent-execution-finished tool is available to the model
`has_local_tools`	boolean	Whether agent has local tools attached
`access_scope`	AgentAccessScope	Access scope (e.g., ORGANIZATIONAL)
`delegation_type`	AgentDelegationType	Delegation type (e.g., ROUTER)
`knowledge_bases`	List	Connected knowledge bases
`organization_id`	string	ID of the organization owning the agent

Agent Core Methods

update() / update()

Updates agent properties on the server.

# Update agent instructions
agent.instructions.general = "You are a helpful research assistant."
agent.instructions.goal = "Find accurate information."
agent.instructions.role = "Research, summarize, explain."

# Apply changes
agent.update()

Returns: Updated Agent object

sync() / sync()

Synchronizes changes to the agent (operations, graph connections, etc.)

# Synchronize agent
agent.sync()

Returns: Updated Agent object

disable_agent_end_tool() / disableAgentEndTool()

Disables the xpfinish-agent-execution-finished tool so the model cannot decide when to finish the task. When disabled, you can implement your own end logic or rely on the task ending once the model stops producing tool calls.

# Disable the xpfinish-agent-execution-finished function
agent.disable_agent_end_tool()

Returns: void

update_user_details() / updateUserDetails()

Updates user details associated with the agent.

# Update user details
agent.update_user_details({
    "user_id": "user123",
    "name": "John Doe",
    "email": "john@example.com"
})

Parameter	Type	Required	Description
`user_details`	object	Yes	User information

Returns: void

retrieve_node_from_graph() / retrieveNodeFromGraph()

Retrieves a node from the agent’s graph by its ID.

# Get a node from the graph
node = agent.retrieve_node_from_graph("tool-id-123")

Parameter	Type	Required	Description
`item_id`	string	Yes	ID of the graph node

Returns: GraphItem object or undefined if not found

enable_agent_end_tool() / enableAgentEndTool()

Allows the model to finish a task by calling the xpfinish-agent-execution-finished function. Use this when you want the LLM to decide when it has completed all required steps.

# Enable the xpfinish-agent-execution-finished function
agent.enable_agent_end_tool()

Returns: void

init_task() / initTask()

Starts a new task execution for the agent.

execution = agent.init_task(execution=execution_obj)

Parameter	Type	Required	Description
`execution`	Execution	Yes	Execution details to start

Returns: Execution object

report_execution_metrics() / reportExecutionMetrics()

Report token usage metrics for the current execution.

agent.report_execution_metrics(llm_tokens)

Parameter	Type	Required	Description
`llm_tokens`	Tokens	Yes	Token counts to report
`ai_model`	string	No	Model identifier
`source_node_type`	string	No	Source node type if relevant

Returns: void

report_llm_usage() / reportLlmUsage()

Send raw LLM usage statistics to xpander.ai.

agent.report_llm_usage(llm_response)

Parameter	Type	Required	Description
`llm_response`	any	Yes	LLM response payload
`llm_inference_duration`	number	No	Inference time in ms
`llm_provider`	LLMProvider	No	Provider name
`source_node_type`	string	No	Source node type

Returns: void

select_llm_provider() / selectLLMProvider()

Specify which LLM provider the agent should use.

agent.select_llm_provider(llm_provider=LLMProvider.OPEN_AI)

Parameter	Type	Required	Description
`llm_provider`	LLMProvider	Yes	Provider to set for requests

Returns: void

stop() / stop()

Gracefully stop the agent’s current execution without reporting a result.

agent.stop()

Returns: void

stop_execution() / stopExecution()

Stop execution and report a final result to the controller.

agent.stop_execution(is_success=True, result="Task complete")

Parameter	Type	Required	Description
`is_success`	boolean	Yes	Whether the task succeeded
`result`	string	No	Optional result string to send back

Returns: void

This method triggers the xpfinish-agent-execution-finished function internally. When stopping an agent due to a step limit you can call:

agent.stop_execution(
    is_success=False,
    result="This request was terminated automatically after reaching the agent's maximum step limit. Try breaking it into smaller, more focused requests."
)

Type Definitions

Instructions

interface Instructions {
  general: string;   // General instructions
  goal: string;      // Goal instructions
  role: string;      // Role instructions
}

Metadata

interface Metadata {
  description?: string;  // Agent description
  created_at: string;    // Creation timestamp
  updated_at: string;    // Last update timestamp
  llm_model?: string;    // Associated LLM model
}

UserDetails

interface UserDetails {
  userId: string;    // User ID
  name?: string;     // User name
  email?: string;    // User email
  role?: string;     // User role
}

Usage Example

from xpander_sdk import XpanderClient
import os

# Initialize client
client = XpanderClient(api_key=os.environ["XPANDER_API_KEY"])

# Get an agent
agent = client.agents.get(agent_id="agent-123")

# Update instructions
agent.instructions.general = "You are a research assistant."
agent.update()

Agent.Messages

Working with agent messages

Agent.Tools

Using agent tools and function calling

Tasks

Managing agent tasks

Agent.Graph

Working with knowledge graphs

LLMMetrics

Recording token usage metrics

ExecutionMetrics

Aggregated execution statistics

For the exhaustive Agent API, see the xpander-sdk documentation.

Getting Started

xpander-sdk

​Agent Class

​Retrieving an Agent

​Agent Properties

​Core Properties

​Configuration Properties

​Agent Core Methods

​update() / update()

​sync() / sync()

​disable_agent_end_tool() / disableAgentEndTool()

​update_user_details() / updateUserDetails()

​retrieve_node_from_graph() / retrieveNodeFromGraph()

​enable_agent_end_tool() / enableAgentEndTool()

​init_task() / initTask()

​report_execution_metrics() / reportExecutionMetrics()

​report_llm_usage() / reportLlmUsage()

​select_llm_provider() / selectLLMProvider()

​stop() / stop()

​stop_execution() / stopExecution()

​Type Definitions

​Instructions

​Metadata

​UserDetails

​Usage Example

​Related Documentation

Agent.Messages

Agent.Tools

Tasks

Agent.Graph

LLMMetrics

ExecutionMetrics

Agent Class

Retrieving an Agent

Agent Properties

Core Properties

Configuration Properties

Agent Core Methods

update() / update()

sync() / sync()

disable_agent_end_tool() / disableAgentEndTool()

update_user_details() / updateUserDetails()

retrieve_node_from_graph() / retrieveNodeFromGraph()

enable_agent_end_tool() / enableAgentEndTool()

init_task() / initTask()

report_execution_metrics() / reportExecutionMetrics()

report_llm_usage() / reportLlmUsage()

select_llm_provider() / selectLLMProvider()

stop() / stop()

stop_execution() / stopExecution()

Type Definitions

Instructions

Metadata

UserDetails

Usage Example

Related Documentation