Types - xpander.ai

A consolidated reference for every enum and Pydantic model exposed at the top level of xpander_sdk. Methods that take or return these types link here.

Enums

`OutputFormat`

from xpander_sdk import OutputFormat

Value	String	Use
`OutputFormat.Text`	`"text"`	Plain text.
`OutputFormat.Markdown`	`"markdown"`	Markdown-formatted text (default for most agents).
`OutputFormat.Json`	`"json"`	Structured JSON. Pair with `output_schema` for validation.
`OutputFormat.Voice`	`"voice"`	MP3 voice output (requires `voice_id` on the agent).

`ThinkMode`

from xpander_sdk.models.shared import ThinkMode

Value	String	Use
`ThinkMode.Default`	`"default"`	Standard reasoning.
`ThinkMode.Harder`	`"harder"`	Extended reasoning (uses more tokens).

`AgentExecutionStatus`

from xpander_sdk import AgentExecutionStatus

Value	String
`Pending`	`"pending"`
`Executing`	`"executing"`
`Paused`	`"paused"`
`Error`	`"error"`
`Failed`	`"failed"`
`Completed`	`"completed"`
`Stopped`	`"stopped"`

See the task lifecycle.

`AgentDeploymentType`

from xpander_sdk import AgentDeploymentType

Value	String
`Serverless`	`"serverless"`
`Container`	`"container"`

`AgentStatus`

from xpander_sdk.modules.agents.models.agent import AgentStatus

Value	String
`DRAFT`	`"DRAFT"`
`ACTIVE`	`"ACTIVE"`
`INACTIVE`	`"INACTIVE"`

`AgentAccessScope`

from xpander_sdk.modules.agents.models.agent import AgentAccessScope

Value	String
`Personal`	`"personal"`
`Organizational`	`"organizational"`

`AgentType`

from xpander_sdk.modules.agents.models.agent import AgentType

Value	String
`Manager`	`"manager"`
`Regular`	`"regular"`
`A2A`	`"a2a"`
`Curl`	`"curl"`
`Orchestration`	`"orchestration"`

`LLMReasoningEffort`

from xpander_sdk.modules.agents.models.agent import LLMReasoningEffort

Value	String
`Low`	`"low"`
`Medium`	`"medium"`
`High`	`"high"`

`Framework`

from xpander_sdk.models.frameworks import Framework

Value	String
`Agno`	`"agno"`
`LangChain`	`"langchain"`
`OpenAIAgents`	`"open-ai-agents"`
`GoogleADK`	`"google-adk"`
`Strands`	`"strands-agents"`
`OpenClaw`	`"open-claw"`

Today only Agno is fully wired through Backend.aget_args; other values are reserved.

`MCPServerType`, `MCPServerAuthType`, `MCPServerTransport`

See MCP types.

`TaskUpdateEventType`

See streaming events.

`KnowledgeBaseType`

from xpander_sdk.modules.knowledge_bases.models.knowledge_bases import KnowledgeBaseType

Value	String
`MANAGED`	`"managed"`
`EXTERNAL`	`"external"`

Models

`Configuration`

See Configuration.

`User`

from xpander_sdk import User

User(
    id: Optional[str] = None,
    first_name: Optional[str] = None,
    last_name: Optional[str] = None,
    email: str,                                # required
    additional_attributes: Optional[dict] = None,
    timezone: Optional[str] = None,            # IANA, e.g. "America/New_York"
)

End-user context. Pass to acreate_task(user_details=...) to scope memory and connector authentication to a specific user.

`Tokens`

from xpander_sdk import Tokens

Tokens(
    completion_tokens: int = 0,
    prompt_tokens: int = 0,
)
# tokens.total_tokens is a computed property: completion + prompt

Used in Backend.areport_external_task and Task.areport_metrics.

`ExecutionTokens`

from xpander_sdk.models.shared import ExecutionTokens

ExecutionTokens(
    inner: Tokens = Tokens(),    # inner orchestration tokens
    worker: Tokens = Tokens(),   # worker LLM tokens
)

Used internally for metrics aggregation.

`AgentInstructions`

from xpander_sdk.modules.agents.models.agent import AgentInstructions

AgentInstructions(
    role: list[str] = [],
    goal: list[str] = [],
    general: str = "",
)

Computed properties: description (= general), instructions (formatted XML block), goal_str, full.

`AgentExecutionInput`

from xpander_sdk.modules.tasks.models.task import AgentExecutionInput

AgentExecutionInput(
    text: Optional[str] = "",
    files: Optional[list[str]] = [],
    user: Optional[User] = None,
)

Stored on task.input. Constructed automatically by acreate_task.

`LocalTaskTest`

from xpander_sdk.modules.tasks.models.task import LocalTaskTest, AgentExecutionInput

LocalTaskTest(
    input: AgentExecutionInput,
    agent_version: Optional[str] = None,
    output_format: Optional[OutputFormat] = None,
    output_schema: Optional[dict] = None,
)

Pass to @on_task(test_task=...) to invoke the handler once locally instead of subscribing to the platform.

`KnowledgeBaseSearchResult`

from xpander_sdk.modules.knowledge_bases.models.knowledge_bases import KnowledgeBaseSearchResult

KnowledgeBaseSearchResult(
    content: str,
    score: float,
)

Returned by KnowledgeBase.asearch.

`KnowledgeBaseDocumentItem`

See the KnowledgeBase reference.

`AgnoSettings`

from xpander_sdk.models.frameworks import AgnoSettings

AgnoSettings(
    session_storage: bool = True,
    learning: bool = False,
    user_memories: bool = False,
    agentic_memory: bool = False,
    agent_memories: bool = False,
    agentic_culture: bool = False,
    session_summaries: bool = False,
    num_history_runs: int = 10,
    max_tool_calls_from_history: int = 0,
    tool_call_limit: Optional[int] = None,
    coordinate_mode: bool = False,
    pii_detection_enabled: bool = False,
    pii_detection_mask: bool = True,
    prompt_injection_detection_enabled: bool = False,
    openai_moderation_enabled: bool = False,
    openai_moderation_categories: Optional[list[str]] = None,
    reasoning_tools_enabled: bool = False,
)

Per-agent Agno configuration stored on agent.agno_settings. Modify in the Workbench; mutating in code only affects the in-memory instance.

`AgentsListItem` / `TasksListItem`

Summary objects returned by agents.alist() and tasks.alist(). See agents.list and tasks.list.

Exceptions

`ModuleException`

from xpander_sdk.exceptions.module_exception import ModuleException

Raised by every SDK module on API failure. Carries status_code: int and description: str. See Error Handling.

Constants

`MAX_PLAN_RETRIES`

from xpander_sdk import MAX_PLAN_RETRIES   # = 5

The maximum number of times the @on_task runtime retries a handler when deep-planning tasks remain incomplete after the first run.

Type aliases

`LLMModelT`

from xpander_sdk.models.shared import LLMModelT
# = type[ABC]

Marker type used internally for typing model classes.

​Enums

​OutputFormat

​ThinkMode

​AgentExecutionStatus

​AgentDeploymentType

​AgentStatus

​AgentAccessScope

​AgentType

​LLMReasoningEffort

​Framework

​MCPServerType, MCPServerAuthType, MCPServerTransport

​TaskUpdateEventType

​KnowledgeBaseType

​Models

​Configuration

​User

​Tokens

​ExecutionTokens

​AgentInstructions

​AgentExecutionInput

​LocalTaskTest

​TaskUpdateEvent

​ToolInvocationResult

​MCPServerDetails

​KnowledgeBaseSearchResult

​KnowledgeBaseDocumentItem

​AgnoSettings

​AgentsListItem / TasksListItem

​Exceptions

​ModuleException

​Constants

​MAX_PLAN_RETRIES

​Type aliases

​LLMModelT