OpenAI Agents SDK - Superserve

The OpenAI Agents SDK is OpenAI’s framework for building agents with tool-use loops. Expose sandbox.commands.run as a function tool so every command the agent generates runs in an isolated VM instead of on your machine.

Setup

npm install @superserve/sdk @openai/agents zod
npm pkg set type=module  # the example uses top-level await
export SUPERSERVE_API_KEY=ss_live_...
export OPENAI_API_KEY=sk-...

pip install superserve openai-agents
export SUPERSERVE_API_KEY=ss_live_...
export OPENAI_API_KEY=sk-...

The agent loop runs on your machine, so the OpenAI Agents SDK reads OPENAI_API_KEY from your local environment. Only the commands that the agent runs go to the sandbox.

Wire the sandbox into the agent

The highlighted block defines a bash tool backed by the sandbox. Everything else is standard OpenAI Agents SDK usage.

import { Agent, run, tool } from "@openai/agents"
import { Sandbox } from "@superserve/sdk"
import { z } from "zod"

const sandbox = await Sandbox.create({ name: "agent-runtime" })

const bash = tool({
  name: "bash",
  description: "Run a shell command in the sandbox.",
  parameters: z.object({ command: z.string() }),
  execute: async ({ command }) => {
    const result = await sandbox.commands.run(command, { timeoutMs: 60_000 })
    return `${result.stdout}\n${result.stderr}`
  },
})

const agent = new Agent({
  name: "Workspace Assistant",
  instructions: "Use the bash tool to inspect the sandbox before answering.",
  tools: [bash],
})

try {
  const result = await run(
    agent,
    "List the files in /tmp and tell me how many there are.",
  )
  console.log(result.finalOutput)
} finally {
  await sandbox.kill() // delete the sandbox even if the agent run fails
}

import asyncio
from agents import Agent, Runner, function_tool
from superserve import Sandbox

sandbox = Sandbox.create(name="agent-runtime")

@function_tool
def bash(command: str) -> str:
    """Run a shell command in the sandbox."""
    result = sandbox.commands.run(command, timeout_seconds=60)
    return f"{result.stdout}\n{result.stderr}"

agent = Agent(
    name="Workspace Assistant",
    instructions="Use the bash tool to inspect the sandbox before answering.",
    tools=[bash],
)

async def main():
    try:
        result = await Runner.run(
            agent,
            "List the files in /tmp and tell me how many there are.",
        )
        print(result.final_output)
    finally:
        sandbox.kill()  # delete the sandbox even if the agent run fails

asyncio.run(main())

Add equivalent tools for file reads/writes the same way; see Run commands and Read & write files.

⌘I