Agent SDK · Reference

Exports.

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

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.