Agent SDK · Reference

Exports.

Classes, functions, constants, and types exported by the 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 `conversationId`.
`AgentAuth`	Managed auth: login, restore, token refresh, logout.
`MatildaAgentRunError`	HTTP-level failure (status, responseText).
`MatildaAgentStreamError`	SSE stream error (code, errors, partial result).
`SafetyReplaceError`	Safety filter replacement error (categories).
`MatildaObjectParseError`	Structured output parse/validation failure (raw, cause).
`MatildaCore`	Underlying API client (re-exported from `@matilda/api-client`).
`FilesResource`	File upload/retrieve resource.
`ConversationsResource`	Conversation list/retrieve/update/feedback resource.
`FeedbackResource`	Bug-report resource (`reportBug`).

Functions

Export	Description
`run(agent, input, options?)`	Run an agent turn via `defaultRunner`. Returns `Promise<AgentRunResult>`.
`stream(agent, input, options?)`	Stream agent events via `defaultRunner`. Returns `AsyncGenerator<AgentRunEvent>`.
`streamText(agent, input, options?)`	Stream text deltas via `defaultRunner`. Returns `AsyncGenerator<string>`.
`runText(agent, input, options?)`	Run and return just the text via `defaultRunner`. Returns `Promise<string>`.
`streamObject(agent, input, schema, options?)`	Stream with structured output via `defaultRunner`. Returns `AsyncGenerator<AgentObjectEvent<T>>`.
`runObject(agent, input, schema, options?)`	Run with structured output via `defaultRunner`. Returns `Promise<AgentObjectResult<T>>`.
`createSession(agent, options?)`	Create a `Session`.
`buildAgentChatRequest(opts)`	Build a `ChatRequest` without executing.
`resumeAgentStream(streamId, lastEventId, handlers, options?)`	Resume a detached durable stream.
`configureClient(options)`	Configure the default `MatildaCore` singleton.
`getClientConfig()`	Get the default core's config.
`getDefaultCore()`	Get the default `MatildaCore` singleton.
`trustApiBaseUrl(rawUrl, policy?)`	Validate and brand a URL as trusted.
`createFileTokenStore(path)`	`0600` JSON file token store with cross-process lock.
`memoryStorage()`	In-memory `StorageAdapter`.

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.
`DEFAULT_SUCCESS_REDIRECT`	`'https://matilda.maincode.com/cli/signed-in'`	Default browser login success redirect.
`MATILDA_API_VERSION_HEADER`	—	API version header name.
`MATILDA_CURRENT_API_VERSION`	—	Current API version string.

Instances

Export	Description
`defaultRunner`	A `Runner` using the default `MatildaCore` singleton.

Types

Export	Description
`AgentPurpose`	`'code' \| 'analysis' \| 'general'`
`AgentInstructions`	`string \| ((ctx: AgentRunContext) => string \| Promise<string>)`
`AgentRunContext`	Context passed to dynamic instructions.
`AgentOptions`	Constructor options for `Agent`.
`AgentRunOptions`	Options for `runner.run()` / `runner.stream()`.
`AgentRunEvent`	22-variant discriminated union of stream events.
`AgentRunResult`	Result of an agent run.
`AgentObjectEvent<T>`	`AgentRunEvent` plus a final `{ type: 'object'; object: T }`.
`AgentObjectResult<T>`	`AgentRunResult` plus the validated `object`.
`AgentObjectRunOptions<T>`	`AgentRunOptions` with an embedded zod `schema`.
`AgentCallbacks`	Callback hooks for `run()`.
`BuildAgentChatRequestOptions`	Options for `buildAgentChatRequest()`.
`ToolHandler`	`(args, ctx) => Promise<ToolResult>`
`ToolHandlers`	`Record<string, ToolHandler>`
`ToolExecutionContext`	Context passed to tool handlers.
`ToolResult`	`{ content: string; isError?: boolean }`
`SessionOptions`	Options for `Session` / `createSession()`.
`FileUploadOptions`	Options for `files.upload()`.
`CoreSource`	`MatildaCore \| (() => MatildaCore)`
`BrowserLoginOptions`	Options for `auth.loginWithBrowser()`.
`DeviceLoginOptions`	Options for `auth.loginWithDeviceFlow()`.
`TokenSet`	`{ accessToken, refreshToken?, idToken?, expiresAt }`
`TokenManager`	Token manager interface.
`StorageAdapter`	Token persistence interface.
`LoginFlowEvent`	Login flow state event type.
`FileTokenStore`	File token store return type.
`ClientConfig`	Core config type (re-exported).
`GetToken`	Token provider function type (re-exported).
`TrustedApiBaseUrl`	Branded string type (re-exported).
`TrustedApiBaseUrlPolicy`	URL validation policy (re-exported).
`ApiMessage`	`{ role, content }` (re-exported).
`ChatRequest`	Chat request type (re-exported).
`ChatResponseMode`	`'auto' \| 'instant' \| 'deep'` (re-exported).
`ChatSseEvent`	SSE event type (re-exported).
`ChatSseEventName`	SSE event name type (re-exported).
`SafetyReplaceEvent`	Safety replace event type (re-exported).
`UsageEvent`	Token usage type (re-exported).
`ConversationListResponse`	Conversation list response (re-exported).
`ConversationRecord`	Full conversation record (re-exported).
`ConversationSummary`	Conversation summary (re-exported).
`FileAttachment`	File metadata (re-exported).
`FileCompleteResponse`	File upload result (re-exported).
`UploadFilesOptions`	Multi-file upload options (re-exported).

Error classes re-exported

Export	Description
`AuthError`	OAuth error (code, retryable). Re-exported from client SDK.