Skip to main content
An agent is anything Smithers can hand a prompt and await an answer. Every agent class in 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 as AgentLike to accept any agent.
object

Durable agent checkpoints

Checkpoint-aware agents declare what they produce with checkpointFormats 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 SDK ToolLoopAgent. 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

Wraps ToolLoopAgent against the Anthropic provider.
AnthropicAgentOptions
required
ToolLoopAgentSettings without model, plus a required model.

OpenAIAgent

Wraps ToolLoopAgent 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.
Source 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 implement AgentLike. 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 optional parseFileChanges method that normalizes a file_change action (as emitted by createOutputInterpreter) into AgentFileChange records:
Callers check 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 Anthropic claude 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 OpenAI codex 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 Google agy 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 older gemini 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. With mode 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 Moonshot kimi 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). Adds provider, 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’s vibe 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-based HermesAgent 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
The model invokes the tool with an HttpToolInput and receives an HttpToolOutput.
HttpToolInput
object
Source createHttpTool.js · CreateHttpToolOptions.ts · Tests http-tool.test.js · See also Common tools, OpenAPI tools

hashCapabilityRegistry

Compute a stable SHA-256 hex digest of an AgentCapabilityRegistry. 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
The capability registry to fingerprint. null / undefined hash to the digest of an empty normalized registry.
A 64-character SHA-256 hex digest of the normalized registry.
Source 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.