Skip to main content

​
What You’ll Learn

  • Defining a @function_tool with the agents package that executes Python in a Declaw sandbox
  • Creating an Agent with instructions and tools
  • Running the agent with Runner.run() and reading result.final_output
  • Demo mode that exercises the sandbox tool directly without needing an OpenAI key

​
Prerequisites

  • Declaw instance running and DECLAW_API_KEY / DECLAW_DOMAIN set
  • OPENAI_API_KEY (optional — the example runs in demo mode without it)
pip install declaw python-dotenv openai-agents
This example is available in Python. TypeScript support coming soon.

​
Code Walkthrough

​
1. Define the Declaw sandbox tool

The @function_tool decorator from the agents package generates a tool schema from the function signature and docstring: 
from agents import function_tool
from declaw import Sandbox

@function_tool
def execute_python(code: str) -> str:
    """Execute Python code in a secure Declaw sandbox."""
    sbx = Sandbox.create(template="python", timeout=300)
    try:
        sbx.files.write("/tmp/code.py", code)
        result = sbx.commands.run("python3 /tmp/code.py", timeout=30)
        return f"stdout: {result.stdout}\nstderr: {result.stderr}"
    finally:
        sbx.kill()

​
2. Create an agent and run it

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="Code Runner",
    instructions=(
        "You are a helpful assistant that can execute Python code "
        "in a secure sandbox. Use the execute_python tool to run code."
    ),
    tools=[execute_python],
)

async def main():
    prompt = "Write Python code to calculate 2^100 and print the result."
    result = await Runner.run(agent, prompt)
    print(f"Agent response: {result.final_output}")

asyncio.run(main())

​
3. Demo mode (no API key needed)

Run the sandbox tool directly to verify it works before connecting the agent: 
from declaw import Sandbox

code = """\
result = 2 ** 100
print(f"2^100 = {result}")
print(f"That's a {len(str(result))}-digit number!")
"""

sbx = Sandbox.create(template="python", timeout=300)
try:
    sbx.files.write("/tmp/code.py", code)
    result = sbx.commands.run("python3 /tmp/code.py", timeout=30)
    print(result.stdout)
finally:
    sbx.kill()

​
Expected Output

In demo mode: 
=======================================================
OpenAI Agents SDK + Declaw Sandbox Example
=======================================================
No OPENAI_API_KEY found -- running demo mode.

--- Tool Definition ---
from agents import Agent, Runner, function_tool
from declaw import Sandbox

@function_tool
def execute_python(code: str) -> str:
    """Execute Python code in a secure Declaw sandbox."""
    ...

--- Running Code Directly in Declaw Sandbox ---
Code:
result = 2 ** 100
print(f"2^100 = {result}")
print(f"That's a {len(str(result))}-digit number!")

stdout: 2^100 = 1267650600228229401496703205376
That's a 31-digit number!
stderr:
exit_code: 0

Sandbox cleaned up.

=======================================================
Done!
=======================================================