API reference

This section is auto-generated from TypeDoc on every build. 249 symbols exported.

Classes

• Agent — Static façade for creating and managing Theo agents.
• AgentBuilder — Fluent builder for AgentOptions. Chainable setters mutate internal
• AgentRunError — Thrown by Agent.prompt (and helpers that go through run.wait()) when
• AuthenticationError — Invalid API key, not logged in, insufficient permissions.
• Cache — no description
• CacheEmbedderError — no description
• CacheInvalidTtlError — no description
• ConfigurationError — Invalid model, bad request parameters, malformed options.
• CredentialPoolExhaustedError — Thrown when every credential in a per-provider pool is in cooldown
• Cron — Static façade for scheduling Theo agent runs on a cron expression.
• Eval — no description
• EvalAlreadyRunningError — no description
• GenerateObjectError — Typed error thrown by Agent.generateObject when the model refuses
• Handoff — no description
• HandoffLoopError — Throw when handoff depth exceeds maxHandoffDepth (default 5; D218).
• HandoffNameCollisionError — Throw when two handoffs in the same parent collide on tool name (D215).
• HandoffPairLoopError — Throw when the same (sender, receiver) pair invoked twice in one send() (D221).
• HandoffReceiverDisposedError — Throw when receiver is disposed at dispatch time (EC-5).
• HandoffSelfReferenceError — Throw when an agent's handoffs[] includes a self-reference (EC-6).
• IntegrationNotConnectedError — Thrown when creating a cloud agent for a repo whose SCM provider is not
• MemoryAdapterError — Error raised by @theokit-memory-* adapters. Carries adapterId
• NetworkError — Service unavailable, timeout, transport-level failure.
• RateLimitError — Too many requests or usage limits exceeded.
• Security — no description
• StreamObjectError — Error thrown by Agent.streamObject when the model refuses to call
• Theokit — Account-level and catalog reads. All methods accept an optional apiKey
• TheokitAgentError — Base class for all errors thrown by @theokit/sdk.
• UnknownAgentError — Catch-all for unclassified server or runtime errors.
• UnsupportedRunOperationError — Thrown when a Run or agent operation is not available on the current
• Workflow — no description
• WorkflowAlreadyRunningError — no description
• WorkflowBuilder — no description
• WorkflowCompensateNotImplementedError — D238 — saga engine not yet implemented.
• WorkflowDuplicateStepIdError — no description
• WorkflowMaxIterationsExceededError — no description
• WorkflowNotSerializableError — EC-4 absorbed — JSON.stringify failed on snapshot payload.
• WorkflowParallelError — Aggregate failure from parallel branches.
• WorkflowResumeStepNotFoundError — EC-8 absorbed — currentStepId from snapshot not found in resumed workflow.
• WorkflowSnapshotNotFoundError — no description

Constantes

• Memory — no description
• RECOMMENDED_HANDOFF_PROMPT_PREFIX — Recommended system-prompt prefix for senders (D215 / EC-13).
• Scorers — no description

Functiones

• agentStep — no description
• createAgentFactory — no description
• definePlugin — no description
• defineTool — no description
• extractRawId — no description
• fn — no description
• handoffTo — no description
• migrateSqliteToLance — no description
• mkMemoryId — no description
• toShareGptTrajectory — no description

Interfacees

• AgentConversationTurn — Agent turn: user message + assistant/tool/thinking steps.
• AgentDefinition — Subagent definition. The parent agent spawns these via its Agent tool.
• AgentFactory — Handle returned by createAgentFactory. See ADR D23 for merge
• AgentMemory — Direct memory API exposed on SDKAgent.memory. Resolves to whichever
• AgentOperationOptions — Options for archive/unarchive/delete.
• AgentOptions — Top-level options accepted by Agent.create().
• AgentStep — An agent.send-driven step.
• AssistantMessage — Plain assistant message in a conversation history.
• BatchItem — Single prompt in a batch. Plain string is shorthand for { prompt }.
• BatchOptions — Options accepted by Agent.batch. Extends AgentOptions — every
• BatchProgress — Live progress snapshot delivered to onProgress.
• BranchStep — First-match-wins predicates + optional fallback.
• CacheEmbedderRuntime — Embedder runtime shape — minimal subset of EmbeddingRuntime (D11) the
• CacheEntry — no description
• CachePersistenceOptions — no description
• CacheSemanticOptions — no description
• CacheStats — no description
• CacheTTLConfig — Public type contract for Cache.semantic / .asPlugin / .stats / .clear
• CloudEnv — Cloud execution environment.
• CloudOptions — Cloud agent configuration.
• CloudRepo — Repo to clone into a cloud agent's VM.
• ContextBudget — Token budget used by the context manager for a single agent.
• ContextSettings — Context configuration accepted by Agent.create() via AgentOptions.context.
• ContextSnapshot — Result of agent.context.snapshot(). Public and secret-free by design — safe
• ContextSource — A single context source resolved by the context manager.
• CronCreateOptions — Options for Cron.create().
• CronGetOptions — Options for Cron.get().
• CronJob — Persistent cron-scheduled invocation of the Theo agent.
• CronOperationOptions — Options for Cron.delete() / Cron.enable() / Cron.disable().
• CronRunOptions — Options for Cron.run() — manually trigger a job off-schedule.
• CronSchedulerStatus — Snapshot of the local scheduler returned by Cron.status().
• CronStartOptions — Options for Cron.start() — activates the in-process scheduler for local
• CustomTool — Inline custom tool — registered with the LLM under the given name + schema
• DatasetEntry — A single dataset row — input prompt + optional reference + free-form metadata.
• DefineToolSpec — Spec accepted by defineTool. inputSchema is a Zod schema; the
• DowhileStep — Loop a step until condFn returns false.
• DreamingSweepOptions — Public Memory namespace.
• DreamingSweepResult — no description
• ErrorMetadata — Structured context for errors that originated from a provider HTTP
• EvalAggregate — Aggregate stats — the production-decision dashboard data (D211).
• EvalHooks — Lifecycle hooks. Each fires inside a safeHook wrapper (EC-4); a throw never ab
• EvalOptions — Public options for Eval.create.
• EvalRowResult — Per-row outcome.
• EvalRun — Final run result — plain serializable JSON (D209).
• EvalRunOptions — Per-call options for eval.run(...).
• FnStep — A pure function step.
• ForeachStep — Map a step over an upstream array output.
• GenerateObjectOptions — Options accepted by Agent.generateObject. Returns a typed object
• GenerateObjectResult — Successful return from Agent.generateObject.
• GetAgentOptions — Options for Agent.get().
• GoalOptions — Per-call configuration for Agent.runUntil.
• GoalResult — Return value of the runUntil async generator. Consumer reads via
• HandoffContext — Context handed to onHandoff callbacks and isEnabled predicates.
• HandoffDescriptor — Public Handoff shape — what Handoff.create() returns. Read-only
• HandoffHistory — The transcript wrapper passed to inputFilter. messages is widened to
• HandoffOptions — Options accepted by Handoff.create(target, opts?).
• HandoffResult — Result of a single handoff dispatch (for telemetry / observability).
• InvalidateCacheOptions — Options for SDKAgent.invalidateCache.
• ListResult — Paginated list shape.
• LocalOptions — Local agent configuration.
• McpAuthConfig — OAuth-style auth bundle for HTTP/SSE MCP servers.
• McpOAuthConfig — OAuth 2.1 PKCE flow descriptor. See ADR D41.
• MemoryAdapter — Portable third-party memory adapter contract. Implementations live
• MemoryAdapterCapabilities — Statically declared adapter feature flags. Consumers feature-detect
• MemoryContext — Portable identity context. userId is the only required field —
• MemoryFact — A single memory fact returned by recall or get.
• MemoryRevision — Versioned snapshot of a memory's history. Only emitted by providers
• MemorySettings — Memory configuration accepted by Agent.create() via AgentOptions.memory.
• MemoryToolSchema — OpenAI-format function-calling schema exposed to the LLM.
• MemoryTurnMessage — One assistant-turn message in the canonical {role, content} shape
• MigrateOptions — Options for migrateSqliteToLance.
• MigrateResult — Outcome of migrateSqliteToLance.
• ModelListItem — Single model entry in the catalog.
• ModelParameterDefinition — Per-model parameter definition discovered from Theokit.models.list().
• ModelParameterValue — One slot in a ModelSelection.params array.
• ModelSelection — Identifies a model plus optional per-model parameters (e.g. reasoning effort).
• ModelVariant — Preset variant for a model — pre-filled parameter combinations.
• NamedScorer — A named scorer — produced by every Scorers.* factory.
• ParallelStep — N concurrent branches, each its own mini-step-list.
• PartialToolCallUpdate — Tool call arguments streaming in incrementally.
• PerScorerStats — Per-scorer breakdown computed across all rows.
• PersonalityPreset — Resolved personality preset surfaced via SDKAgent.usePersonality
• PluginContext — no description
• PluginsSettings — Plugins configuration accepted by Agent.create() via
• PreToolCallContext — no description
• PreToolCallDecision — no description
• ProviderProfile — no description
• ProviderRoute — A single user-declared routing rule. Maps a capability to a provider, and
• ProviderRoutingSettings — Provider routing configuration accepted by Agent.create() via
• ResolvedProviderRoute — Resolved routing decision returned by agent.providers.routes(). Public and
• RetryPolicy — D237 — retry policy applied per fn/agent step.
• Run — Handle to a single prompt submission.
• RunErrorDetail — Structured error attached to a RunResult when the underlying run
• RunGitInfo — Git metadata attached to cloud runs.
• RunResult — Terminal result of a Run.
• Score — Outcome of a single scoring decision. score in [0, 1]; the runner clamps.
• SDKAgent — Handle returned by Agent.create() and Agent.resume().
• SDKAgentPlugins — Public plugin listing handle exposed as agent.plugins. Populated when
• SDKAgentSkills — Public skill listing handle exposed as agent.skills. Populated when
• SDKArtifact — Artifact produced inside an agent's workspace. Cloud-only.
• SDKAssistantMessage — Model text output for this run.
• SDKContextManager — Public context manager handle exposed as agent.context.
• SDKImageDimension — Dimensions of an inline image attachment.
• SDKObjectDelta — Partial object emitted during Agent.streamObject<T> streaming (ADR D45).
• SDKPluginMetadata — Public plugin metadata returned by agent.plugins.list(). Mirrors the
• SDKProvider — Provider catalog entry returned by Theokit.providers.list().
• SDKProvidersManager — Public providers manager handle exposed as agent.providers.
• SDKRepository — GitHub repository connected to the team. Cloud-only.
• SDKRequestMessage — Awaiting user input or approval.
• SDKStatusMessage — Cloud run lifecycle transitions.
• SDKSystemMessage — Init metadata. Emitted once at the start of a run.
• SDKTaskMessage — Task-level milestones and summaries.
• SDKThinkingMessage — Reasoning content.
• SDKToolUseMessage — Tool invocation lifecycle event. Emitted at start with args, then again on
• SDKUser — Account-level user info returned by Theokit.me().
• SDKUserMessage — Structured form of agent.send()'s message argument. Use it to send images
• SDKUserMessageEvent — Echo of the user prompt for this run.
• SendOptions — Per-send overrides and callbacks.
• ShareGptMessage — One ShareGPT message in a conversation. from identifies the role and
• ShareGptTrajectory — One full ShareGPT-format trajectory — a single conversation plus
• ShellCommand — Shell command executed during a run.
• ShellConversationTurn — Shell turn: a command and its output.
• ShellOutput — Output of a shell command.
• ShellOutputDeltaUpdate — no description
• SkillsSettings — Skills configuration accepted by Agent.create() via
• SleepStep — Pause for a fixed duration.
• StepCompletedUpdate — Conversation step completed.
• StepContext — D247 — context handed to every step.fn.
• StepResult — no description
• StepStartedUpdate — Conversation step started.
• StreamObjectOptions — Options accepted by Agent.streamObject. Same shape as
• SummaryCompletedUpdate — no description
• SummaryStartedUpdate — no description
• SummaryUpdate — no description
• SuspendStep — Standalone explicit suspend point.
• SystemPromptContext — Context passed to a SystemPromptResolver. Field order is a
• SystemPromptMemoryFact — Public view of a recalled memory fact exposed to the system-prompt resolver.
• SystemPromptSkillRef — Public skill metadata exposed to the system-prompt resolver. Mirrors the
• TelemetrySettings — Telemetry configuration for an agent. When enabled: true, the SDK emits
• TextBlock — Plain text content block emitted by the assistant or user.
• TextDeltaUpdate — Incremental text token from the assistant.
• TheokitRequestOptions — Options shared by every Theokit.* request.
• ThinkingCompletedUpdate — Emitted when a reasoning block completes.
• ThinkingDeltaUpdate — Incremental reasoning token.
• ThinkingMessage — Reasoning step in a conversation history.
• TokenDeltaUpdate — Token count delta for usage tracking.
• ToolCall — Single tool call event. The internal args and result shapes are NOT stable.
• ToolCallCompletedUpdate — Tool call completed.
• ToolCallStartedUpdate — Tool call started — args committed.
• ToolUseBlock — Tool invocation block emitted by the assistant.
• TurnEndedUpdate — Turn ended with usage summary.
• UserMessage — User-authored message in a conversation history.
• UserMessageAppendedUpdate — User message appended to the conversation.
• WorkflowOptions — no description
• WorkflowPersistenceOptions — no description
• WorkflowResumeOptions — no description
• WorkflowRun — no description
• WorkflowRunOptions — no description
• WorkflowSnapshot — no description

Typees

• AgentPromptResult — Result of a one-shot Agent.prompt call.
• BatchResult — Per-prompt outcome. Discriminated union — check ok before reading
• ContextManagerKind — Context manager backend.
• ContextSourceStatus — Inclusion state of a single context source in a ContextSnapshot.
• ConversationStep — Single step inside an agent turn.
• ConversationTurn — Structured per-turn view of a run.
• CronJobStatus — Lifecycle state reported by Cron.list() / Cron.get().
• CronListOptions — Options for Cron.list().
• CronRuntime — Runtime hosting a cron job. Mirrors the agent runtime split.
• Dataset — Dataset is either an array OR a factory returning a (sync or async)
• DeepPartial — Recursive partial — T where every nested field becomes optional.
• ErrorCode — Finite, machine-readable error codes for provider-originated errors
• EvalAgentOptions — Inferred Agent.create options shape — avoid cycling through AgentOptions dir
• GetRunOptions — Options for Agent.getRun(). Cloud requires the parent agentId.
• GoalEvent — Single event emitted while iterating a goal-driven loop. Five variants:
• HookName — no description
• InteractionUpdate — Lowest-level raw update from a run. Pass onDelta to agent.send() to
• ListAgentsOptions — Options for Agent.list().
• ListRunsOptions — Options for Agent.listRuns().
• McpHttpServerConfig — HTTP or SSE MCP server.
• McpServerConfig — Union of MCP server configs. See docs.md for the full reference.
• McpStdioServerConfig — MCP server configuration accepted by Agent.create() and agent.send().
• MemoryAdapterErrorCode — Finite error codes specific to memory adapter operations (ADR D141).
• MemoryId — Branded provider memory ID. Format: ${adapterId}:${rawProviderId}.
• Plugin — no description
• ProviderCapability — Capability slot a provider can fulfill.
• RunOperation — Operations that may or may not be supported on a given Run, or on
• RunStatus — Lifecycle status of a Run.
• RunUntilIterator — Return type of import("../internal/runtime/local-agent.js").LocalAgent.runUntil.
• Scorer — Scorer signature (D207). Returns Score synchronously OR via Promise —
• SDKAgentInfo — Metadata returned by Agent.list() and Agent.get().
• SDKImage — Either a remote URL or inline base64 payload.
• SDKMessage — Discriminated union of all stream events. Discriminate on type.
• SDKModel — no description
• SettingSource — Which on-disk settings layers a local agent loads.
• Step — no description
• StreamObjectEvent — Event emitted by Agent.streamObject. Discriminate on type.
• SystemPromptResolver — Resolver function that produces the system prompt dynamically. Receives