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

# OpenAI Agents SDK

> Use Nullspace as an Agents SDK tool or deploy an Agents SDK app as a job or service.

OpenAI Agents SDK apps usually integrate with Nullspace in one of two ways:

| Shape            | Use When                                                                                |
| ---------------- | --------------------------------------------------------------------------------------- |
| Tool wrapper     | The model loop stays in your app and calls Nullspace for isolated command or file work. |
| Agent Deployment | The whole Agents SDK app should run in Nullspace as a managed `job` or `service`.       |

## Wrap Nullspace As A Tool

Use this pattern when an Agents SDK app should create a machine, run a bounded
command, and return a concise result to the agent. Your application process
stays in control of credentials, retries, cleanup, tracing, handoffs, and
approval state.

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
python -m pip install "openai-agents" "nullspace-sdk==1.0.0"
export OPENAI_API_KEY=sk-...
export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
```

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
import asyncio

from agents import Agent, Runner, function_tool
from nullspace import Machine


@function_tool
def run_in_nullspace(command: str) -> str:
    """Run a short shell command in an isolated Nullspace machine."""
    with Machine.create(template="base", timeout=300) as machine:
        result = machine.commands.run(command, shell=True, timeout=120)
        return result.stdout[-4000:] or result.stderr[-4000:]


agent = Agent(
    name="Machine Operator",
    instructions="Use the machine tool for commands that need isolated execution.",
    tools=[run_in_nullspace],
)


async def main() -> None:
    result = await Runner.run(agent, "Use a machine to print Python's platform.")
    print(result.final_output)


asyncio.run(main())
```

## Deploy An Agents SDK Job

Use [Agent Deployments](./deployments) when the whole Agents SDK app should run
as a managed process instead of calling a machine from your local process.

```toml theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
name = "openai-agents-job"
mode = "job"
template = "base"
workdir = "/workspace/project"
install = "python -m pip install -e ."
entrypoint = "python main.py"

[env]
required = ["OPENAI_API_KEY"]

[outputs]
paths = ["result.json", "reports"]
```

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace agent deploy .
nullspace agent run openai-agents-job \
  --input-json '{"task":"summarize the deployment plan"}' \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --json
```

See the [OpenAI Agents SDK job example](../examples/agent-deployment-openai-agents)
for a complete project.

## Deploy An Agents SDK Service

Use `mode = "service"` when your Agents SDK app exposes an HTTP API, chat
backend, or internal coordinator.

```toml theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
name = "openai-agents-service"
mode = "service"
template = "base"
workdir = "/workspace/project"
install = "python -m pip install -e ."
entrypoint = "python -m uvicorn app:app --host 0.0.0.0 --port 8000"

[service]
port = 8000
readiness = { type = "http", path = "/health", timeout_seconds = 30 }

[permissions]
public_url = true
```

## State Boundary

Nullspace owns deployment runs, service instances, backing machines, logs,
outputs, URLs, and cleanup. OpenAI Agents SDK tracing, handoffs, and approval
state stay owned by the Agents SDK app. Store framework run persistence in your
database, a volume, or app-managed storage.

The generic process-level deployment path is the supported path today. A future
native Nullspace machine client adapter can make Nullspace machines feel like an
Agents SDK machine backend, but it should not own the model loop, tracing,
handoffs, approval state, or framework run persistence.

## Related

* [Agent Primitives](./primitives)
* [Agents overview](./overview)
* [Agent Deployments](./deployments)
* [OpenAI Agents SDK job example](../examples/agent-deployment-openai-agents)
* [Local MCP](./local-mcp)