Superserve

Use Superserve sandbox tools with Agno agents.

Superserve enables Agno agents to run agent-generated code in an isolated cloud sandbox (Firecracker microVM). The sandbox persists across tool calls, so files written and packages installed remain available.

Prerequisites

  1. Get your Superserve API key: https://superserve.ai
  2. Set the API key as an environment variable: 
    export SUPERSERVE_API_KEY=ss_live_...
  3. Install the dependencies: uv pip install agno openai superserve
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.superserve import SuperserveTools

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------

# A focused default tool set is enabled. Every tool has its own enable_* flag, so
# you can toggle tools individually or turn everything on with all=True:
#   SuperserveTools(enable_pause_sandbox=True, enable_resume_sandbox=True)
#   SuperserveTools(enable_attach_secret=True, enable_detach_secret=True)
#   SuperserveTools(all=True)  # register every tool
# Sandboxes default to a Python-ready template; override it for other runtimes:
#   SuperserveTools(template="superserve/node-22")
# To bind a team secret to the sandbox without exposing the real credential:
#   SuperserveTools(secrets={"OPENAI_API_KEY": "openai-prod"})

agent = Agent(
    name="Coding Agent with Superserve tools",
    model=OpenAIResponses(id="gpt-5.5"),
    tools=[SuperserveTools(timeout=600)],
    markdown=True,
    instructions=[
        "You are an expert at writing and executing code in a secure Superserve sandbox.",
        "Your primary purpose is to:",
        "1. Write clear, efficient code based on user requests",
        "2. ALWAYS execute the code in the sandbox using run_python_code or run_command",
        "3. Show the actual execution results to the user",
        "4. Provide explanations of how the code works and what the output means",
        "Guidelines:",
        "- NEVER just provide code without executing it",
        "- Install missing packages when needed using run_command, for example pip install <package>",
        "- Use file operations (create_file, read_file, list_files) when working with scripts",
        "- Always show both the code AND the execution output",
        "- Handle errors gracefully and explain any issues encountered",
    ],
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response(
        "Write Python code to generate the first 10 Fibonacci numbers and calculate their sum and average"
    )

Sandbox lifetime

timeout=600 sets the sandbox's auto-stop lifetime; each command still defaults to a 60-second timeout. Files persist while that sandbox remains available. The script has no session database, so restarting it does not restore the saved sandbox ID automatically. Reconnect with an explicit sandbox_id, or persist the agent's session state when building a longer-lived application.

To delete the sandbox after the example, retain the toolkit in a variable (sandbox_tools = SuperserveTools(timeout=600)), pass tools=[sandbox_tools] to the agent, and call sandbox_tools.shutdown_sandbox(agent) in a finally block after the run. Auto-stop and deletion are distinct lifecycle operations.

Run the Example

# Clone and setup repo
git clone https://github.com/agno-agi/agno.git
cd agno
git checkout d703c34f3abf3c41275d3fb2da6e0518a8881f24

# Create and activate virtual environment
./scripts/demo_setup.sh
source .venvs/demo/bin/activate

uv pip install -U superserve openai
export OPENAI_API_KEY="your_openai_api_key_here"

python cookbook/91_tools/superserve_tools.py

For details, see Superserve cookbook.