Run AI agents in sandboxed environments with tool calling, skills, permissions,
and multi-turn conversation support. agent-harness-experimental provides a unified
interface on top of the AI SDKAgent type, executing
agent logic inside Vercel Sandbox for
isolation and safety.
network.allow.hosts is native direct network access for non-proxyable traffic like databases.
network.allow.urlPrefixes and network.deny.urlPrefixes are proxy-enforced HTTP(S) controls.
Secret-backed sandbox.env entries inject real header values outside the sandbox while the sandbox only receives placeholders.
Runtime RequestHostAccess expands proxy-mediated host access; direct native access should be declared statically in network.allow.hosts.
Permissions
Control which agent-native tools require user approval:
Common tools are shared contracts the harness injects when the adapter does not expose an equivalent natively. plan is a local tool that maintains the shared task list (mirrored by agent.tasks and task-update events). ask_user_a_question is an external continuation tool — the harness pauses, the caller reads agent.pending.toolResults, supplies an answer via continue(), and the run resumes.
Adapters can declare native equivalents to suppress redundant backfills — for example the codex adapter maps its native todoList to plan via commonToolEquivalents: { plan: ["todoList"] }.
Skills
Skills are first-class agent capabilities discovered via filesystem conventions:
import { loadSkill, loadSkillsFromDir } from "agent-harness-experimental";// Load from markdown files with YAML frontmatterconst skill = loadSkill("./skills/deploy.md");const skills = loadSkillsFromDir("./skills");createAgentSession({ adapter: claudeCode(), skills });
Use activeSkills to enable a subset of the available skills, and forcedSkills to require that some active skills are preloaded:
const skills = [ { name: "deploy", description: "Deploy the app", content: "Deploy with the release workflow.", }, { name: "security-reviewer", description: "Review code for security issues", content: "Prioritize auth, secrets, and injection flaws.", },];createAgentSession({ adapter: claudeCode(), skills, activeSkills: ["deploy", "security-reviewer"], forcedSkills: ["security-reviewer"],});
Skill selectors are exact names. forcedSkills must also be active.
Skill file format:
---name: deploydescription: Deploy the application to production---# Deploy SkillSteps to deploy...
Subagents
Define subagents the main agent can delegate to:
createAgentSession({ adapter: claudeCode(), agents: { researcher: { description: "Research a topic in depth", prompt: "You are a research assistant...", model: "claude-sonnet-4", maxTurns: 10, }, },});
Tool Policies
Wrap tools with approval requirements or input transformations:
The SandboxAgent returned by createAgentSession provides:
Method
Description
generate(prompt)
Send a prompt and wait for the full response
stream(prompt)
Send a prompt and stream the response
streamInput(text)
Send a follow-up message mid-conversation
compact()
Ask the agent to compact its context
close("stop")
Stop the sandbox and clean up resources
close("detach")
Detach without stopping (for workflow handoff)
continue(responses)
Respond to pending continuations
continueStream(responses)
Respond to pending continuations and stream the resumed run
session.exportState()
Export state for workflow resume
Properties
Property
Description
sessionId
The session identifier
tasks
Current todo task list
skills
Current skill state (available, active, forced)
sandbox
Handle for reading/writing sandbox files
pending.toolResults
Tool calls waiting on a caller-supplied result (e.g. ask_user_a_question)
Transcript Persistence
Every generate() result exposes a flattened assistant + tool message array and an aggregated transcript, ready to persist without reconstructing from deltas:
import { createAgentSession } from "agent-harness-experimental";import { claudeCode } from "@agent-harness-experimental/adapter-claude-code";const agent = createAgentSession({ adapter: claudeCode() });const result = await agent.generate("Summarize the repo");// result.messages is AgentResponseMessage[] — assistant + tool messages flattened across steps.// result.transcript bundles messages + steps + text + usage for easy persistence.const { sessionId, messages, totalUsage } = result.transcript;
stream() results expose the same data as promises (stream.messages, stream.transcript). Pure stream consumers can instead read the terminal finish-stream part, which the harness emits immediately before finish:
import { createAgentSession } from "agent-harness-experimental";import { claudeCode } from "@agent-harness-experimental/adapter-claude-code";import type { AgentTranscript } from "agent-harness-experimental";const agent = createAgentSession({ adapter: claudeCode() });const stream = await agent.stream("Summarize the repo");for await (const part of stream.fullStream) { const typed = part as { type: string; transcript?: AgentTranscript }; if (typed.type === "finish-stream" && typed.transcript) { const { messages, totalUsage } = typed.transcript; // persist messages here }}
Structured Output
import { Output } from "ai";const agent = createAgentSession({ adapter: claudeCode(), output: Output.object({ schema: z.object({ answer: z.string(), confidence: z.number(), }), }),});const result = await agent.generate("Answer this question");console.log(result.output); // { answer: "...", confidence: 0.95 }console.log(result.text); // canonical JSON for result.outputconsole.log(result.outputMetadata?.source); // "native", "core-parse", or "core-repair"
Session Resume
Resume a previous session by reconnecting to its persistent sandbox:
// First sessionconst agent1 = createAgentSession({ adapter: claudeCode(), sessionId: "my-session" });await agent1.generate("Set up the project");await agent1.close("stop"); // auto-snapshots filesystem// Later — resumeconst agent2 = resumeAgentSession({ adapter: claudeCode(), sessionId: "my-session",});await agent2.generate("Continue where we left off");
Workflow Integration
For long-running tasks that need to survive function timeouts, export and
restore workflow state: