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 smithers-orchestrator 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.
AgentLike
object
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.
options
AnthropicAgentOptions
required
ToolLoopAgentSettings without model, plus a required model.

OpenAIAgent

Wraps ToolLoopAgent against the OpenAI provider or any OpenAI-compatible endpoint.
options
OpenAIAgentOptions
required
The Anthropic shape plus nativeStructuredOutput, in one of two model forms.

HermesAgent

OpenAI-compatible wrapper preconfigured for a Nous Research Hermes server.
options
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.
Smithers-generated workflows are Codex-first: start Luna (gpt-5.6-luna) for research, implementation, ordinary tool use, UI, and routine-to-substantial execution. Escalate to Terra (gpt-5.6-terra) for stronger validation, structured checking, or tool-heavy judgment; use Sol (gpt-5.6-sol) for ambiguity, high-stakes decisions, novel architecture, orchestration, final review, or repeated failure. Non-Codex CLI agents enter automatic pools only when Codex is unavailable or fails; explicitly constructed agents always run as written. See SOTA role defaults.
options
BaseCliAgentOptions
Shared by every CLI agent class.

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.

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.
options
CreateHttpToolOptions
The model invokes the tool with an HttpToolInput and receives an HttpToolOutput.
input
HttpToolInput
HttpToolOutput
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.
registry
AgentCapabilityRegistry | null | undefined
required
The capability registry to fingerprint. null / undefined hash to the digest of an empty normalized registry.
string
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.