Two AI Agent Sandbox Architectures: LangChain Guide
The Blind Spot Most AI Teams Miss
AI agents are powerful precisely because they can execute code, browse the web, read files, and call external APIs. That same power is what makes them dangerous when deployed without proper isolation.
Harrison Chase, founder of LangChain, has been consistently clear on this point: most teams focus obsessively on making their agent smarter while completely ignoring the environment where that agent actually runs. The environment is everything once your agent has real-world action capabilities.
In his analysis of production-ready agent architectures, Chase identifies two major sandbox families that every engineering team should understand before shipping. Below, we break them down with concrete examples and TypeScript code applicable to React and Next.js projects.
What Is an AI Agent Sandbox?
A sandbox is an isolated execution environment where the agent operates without touching the host system. Think of it as a controlled play area: the agent can do whatever it needs inside, but cannot reach out to damage your real infrastructure.
Without a sandbox, an agent executing LLM-generated code could — through an accident or a malicious prompt injection — delete files, make unauthorized API calls, or consume unbounded compute resources.
The question is never whether you need a sandbox. The question is which type of sandbox fits your use case.
Architecture 1: The Ephemeral Sandbox (Stateless)
The ephemeral or stateless sandbox is the simplest and most secure option. The lifecycle looks like this:
- The agent receives a task.
- A brand-new isolated environment (container, microVM...) is spun up.
- The agent executes its logic inside that environment.
- The environment is destroyed when done — no trace left.
Best for:
- Executing LLM-generated code (data analysis, transformations, calculations)
- One-off web scraping or API access
- Single-step tasks with no need for prior context
Popular tools for this pattern: E2B Code Interpreter SDK, Modal, Daytona.
// Simplified example using E2B in a Next.js API Route
import { Sandbox } from "@e2b/code-interpreter";
export async function POST(req: Request) {
const { code } = await req.json();
// Each call creates a new sandbox and destroys it on exit
const sandbox = await Sandbox.create();
try {
const result = await sandbox.runCode(code);
return Response.json({ output: result.text });
} finally {
await sandbox.kill(); // environment destroyed — clean slate
}
}
The finally block is the key: the sandbox is always destroyed, regardless of errors. No state persists between executions. Maximum security, minimal attack surface.
Main limitation: if your agent needs to remember what it did in a previous step (e.g., install a library, save an intermediate file), this pattern won't cut it.
Architecture 2: The Persistent Sandbox (Stateful)
The persistent or stateful sandbox keeps the environment alive across multiple agent interactions. The same environment accumulates context: created files, installed packages, session variables.
Best for:
- Multi-step project agents (write code → install deps → run tests → iterate)
- Workflow automation where state matters
- User sessions where the agent acts as a continuous assistant
// Stateful sandbox pattern — sandbox lives for the full session
import { Sandbox } from "@e2b/code-interpreter";
const activeSandboxes = new Map<string, Sandbox>();
async function getOrCreateSandbox(sessionId: string): Promise<Sandbox> {
if (activeSandboxes.has(sessionId)) {
return activeSandboxes.get(sessionId)!;
}
const sandbox = await Sandbox.create({ timeoutMs: 10 * 60 * 1000 }); // 10 min
activeSandboxes.set(sessionId, sandbox);
return sandbox;
}
// The agent can install pandas in step 1 and use it in step 10
export async function runAgentStep(sessionId: string, code: string) {
const sandbox = await getOrCreateSandbox(sessionId);
return sandbox.runCode(code);
}
In this model, the sandbox tied to sessionId persists while the session is active. An agent can install pandas on turn one and use it ten turns later without reinstalling.
Main limitation: higher operational complexity. You must manage the sandbox lifecycle (timeouts, cleanup), and the attack surface grows because state accumulates over time.
How to Choose Between the Two Architectures
| Criterion | Ephemeral (stateless) | Persistent (stateful) |
|---|---|---|
| Security | Maximum | Medium-high (requires management) |
| Complexity | Low | Medium-high |
| Performance | Slight startup penalty | Faster for successive executions |
| Use cases | One-off tasks, isolated analysis | Multi-step flows, session assistants |
| Cost model | Per execution (cheap for short tasks) | Per active time (watch for idle timeouts) |
In practice, the most robust agent systems combine both patterns: ephemeral sandboxes for high-risk subtasks (running untrusted code), persistent sandboxes for the main agent workflow.
Real-World Application in React/Next.js Projects
In our AI integration projects, we apply this dual architecture in systems where agents help users analyze data or generate custom code:
- Ephemeral for the CSV analysis module where users upload files: LLM-generated code runs in a fresh sandbox every time, with zero risk of cross-user contamination.
- Persistent for the development assistant that helps teams iterate on code across long working sessions.
The decision framework is straightforward: map the risk and the required state before choosing. This is not a purely technical decision — it's a product decision.
Conclusion
The two sandbox architectures Harrison Chase describes are not mutually exclusive alternatives — they are complementary tools. Ephemeral = maximum safety for isolated tasks. Persistent = more power for stateful workflows.
The most common mistake is skipping this design layer entirely and letting the agent run directly on the host system. There are no safe shortcuts here.
If you're designing an AI agent system and want to make sure you're picking the right architecture for your specific use case, we can help you design it from scratch. Drop us a message and we'll work through it together: