Skip to content

Public API

Export Description
createAgent(options) Creates an in-memory Agent with a private workspace and default workspace tools.
createBareAgent(options) Creates an in-memory Agent without default tools, workspace instructions, or workspace directory creation.
defineAgent(options) Creates an AgentSpec template from agent options. The spec is stateless; spawn() creates an independent session with its own history and workspace.
isAgentSpec(target) Type guard distinguishing an AgentSpec template from a live AgentLike session.
query(params) One-shot async generator helper.
tool(name, description, inputSchema, handler) Creates a custom tool definition.
agentTool(name, target, metadata) Exposes another AgentLike or AgentSpec as a model tool with explicit ask, handoff, or observe modes. A spec target spawns a fresh session per call; a session target keeps its history across calls. With inputSchema + mapInput (requires 0.21.0) the tool takes a custom typed input shape instead (ask-only) and the return type is ToolDefinition<any>.
delegateTool(name, description, agent, options) Advanced helper that exposes an AgentLike or AgentSpec as a mailbox-backed delegate tool.
skill(options) Creates an in-memory skill definition.
loadSkill(path) Loads a skill from a directory containing SKILL.md.
createMCPTools(client, options) Maps an MCP client into SDK tool definitions.
connectMCPStdioServer(server, options) Connects a stdio MCP server and returns SDK tools plus a close handle.
connectMCPStreamableHTTPServer(url, options) Connects a remote Streamable HTTP MCP server, with optional OAuth support.
createJsonlContextTracer(options) Creates a JSONL trace sink for agent run context events.
createLangSmithContextTracer(options) Creates a LangSmith trace sink from the same provider-agnostic context events.
createLangfuseContextTracer(options) Creates a Langfuse trace sink (built on @langfuse/tracing v5) from the same provider-agnostic context events.
createCompositeContextTracer(tracers) Fans context trace events out to multiple trace sinks.
defineContextTracer(impl) Creates a custom trace sink from an implementation object, validating onEvent and binding failOnError at creation time.
createCompositeAgentHooks(hooks) Chains hooks in array order; each receives the previous one’s output.
createJsonlHistoryStore(options) Creates a JSONL history store that persists an Agent’s conversation as one message per line.
defineHistoryStore(impl) Creates a custom history store from an implementation object, validating load/append/replace and binding failOnError at creation time.
DEFAULT_COMPACTION_PROMPT The built-in summarization instruction used by autoCompact.
SUBMIT_OUTPUT_TOOL_NAME Name of the built-in tool ("submit_output") injected when AgentOptions.outputSchema is set. The name is reserved in that mode.
teamMember(options) Creates a named team member with role, focus, and agent.
createTeam(options) Creates a callable team wrapper around a lead, members, mailbox, and built-in runtime. After the lead queues a handoff batch, members run before the lead model is called again. Set runner.maxConcurrentWorkItems for bounded cross-member concurrency; the default is 1.
createTeamRunner(options) Advanced runtime for manually running a root AgentLike with mailbox-backed delegate tools. Accepts maxConcurrentWorkItems; member failures stay isolated and a run-wide abort cancels remaining work.
createMemoryMailbox() Creates the default in-memory team mailbox adapter.
createSQLiteMailbox(options) Creates a durable team mailbox adapter from a SQLite-like database.
createBuiltinTools(options) Creates the built-in file and shell tools for manual tool assembly.
createAgentWorkspaceTools(options) Creates opt-in file and shell workspace tools for agents.

Agent is a type-only export (breaking in 0.17.0: the constructor is no longer exported). Create instances with createAgent(), createBareAgent(), or AgentSpec.spawn() — the factories also generate the session id and install the workspace.

const agent = createAgent(options);
for await (const message of agent.query(prompt)) {
console.log(message);
}
const result = await agent.prompt(prompt);
// A deep copy of the conversation history, including messages seeded from
// AgentOptions.historyStore. Mutating it cannot corrupt the live history.
const history = await agent.getHistory();
// Replace the whole conversation history. Idle only (throws
// ConcurrentQueryError while a query runs); a configured historyStore is
// replaced too, so persistence stays in sync. The SDK does not validate the
// content — the host owns it.
await agent.replaceHistory(messages);
// End the running query with subtype "interrupted", keeping completed turns
// in history so a follow-up query can continue the conversation. Returns
// true when a query was interrupted, false when idle.
agent.interrupt();
// The structured output contract declared via AgentOptions.outputSchema,
// if any. Read-only; used by agentTool() for contract inheritance.
// Requires 0.21.0 or later.
agent.outputSchema;

interrupt() is the cooperative counterpart of QueryOptions.signal: the signal terminates the query with error_abort, while an interrupt finishes it with interrupted (not an error) after dropping only the in-flight turn. It returns false when no query is running, so the host knows it can send its next query directly.

Use createAgent() when the agent should have a private workspace for durable files and test evidence. Use createBareAgent() when the host wants a plain model loop and will pass every system prompt and tool explicitly:

import { createBareAgent, createBuiltinTools } from "agent-lattice";
const agent = createBareAgent({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: "https://api.deepseek.com/anthropic",
model: "deepseek-v4-flash",
systemPrompt: "You are a concise engineering assistant.",
tools: createBuiltinTools({
cwd: process.cwd(),
allowedDirectories: [process.cwd()],
}),
});
Option Type Description
apiKey string Provider API key.
baseURL string Optional Anthropic-compatible endpoint, such as DeepSeek.
name string Optional source name used in context trace events.
model string Model name.
systemPrompt string Stable role and responsibility instructions sent as the provider system prompt.
maxTokens number Maximum output tokens per model request.
maxTurns number Maximum agent loop turns before returning error_max_turns.
thinkingConfig ThinkingConfig Default reasoning configuration. Accepts { type: "adaptive" }, { type: "enabled", budgetTokens }, or { type: "disabled" }. disabled is sent to the provider explicitly (as thinking: { "type": "disabled" }) because some Anthropic-compatible providers, such as DeepSeek, default thinking to on. When omitted, the SDK sends no thinking configuration. See Provider Compatibility for what each provider actually honors.
reasoningEffort ReasoningEffort Default provider reasoning effort. Accepts "low", "high", or "max" and is sent as reasoning_effort (a Kimi convention — ignored by DeepSeek; see Provider Compatibility). When omitted, the provider applies its default.
requestTimeoutMs number Deadline for each single model request, in milliseconds. Enforced by the SDK even when a model client ignores it. Unset means no SDK-side limit.
outputSchema OutputSchema Requires the run to end with a validated structured payload. The SDK injects a built-in submit_output tool; a valid submission ends the run with subtype: "success" and the payload on SDKResultMessage.structuredResult, while ending the turn without submitting fails with error_missing_output (MissingOutputError). Unlike QueryOptions.outputFormat, it only requires a tool-capable provider.
tools ToolDefinition[] Custom tools available to the model.
toolBatchPolicy ToolBatchPolicy Optional pre-execution hook that accepts or rejects the complete tool-call batch before any handler runs.
hooks AgentHooks Lifecycle callbacks that rewrite tool results and outgoing model requests. Not inherited by delegated agents.
autoCompact boolean | AutoCompactOptions Replaces older history with a model-written summary past a token threshold. Off unless set; true uses the defaults.
toolConcurrency ToolConcurrencyOptions Tool-call scheduling. Defaults to { mode: "safe", maxConcurrency: 10 }; undeclared tools stay sequential.
skills SkillDefinition[] Reusable instruction bundles selected per query.
workspace string | false | { cwd: string; allowedDirectories?: string[]; bashTimeoutMs?: number } Optional override for the private agent workspace. Defaults to ~/.agent/workspaces/<name> when name is set, otherwise ~/.agent/workspaces/agent-<session-id>. false (requires 0.23.0) opts out of the built-in workspace entirely — no built-in file/shell tools, no workspace prompt section — equivalent to createBareAgent() and also effective through defineAgent().
permission function Callback that can allow or deny tool execution.
modelClient ModelClient Custom model client for tests or alternate providers.
tracer ContextTracer Optional trace sink for agent context events.
historyStore HistoryStore Optional persistence adapter for the conversation history. Loaded once before the first query; append() follows every history write and replace() follows compaction.

createBareAgent() accepts BareAgentOptions, which is AgentOptions without workspace. It does not add workspace instructions, create a default workspace directory, or register built-in tools unless you pass them in tools.

Option Type Description
stream boolean Enables raw provider stream events. Defaults to true.
outputFormat OutputFormat Requests structured output via "json" or JSON Schema output via { type: "json_schema", schema }; the final text is returned unchanged.
thinkingConfig ThinkingConfig Overrides the agent’s reasoning configuration for this query. A fixed budget is capped at maxTokens - 1.
reasoningEffort ReasoningEffort Overrides the agent’s provider reasoning effort for this query.
requestTimeoutMs number Overrides the agent’s per-request deadline for this query.
signal AbortSignal Cancels the running query, ending it with subtype error_abort. Compare Agent.interrupt(), which ends it with interrupted and keeps the conversation.
runtime AgentRuntimeContext Runtime context supplied by team runners and delegate tools.
tracer ContextTracer Query-scoped trace sink. Overrides or supplies tracing for this query.
import {
createAgent,
createCompositeContextTracer,
createJsonlContextTracer,
createLangSmithContextTracer,
} from "agent-lattice";
const tracer = createCompositeContextTracer([
createJsonlContextTracer({ path: ".agent-runs/session.jsonl" }),
createLangSmithContextTracer({
projectName: process.env.LANGSMITH_PROJECT,
workspaceId: process.env.LANGSMITH_WORKSPACE_ID,
}),
]);
const agent = createAgent({
model: "deepseek-v4-flash",
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: "https://api.deepseek.com/anthropic",
tracer,
});
try {
await agent.prompt("Trace this run.", { stream: false });
} finally {
await tracer.close?.();
}

createJsonlContextTracer() accepts either path for one explicit file or dir for one file per session_id. It also accepts redact(event) for local filtering before persistence and failOnError for hosts that want trace write failures to fail the agent run.

createLangSmithContextTracer() uses the bundled langsmith RunTree by default (since 0.17.0); pass a LangSmith-compatible RunTree constructor or runTree(config) factory only to inject a custom runtime or a test fake. The SDK depends on langsmith directly and uses the official RunTree / RunTreeConfig types from langsmith/run_trees. Configure LangSmith with its standard environment variables: LANGSMITH_TRACING, LANGSMITH_ENDPOINT, LANGSMITH_API_KEY, and LANGSMITH_PROJECT. LANGSMITH_WORKSPACE_ID is required only for org-scoped or multi-workspace API keys. You can pass apiKey, apiUrl, and workspaceId directly to createLangSmithContextTracer(); workspaceId is only for selecting a LangSmith workspace and is not the project name. If you need full LangSmith client customization, pass an explicit Client as client. In short-lived tests or scripts, close or flush the tracer in finally before the process exits so LangSmith receives the final root run patch.

createLangfuseContextTracer() (requires 0.19.0) maps the same events onto Langfuse observations through the current @langfuse/tracing (v5) SDK: a chain observation per agent run, a generation per model turn, a tool per tool call, and auto-ended event observations for auxiliary events. The Langfuse SDK is OpenTelemetry-based — register a LangfuseSpanProcessor (from @langfuse/otel) with a tracer provider at process startup and configure the standard LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_BASE_URL environment variables. Pass the registered processor as spanProcessor so flush()/close() drains pending spans before a short-lived process exits. startObservation defaults to the bundled @langfuse/tracing function; pass it only to inject a custom runtime or a test fake.

When the tracer is passed to team.query() or team.prompt(), one Team call creates one root chain. Lead runs, delegated Member runs, and later Lead runs share its trace session and appear as child chains. Their original Agent session IDs remain available as agent_session_id metadata.

Everything below works on the version shown and later. Before 0.22.0 the SDK ignored unknown options rather than rejecting them, so calling a newer API on an older install succeeded with the feature silently absent. Since 0.22.0 the main factories (createAgent()/createBareAgent()/defineAgent(), agentTool(), delegateTool(), tool()) throw on unknown option keys, but other options objects still ignore them — check the installed version rather than relying on an error.

Feature Requires
toolConcurrency, isConcurrencySafe, toolBatchPolicy, reasoningEffort 0.9.25
SDKResultMessage.usage, stop_reason, TokenUsage, ConcurrentQueryError 0.10.0
requestTimeoutMs, TimeoutError, result subtype error_timeout 0.11.0
hooks, AgentHooks, createCompositeAgentHooks 0.12.0
autoCompact, DEFAULT_COMPACTION_PROMPT, SDKSystemCompactionMessage 0.13.0
Compaction recovery after an overflow, model_context_window_exceeded 0.14.0
defineAgent(), AgentSpec, AgentToolTarget, isAgentSpec(), AgentSpec targets for agentTool()/delegateTool() 0.15.0
AssistantModelMessage.providerResponseId, AssistantModelMessage.model, ToolResult.endTurn, Agent.interrupt() (also on the AgentLike interface — breaking for custom implementers), result subtype interrupted, AgentOptions.historyStore, HistoryStore, createJsonlHistoryStore, Agent.getHistory() 0.16.0
Agent.replaceHistory(), AgentLike.interrupt() returns boolean (breaking for custom implementers), defineContextTracer(), defineHistoryStore() (breaking: failOnError removed from the ContextTracer/HistoryStore port types — custom implementations must use the defineXxx factories), Agent becomes a type-only export (breaking: new Agent() no longer available), createLangSmithContextTracer() defaults to the bundled RunTree, tool_use trace events carry the tool description 0.17.0
thinkingConfig: { type: "disabled" } is sent to the provider explicitly as thinking: { "type": "disabled" } instead of being omitted (fixes providers that default thinking to on, e.g. DeepSeek) 0.17.1
Tool calls in a response truncated at max_tokens are not executed; each call gets an error tool_result asking the model to reissue it with shorter output 0.18.0
createLangfuseContextTracer(), LangfuseContextTracerOptions, LangfuseObservationLike, LangfuseChainLike, LangfuseGenerationLike, LangfuseToolLike, LangfuseStartObservation, LangfuseFlushableSpanProcessor, LangfuseKVMap 0.19.0
AgentOptions.outputSchema, OutputSchema, SUBMIT_OUTPUT_TOOL_NAME, MissingOutputError, SDKResultMessage.structuredResult, result subtype error_missing_output, AgentRuntimeFailure code missing_output, ToolResult.structuredResult, AgentToolOptions.outputSchema 0.20.0
AgentToolOptions.inputSchema + mapInput (typed ask-only delegation), agentTool() inherits outputSchema from the target and cross-checks explicit copies at assembly time, Agent.outputSchema getter, agentTool() returns ToolDefinition<any> (behavior change: ask with an inherited schema now returns the validated JSON instead of the fixed "Structured output submitted." text) 0.21.0
Strict option validation: createAgent()/createBareAgent()/defineAgent() (AgentOptions), agentTool() (AgentToolOptions), delegateTool() (DelegateToolOptions), and tool() (ToolOptions) throw on unknown option keys at assembly time (behavior change: extra keys that used to be silently ignored, e.g. spread host fields, now throw). ToolOptions.metadata / AgentToolOptions.metadata pass through to ToolDefinition.metadata (host-owned, never shown to the model) 0.22.0
AgentOptions.workspace: false (bare mode, also via defineAgent()), agentTool() contract pinned: explicit outputSchema with no target declaration validates the child’s structuredResult, and with no schema on either side ask passes the child’s structuredResult through as unvalidated JSON (behavior change: previously the ask result fell back to the text content and dropped it) 0.23.0

Read the installed version from node_modules/agent-lattice/package.json; the package does not export it as an importable path.

Export Description
SDKMessage Union of all emitted SDK events.
AgentLikeEvent Union emitted by AgentLike.query(), including plain SDK messages and team runtime events.
AgentLike Minimal callable interface implemented by Agent and the callable Team wrapper: query(), prompt(), and interrupt() (the latter requires 0.16.0; its boolean return requires 0.17.0).
AgentSpec Agent template created by defineAgent(): a stateless identity (name, model, prompt, tools, workspace policy) plus spawn() for creating independent sessions.
AgentToolTarget Union accepted by agentTool() and delegateTool(): a live AgentLike session or an AgentSpec template.
AgentOptions Agent construction options.
BareAgentOptions Construction options for createBareAgent(), equivalent to AgentOptions without workspace.
AgentWorkspaceOptions String path or workspace configuration object accepted by AgentOptions.workspace to override the default workspace.
AgentWorkspaceToolsOptions cwd, write-root, and shell timeout options accepted by createBuiltinTools() and createAgentWorkspaceTools().
QueryOptions Per-query options for streaming, cancellation, runtime, and tracing.
OutputFormat Structured output format accepted by QueryOptions.outputFormat: "json" or { type: "json_schema", schema }.
OutputSchema Validation shape accepted by AgentOptions.outputSchema and AgentToolOptions.outputSchema: { parse(input: unknown): T }. A zod schema satisfies it directly (requires 0.20.0).
ThinkingConfig Reasoning configuration accepted by AgentOptions.thinkingConfig and QueryOptions.thinkingConfig.
ReasoningEffort Provider reasoning effort accepted by AgentOptions.reasoningEffort and QueryOptions.reasoningEffort: "low", "high", or "max".
TokenUsage Token counts reported on SDKResultMessage.usage and AssistantModelMessage.usage.
AssistantModelMessage One assistant turn returned by a ModelClient: content, optional usage and stopReason, plus optional provider metadata providerResponseId (the provider-assigned response id) and model (the model that actually served the response, which may differ from the requested one).
StopReason Why the model stopped. "max_tokens" means the output was truncated; "model_context_window_exceeded" means the context window ran out and is what autoCompact recovers from.
AgentRuntimeFailure Normalized member failure stored in failure events and upstream report metadata.
TeamRunnerConfig Team runtime limits: maxDelegateDepth and maxConcurrentWorkItems. Concurrency defaults to 1, and the same target mailbox remains serial.
ContextTracer Trace sink interface with onEvent, optional flush, and optional close. Methods only — failOnError is bound by the creating factory (createXxxContextTracer options or defineContextTracer()).
ContextTraceEvent Structured trace event envelope emitted by agents.
ContextTraceEventType Union of trace event type strings.
JsonlContextTracerOptions Options for the built-in JSONL tracer.
LangSmithContextTracerOptions Options for the LangSmith tracer adapter.
LangfuseContextTracerOptions Options for the Langfuse tracer adapter (requires 0.19.0).
LangfuseObservationLike Alias for the @langfuse/tracing LangfuseObservation union; LangfuseChainLike, LangfuseGenerationLike, and LangfuseToolLike alias the concrete observation classes (requires 0.19.0).
LangfuseStartObservation Alias for the @langfuse/tracing startObservation function type, accepted by LangfuseContextTracerOptions.startObservation (requires 0.19.0).
LangfuseFlushableSpanProcessor Minimal forceFlush() shape a LangfuseSpanProcessor satisfies, accepted by LangfuseContextTracerOptions.spanProcessor (requires 0.19.0).
HistoryStore Persistence adapter interface for an Agent’s conversation history: load(), append(message), replace(messages). Compaction calls replace(), so stores must support full replacement. Methods only — failOnError is bound by the creating factory (createJsonlHistoryStore options or defineHistoryStore()).
JsonlHistoryStoreOptions Options for the built-in JSONL history store: path and optional failOnError.
LangSmithRunTreeLike Alias for LangSmith’s official RunTree type.
LangSmithRunTreeConfig Alias for LangSmith’s official RunTreeConfig type.
ToolDefinition Tool shape passed to an agent. Carries optional host-owned metadata passed through from ToolOptions.metadata/AgentToolOptions.metadata (requires 0.22.0); never shown to the model.
ToolResult Tool handler return value: content plus optional endTurn, which ends the run with subtype: "success" after the batch instead of calling the model again, and optional structuredResult (requires 0.20.0), a structured payload carried to SDKResultMessage.structuredResult when combined with endTurn: true and ignored otherwise.
ToolOptions Optional tool() settings, including the input-aware isConcurrencySafe check and host-owned metadata (requires 0.22.0) passed through to ToolDefinition.metadata.
ToolConcurrencyMode Tool scheduling mode: "safe", "all", or "sequential".
ToolConcurrencyOptions Agent tool scheduling mode and positive maxConcurrency limit.
AutoCompactOptions Compaction settings: thresholdTokens (100000), keepRecentMessages (6), prompt, model, maxTokens.
SDKSystemCompactionMessage system message with subtype: "compaction", emitted when history is summarized. Reports message counts and the summary’s own usage.
AgentHooks Lifecycle callbacks accepted by AgentOptions.hooks: onToolResult and onModelRequest. A hook that throws propagates out of query().
ToolResultHookContext onToolResult input: tool name, raw input, the result block, and the error when the call failed.
ModelRequestHookContext onModelRequest input: the messages and system prompt about to be sent, plus the turn number.
ModelRequestHookResult Replacement messages and/or systemPrompt for one request; the stored history is untouched.
ToolBatchPolicy Optional Agent policy that validates a complete tool-call batch before execution.
ToolBatchPolicyContext Policy input containing source, host context, signal, and tool calls with tool or agent_tool kind.
ToolBatchPolicyResult Allows a batch or rejects it with a code, message, conflicting call IDs, and suggested next step.
AgentToolInput Standard input shape for agentTool().
AgentToolOptions Description and target mailbox options for agentTool(), plus outputSchema (requires 0.20.0): in ask mode the tool result is the child’s validated structured output as a JSON string, and a missing or invalid child submission surfaces as a child_output_invalid tool error. Since 0.21.0 an omitted outputSchema is inherited from the target’s own declaration (spec.options.outputSchema or the live Agent’s outputSchema getter; host-defined AgentLike adapters carry no declaration, so nothing is inherited or cross-checked), and an explicit copy that does not match the target’s declaration throws at assembly time. Also since 0.21.0, inputSchema + mapInput (required as a pair) enable typed delegation: the tool takes the custom schema as input — ask-only, no mode/workspaceGrants — validates the parent’s arguments before the child runs, and projects the validated input into the child prompt. Also accepts host-owned metadata (requires 0.22.0) passed through to ToolDefinition.metadata; never shown to the model. Since 0.23.0 two more contract combinations are pinned: an explicit outputSchema with no target declaration is allowed and validates the child’s structuredResult; and with no schema on either side, an ask result passes the child’s structuredResult through as unvalidated JSON instead of falling back to the text content.
DelegateToolOptions Options for mailbox-backed AgentLike delegation.
SkillDefinition Reusable instruction bundle passed to an agent.
MCPClient Minimal MCP client interface used by createMCPTools().
MCPStdioConnection Connected stdio MCP server with mapped tools.
MCPStreamableHTTPConnection Connected remote Streamable HTTP MCP server with auth/session helpers.
Team Callable wrapper around a lead with members, member AgentLike tools, and advanced mailbox controls. Its default prompt() result is the root lead’s final answer, not a handoff receipt.
TeamRunner Advanced runtime that drives mailbox-backed AgentLike delegate tools, including accepted handoffs that need mailbox follow-up before final delivery.
TeamRunnerMessage Union of root SDK messages and team runner activity events.
TeamMemberDefinition Named team member with role and AgentLike.
TeamMailbox Storage adapter interface for team messages, including member-scoped claimNext().
TeamMessage Message record with thread and work-item context.
TeamDrainOptions Limits and abort signal for team.drain().
TeamDrainResult Processed, failed, and round counts from team.drain().
SQLiteDatabaseLike Minimal database interface accepted by createSQLiteMailbox().
SQLiteMailboxOptions SQLite mailbox adapter options.
PermissionDecision Allow or deny decision returned by a permission callback.
ModelClient Interface for custom or mocked model clients.
Error Description
APIError Provider request or response failure.
ToolExecutionError Tool handler failure.
MaxTurnsError Agent loop reached maxTurns.
AbortError Request was aborted.
TimeoutError A model request exceeded requestTimeoutMs; the result subtype is error_timeout.
ToolBatchRejectedError Tool batch was rejected before any tool executed.
ConcurrentQueryError A second query was started while the Agent was still running one. An Agent holds one conversation.
MissingOutputError A run with AgentOptions.outputSchema ended without the model calling submit_output; the result subtype is error_missing_output.