​
Task Methods

The Tasks API provides methods for creating, monitoring, and managing tasks assigned to xpander agents.

​
add_task() / addTask()

Creates a new task for the agent with the specified input. 
task = agent.add_task(
    input="Research quantum computing",
    thread_id="thread_abc123",  # Optional
    files=[{"name": "data.csv", "content": "base64-encoded-content"}]  # Optional
)
ParameterTypeRequiredDescription
inputstringYesTask description or user message
thread_idstringNoThread ID for connecting related tasks
filesList[Dict]NoFiles to attach to the task
use_workerbooleanNoWhether to use a worker for execution (default: true)
Returns: Task object
After calling add_task(), the agent’s execution property is initialized, and agent.messages is populated with system instructions and the user input.

​
is_finished() / isFinished()

Checks if the current task has finished. 
is_done = agent.is_finished()
Returns: boolean - True if task has finished, False otherwise.
A task is considered finished when the AI model calls the xpfinish-agent-execution-finished tool or if the task has failed.

​
get_execution_status() / getExecutionStatus()

Fetches the latest status of the current task. 
status = agent.get_execution_status()
Returns: Task status object with the following properties: 
interface TaskStatus {
  id: string;
  status: "RUNNING" | "COMPLETED" | "FAILED" | "PENDING";
  createdAt: string;
  updatedAt: string;
  input: string;
  memoryThreadId: string;
}

​
retrieve_execution_result() / retrieveExecutionResult()

Retrieves the result of a completed task, including the thread ID which can be used to connect related tasks. 
result = agent.retrieve_execution_result()
Returns: Result object with the following properties: 
interface ExecutionResult {
  status: "COMPLETED" | "FAILED";
  result?: string;      // Present when status is "COMPLETED"
  error?: string;       // Present when status is "FAILED"
  executionId: string;
  threadId: string;     // Thread ID for connecting related tasks
}

​
list_executions() / listExecutions()

Lists tasks for the current agent. 
tasks = agent.list_executions()
Returns: Array of task objects.

​
get_execution() / getExecution()

Gets a task by ID. 
task = agent.get_execution(execution_id="execution-1234")
ParameterTypeRequiredDescription
execution_idstringYesID of the task
Returns: Task object

​
Task Execution Properties

​
agent.execution

The current execution task object, available after calling add_task(). 
execution = agent.execution
execution_id = execution.id
To retrieve the thread ID, you should use the result from retrieve_execution_result() rather than the execution object.

​
Type Definitions

​
Execution

Represents a task assigned to an agent. 
interface Execution {
  id: string;
  status: "RUNNING" | "COMPLETED" | "FAILED" | "PENDING";
  createdAt: string;
  updatedAt: string;
  input: string;
  result?: string;
  error?: string;
  memoryThreadId: string;
}

​
ExecutionStatus

Represents the current status of a task. 
interface ExecutionStatus {
  id: string;
  status: "RUNNING" | "COMPLETED" | "FAILED" | "PENDING";
  createdAt: string;
  updatedAt: string;
  input: string;
  memoryThreadId: string;
}

​
ExecutionResult

Represents the result of a completed task. 
interface ExecutionResult {
  status: "COMPLETED" | "FAILED";
  result?: string;      // Present when status is "COMPLETED"
  error?: string;       // Present when status is "FAILED"
  executionId: string;
  threadId: string;     // Thread ID for connecting related tasks
}

​
Usage Examples

​
Basic Task Execution

# Create a task
agent.add_task(input="Summarize the latest news on AI")

# Run until completion
while not agent.is_finished():
    # Run LLM to process messages and generate tool calls
    response = openai_client.chat.completions.create(
        model="gpt-4.1",
        messages=agent.messages,
        temperature=0
    )
    
    # Add response to messages
    agent.add_messages(response.model_dump())
    
    # Process tool calls
    tool_calls = agent.extract_tool_calls(
        llm_response=response.model_dump(),
    )
    
    if tool_calls:
        agent.run_tools(tool_calls=tool_calls)

# Get result
result = agent.retrieve_execution_result()
print(result.result)

​
Multi-Agent Workflow

# Start with first agent
agent_a = client.agents.get(agent_id="agent_a_id")
agent_a.add_task(input="Collect data for analysis")

# Process with first agent
# ... (code for processing the task) ...

# Get the execution result which contains the thread ID
result = agent_a.retrieve_execution_result()
thread_id = result.thread_id

# Transfer to second agent using the thread ID
agent_b = client.agents.get(agent_id="agent_b_id")
agent_b.add_task(
    input="Analyze the collected data",
    thread_id=thread_id  # Continue the same conversation
)

# Process with second agent
# ... (code for processing the task) ...

​
Retrieving Past Tasks

# Get all tasks for the agent
tasks = agent.list_executions()

# Get a specific task by ID
task = agent.get_execution(execution_id="execution-1234")

# Get the result of a completed task
if task.status == "COMPLETED":
    result = agent.retrieve_execution_result()
    print(result.result)

Agent

Core agent functionality

Agent.Messages

Working with agent messages

Agent.Tools

Using agent tools and function calling

XpanderClient

Main client for the xpander.ai SDK

LLMMetrics

Token usage metrics

ExecutionMetrics

Execution statistics
You can find detailed task examples in the xpander-sdk docs.