ai-sdk/harness

51 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Codex adapter known limitations

Codex does not currently support built-in tool approval requests; use permissionMode: 'allow-all' with this adapter (host-executed AI SDK tool approvals still work). Codex does not currently support built-in tool filtering; activeTools and inactiveTools can filter host-executed tools, but filtering Codex built-ins such as bash or webSearch will throw.

Codex harness structured output support

Codex supports schema-backed HarnessAgent structured output. The adapter passes the JSON Schema through the Codex SDK's native outputSchema turn option.

Codex harness environment variables required

To use the Codex harness agent, ensure environment variables include VERCEL_OIDC_TOKEN for Vercel Sandbox and one of the authentication variables (OPENAI_API_KEY, CODEX_API_KEY, AI_GATEWAY_API_KEY, or equivalent) for Codex.

Codex harness basic usage example

Example of using Codex harness with HarnessAgent: import { HarnessAgent } from '@ai-sdk/harness/agent'; import { codex } from '@ai-sdk/harness-codex'; import { createVercelSandbox } from '@ai-sdk/sandbox-vercel'; const agent = new HarnessAgent({ harness: codex, model: 'gpt-5.6-luna', sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000], }), }); const session = await agent.createSession(); let exitCode = 0; try { const result = await agent.stream({ session, prompt: 'Check the test failures and fix the production code.', }); for await (const part of result.stream) { if (part.type === 'text-delta') { process.stdout.write(part.text); } } } catch (err) { exitCode = 1; console.error(err); } finally { await session.destroy(); process.exit(exitCode); }

Codex harness adapter import statement

Import Codex harness adapter using: import { codex, createCodex } from '@ai-sdk/harness-codex'. The codex export is equivalent to createCodex() with default configuration.

Codex harness setup packages

Install the following packages for Codex harness: @ai-sdk/harness, @ai-sdk/harness-codex, and @ai-sdk/sandbox-vercel.

Codex adapter settings configuration

Use createCodex() to configure the Codex harness adapter with these settings: auth (authentication mode: auto, direct, or ai-gateway, or isolated authentication environment), credentialForwarding (optional callback to customize credentials before forwarding to sandbox), codexConfig (additional native Codex configuration using snake_case keys from Codex config.toml), mcpServers (MCP server definitions keyed by server name), reasoningEffort (low, medium, high, xhigh, or max), webSearch (allow live web search boolean), port (bridge port override), startupTimeoutMs (maximum time to wait for bridge to start), mintBridgeToken (synchronous function that receives sandbox id and returns bridge authentication token; defaults to random 32-byte token).

Codex adapter authentication modes

The auth setting selects credential resolution: auto (default, uses AI Gateway credentials when available, then falls back to direct OpenAI credentials), direct (uses OpenAI credentials), or ai-gateway (uses AI Gateway credentials). When sandbox supports additive request transformations, bridge receives placeholders and adapter injects credentials into outbound requests. Sandboxes without that capability use direct credential forwarding.

Codex adapter supported environment variables

The Codex harness adapter supports these environment variables for authentication: VERCEL_OIDC_TOKEN, AI_GATEWAY_API_KEY, AI_GATEWAY_BASE_URL, OPENAI_API_KEY, CODEX_API_KEY, OPENAI_BASE_URL, OPENAI_ORGANIZATION, and OPENAI_PROJECT.

Codex adapter authentication mode selection

Select specific authentication mode using: const directHarness = createCodex({ auth: 'direct' }); or const gatewayHarness = createCodex({ auth: 'ai-gateway' }); Pass an authentication environment programmatically using: const harness = createCodex({ auth: { OPENAI_API_KEY: await resolveOpenAIToken() } }); The supplied record replaces the host environment and only recognized authentication variables are forwarded.

Codex adapter sandbox requirements

Codex requires a network sandbox with at least one exposed port, such as @ai-sdk/sandbox-vercel. Configuration example: const sandbox = createVercelSandbox({ runtime: 'node24', ports: [4000] });

Codex adapter built-in tools

The Codex harness adapter exposes these common built-in tools through agent.tools: bash and webSearch. Additional Codex built-ins may appear in agent.tools when they do not fit a common tool shape. Codex file changes may appear as dynamic fileChange tool parts because some Codex file mutations do not originate from a visible model-callable tool.

Deep Agents harness adapter settings

The createDeepAgents() function accepts these settings: - auth: authentication mode (auto, anthropic, or ai-gateway) or an isolated authentication environment object. Default is auto. - credentialForwarding: optional synchronous or asynchronous callback that customizes each credential immediately before forwarding into sandbox process. Receives the credential value and environment variable name. - mcpServers: MCP server definitions keyed by server name. - port: bridge port override. - recursionLimit: maximum LangGraph super-steps per turn. When omitted, Deep Agents default applies. - startupTimeoutMs: maximum time to wait for bridge to start. - mintBridgeToken: synchronous function that receives sandbox id and returns bridge authentication token. Default generates random 32-byte token.

Deep Agents authentication modes

Deep Agents auth setting has three modes: auto (default, uses AI Gateway credentials when available, then falls back to Anthropic), anthropic (uses Anthropic credentials only), and ai-gateway (uses AI Gateway credentials only).

Deep Agents supported environment variables

Deep Agents supports these authentication environment variables: AI_GATEWAY_API_KEY, VERCEL_OIDC_TOKEN, AI_GATEWAY_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL.

Deep Agents harness adapter packages

To use the Deep Agents harness adapter, install these packages: @ai-sdk/harness, @ai-sdk/harness-deepagents, and @ai-sdk/sandbox-vercel.

Deep Agents harness import statement

Import Deep Agents harness adapter using: import { deepAgents, createDeepAgents } from '@ai-sdk/harness-deepagents';

deepAgents default configuration

The deepAgents export is equivalent to createDeepAgents() with its default configuration.

Deep Agents harness basic usage example

Example showing how to create a HarnessAgent with Deep Agents harness, model selection, Vercel sandbox setup with Node 24 runtime, session creation, streaming output handling, and session cleanup: import { HarnessAgent } from '@ai-sdk/harness/agent'; import { deepAgents } from '@ai-sdk/harness-deepagents'; import { createVercelSandbox } from '@ai-sdk/sandbox-vercel'; const agent = new HarnessAgent({ harness: deepAgents, model: 'anthropic/claude-sonnet-4-6', sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000], }), }); const session = await agent.createSession(); let exitCode = 0; try { const result = await agent.stream({ session, prompt: 'Analyze this codebase and suggest improvements.', }); for await (const part of result.stream) { if (part.type === 'text-delta') { process.stdout.write(part.text); } } } catch (err) { exitCode = 1; console.error(err); } finally { await session.destroy(); process.exit(exitCode); }

Deep Agents using non-Anthropic models

To run a non-Anthropic model with Deep Agents harness, select ai-gateway auth mode and specify the model. Example: const harness = createDeepAgents({ auth: 'ai-gateway' }); const agent = new HarnessAgent({ harness, model: 'google/gemini-2.5-flash', sandbox });

Deep Agents programmatic authentication

Pass an authentication environment object to createDeepAgents to use programmatically resolved credentials without reading process.env. The supplied record replaces host environment for authentication discovery. Only recognized authentication variables are forwarded. Example: const harness = createDeepAgents({ auth: { ANTHROPIC_API_KEY: await resolveAnthropicToken() } });

Deep Agents sandbox requirements

Deep Agents requires a network sandbox with at least one exposed port. Example using Vercel sandbox with Node 24 runtime and port 4000: const sandbox = createVercelSandbox({ runtime: 'node24', ports: [4000] });

Deep Agents structured output support

Deep Agents supports schema-backed HarnessAgent structured output. The adapter applies a per-turn LangChain tool strategy and returns the graph's validated structuredResponse as JSON text.

Deep Agents skills materialization

Skills passed to the Deep Agents session are materialized as native Deep Agents skill folders (name/SKILL.md plus any attached files) under $HOME/.agents/skills/ in the sandbox outside the work directory so they don't clash with cloned code. Skills are loaded via Deep Agents' skills option so the agent loads them on demand. Skills already present under <workDir>/.agents/skills/ in a cloned repo are also discovered.

Deep Agents built-in tools

Deep Agents harness adapter exposes these built-in tools through agent.tools: read, write, edit, bash, grep, glob, ls, task, write_todos.

Deep Agents known limitation: session resumption

Resuming a stopped Deep Agents session's conversation is not supported. After session.stop(), Deep Agents' in-memory conversation state (LangGraph MemorySaver) is gone and only the sandbox workspace persists via snapshot. Use session.detach() for cross-process handoff or session.suspendTurn() for turn continuation while keeping the live bridge running.

Deep Agents known limitation: manual compaction

Manual compaction is not supported in Deep Agents harness adapter.

Deep Agents harness is experimental

Harness packages including Deep Agents are experimental and may have breaking changes between releases as the early API gets further refined.

Deep Agents bridge bootstrap process

The Deep Agents harness adapter bootstraps the bridge's Node dependencies (the deepagents package and LangChain) inside the sandbox via pnpm when the first session starts.

Claude Code authentication environment replaces host environment

When an authentication environment object is supplied to createClaudeCode, it replaces the host environment for authentication discovery. Only recognized authentication variables are forwarded.

Claude Code harness adapter packages

To set up Claude Code harness adapter, install three packages: @ai-sdk/harness, @ai-sdk/harness-claude-code, and @ai-sdk/sandbox-vercel.

Claude Code HarnessAgent basic setup example

const agent = new HarnessAgent({ harness: claudeCode, model: 'claude-sonnet-4-6', sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000], }), }); This example shows how to instantiate a HarnessAgent with Claude Code harness and Vercel sandbox.

Claude Code HarnessAgent streaming example

Claude Code harness environment variables required

To use Claude Code harness agent, ensure environment variables include VERCEL_OIDC_TOKEN for Vercel Sandbox and one of the authentication variables for Claude Code (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AI_GATEWAY_API_KEY, or ANTHROPIC_BASE_URL).

createClaudeCode configuration settings

createClaudeCode accepts these settings: auth (authentication mode: 'auto', 'direct', or 'ai-gateway', or an isolated authentication environment object), credentialForwarding (optional callback to customize credentials before forwarding), mcpServers (MCP server definitions keyed by name), maxTurns (maximum internal turns before yielding), env (environment variables merged with sandbox bridge process environment), thinking (extended-thinking configuration with type 'enabled', 'disabled', or 'adaptive' and display 'summarized' or 'omitted'), port (bridge port override), startupTimeoutMs (maximum time for bridge startup), and mintBridgeToken (function returning bridge authentication token).

Claude Code harness default thinking configuration

The default thinking configuration for Claude Code harness is { type: 'adaptive', display: 'summarized' }.

Claude Code harness createClaudeCode example configuration

const harness = createClaudeCode({ maxTurns: 10, env: { DEPLOYMENT_ENV: 'staging', }, thinking: { type: 'adaptive', display: 'summarized', }, }); This example shows how to configure Claude Code harness with custom max turns, environment variables, and thinking settings.

Claude Code authentication modes

Claude Code harness supports three authentication modes via the auth setting: 'auto' (default, uses AI Gateway credentials when available, then falls back to direct Anthropic credentials), 'direct' (uses Anthropic credentials), and 'ai-gateway' (uses AI Gateway credentials). You can also pass an authentication environment object with programmatically resolved credentials.

Claude Code authentication environment variables

Supported authentication environment variables for Claude Code harness: VERCEL_OIDC_TOKEN, AI_GATEWAY_API_KEY, AI_GATEWAY_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and ANTHROPIC_BASE_URL.

Claude Code harness direct authentication example

const directHarness = createClaudeCode({ auth: 'direct' });

Claude Code harness AI Gateway authentication example

const gatewayHarness = createClaudeCode({ auth: 'ai-gateway' });

Claude Code harness import statement

Import claudeCode and createClaudeCode from '@ai-sdk/harness-claude-code'. The claudeCode export is equivalent to createClaudeCode() with default configuration.

Claude Code harness programmatic credentials example

const harness = createClaudeCode({ auth: { ANTHROPIC_API_KEY: await resolveAnthropicToken() }, }); This shows how to pass programmatically resolved credentials to Claude Code harness without reading process.env.

Claude Code sandbox requirements

Claude Code requires a network sandbox with at least one exposed port, such as @ai-sdk/sandbox-vercel.

Claude Code Vercel sandbox example

const sandbox = createVercelSandbox({ runtime: 'node24', ports: [4000], });

Claude Code built-in tools exposed through HarnessAgent

Claude Code adapter exposes these built-in tools through agent.tools: read, write, edit, bash, glob, grep, and webSearch. Additional Claude Code built-ins may also appear in agent.tools when they do not fit a common tool shape.

Claude Code tool approval requests

Claude Code supports built-in tool approval requests when permissionMode is set to 'allow-reads' or 'allow-edits'.

Claude Code structured output support

Claude Code supports schema-backed HarnessAgent structured output. The adapter passes the JSON Schema through the Agent SDK's native outputFormat option and returns its structured_output value as JSON text.

Claude Code harness experimental status

Harness packages are experimental. Breaking changes should be expected between releases as the early API is further refined.

Claude Code credential forwarding callback behavior

The credentialForwarding callback receives the credential value that would otherwise be forwarded (either the real credential or a masked value) and the environment variable name. This callback only controls the value forwarded into the sandbox process and does not restrict which credentials the harness adapter can discover, read, or access in the host process.

Claude Code credential forwarding with sandboxes

When the sandbox supports additive request transformations, the bridge receives placeholders and the adapter injects credentials into matching outbound requests. Sandboxes without that capability retain direct credential forwarding.

Give your agent this brain