> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> Enums, models, and type aliases exported by the SDK.

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`

```python theme={"dark"}
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`

```python theme={"dark"}
from xpander_sdk.models.shared import ThinkMode
```

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

### `AgentExecutionStatus`

```python theme={"dark"}
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](/developers/sdk-reference/tasks/overview#lifecycle).

### `AgentDeploymentType`

```python theme={"dark"}
from xpander_sdk import AgentDeploymentType
```

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

### `AgentStatus`

```python theme={"dark"}
from xpander_sdk.modules.agents.models.agent import AgentStatus
```

| Value      | String       |
| ---------- | ------------ |
| `DRAFT`    | `"DRAFT"`    |
| `ACTIVE`   | `"ACTIVE"`   |
| `INACTIVE` | `"INACTIVE"` |

### `AgentAccessScope`

```python theme={"dark"}
from xpander_sdk.modules.agents.models.agent import AgentAccessScope
```

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

### `AgentType`

```python theme={"dark"}
from xpander_sdk.modules.agents.models.agent import AgentType
```

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

### `LLMReasoningEffort`

```python theme={"dark"}
from xpander_sdk.modules.agents.models.agent import LLMReasoningEffort
```

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

### `Framework`

```python theme={"dark"}
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](/developers/sdk-reference/tools/mcp).

### `TaskUpdateEventType`

See [streaming events](/developers/sdk-reference/tasks/events#event-types).

### `KnowledgeBaseType`

```python theme={"dark"}
from xpander_sdk.modules.knowledge_bases.models.knowledge_bases import KnowledgeBaseType
```

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

## Models

### `Configuration`

See [Configuration](/developers/sdk-reference/configuration).

### `User`

```python theme={"dark"}
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`

```python theme={"dark"}
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`

```python theme={"dark"}
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`

```python theme={"dark"}
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`

```python theme={"dark"}
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`

```python theme={"dark"}
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.

### `TaskUpdateEvent`

See [streaming events](/developers/sdk-reference/tasks/events).

### `ToolInvocationResult`

See [Tool class: ToolInvocationResult](/developers/sdk-reference/tools/tool#toolinvocationresult).

### `MCPServerDetails`

See [MCP types](/developers/sdk-reference/tools/mcp).

### `KnowledgeBaseSearchResult`

```python theme={"dark"}
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](/developers/sdk-reference/knowledge-bases/knowledge-base#alist_documents--list_documents).

### `AgnoSettings`

```python theme={"dark"}
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`](/developers/sdk-reference/agents/list) and [`tasks.list`](/developers/sdk-reference/tasks/list).

## Exceptions

### `ModuleException`

```python theme={"dark"}
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](/developers/sdk-reference/error-handling).

## Constants

### `MAX_PLAN_RETRIES`

```python theme={"dark"}
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`

```python theme={"dark"}
from xpander_sdk.models.shared import LLMModelT
# = type[ABC]
```

Marker type used internally for typing model classes.