AnthropicAgent, OpenAIAgent, and HermesAgent are provider-backed AI SDK agents with class-style ergonomics matching the CLI agents. AnthropicAgent and OpenAIAgent wrap ToolLoopAgent directly; HermesAgent extends the OpenAI-compatible path with Hermes defaults.
API reference: Agents lists every agent class, its options, and links to source and tests.
Import
Quick Start
output={outputs.plan}. You do not also configure the schema on the agent
constructor. At execution time the engine infers the task’s Zod schema and calls
the SDK agent with agent.generate({ outputSchema }); the agent receives both
the prompt and the schema for that task. The ctx variable in the example is
the normal parameter of the smithers((ctx) => ...) builder, typed from the
input schema above.
You can also call an SDK agent once without rendering a workflow. Pass
outputSchema directly to generate() when you want typed structured output:
AnthropicAgent, outputSchema is forwarded as AI SDK
Output.object({ schema }), which uses Anthropic’s native structured-output
request path for Claude models. OpenAIAgent does the same unless
nativeStructuredOutput: false; HermesAgent defaults that option to false
because many local Hermes servers do not honor JSON-schema response formats.
Model Input
AnthropicAgent and OpenAIAgent accept a model ID string ("claude-fable-5", "gpt-5.5") or a prebuilt provider model instance. HermesAgent accepts an optional model ID string and defaults it to "hermes".
Options
Constructors forward standard AI SDKToolLoopAgent settings: instructions, tools, stopWhen, maxOutputTokens, temperature, providerOptions, prepareCall. The wrappers add provider model resolution on top.
AnthropicAgentOptionsisToolLoopAgentSettingswithoutmodel, plus requiredmodel: string | anthropic(...).OpenAIAgentOptionsaddsnativeStructuredOutput?: booleanand has two model forms: a string model may includebaseURLandapiKey; a prebuilt OpenAI provider model must not includebaseURLorapiKey.HermesAgentOptionsmakesmodeloptional, allowsbaseURLandapiKey, and defaultsnativeStructuredOutputtofalse. A runtimebaseURLorHERMES_BASE_URLis required.
OpenAIAgent, pass baseURL and apiKey directly when targeting an OpenAI-compatible endpoint instead of the default OpenAI API. This is the simplest path for local servers such as llama.cpp:
apiKey: "none" in the OpenAIAgent config when your local server accepts OpenAI-compatible requests but does not require a real key.
Some OpenAI-compatible local servers accept chat requests but do not reliably implement JSON schema structured output. For those servers, keep the output schema on the Smithers task and disable native structured output on the agent so Smithers uses prompt-based JSON extraction instead:
OpenAIAgent:
createOpenAI path when you need provider-level configuration beyond baseURL and apiKey; in that form, baseURL and apiKey belong in the createOpenAI config, not in the OpenAIAgent constructor.
Generic HTTP Tool
createHttpTool() returns an AI SDK tool that can call any REST endpoint without an OpenAPI spec. Use it as the universal escape hatch when no curated connector or MCP server exists yet.
method, url, headers, query, body, optional auth (bearer, basic, or custom header), and timeoutMs. Results include ok, status, statusText, response headers, and a parsed JSON or text body.
Generic HTTP Tool
createHttpTool() returns an AI SDK tool that can call any REST endpoint without an OpenAPI spec. Use it as the universal escape hatch when no curated connector or MCP server exists yet.
method, url, headers, query, body, optional auth (bearer, basic, or custom header), and timeoutMs. Results include ok, status, statusText, response headers, and a parsed JSON or text body.
Generic HTTP Tool
createHttpTool() returns an AI SDK tool that can call any REST endpoint without an OpenAPI spec. Use it as the universal escape hatch when no curated connector or MCP server exists yet.
method, url, headers, query, body, optional auth (bearer, basic, or custom header), and timeoutMs. Results include ok, status, statusText, response headers, and a parsed JSON or text body.
Hermes
Hermes (Nous Research) exposes an OpenAI-compatible HTTP API, soHermesAgent is a convenience subclass of OpenAIAgent that points the provider at your Hermes server and disables native structured output by default (a local Hermes server may not honor JSON-schema response formats).
baseURL falls back to the HERMES_BASE_URL env var and must be set in either place. apiKey falls back to HERMES_API_KEY (then "hermes"). Pass nativeStructuredOutput: true if your server does honor JSON-schema output. To use Smithers from Hermes instead of running Hermes as a worker, see Agent Support → Hermes.
Hijack Support
SDK agents do not reopen a provider-native CLI. Smithers persists the agent conversation and reopens it through a Smithers-managed REPL viabunx smithers-orchestrator hijack RUN_ID.
Live-run behavior:
- Smithers captures response history after each step via
onStepFinish. bunx smithers-orchestrator hijackwaits until history is durable, aborts the current agent task (handing it off to the REPL), and opens the REPL.- On clean REPL exit, Smithers writes updated message history back and resumes the workflow automatically.
- Smithers reconstructs the agent from the workflow source on hijack. This means cross-engine hijack is not supported: the REPL will use the same agent class that ran originally.
CLI vs SDK
Choosing an agent for typed/JSON-output tasks. Only
AnthropicAgent and OpenAIAgent declare supportsNativeStructuredOutput = true, so when a <Task> has an output schema they pass it through the AI SDK’s native structured-output API (Output.object({ schema })) and the result is schema-constrained. CLI agents (ClaudeCodeAgent, CodexAgent, etc.) do not set this flag: the engine falls back to injecting JSON instructions into the prompt and extracting the object from the model’s text, and emits a console.warn (“engine … does not support native structured output. Falling back to prompt-injection + text JSON extraction”). Schema-validation retries still run, but valid JSON shape does not guarantee meaningful values. For tasks whose primary job is producing typed/JSON output, prefer AnthropicAgent/OpenAIAgent (or, for an OpenAI-compatible endpoint that honors JSON schema, an OpenAIAgent with nativeStructuredOutput left enabled). CodexAgent additionally forwards the task schema to the CLI via --output-schema for constrained decoding, but the engine still wraps it with the prompt-injection fallback because the flag is unset.
Pass a raw ToolLoopAgent directly if you prefer; the wrappers are convenience, not a separate runtime.
Transcription Tool
UsecreateTranscriptionTool when an SDK agent needs to transcribe audio as part of its tool loop. The tool accepts either an audioUrl or audioBase64 input and normalizes Whisper or Deepgram responses to { text, provider, language?, durationSeconds? }.
Transcription Tool
UsecreateTranscriptionTool when an SDK agent needs to transcribe audio as part of its tool loop. The tool accepts either an audioUrl or audioBase64 input and normalizes Whisper or Deepgram responses to { text, provider, language?, durationSeconds? }.
Transcription Tool
UsecreateTranscriptionTool when an SDK agent needs to transcribe audio as part of its tool loop. The tool accepts either an audioUrl or audioBase64 input and normalizes Whisper or Deepgram responses to { text, provider, language?, durationSeconds? }.