Skip to main content
Last updated on
Tags:
Options
Open in ChatGPTAsk ChatGPT about this pageOpen in ClaudeAsk Claude about this page

Getting Started with Deep Agents

Docs

The OpenBox SDK for DeepAgents is open source. Refer to the README for setup instructions: OpenBox-AI/openbox-deepagent-sdk-python

One Code Change​

The entire integration adds one import and two lines:

agent.py
import os
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model
from openbox_deepagent import create_openbox_middleware  # Added import

# Create OpenBox middleware
middleware = create_openbox_middleware(
    api_url=os.getenv("OPENBOX_URL"),
    api_key=os.getenv("OPENBOX_API_KEY"),
    agent_name="ResearchBot",

)

agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o-mini"),
    tools=[search_web, write_report, export_data],
    subagents=[
        {"name": "researcher", "tools": [search_web]},
        {"name": "writer", "tools": [write_report]},
    ],
    middleware=[middleware],  # Added middleware
)

result = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "Research AI safety"}]},
    config={"configurable": {"thread_id": "session-001"}},
)

Choose Your Path​

I already use DeepAgents​

Add the trust layer to your existing agent in 5 minutes. Install the SDK, create middleware, and your agent is governed.

Show me the SDK reference​

Full developer reference: middleware hooks, HITL conflict detection, and all configuration options.

Wrap an Existing Agent​

Step 1: Install the SDK​

uv add openbox-deepagent-sdk-python

# Or with pip
pip install openbox-deepagent-sdk-python

Requires Python 3.11+.

Step 2: Configure Environment Variables​

export OPENBOX_URL=https://core.openbox.ai
export OPENBOX_API_KEY=obx_live_your_api_key_here
Using an .env file?
.env
OPENBOX_URL=https://core.openbox.ai
OPENBOX_API_KEY=obx_live_your_api_key_here

Install python-dotenv and load it before creating middleware:

pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()

Step 3: Create Middleware and Add to Your Agent​

agent.py
import os
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model
from openbox_deepagent import create_openbox_middleware

middleware = create_openbox_middleware(
    api_url=os.getenv("OPENBOX_URL"),
    api_key=os.getenv("OPENBOX_API_KEY"),
    agent_name="ResearchBot",

)

agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o-mini"),
    tools=[search_web, write_report, export_data],
    subagents=[
        {"name": "researcher", "tools": [search_web]},
        {"name": "writer", "tools": [write_report]},
    ],
    middleware=[middleware],
)

Step 4: Run Your Agent​

Run your agent as you normally would:

python agent.py

The SDK initializes on first call and connects to OpenBox. You will see output similar to:

OpenBox SDK initialized successfully
  - Agent: ResearchBot
  - Governance policy: fail_open

Step 5: See It in Action​

Invoke your agent with a task. Once it completes:

  1. Open the OpenBox Dashboard
  2. Navigate to Agents → click your agent
  3. On the Overview tab, find the session that just ran
  4. Click Details to open the session

The Event Log Timeline shows the full execution trace — model calls, tool calls, and governance decisions. Click Watch Replay to open Session Replay for step-by-step playback.

What Just Happened?​

Under the hood, the OpenBox middleware:

  • Intercepted every model call — recorded prompts and completions, ran PII redaction before sending to the LLM
  • Governed every tool call — evaluated your policies before each tool executed, blocking or flagging as needed
  • Captured HTTP, database, and file I/O — automatic telemetry via OpenTelemetry instrumentation
  • Evaluated governance policies — every action was checked against your trust rules on the OpenBox platform
  • Detected HITL conflicts — if your DeepAgents interrupt_on config clashes with OpenBox HITL, the SDK warns you at startup

This runs on every agent invocation automatically.

Next Steps​