Agents API - Smithers

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 {
  AnthropicAgent,
  ClaudeCodeAgent,
  createHttpTool,
  hashCapabilityRegistry,
} from "smithers-orchestrator";
import type { AgentLike, AnthropicAgentOptions } from "smithers-orchestrator";

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

Show members

string

Optional stable identifier. Surfaced in run metadata and used to attribute events and quota errors to a specific agent.

generate

(args?: AgentGenerateOptions) => Promise<unknown>

required

Runs one generation. args carries prompt, outputSchema, abortSignal, timeout, and onStdout / onStderr streaming callbacks.

tools

Record<string, unknown>

Tools the agent may call during generation.

capabilities

AgentCapabilityRegistry

Structured capability descriptor used for cache keys and diagnostics. See hashCapabilityRegistry.

supportsNativeStructuredOutput

boolean

true when the agent consumes an outputSchema through a native structured-output API rather than prompt-based JSON extraction.

preflight

(args?: AgentGenerateOptions) => Promise<void>

Deterministic startup check run once before the first generation. A rejected promise fails the task without retrying.

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.

import { AnthropicAgent, OpenAIAgent, tools } from "smithers-orchestrator";
import { stepCountIs } from "ai";

const claude = new AnthropicAgent({
  model: "claude-fable-5",
  tools,
  instructions: "You are a careful planner.",
  stopWhen: stepCountIs(40),
});

const codex = new OpenAIAgent({
  model: "gpt-5.5",
  tools,
  instructions: "You are a precise implementation agent.",
  stopWhen: stepCountIs(40),
});

AnthropicAgent

Wraps ToolLoopAgent against the Anthropic provider.

options

AnthropicAgentOptions

required

ToolLoopAgentSettings without model, plus a required model.

Show AnthropicAgentOptions

model

string | anthropic(...)

required

A provider model id ("claude-fable-5") or a prebuilt @ai-sdk/anthropic model instance. The instance form is mainly for tests and advanced provider setup.

...settings

ToolLoopAgentSettings

All other AI SDK agent settings: instructions, tools, stopWhen, maxOutputTokens, temperature, providerOptions, prepareCall.

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.

Show OpenAIAgentOptions

model

string | openai(...)

required

A model id string or a prebuilt @ai-sdk/openai model instance.

baseURL

string

Base URL for an OpenAI-compatible endpoint (e.g. a local llama.cpp server). Allowed only with the string-model form.

apiKey

string

API key for the endpoint. Local servers often accept "none". Allowed only with the string-model form.

nativeStructuredOutput

boolean

default:"true"

Set false to disable AI SDK native structured output and use prompt-based JSON extraction instead. Useful for local servers that do not honor JSON schema response formats. Per-agent defaults: AnthropicAgent and OpenAIAgent default on; CodexAgent and HermesAgent default off (native schema makes Codex emit only final JSON and lose tool access).

const local = new OpenAIAgent({
  model: "llama-3.1-8b-instruct",
  baseURL: "http://127.0.0.1:8080/v1",
  apiKey: "none",
  nativeStructuredOutput: false,
});

HermesAgent

OpenAI-compatible wrapper preconfigured for a Nous Research Hermes server.

options

HermesAgentOptions

Mirrors the string-model form of OpenAIAgentOptions, with Hermes defaults.

Show HermesAgentOptions

model

string

default:"\"hermes\""

Model id advertised by your Hermes server.

baseURL

string

Hermes OpenAI-compatible API URL (e.g. http://127.0.0.1:5123/v1). Falls back to the HERMES_BASE_URL environment variable; one or the other is required.

apiKey

string

API key sent to the server. Falls back to HERMES_API_KEY, then "hermes".

nativeStructuredOutput

boolean

default:"false"

Off by default because a local Hermes server may not honor JSON-schema response formats; Smithers falls back to prompt-based JSON extraction.

Source AnthropicAgent.js · OpenAIAgent.js · HermesAgent.js · Tests sdk-agents.test.js · See also SDK Agents, AnthropicAgentOptions

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.

import { ClaudeCodeAgent, Task, Workflow, createSmithers } from "smithers-orchestrator";
import { z } from "zod";

const { smithers, outputs } = createSmithers({
  analysis: z.object({ summary: z.string() }),
});

const claude = new ClaudeCodeAgent({
  model: "claude-fable-5",
  systemPrompt: "You are a careful code reviewer.",
  timeoutMs: 30 * 60 * 1000,
});

export default smithers(() => (
  <Workflow name="review">
    <Task id="analysis" output={outputs.analysis} agent={claude}>
      Analyze the codebase and identify potential improvements.
    </Task>
  </Workflow>
));

options

BaseCliAgentOptions

Shared by every CLI agent class.

Show BaseCliAgentOptions

string

Stable agent id used in events and diagnostics.

model

string

Model id passed through to the CLI. Defaults to the CLI’s own default.

systemPrompt

string

System prompt sent to the CLI.

instructions

string

Additional instructions merged into the agent’s context.

cwd

string

Working directory for the spawned process.

env

Record<string, string>

Extra environment variables for the spawned process.

yolo

boolean

Run the CLI in its most permissive (no-confirmation) mode.

timeoutMs

number

Hard wall-clock timeout for one generation.

idleTimeoutMs

number

Timeout for no output between writes.

maxOutputBytes

number

Cap on captured stdout/stderr before truncation.

extraArgs

string[]

Raw extra arguments appended to the CLI invocation.

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. Source ClaudeCodeAgent.js · CodexAgent.js · BaseCliAgentOptions.ts · Tests claude-support.test.js · codex-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.

function createHttpTool(options?: CreateHttpToolOptions): Tool;

options

CreateHttpToolOptions

Show CreateHttpToolOptions

description

string

Tool description shown to the model. Defaults to a generic REST-call description.

defaultHeaders

Record<string, string>

Headers merged into every request, overridable per call.

The model invokes the tool with an HttpToolInput and receives an HttpToolOutput.

input

HttpToolInput

Show HttpToolInput

url

string

required

Request URL.

method

default:"\"GET\""

HTTP method.

headers

Record<string, string>

Per-call headers, merged over defaultHeaders.

query

Record<string, string | number | boolean | null | undefined>

Query parameters; null and undefined values are skipped.

body

unknown

Request body. Objects are JSON-serialized with a JSON content type unless one is already set; strings, Blob, FormData, and URLSearchParams pass through. Ignored for GET and HEAD.

auth

HttpToolAuth

Optional auth applied as a header.

Show HttpToolAuth

{ type: "bearer", token }

Sets Authorization: Bearer <token>.

{ type: "basic", username, password }

Sets Authorization: Basic <base64>.

{ type: "header", name, value }

Sets an arbitrary header.

timeoutMs

number

Positive integer; aborts the request after this many milliseconds.

HttpToolOutput

object

Show HttpToolOutput

boolean

true for a 2xx response.

status

number

HTTP status code.

statusText

string

HTTP status text.

headers

Record<string, string>

Response headers.

body

unknown

Parsed JSON when the content type is JSON, the raw text otherwise, or null for an empty or 204/205 response.

const claude = new AnthropicAgent({
  model: "claude-fable-5",
  tools: {
    http: createHttpTool({
      defaultHeaders: { "user-agent": "smithers" },
    }),
  },
});

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.

function hashCapabilityRegistry(
  registry: AgentCapabilityRegistry | null | undefined,
): string;

registry

AgentCapabilityRegistry | null | undefined

required

The capability registry to fingerprint. null / undefined hash to the digest of an empty normalized registry.

Show AgentCapabilityRegistry

version

required

Registry schema version.

engine

string

required

The CLI engine: one of "claude-code", "codex", "antigravity", "gemini", "kimi", "pi", "amp", "forge", "opencode", "vibe".

runtimeTools

Record<string, AgentToolDescriptor>

required

Tools available at runtime. Each AgentToolDescriptor has an optional description and source ("builtin" | "mcp" | "extension" | "skill" | "runtime").

mcp

{ bootstrap, supportsProjectScope, supportsUserScope }

required

MCP support descriptor.

skills

{ supportsSkills, installMode?, smithersSkillIds }

required

Skill support descriptor.

humanInteraction

{ supportsUiRequests, methods }

required

Human-interaction support descriptor.

builtIns

string[]

required

Names of built-in capabilities.

string

A 64-character SHA-256 hex digest of the normalized registry.

const key = hashCapabilityRegistry(claude.capabilities);

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.

​AgentLike

​SDK agents

​AnthropicAgent

​OpenAIAgent

​HermesAgent

​CLI agents

​ClaudeCodeAgent

​CodexAgent

​AntigravityAgent

​GeminiAgent

​PiAgent

​KimiAgent

​ForgeAgent

​AmpAgent

​VibeAgent

​OpenCodeAgent

​createHttpTool

​hashCapabilityRegistry

AgentLike

SDK agents

AnthropicAgent

OpenAIAgent

HermesAgent

CLI agents

ClaudeCodeAgent

CodexAgent

AntigravityAgent

GeminiAgent

PiAgent

KimiAgent

ForgeAgent

AmpAgent

VibeAgent

OpenCodeAgent

createHttpTool

hashCapabilityRegistry