# Exports

> Classes, errors, functions, constants, and types exported by the Python agent SDK package.

Source: https://maincode.com/docs/python-agent-sdk-exports
Section: Agent SDK · Matilda documentation

---

## Classes

| Export | Description |
| - | - |
| `Agent` | Named persona with static or dynamic instructions. |
| `Runner` | Main execution class. Holds `auth`, `files`, `conversations`, `feedback` resources. |
| `Session` | Multi-turn conversation wrapper with auto-managed `conversation_id`. |
| `AgentAuth` | Managed auth: login, restore, token refresh, logout (via `runner.auth`). |
| `MatildaAgentRunError` | HTTP-level failure (`status`, `response_text`). |
| `MatildaAgentStreamError` | SSE stream error (`code`, `errors`, partial `result`). |
| `MatildaClient` | Underlying API client (re-exported from `matilda-client`). |
| `MatildaConfig` | Client config dataclass (re-exported). |
| `FilesResource` | File upload/retrieve resource (re-exported; also at `runner.files`). |
| `ConversationsResource` | Conversation list/retrieve/update/feedback resource (re-exported). |
| `FeedbackResource` | Bug-report resource, agent-stamped (`report_bug`; also at `runner.feedback`). |

## Errors (re-exported)

| Export | Description |
| - | - |
| `MatildaError` | Shared base class. |
| `MatildaAPIError` | Non-2xx HTTP response. |
| `QuotaExceededError` | 429 quota error with structured attributes. |
| `MatildaStreamError` | Terminal stream `error` event (`code`). |
| `SafetyReplaceError` | Safety filter replacement (`categories`). |
| `MatildaObjectParseError` | Structured output parse/validation failure (`raw`, `cause`). |
| `UploadError` | File upload failure. |

## Functions

| Export | Description |
| - | - |
| `run(agent, prompt, **options)` | Run an agent turn via the shared default runner. Returns `AgentRunResult`. |
| `stream(agent, prompt, **options)` | Stream agent events. Returns an async generator of `AgentEvent`. |
| `stream_text(agent, prompt, **options)` | Stream text deltas. Returns an async generator of `str`. |
| `run_text(agent, prompt, **options)` | Run and return just the text. Returns `str`. |
| `stream_object(agent, prompt, schema, **options)` | Stream with structured output. Async generator of `AgentObjectEvent`. |
| `run_object(agent, prompt, schema, **options)` | Run with structured output. Returns `AgentObjectResult`. |
| `create_session(agent, **options)` | Create a `Session`. |
| `build_agent_chat_request(**options)` | Build a chat request dict without executing. Async. |
| `resume_agent_stream(stream_id, last_event_id=None, **options)` | Resume a detached durable stream. Returns `AgentRunResult`. |
| `configure_default_client(client)` | Install the shared default `MatildaClient`. |

## Constants

| Export | Value | Description |
| - | - | - |
| `DEFAULT_AGENT_PURPOSE` | `'code'` | Default agent purpose. |
| `DEFAULT_AGENT_STALL_TIMEOUT_MS` | `45_000` | Default SSE stall watchdog timeout. |
| `DEFAULT_MAX_TOOL_ROUNDTRIPS` | `25` | Default maximum tool roundtrips. |
| `DEFAULT_MAX_RETRIES` | `0` | Default maximum retries. |
| `AGENT_SDK_NAME` / `AGENT_SDK_LANGUAGE` | — | SDK provenance constants stamped on requests. |
| `DSML_TOOL_CALL_OPEN` / `DSML_TOOL_CALL_CLOSE` | — | DSML tool-call tag constants. |

## Types

| Export | Description |
| - | - |
| `AgentPurpose` | `Literal['code', 'analysis', 'general']` |
| `AgentInstructions` | `str \| Callable[[dict], str \| Awaitable[str]]` |
| `AgentEvent` | Union of the 20 agent stream event dataclasses. |
| `AgentObjectEvent` | `AgentEvent` plus the terminal `ObjectEvent`. |
| `AgentRunResult` | Result of an agent run (dataclass). |
| `AgentObjectResult[T]` | `AgentRunResult` plus the validated `object`. |
| `ToolHandler` | `(args, ctx) -> Awaitable[ToolResult]` |
| `ToolHandlers` | `dict[str, ToolHandler]` |
| `ToolExecutionContext` | Context passed to tool handlers (`tool_call_id`). |
| `ToolResult` | `{content, is_error}` dataclass. |
| `StreamErrorDetail` | `{code, message}` pair on `AgentRunResult.errors`. |
| `UsageSummary` | Token usage summary on `AgentRunResult`. |
| `UsageEvent` | `response.usage` event (re-exported from `matilda-client`). |
| `EventCallback` / `ObjectEventCallback` | Catch-all event callback types. |
| `MatildaClientProtocol` | Protocol a `Runner` client's object must satisfy. |
| `RunStarted` / `StreamStarted` | Agent lifecycle events. |
| `ClientToolRequested` / `ClientToolExecuting` / `ClientToolResult` / `ClientToolRoundtrip` | Client-tool events. |
| `TurnRetrying` | Retry notice event. |
| `OutputTextDelta` / `OutputTextReplace` / `StatusEvent` / `QueuedEvent` / `ToolCallStarted` / `ToolCallProgress` / `ToolCallCompleted` / `GenerationStatus` / `CursorEvent` / `Truncated` / `Completed` / `ResponseError` | Chat events re-exported from `matilda-client` so consumers dispatch on one set of types. |

## Auth imports

Auth types (`AuthError`, `StorageAdapter`, `TokenManager`, `TokenSet`, `MemoryStorage` / `memory_storage`, `AuthServerMetadata`, login-flow functions, `create_file_token_store`, `DEFAULT_SUCCESS_REDIRECT`) live in `matilda_client` / `matilda_client.auth` / `matilda_client.auth_local` — import them from there. See the [client SDK exports](https://maincode.com/docs/python-client-sdk-exports).