OpenAI Agents SDK

The declaw.openai module plugs declaw into the OpenAI Agents SDK as a sandbox backend. Agent authors keep their existing Agents-SDK code; the only change is handing a DeclawSandboxClient to the runner. Every tool the agent invokes — bash, read_file, write_file, apply_patch, pty_exec_start, etc. — runs inside the VM, with the full declaw security surface applied at the VM’s network boundary.

Install

pip install "declaw[openai-agents]"

Imports

Everything you need is available from a single namespace:

from declaw.openai import (
    # Adapter surface
    DeclawSandboxClient,
    DeclawSandboxClientOptions,
    DeclawSandboxSession,
    DeclawSandboxSessionState,
    DeclawSandboxTimeouts,
    DeclawSandboxType,
    # Security knobs (re-exported from declaw.security)
    SecurityPolicy,
    PIIConfig,
    InjectionDefenseConfig,
    TransformationRule,
    ToxicityConfig,
    CodeSecurityConfig,
    InvisibleTextConfig,
    EnvSecurityConfig,
    AuditConfig,
    # Network + lifecycle
    NetworkPolicy,
    SandboxNetworkOpts,
    SandboxLifecycle,
    ALL_TRAFFIC,
    # Agent-side guardrails helpers
    PIIHandler,
    GuardrailsClient,
)

`DeclawSandboxClient`

The sandbox-provider class. backend_id = "declaw".

await client.create(*, options: DeclawSandboxClientOptions) -> SandboxSession
await client.delete(session) -> SandboxSession
await client.resume(state: DeclawSandboxSessionState) -> SandboxSession
client.deserialize_session_state(payload) -> DeclawSandboxSessionState

`DeclawSandboxClientOptions`

Pydantic frozen model. Every field declaw’s Sandbox.create accepts is exposed here, plus the individual security sub-configs as convenience shortcuts.

Field	Type	Default	What it controls
`template`	`str`	`"base"`	Which preloaded sandbox template to spawn from. See templates.
`api_key`	`str \| None`	from `DECLAW_API_KEY`	Override the API key for this client.
`domain`	`str \| None`	from `DECLAW_DOMAIN`	API host (e.g. `api.declaw.ai`).
`timeout`	`int \| None`	`300`	Sandbox lifetime in seconds.
`envs`	`dict[str,str]`	`None`	Environment variables for the sandbox process.
`metadata`	`dict[str,str]`	`None`	Custom labels for audit / routing.
`allow_internet_access`	`bool`	`True`	Shorthand for “no egress lockdown”; overridden by `network`.
`security`	`SecurityPolicy`	`None`	Full security policy — see below.
`pii`	`PIIConfig`	`None`	Shortcut; overrides `security.pii` if set.
`injection_defense`	`InjectionDefenseConfig`	`None`	Shortcut for `security.injection_defense`.
`transformations`	`list[TransformationRule]`	`None`	Regex substitution rules.
`toxicity`	`ToxicityConfig`	`None`	Harmful-content detection.
`code_security`	`CodeSecurityConfig`	`None`	Code-injection scanning in HTTP traffic.
`invisible_text`	`InvisibleTextConfig`	`None`	Zero-width / hidden-character stripping.
`env_security`	`EnvSecurityConfig`	`None`	Env-var masking for audit logs.
`audit`	`AuditConfig`	`None`	Per-sandbox audit toggle.
`network`	`SandboxNetworkOpts`	`None`	`allow_out` / `deny_out` / `mask_request_host`.
`lifecycle`	`SandboxLifecycle`	`None`	`on_timeout` (`kill` / `pause`), `auto_resume`.
`volumes`	`list[VolumeAttachment \| dict]`	`None`	Pre-uploaded volumes (create with `declaw.Volumes.create`) to hydrate into the agent’s sandbox at boot. Each entry is `{"volume_id": "...", "mount_path": "/data"}`.
`timeouts`	`DeclawSandboxTimeouts`	`None`	Adapter-internal op timeouts.

Composition rule. If you pass a full SecurityPolicy via security=, we use it. Any per-field shortcut (e.g. pii=PIIConfig(...)) that’s also set overrides the matching sub-field on the composite policy. If neither is set, the sandbox runs with platform defaults.

`DeclawSandboxSession`

Returned from client.create() and client.resume(). Implements the BaseSandboxSession ABC — _exec_internal, read, write, running, persist_workspace, hydrate_workspace — plus a handful of declaw-specific conveniences:

# Wrapped by agents.sandbox.SandboxSession; unwrap to reach these:
declaw_session: DeclawSandboxSession = session._inner  # or session.inner
await declaw_session.list_snapshots()
await declaw_session.metrics(start=..., end=...)   # not available yet -- see below
await declaw_session.pause()
await declaw_session.resume()
declaw_session.underlying_sandbox      # the raw declaw AsyncSandbox

Not available yet. The platform endpoint behind this returns 501 metrics collection not yet implemented, so metrics() currently fails. The method is part of the SDK surface, but there is no metrics data to retrieve.

`DeclawSandboxSessionState`

Serializable state for client.resume(). Carries:

sandbox_id: str — to reattach to a live sandbox.
snapshot_id: str | None — if set, resume() restores from a memory+disk snapshot (Sandbox.restore), otherwise it reattaches to a still-running sandbox (Sandbox.connect).
template: str, created_at: datetime.

Quick start

import asyncio
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from declaw.openai import (
    DeclawSandboxClient, DeclawSandboxClientOptions,
    SecurityPolicy, PIIConfig, InjectionDefenseConfig, SandboxNetworkOpts,
)

async def main():
    options = DeclawSandboxClientOptions(
        template="python",
        security=SecurityPolicy(
            pii=PIIConfig(enabled=True, action="redact"),
            injection_defense=InjectionDefenseConfig(enabled=True, sensitivity="medium"),
        ),
        network=SandboxNetworkOpts(allow_out=["api.openai.com", "pypi.org"]),
    )

    client = DeclawSandboxClient()
    session = await client.create(options=options)
    try:
        agent = SandboxAgent(name="demo", model="gpt-5.4", instructions="...")
        result = await Runner.run(
            agent,
            "Write 'hello' to /workspace/x.txt and print its byte count.",
            run_config=RunConfig(sandbox=SandboxRunConfig(session=session)),
        )
        print(result.final_output)
    finally:
        await client.delete(session)

asyncio.run(main())

Security — exactly what the core SDK provides

The adapter does not introduce a parallel security path. Whatever you set in SecurityPolicy here is the same policy enforced by the sandbox’s edge proxy for any sandbox — the same six guardrail scanners, the same audit log entries, the same outcome. When the agent’s bash tool runs curl https://api.example.com/?email=alice@acme.com, the request is intercepted and scanned before it reaches the upstream. See Security → Overview for the full scanner list and policy reference.

Session resume

persist_workspace creates a declaw snapshot of memory + disk; the returned session state carries snapshot_id which client.resume() uses to restore the exact VM state later — in a different process, on a different machine, or across a cluster restart. Snapshots are persisted to the platform’s blob store (GCS in our managed cloud).

Python SDK

TypeScript SDK

Go SDK

OpenAI Agents SDK

Install

Imports

`DeclawSandboxClient`

`DeclawSandboxClientOptions`

`DeclawSandboxSession`

`DeclawSandboxSessionState`

Quick start

Security — exactly what the core SDK provides

Session resume

See also

​Install

​Imports

​DeclawSandboxClient

​DeclawSandboxClientOptions

​DeclawSandboxSession

​DeclawSandboxSessionState

​Quick start

​Security — exactly what the core SDK provides

​Session resume

​See also

Install

Imports

`DeclawSandboxClient`

`DeclawSandboxClientOptions`

`DeclawSandboxSession`

`DeclawSandboxSessionState`

Quick start

Security — exactly what the core SDK provides

Session resume

See also