SDK Types Reference

The xpander.ai SDK uses various data types, enumerations, and models across its modules. This reference provides comprehensive documentation for all shared types.

Enumerations

`AgentExecutionStatus`

Enumeration of task execution statuses used throughout the Tasks and Agents modules.

class AgentExecutionStatus:
    Pending = "pending"
    Executing = "executing"
    Paused = "paused"
    Error = "error"
    Failed = "failed"
    Completed = "completed"
    Stopped = "stopped"

Values:

Pending: Task is queued and waiting to start
Executing: Task is currently being executed
Paused: Task execution is temporarily paused
Error: Task encountered an error during execution
Failed: Task execution failed to complete successfully
Completed: Task finished successfully
Stopped: Task was manually stopped

Usage:

from xpander_sdk.types import AgentExecutionStatus

# Check task status
if task.status == AgentExecutionStatus.Completed:
    print("Task finished successfully!")

`AgentDeploymentType`

Enumeration of supported deployment types for agents.

class AgentDeploymentType:
    Serverless = "serverless"
    Container = "container"

Values:

Serverless: Agent runs in a serverless environment, ideal for lightweight tasks
Container: Agent runs in a containerized environment, suitable for resource-intensive operations

Usage:

from xpander_sdk import AgentDeploymentType

# Check agent deployment type
if agent.deployment_type == AgentDeploymentType.Serverless:
    print("Agent configured for serverless deployment")
elif agent.deployment_type == AgentDeploymentType.Container:
    print("Agent configured for container deployment")

`OutputFormat`

Enumeration of supported output formats for task results.

class OutputFormat:
    Text = "text"
    Json = "json"
    Markdown = "markdown"
    Html = "html"

Values:

Text: Plain text output
Json: JSON-formatted output
Markdown: Markdown-formatted output
Html: HTML-formatted output

Usage:

from xpander_sdk.types import OutputFormat

task = await agent.acreate_task(
    prompt="Generate a report",
    output_format=OutputFormat.Json
)

`TaskUpdateEventType`

Enumeration of task event types for real-time streaming.

class TaskUpdateEventType:
    TaskCreated = "task_created"
    TaskUpdated = "task_updated"
    TaskFinished = "task_finished"
    ToolCallRequest = "tool_call_request"
    ToolCallResult = "tool_call_result"
    SubAgentTrigger = "sub_agent_trigger"

Values:

TaskCreated: Task was created
TaskUpdated: Task status or data was updated
TaskFinished: Task execution completed
ToolCallRequest: Agent is requesting to use a tool
ToolCallResult: Tool execution result is available
SubAgentTrigger: A sub-agent is triggered during execution

Usage:

from xpander_sdk.types import TaskUpdateEventType

async for event in task.aevents():
    if event.type == TaskUpdateEventType.TaskFinished:
        print("Task completed!")
        break

Data Models

`AgentExecutionInput`

Input configuration for task execution.

class AgentExecutionInput:
    text: Optional[str] = ""
    files: Optional[List[str]] = []
    user: Optional[User] = None

Properties:

text (Optional[str]): The main prompt or instruction text
files (Optional[List[str]]): URLs of files to process with the task
user (Optional[User]): User details associated with task execution

Note: Either text or files must be provided (validated automatically).

`TaskUpdateEvent`

Real-time event data from task execution.

class TaskUpdateEvent:
    type: TaskUpdateEventType
    task_id: str
    organization_id: str
    time: datetime
    data: Union[Task, ToolCallRequest, ToolCallResult]

Properties:

type (TaskUpdateEventType): The type of event
task_id (str): Unique identifier of the associated task
organization_id (str): Organization identifier
time (datetime): Timestamp when the event occurred
data (Union[Task, ToolCallRequest, ToolCallResult]): Event-specific data payload

Usage:

async for event in task.aevents():
    print(f"Event: {event.type} at {event.time}")
    print(f"Data: {event.data}")

`AgentActivityThread`

Complete activity log for a task execution containing all messages, tool calls, reasoning, and events.

class AgentActivityThread:
    id: str
    created_at: datetime
    messages: List[AgentActivityThreadMessageType]
    user: Optional[User] = None

Properties:

id (str): Unique identifier for the activity thread
created_at (datetime): When the activity thread was created
messages (List[AgentActivityThreadMessageType]): Ordered list of all activity messages (messages, tool calls, reasoning steps, etc.)
user (Optional[User]): User associated with the activity, if available

Message Types:

AgentActivityThreadMessage: User/agent conversation messages
AgentActivityThreadToolCall: Tool invocations and results
AgentActivityThreadReasoning: Agent reasoning steps
AgentActivityThreadSubAgentTrigger: Sub-agent invocations
AgentActivityThreadAuth: Authentication events

Usage:

from xpander_sdk import Task
from xpander_sdk.models.activity import (
    AgentActivityThreadMessage,
    AgentActivityThreadToolCall
)

task = await Task.aload("task-123")
activity_log = await task.aget_activity_log()

for message in activity_log.messages:
    if isinstance(message, AgentActivityThreadMessage):
        print(f"{message.role}: {message.content.text}")
    elif isinstance(message, AgentActivityThreadToolCall):
        print(f"Tool: {message.tool_name}")

`AgentActivityThreadMessage`

User or agent conversation message in the activity log.

class AgentActivityThreadMessage:
    id: str
    created_at: datetime
    role: Literal["user", "agent"]
    content: AgentActivityThreadMessageContent

Properties:

id (str): Message unique identifier
created_at (datetime): When the message was created
role (Literal[“user”, “agent”]): Whether message is from user or agent
content (AgentActivityThreadMessageContent): Message content with text and files

`AgentActivityThreadToolCall`

Tool invocation record in the activity log.

class AgentActivityThreadToolCall:
    id: str
    created_at: datetime
    tool_name: str
    payload: Any
    is_error: Optional[bool] = False
    reasoning: Optional[ToolCallRequestReasoning] = None
    result: Optional[Any] = None

Properties:

id (str): Tool call unique identifier
created_at (datetime): When the tool was called
tool_name (str): Name of the invoked tool
payload (Any): Input parameters sent to the tool
is_error (bool): Whether the tool call resulted in an error
reasoning (Optional[ToolCallRequestReasoning]): Agent’s reasoning for using this tool
result (Optional[Any]): Tool execution result

`AgentActivityThreadReasoning`

Agent reasoning step in the activity log.

class AgentActivityThreadReasoning:
    id: str
    created_at: datetime
    type: AgentActivityThreadReasoningType  # "think" or "analyze"
    title: str
    confidence: float
    thought: Optional[str] = None
    action: Optional[str] = None
    result: Optional[str] = None
    analysis: Optional[str] = None

Properties:

id (str): Reasoning step unique identifier
created_at (datetime): When the reasoning occurred
type (AgentActivityThreadReasoningType): Type of reasoning (think/analyze)
title (str): Brief title for the reasoning step
confidence (float): Agent’s confidence level (0.0 to 1.0)
thought (Optional[str]): Agent’s internal thought process
action (Optional[str]): Planned action based on reasoning
result (Optional[str]): Result of the reasoning step
analysis (Optional[str]): Detailed analysis

`AgentActivityThreadSubAgentTrigger`

Sub-agent invocation record in the activity log.

class AgentActivityThreadSubAgentTrigger:
    id: str
    created_at: datetime
    agent_id: str
    query: Optional[str] = None
    files: Optional[List[str]] = []
    reasoning: ToolCallRequestReasoning

Properties:

id (str): Sub-agent trigger unique identifier
created_at (datetime): When the sub-agent was triggered
agent_id (str): ID of the sub-agent being invoked
query (Optional[str]): Query sent to the sub-agent
files (Optional[List[str]]): File URLs passed to the sub-agent
reasoning (ToolCallRequestReasoning): Reasoning for triggering the sub-agent

`ToolCallRequest`

Tool invocation request event data.

class ToolCallRequest:
    request_id: str
    operation_id: str
    tool_call_id: Optional[str] = None
    graph_node_id: Optional[str] = None
    tool_name: Optional[str] = None
    payload: Optional[Any] = None

Properties:

request_id (str): Unique identifier for this specific request
operation_id (str): Unique identifier for the operation
tool_call_id (Optional[str]): Tool call identifier
graph_node_id (Optional[str]): Graph node identifier
tool_name (Optional[str]): Name of the tool being requested
payload (Optional[Any]): Input parameters for the tool

Usage:

async for event in task.aevents():
    if event.type == TaskUpdateEventType.ToolCallRequest:
        tool_request: ToolCallRequest = event.data
        print(f"Tool requested: {tool_request.tool_name}")
        print(f"Payload: {tool_request.payload}")

`ToolCallResult`

Tool invocation result event data.

class ToolCallResult:
    request_id: str
    operation_id: str
    tool_call_id: Optional[str] = None
    graph_node_id: Optional[str] = None
    tool_name: Optional[str] = None
    payload: Optional[Any] = None
    result: Optional[Any] = None
    is_error: Optional[bool] = False

Properties:

request_id (str): Unique identifier for the original request
operation_id (str): Unique identifier for the operation
tool_call_id (Optional[str]): Tool call identifier
graph_node_id (Optional[str]): Graph node identifier
tool_name (Optional[str]): Name of the tool that was executed
payload (Optional[Any]): Original payload from the request
result (Optional[Any]): Result data from the tool execution
is_error (Optional[bool]): Whether the tool execution resulted in an error

Usage:

async for event in task.aevents():
    if event.type == TaskUpdateEventType.ToolCallResult:
        tool_result: ToolCallResult = event.data
        if tool_result.is_error:
            print(f"Tool error: {tool_result.result}")
        else:
            print(f"Tool success: {tool_result.result}")

`ToolInvocationResult`

Result of invoking a tool, containing details about the execution outcome.

class ToolInvocationResult:
    result: Any
    is_success: bool
    error: Optional[str]
    execution_time: float

Properties:

result (Any): The actual result data from the tool execution
is_success (bool): Whether the tool execution was successful
error (Optional[str]): Error message if execution failed
execution_time (float): Time taken for execution in seconds

Usage:

result = await tool.ainvoke("agent-123", {"param": "value"})
if result.is_success:
    print(f"Result: {result.result}")
    print(f"Execution time: {result.execution_time}s")
else:
    print(f"Error: {result.error}")

`KnowledgeBaseDocumentItem`

Represents a document within a knowledge base.

class KnowledgeBaseDocumentItem:
    id: str
    document_url: str
    added_at: datetime

Properties:

id (str): Unique identifier for the document
document_url (str): URL where the document was originally located
added_at (datetime): Timestamp when the document was added

`KnowledgeBaseSearchResult`

Represents a search result from a knowledge base.

class KnowledgeBaseSearchResult:
    content: str
    score: float

Properties:

content (str): The matching content from the knowledge base
score (float): Relevance score for the search result (0.0 to 1.0)

Usage:

results = await kb.asearch("authentication methods")
for result in results:
    print(f"Score: {result.score:.3f}")
    print(f"Content: {result.content[:200]}...")

`AgnoSettings`

Configuration settings for the Agno framework, including memory management and tool optimization.

class AgnoSettings:
    session_storage: Optional[bool] = True
    agent_memories: Optional[bool] = False
    user_memories: Optional[bool] = False
    agentic_memory: Optional[bool] = False
    agentic_culture: Optional[bool] = False
    session_summaries: Optional[bool] = False
    num_history_runs: Optional[int] = 3
    max_tool_calls_from_history: Optional[int] = 0
    tool_call_limit: Optional[int] = None
    coordinate_mode: Optional[bool] = False
    pii_detection_enabled: Optional[bool] = False
    pii_detection_mask: Optional[bool] = True
    prompt_injection_detection_enabled: Optional[bool] = False
    openai_moderation_enabled: Optional[bool] = False
    openai_moderation_categories: Optional[List[str]] = None
    reasoning_tools_enabled: Optional[bool] = False
    tool_calls_compression: Optional[AgnoToolCallsCompressionSettings] = None

Memory & Storage Properties:

session_storage (bool): Enable session-level storage for conversation context. Default: True
agent_memories (bool): Enable agent-specific memory storage. Default: False
user_memories (bool): Enable user-specific memory across sessions. Default: False
agentic_memory (bool): Enable advanced agentic memory capabilities. Default: False
agentic_culture (bool): Enable cultural context for agents. Default: False
session_summaries (bool): Generate summaries of sessions. Default: False
num_history_runs (int): Number of historical runs to retain. Default: 3
max_tool_calls_from_history (int): Max tool calls to load from history. Default: 0

Tool & Execution Properties:

tool_call_limit (int): Maximum tool calls per run. Default: None (unlimited)
coordinate_mode (bool): Load agent as a Team for coordination. Default: False
reasoning_tools_enabled (bool): Enable Agno reasoning tools. Default: False
tool_calls_compression (AgnoToolCallsCompressionSettings): Tool call compression settings

Security & Guardrails:

pii_detection_enabled (bool): Enable PII detection on agent input. Default: False
pii_detection_mask (bool): Mask detected PII instead of blocking. Default: True
prompt_injection_detection_enabled (bool): Enable prompt injection detection. Default: False
openai_moderation_enabled (bool): Enable OpenAI content moderation. Default: False
openai_moderation_categories (List[str]): Specific moderation categories to enforce

Usage:

from xpander_sdk.models.frameworks import AgnoSettings

# Configure agent with memory features
agno_settings = AgnoSettings(
    session_storage=True,
    agent_memories=True,
    user_memories=True,
    session_summaries=True,
    num_history_runs=5,
    tool_call_limit=20
)

# Agent configuration would use these settings
# (typically configured via UI or API)

`AgnoToolCallsCompressionSettings`

Settings for compressing tool call history to optimize context usage.

class AgnoToolCallsCompressionSettings:
    enabled: Optional[bool] = False
    threshold: Optional[int] = 3
    instructions: Optional[str] = ""

Properties:

enabled (bool): Enable tool calls compression. Default: False
threshold (int): Number of tool calls before compression activates. Default: 3
instructions (str): Custom instructions for compression behavior. Default: ""

Usage:

from xpander_sdk.models.frameworks import AgnoSettings, AgnoToolCallsCompressionSettings

agno_settings = AgnoSettings(
    tool_calls_compression=AgnoToolCallsCompressionSettings(
        enabled=True,
        threshold=5,
        instructions="Summarize tool calls focusing on results"
    )
)

Model Providers

Supported AI model providers in the xpander.ai platform: Supported Providers:

OpenAI - GPT models (gpt-4, gpt-4o, etc.)
- Environment: OPENAI_API_KEY or AGENTS_OPENAI_API_KEY
Anthropic - Claude models
- Environment: ANTHROPIC_API_KEY
Google AI Studio - Gemini models
- Environment: GOOGLE_API_KEY
NVIDIA NIM - NVIDIA inference microservices
- Environment: NVIDIA_API_KEY
Amazon Bedrock - AWS Bedrock models
- Environment: AWS_BEARER_TOKEN_BEDROCK
Fireworks - Fireworks AI models
- Environment: FIREWORKS_API_KEY
Helicone - OpenAI-compatible with monitoring
- Environment: HELICONE_API_KEY
Nebius - Nebius AI models
- Environment: NEBIUS_API_KEY
OpenRouter - Multi-model router
- Environment: OPENROUTER_API_KEY

Note: Model providers are configured at the agent level. The SDK automatically loads the appropriate provider based on agent configuration.

Common Patterns

Type Checking

from xpander_sdk.types import TaskUpdateEventType, ToolCallRequest, ToolCallResult

async for event in task.aevents():
    if event.type == TaskUpdateEventType.ToolCallRequest:
        # Type-safe access to ToolCallRequest properties
        tool_request: ToolCallRequest = event.data
        print(f"Tool: {tool_request.tool_name}")
    
    elif event.type == TaskUpdateEventType.ToolCallResult:
        # Type-safe access to ToolCallResult properties
        tool_result: ToolCallResult = event.data
        print(f"Success: {not tool_result.is_error}")

Status Comparisons

from xpander_sdk.types import AgentExecutionStatus

def is_task_complete(task) -> bool:
    return task.status in [
        AgentExecutionStatus.Completed,
        AgentExecutionStatus.Failed,
        AgentExecutionStatus.Error,
        AgentExecutionStatus.Stopped
    ]

def is_task_running(task) -> bool:
    return task.status == AgentExecutionStatus.Executing

Output Format Selection

from xpander_sdk.types import OutputFormat

def get_task_output_format(structured: bool = False) -> OutputFormat:
    return OutputFormat.Json if structured else OutputFormat.Text

# Usage
task = await agent.acreate_task(
    prompt="Generate a report",
    output_format=get_task_output_format(structured=True)
)

Import Patterns

Individual Types

from xpander_sdk.modules.tasks.models.task import AgentExecutionStatus
from xpander_sdk.models.shared import OutputFormat
from xpander_sdk.modules.tasks.sub_modules.task import TaskUpdateEvent
from xpander_sdk.modules.agents.models.agent import AgentDeploymentType

All Types

# Import modules containing types
from xpander_sdk.modules.tasks.models import task as task_models
from xpander_sdk.models import events, shared

# Access types with module namespace
if task.status == task_models.AgentExecutionStatus.Completed:
    print("Task finished!")

Specific Module Types

# For tasks-related types
from xpander_sdk.modules.tasks.models.task import AgentExecutionStatus
from xpander_sdk.models.events import TaskUpdateEventType, ToolCallRequest, ToolCallResult
from xpander_sdk.modules.tasks.sub_modules.task import TaskUpdateEvent

# For knowledge base types
from xpander_sdk.types import (
    KnowledgeBaseDocumentItem,
    KnowledgeBaseSearchResult
)

[Agents Module](/API reference/agents): Using types with agent operations
[Tasks Module](/API reference/tasks): Task execution and status types
[Tools Repository](/API reference/tools): Tool invocation result types
[Knowledge Bases](/API reference/knowledge): Document and search result types
[Events Module](/API reference/events): Event streaming types
[SDK Exceptions](/API reference/exceptions): Error handling types

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

SDK Types Reference

SDK Types Reference

Enumerations

`AgentExecutionStatus`

`AgentDeploymentType`

`OutputFormat`

`TaskUpdateEventType`

Data Models

`AgentExecutionInput`

`TaskUpdateEvent`

`AgentActivityThread`

`AgentActivityThreadMessage`

`AgentActivityThreadToolCall`

`AgentActivityThreadReasoning`

`AgentActivityThreadSubAgentTrigger`

`ToolCallRequest`

`ToolCallResult`

`ToolInvocationResult`

`KnowledgeBaseDocumentItem`

`KnowledgeBaseSearchResult`

`AgnoSettings`

`AgnoToolCallsCompressionSettings`

Model Providers

Common Patterns

Type Checking

Status Comparisons

Output Format Selection

Import Patterns

Individual Types

All Types

Specific Module Types

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

​SDK Types Reference

​Enumerations

​AgentExecutionStatus

​AgentDeploymentType

​OutputFormat

​TaskUpdateEventType

​Data Models

​AgentExecutionInput

​TaskUpdateEvent

​AgentActivityThread

​AgentActivityThreadMessage

​AgentActivityThreadToolCall

​AgentActivityThreadReasoning

​AgentActivityThreadSubAgentTrigger

​ToolCallRequest

​ToolCallResult

​ToolInvocationResult

​KnowledgeBaseDocumentItem

​KnowledgeBaseSearchResult

​AgnoSettings

​AgnoToolCallsCompressionSettings

​Model Providers

​Common Patterns

​Type Checking

​Status Comparisons

​Output Format Selection

​Import Patterns

​Individual Types

​All Types

​Specific Module Types

​Related Documentation

SDK Types Reference

Enumerations

`AgentExecutionStatus`

`AgentDeploymentType`

`OutputFormat`

`TaskUpdateEventType`

Data Models

`AgentExecutionInput`

`TaskUpdateEvent`

`AgentActivityThread`

`AgentActivityThreadMessage`

`AgentActivityThreadToolCall`

`AgentActivityThreadReasoning`

`AgentActivityThreadSubAgentTrigger`

`ToolCallRequest`

`ToolCallResult`

`ToolInvocationResult`

`KnowledgeBaseDocumentItem`

`KnowledgeBaseSearchResult`

`AgnoSettings`

`AgnoToolCallsCompressionSettings`

Model Providers

Common Patterns

Type Checking

Status Comparisons

Output Format Selection

Import Patterns

Individual Types

All Types

Specific Module Types

Related Documentation