packages/agents satisfies one interface, AgentLike, so
they are interchangeable wherever a component takes an agent prop, including
<Task>.
There are two families. SDK agents wrap the AI SDK and
bill a provider over HTTP; they take an Options object and a model id. CLI
agents spawn a vendor’s local command-line tool and share
BaseCliAgentOptions. Two helpers round out the surface:
createHttpTool builds an ad-hoc REST tool, and hashCapabilityRegistry
fingerprints an agent’s capabilities for cache keys.
Import agent classes, the tool factories, and their option types from the
smthrs facade. The option type shapes are also listed in the
Types reference.AgentLike
The structural contract every agent satisfies. You rarely implement it by hand; the built-in classes already do. Type a parameter asAgentLike to accept any
agent.
object
Durable agent checkpoints
Checkpoint-aware agents declare what they produce withcheckpointFormats and
what they consume with checkpointCapabilities. They can return
{ checkpoint: { codec, version, payload } } from generate() or publish
progress through await args.onCheckpoint(checkpoint). The promise is a
durability fence: resolution means Smithers stored the checkpoint while it
still owned the invocation; rejection means publication failed or ownership
was lost. Agents must await it before treating state as durable.
Smithers requires the exact { codec, version, payload } envelope: codec is a
non-empty string, version is a positive safe integer, and payload is strict,
lossless JSON (finite numbers, strings, booleans, null, arrays, and plain
string-keyed objects only). Accessors, sparse arrays, undefined, bigint,
symbols, functions, cycles, non-finite numbers, and custom prototypes are
rejected. The encoded limit defaults to 16 MiB and can be lowered with
maxAgentCheckpointBytes on the workflow run; values above the 16 MiB system
ceiling are rejected because durability snapshots enforce the same ceiling.
Smithers passes the effective ceiling to agent preflight and every generation,
including correction turns, so an agent can enforce it before publishing state.
An agent with a smaller local or protocol limit must enforce the lower value.
A later call receives compatible state as the discriminated pair
{ resumeCheckpoint, checkpointMode: "resume" | "fork" }; it never receives a
checkpoint together with resumeSession. Compatibility requires an exact
codec, version, and mode match in checkpointCapabilities. An omitted result
checkpoint preserves the last published state. Agents without compatible
native state continue through existing CLI sessions, recorded messages, or
fresh stateless generation as applicable.
Checkpoint bytes are opaque to Smithers: it validates, hashes, stores, and
returns them but never interprets payload. Time-travel snapshots privately
embed the snapshot-visible attempt/checkpoint provenance so later GC or attempt
reuse cannot change an older frame; this metadata is removed from parsed user
outputs. Snapshot capture caps each checkpoint at 16 MiB, total encoded
checkpoint provenance at 64 MiB, and visible attempts and references at 100,000
each; capture fails if a bound is exceeded.
Checkpoint production and consumption declarations are part of task cache
identity. The semantic codec/version/mode sets are hashed, so changing support
invalidates prior cache entries while declaration order and duplicates do not.
Use cloneAgentCheckpoint(checkpoint, maxBytes?) to validate and detach data at
adapter boundaries. agentProducesCheckpoint checks the production declaration;
agentSupportsCheckpoint checks consumption; and
hashAgentCheckpointCapabilities computes the cache-identity hash.
DEFAULT_AGENT_CHECKPOINT_MAX_BYTES exposes the 16 MiB default.
Source AgentLike.ts · Tests agent-contract.test.js · See also Agents overview, SmithersCtx
SDK agents
Provider-backed wrappers around the AI SDKToolLoopAgent. Construct with an
Options object whose core fields are standard AI SDK
ToolLoopAgentSettings (instructions, tools,
stopWhen, maxOutputTokens, temperature, providerOptions, prepareCall)
plus a model. Reach for these to bill a provider’s API directly. For a vendor’s
full CLI surface, use a CLI agent.
AnthropicAgent
WrapsToolLoopAgent against the Anthropic provider.
AnthropicAgentOptions
required
ToolLoopAgentSettings without model, plus a required model.OpenAIAgent
WrapsToolLoopAgent against the OpenAI provider or any OpenAI-compatible
endpoint.
OpenAIAgentOptions
required
The Anthropic shape plus
nativeStructuredOutput, in one of two model forms.HermesAgent
OpenAI-compatible wrapper preconfigured for a Nous Research Hermes server.HermesAgentOptions
Mirrors the string-model form of
OpenAIAgentOptions, with Hermes defaults.OpenAIAgent.js · AnthropicAgent.js · HermesAgent.js · Tests sdk-agents.test.js · See also SDK Agents, OpenAIAgentOptions
CLI agents
CLI-backed classes spawn a vendor’s command-line tool, stream its output through the runtime, and implementAgentLike. The binary must be on PATH. When you
omit model, the underlying CLI picks its own default. Each class adds a few
vendor-specific options on top of the shared base below.
In Smithers-generated workflows, Claude builds and gates and Codex checks:
substantial implementation starts on Claude Opus 5 (
claude-opus-5),
escalating to Fable (claude-fable-5) for the most ambitious builds. Sol
(gpt-5.6-sol) takes final code review and second opinions, Terra
(gpt-5.6-terra) takes validation and tool-heavy checking, and Luna
(gpt-5.6-luna) stays on trivial, minimal-risk edits, cheap passes, and
research gathering. Orchestration and gating (scope, direction, progress,
done-or-not) also run on Claude: claude-opus-5 by default,
claude-fable-5 for planning. Other CLI agents enter the automatic pools
only when earlier entries are unavailable or fail; explicitly
constructed agents always run as written.
See SOTA role defaults.BaseCliAgentOptions
Shared by every CLI agent class.
File-change parsing
CLI agent subclasses may implement an optionalparseFileChanges method that
normalizes a file_change action (as emitted by createOutputInterpreter)
into AgentFileChange records:
typeof agent.parseFileChanges === "function" before calling:
an agent that can’t normalize simply omits the method (a graceful absence,
not a stub returning [], since an empty array would wrongly imply “no
changes” rather than “unsupported”). When implemented, the same normalization
also runs live inside createOutputInterpreter, which attaches the result to
the streamed action’s detail.fileChanges.
Each AgentCapabilityRegistry.fileChanges declares what an engine supports:
supportsFileChanges (can it identify file-mutating tool calls at all) and
supportsUnifiedDiff (can it additionally report or reconstruct full diff
content). Per-engine support:
Source
AgentFileChange.ts · parseAnthropicStyleFileChanges.js · Tests file-change-contract.test.js
ClaudeCodeAgent
Wraps the Anthropicclaude CLI. Adds session and permission flags on top of the
base: permissionMode, allowedTools / disallowedTools, mcpConfig,
resume, sessionId, addDir, agents, appendSystemPrompt, configDir,
apiKey, maxBudgetUsd, outputFormat (default stream-json). See
ClaudeCodeAgentOptions.
CodexAgent
Wraps the OpenAIcodex CLI (codex exec). Adds sandbox
("read-only" | "workspace-write" | "danger-full-access"), config, profile,
fullAuto, outputSchema, nativeStructuredOutput (default false),
configDir, and apiKey. See
CodexAgentOptions.
nativeStructuredOutput on CodexAgent makes the model emit only final JSON and
refuse tool calls, which breaks agentic tasks. Leave it off for read/edit/run
work; enable it only for pure, tool-free extraction.AntigravityAgent
Wraps the Googleagy CLI. Adds allowedMcpServerNames, allowedTools,
conversation, continue, resume, includeDirectories, sandbox,
configDir, geminiDir, and apiKey. Options that map to removed agy flags
fail fast with AGENT_CONFIG_INVALID. Prefer this over GeminiAgent for new
Google CLI work.
GeminiAgent
Deprecated legacy wrapper for the oldergemini CLI. Adds approvalMode,
sandbox, extensions, resume, includeDirectories, configDir, and
apiKey. Use AntigravityAgent instead for new workflows.
PiAgent
Wraps the Pi CLI and adds extension UI hook support. Key additions:provider,
mode ("text" | "json" | "rpc"), thinking, extension, skill, and
onExtensionUiRequest. See
PiAgentOptions and Pi integration.
OmpAgent
Wraps the Oh My Pi (OMP) harness in headless text, JSON print, or RPC mode. Withmode omitted, streaming runs default to rpc (a persistent session, so the
multi-turn tool loop runs) and everything else defaults to text; set
mode: "json" for a one-shot execution, which streaming runs also fall back to
when file arguments are passed. See
CLI agents → Mode defaults.
Adds provider, mode ("text" | "json" | "rpc"), thinking ("off" through
"max", or "auto"), skills (plural, comma-separated), hooks, maxTime,
autoApprove, approvalMode, and session controls (resume, continueSession,
sessionDir, noSession). A valued resume takes precedence over
continueSession; file arguments are rejected in RPC mode. Native hijack is not
yet supported. See
OmpAgentOptions
and CLI agents → Oh My Pi (OMP).
KimiAgent
Wraps the Moonshotkimi CLI and auto-isolates KIMI_SHARE_DIR per run. Adds
thinking, agent, maxRalphIterations, session, continue, configDir,
and MCP config flags.
ForgeAgent
Wraps the Forge CLI (300+ models via provider/model strings). Addsprovider,
agent, conversationId, workflow, sandbox, and restricted.
AmpAgent
Wraps the Amp CLI in--execute headless mode. Adds visibility
("private" | "public" | "workspace" | "group"), mcpConfig,
dangerouslyAllowAll, and logLevel.
VibeAgent
Wraps Mistral’svibe CLI with streaming JSON output. Adds agent, maxTurns,
maxPrice, maxTokens, enabledTools, sessionId, and continueSession. See
VibeAgentOptions.
OpenCodeAgent
Wraps the OpenCode CLI (opencode run --format json). Adds agentName,
attachFiles, continueSession, sessionId, and variant. Native hijack is
not yet supported. See OpenCodeAgentOptions.
OpenClawAgent
Wraps the OpenClaw gateway-backed agent CLI (openclaw agent --message <prompt> --json). Adds agent, session, workspace, json, and continueSession; a
per-call resumeSession emits --session-id. See
OpenClawAgentOptions.
HermesCliAgent
CLI-driver variant of Hermes (distinct from the SDK-basedHermesAgent above),
wrapping the hermes CLI. Adds model, provider, and continueSession, and
emits --model / --provider flags. See
HermesCliAgentOptions.
Source CodexAgent.js · ClaudeCodeAgent.js · BaseCliAgentOptions.ts · Tests codex-support.test.js · claude-support.test.js · See also CLI Agents, Agents overview
createHttpTool
Build an AI SDK tool that calls any REST API without an OpenAPI spec. The returned tool takes a method, url, headers, query, body, and optional auth at call time;createHttpTool only configures the description and any default
headers. Pass it to an agent’s tools.
CreateHttpToolOptions
HttpToolInput and receives an
HttpToolOutput.
HttpToolInput
object
createHttpTool.js · CreateHttpToolOptions.ts · Tests http-tool.test.js · See also Common tools, OpenAPI tools
hashCapabilityRegistry
Compute a stable SHA-256 hex digest of anAgentCapabilityRegistry.
The registry is normalized and stably stringified first, so the hash is
order-independent and stable across runs. Use it as a cache key when an agent’s
declared capabilities are part of what makes a task result reusable.
AgentCapabilityRegistry | null | undefined
required
A 64-character SHA-256 hex digest of the normalized registry.
hashCapabilityRegistry.js · AgentCapabilityRegistry.ts · Tests capability-registry.test.js · See also Caching, Agents overview
For end-to-end agent setup and provider auth, see CLI Agents and SDK Agents. For the full option type shapes, see the Types reference.