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 Integration Point​

The integration adds one import, one middleware object, and the middleware list on create_deep_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  # Added import

# Create OpenBox middleware
middleware = create_openbox_middleware(
    api_url=os.getenv("OPENBOX_URL"),
    api_key=os.getenv("OPENBOX_API_KEY"),
    agent_did=os.getenv("OPENBOX_AGENT_DID"),
    agent_private_key=os.getenv("OPENBOX_AGENT_PRIVATE_KEY"),
    agent_name="ResearchBot",
    known_subagents=["researcher", "writer", "general-purpose"],
)

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"}},
)

Newly created OpenBox agents require DID signing by default. If Require signing is disabled for the agent, omit agent_did and agent_private_key. See Agent DID Identity for the required environment variables.

Choose Your Path​

Deep Agents 101​

Get the DeepAgents concepts that matter for OpenBox before you wire governance into a real multi-agent workflow.

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, DID signing, HITL behavior, telemetry, 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

If this is a new project that does not already include DeepAgents, install the optional runtime extra:

uv add "openbox-deepagent-sdk-python[deepagents]"
pip install "openbox-deepagent-sdk-python[deepagents]"

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
export OPENBOX_AGENT_DID=did:aip:550e8400-e29b-41d4-a716-446655440000
export OPENBOX_AGENT_PRIVATE_KEY=base64_raw_ed25519_seed
Using an .env file?
.env
OPENBOX_URL=https://core.openbox.ai
OPENBOX_API_KEY=obx_live_your_api_key_here
OPENBOX_AGENT_DID=did:aip:550e8400-e29b-41d4-a716-446655440000
OPENBOX_AGENT_PRIVATE_KEY=base64_raw_ed25519_seed

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_did=os.getenv("OPENBOX_AGENT_DID"),
    agent_private_key=os.getenv("OPENBOX_AGENT_PRIVATE_KEY"),
    agent_name="ResearchBot",
    known_subagents=["researcher", "writer", "general-purpose"],
)

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; pass sqlalchemy_engine for database engines created before middleware initialization
  • Evaluated governance policies — every action was checked against your trust rules on the OpenBox platform
  • Signed governance requests — used the agent DID identity when signing is required for the registered agent
  • Enforced OpenBox approvals — if policy returns require_approval, the SDK waits for the OpenBox decision; avoid also using DeepAgents interrupt_on for the same tool

This runs on every agent invocation automatically.

Next Steps​

  1. Read Deep Agents 101 if you want the conceptual model first.
  2. Use Wrap an Existing Agent if you already have DeepAgents in production.
  3. Continue to the Deep Agents Developer Guide for configuration, event semantics, telemetry, and troubleshooting.