SDK Development Guide
Full integration guide for SandAgent SDK
Installation
npm install @sandagent/sdk aiOptional sandbox providers:
npm install @sandagent/sandbox-e2b
npm install @sandagent/sandbox-daytona
npm install @sandagent/sandbox-sandockCore Concepts
- Provider:
createSandAgent()returns an AI SDK-compatible model - Sandbox: isolates code execution (local or cloud)
- Runner: executes the agent inside the sandbox
Minimal Setup
import { createSandAgent, LocalSandbox } from "@sandagent/sdk";
const sandbox = new LocalSandbox({
workdir: process.cwd(),
templatesPath: process.cwd(),
});
const sandagent = createSandAgent({
sandbox,
cwd: sandbox.getWorkdir(),
});Next.js Integration
import { createSandAgent, LocalSandbox } from "@sandagent/sdk";
import {
convertToModelMessages,
createUIMessageStream,
createUIMessageStreamResponse,
streamText,
} from "ai";
export async function POST(request: Request) {
const { messages } = await request.json();
const sandbox = new LocalSandbox({
workdir: process.cwd(),
templatesPath: process.cwd(),
runnerCommand: ["npx", "-y", "@sandagent/runner-cli@latest", "run"],
env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
const stream = createUIMessageStream({
execute: async ({ writer }) => {
const sandagent = createSandAgent({ sandbox, cwd: sandbox.getWorkdir() });
const result = streamText({
model: sandagent("sonnet"),
messages: await convertToModelMessages(messages),
abortSignal: request.signal,
});
writer.merge(result.toUIMessageStream());
},
});
return createUIMessageStreamResponse({ stream });
}Sandbox Options
| Adapter | Use Case | Package |
|---|---|---|
LocalSandbox | Local dev/test | Built in |
E2BSandbox | Cloud production | @sandagent/sandbox-e2b |
DaytonaSandbox | Persistent volumes | @sandagent/sandbox-daytona |
SandockSandbox | Docker-based | @sandagent/sandbox-sandock |
See Sandbox Configuration and Sandbox Reuse for details.
Production Notes
- Use a server sandbox provider (E2B/Daytona/Sandock)
- Ensure provider API keys are set
- Increase
timeoutfor long-running tasks
Troubleshooting
- Missing API key → verify env vars
- Template not found → deploy or use
templatesPath - No streaming → check AI SDK integration and
createUIMessageStream