Agent

​

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")

Returns: Agent instance

​

Agent Properties

​

Core Properties

​

Configuration Properties

​

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"
})

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")

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)

Returns: Execution object

​

report_execution_metrics() / reportExecutionMetrics()

Report token usage metrics for the current execution.

agent.report_execution_metrics(llm_tokens)

Returns: void

​

report_llm_usage() / reportLlmUsage()

Send raw LLM usage statistics to xpander.ai.

agent.report_llm_usage(llm_response)

Returns: void

​

select_llm_provider() / selectLLMProvider()

Specify which LLM provider the agent should use.

agent.select_llm_provider(llm_provider=LLMProvider.OPEN_AI)

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")

Returns: void

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()

​

Related Documentation