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

# OpenAI Agents SDK + Declaw

> Add a Declaw sandbox tool to an OpenAI Agents SDK agent using @function_tool. Create an Agent, run it with Runner.run(), and get secure code execution out of the box.

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

```bash theme={null}
pip install declaw python-dotenv openai-agents
```

<Note>This example is available in Python. TypeScript support coming soon.</Note>

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

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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!
=======================================================
```