> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Use Superserve sandboxes as the execution runtime for agents built with the OpenAI Agents SDK.

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

<CodeGroup>
  ```bash TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  npm install @superserve/sdk @openai/agents zod
  export SUPERSERVE_API_KEY=ss_live_...
  ```

  ```bash Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  pip install superserve openai-agents
  export SUPERSERVE_API_KEY=ss_live_...
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```typescript TypeScript {7-15} theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  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],
  })

  const result = await run(
    agent,
    "List the files in /tmp and tell me how many there are.",
  )
  console.log(result.finalOutput)

  await sandbox.kill()
  ```

  ```python Python {7-11} theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  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():
      result = await Runner.run(
          agent,
          "List the files in /tmp and tell me how many there are.",
      )
      print(result.final_output)
      sandbox.kill()

  asyncio.run(main())
  ```
</CodeGroup>

Add equivalent tools for file reads/writes the same way; see [Run commands](/commands/overview) and [Read & write files](/filesystem/read-write).