open-agent-sdk

A stupidly simple open-source agent SDK with pluggable brains and sandboxes.

Think of it as "IaC for agents" - declare your providers and go.

import { Agent } from "open-agent-sdk";
import { ClaudeCodeBrain } from "open-agent-sdk/brains/claude-code";
import { E2BSandbox } from "open-agent-sdk/sandboxes/e2b";

const agent = new Agent({
  brain: new ClaudeCodeBrain(),
  sandbox: new E2BSandbox(),
});

for await (const event of agent.run("Analyze this repo and fix the bug")) {
  console.log(event);
}

Why?

Every SaaS app shipping an embedded agent needs:

• A brain (the reasoning engine - Claude Code, Codex, etc.)
• A sandbox (isolated execution - E2B, Docker, Modal, etc.)
• Pluggability (swap providers without rewriting code)

This SDK gives you a simple abstraction layer. Bring your own brain, bring your own sandbox.

Installation

npm install open-agent-sdk

You'll also need a brain. Currently supported:

npm install @anthropic-ai/claude-agent-sdk  # For ClaudeCodeBrain

And optionally a sandbox:

npm install @e2b/code-interpreter  # For E2BSandbox

Quick Start

Basic usage (no sandbox)

import { Agent } from "open-agent-sdk";
import { ClaudeCodeBrain } from "open-agent-sdk/brains/claude-code";

const agent = new Agent({
  brain: new ClaudeCodeBrain({
    allowedTools: ["Read", "Glob", "Grep", "Bash"],
  }),
});

for await (const event of agent.run("What files are in this directory?")) {
  if (event.type === "message") {
    console.log(event.content);
  }
}

With E2B sandbox (isolated execution)

import { Agent } from "open-agent-sdk";
import { ClaudeCodeBrain } from "open-agent-sdk/brains/claude-code";
import { E2BSandbox } from "open-agent-sdk/sandboxes/e2b";

const agent = new Agent({
  brain: new ClaudeCodeBrain({
    permissionMode: "bypassPermissions", // Safe in sandbox
  }),
  sandbox: new E2BSandbox({
    template: "base",
  }),
});

for await (const event of agent.run("Create and run a Python script")) {
  console.log(event);
}
// Sandbox is automatically cleaned up

Using hooks

const agent = new Agent({
  brain: new ClaudeCodeBrain(),
  hooks: {
    onStart: () => console.log("Started"),
    onToolUse: (e) => console.log(`Using: ${e.toolName}`),
    onMessage: (e) => console.log(e.content),
    onDone: (e) => console.log(`Done! Tokens: ${e.usage?.inputTokens}`),
    onError: (e) => console.error(e.error),
  },
});

Core Concepts

Agent

The orchestrator that ties everything together. It:

• Initializes the sandbox (if provided)
• Runs the brain with your prompt
• Streams events as the agent works
• Cleans up the sandbox when done

Brain

The reasoning engine. Implements the AgentBrain interface:

interface AgentBrain {
  readonly name: string;
  run(prompt: string, options?: BrainRunOptions): AsyncIterable<AgentEvent>;
  abort(): void;
}

Available brains:

• ClaudeCodeBrain - Wraps the Claude Agent SDK

Coming soon:

• CodexBrain - OpenAI Codex
• OpenCodeBrain - Open source coding agents

Sandbox

Isolated execution environment. Implements the Sandbox interface:

interface Sandbox {
  readonly name: string;
  create(): Promise<void>;
  destroy(): Promise<void>;
  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
  writeFile(path: string, content: string | Buffer): Promise<void>;
  readFile(path: string): Promise<string>;
  listFiles(path: string): Promise<string[]>;
  exists(path: string): Promise<boolean>;
}

Available sandboxes:

• LocalSandbox - Direct local execution (no isolation)
• E2BSandbox - Secure cloud sandbox via E2B

Coming soon:

• DockerSandbox - Local Docker containers
• ModalSandbox - Modal cloud functions
• FlyMachineSandbox - Fly.io machines

Configuration

ClaudeCodeBrain options

new ClaudeCodeBrain({
  model: "claude-sonnet-4-20250514",  // Model to use
  allowedTools: ["Read", "Edit", "Bash"],  // Tools the agent can use
  permissionMode: "acceptEdits",  // "default" | "acceptEdits" | "bypassPermissions"
  mcpServers: {  // MCP servers to connect
    playwright: { command: "npx", args: ["@playwright/mcp@latest"] }
  },
});

E2BSandbox options

new E2BSandbox({
  template: "base",  // E2B template name
  apiKey: "...",     // Or set E2B_API_KEY env var
  timeout: 60000,    // Sandbox creation timeout (ms)
});

Events

The agent emits events as it works:

Event	Description
start	Agent began execution
message	Text message from assistant or user
tool_use	Agent is invoking a tool
tool_result	Tool returned a result
error	An error occurred
done	Agent finished (includes token usage)

Implementing Custom Brains/Sandboxes

Custom Brain

import { AgentBrain, AgentEvent, BrainRunOptions } from "open-agent-sdk";

class MyBrain implements AgentBrain {
  readonly name = "my-brain";

  async *run(prompt: string, options?: BrainRunOptions): AsyncIterable<AgentEvent> {
    yield { type: "start", timestamp: Date.now() };

    // Your agent logic here...
    yield { type: "message", timestamp: Date.now(), content: "Hello!", role: "assistant" };

    yield { type: "done", timestamp: Date.now() };
  }

  abort(): void {
    // Handle abort
  }
}

Custom Sandbox

import { Sandbox, ExecResult, ExecOptions } from "open-agent-sdk";

class MySandbox implements Sandbox {
  readonly name = "my-sandbox";

  async create(): Promise<void> {
    // Initialize your sandbox
  }

  async destroy(): Promise<void> {
    // Clean up
  }

  async exec(command: string, options?: ExecOptions): Promise<ExecResult> {
    // Execute command
    return { exitCode: 0, stdout: "", stderr: "" };
  }

  // ... implement other methods
}

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	Required for ClaudeCodeBrain
E2B_API_KEY	Required for E2BSandbox

Examples

See the examples/ directory:

• basic.ts - Simple local usage
• with-e2b.ts - Secure cloud sandbox

Run examples:

npx tsx examples/basic.ts "What files are here?"
npx tsx examples/with-e2b.ts "Create a Python script"

License

MIT