Last updated on Aug 24, 2026

Tags:

LangChain Integration Walkthrough

This guide shows how to add OpenBox governance to an existing LangChain agent without rewriting the agent. The integration point is LangChain middleware: create an OpenBoxLangChainMiddleware instance and pass it to create_agent(..., middleware=[...]).

Existing agent?

If you only need the shortest setup path, start with Getting Started with LangChain.

Prerequisites

Python 3.11+
LangChain 0.3+ with an agent builder that accepts middleware
openbox-langchain-sdk-python 0.2.0+
an OpenBox agent registration with an API key
the OpenBox agent DID and private key unless Require signing is disabled

Part 1: Register Your Agent In OpenBox

Open the OpenBox Dashboard
Navigate to Agents
Create or open the agent you want to govern
Generate an API key
Copy the generated DID and private key unless Require signing is disabled
Keep the credentials in your runtime secret store

See Registering Agents for the dashboard flow.

Part 2: Install The SDK

uv add openbox-langchain-sdk-python

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

The LangChain SDK reuses the shared OpenBox LangGraph governance core, so the package depends on openbox-langgraph-sdk-python >= 0.2.0.

Part 3: Configure Environment

.env
OPENBOX_URL=https://core.openbox.ai
OPENBOX_API_KEY=obx_live_your_api_key

# Required by default for newly created agents unless Require signing is disabled.
OPENBOX_AGENT_DID=did:aip:your_agent_did
OPENBOX_AGENT_PRIVATE_KEY=your_agent_private_key

OPENBOX_AGENT_DID and OPENBOX_AGENT_PRIVATE_KEY must be configured together. Supplying only one value fails during SDK configuration.

Part 4: Add Middleware

LangChain
OpenBox

agent.py
from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4o",
    tools=[search_web, lookup_customer],
)

result = agent.invoke({"messages": [("user", "Check this customer issue")]})

agent.py
import os

from dotenv import load_dotenv
from langchain.agents import create_agent
from openbox_langchain import create_openbox_langchain_middleware

load_dotenv()

middleware = create_openbox_langchain_middleware(
    api_url=os.environ["OPENBOX_URL"],
    api_key=os.environ["OPENBOX_API_KEY"],
    agent_did=os.environ["OPENBOX_AGENT_DID"],
    agent_private_key=os.environ["OPENBOX_AGENT_PRIVATE_KEY"],
    agent_name="SupportAgent",
    tool_type_map={
        "search_web": "http",
        "lookup_customer": "database",
    },
)

agent = create_agent(
    model="openai:gpt-4o",
    tools=[search_web, lookup_customer],
    middleware=[middleware],
)

result = agent.invoke({"messages": [("user", "Check this customer issue")]})

Part 5: Verify A Live Run

Run one real request through the governed agent, then check OpenBox for:

a run under the registered agent
model call events with prompt and response metadata
tool call activities with started and completed events
hook-level telemetry for HTTP, database, or file I/O when instrumentation is active
governance decisions for allowed, blocked, halted, or approval-required operations
signed request authentication when Require signing is enabled

Open the OpenBox Dashboard, navigate to Agents, open the agent, and inspect the latest run.

How The Integration Works

The SDK uses LangChain AgentMiddleware hooks:

Hook	Purpose
`before_agent` / `abefore_agent`	Starts the OpenBox run and pre-screens the user prompt
`wrap_model_call` / `awrap_model_call`	Records model start/completion and applies LLM governance
`wrap_tool_call` / `awrap_tool_call`	Evaluates tool calls before and after execution
`after_agent` / `aafter_agent`	Completes the run and flushes telemetry

The SDK also initializes hook-level OpenTelemetry instrumentation so lower-level HTTP, database, and file operations can be attributed to the active LangChain activity.

Tool Classification

Use tool_type_map to classify tools for policy targeting:

middleware = create_openbox_langchain_middleware(
    api_url=os.environ["OPENBOX_URL"],
    api_key=os.environ["OPENBOX_API_KEY"],
    agent_did=os.environ["OPENBOX_AGENT_DID"],
    agent_private_key=os.environ["OPENBOX_AGENT_PRIVATE_KEY"],
    tool_type_map={
        "search_web": "http",
        "lookup_customer": "database",
        "send_email": "communication",
    },
)

Policies can then target semantic tool categories rather than individual tool names.

Human-in-the-Loop Approvals

If OpenBox returns REQUIRE_APPROVAL, the SDK follows the approval behavior from the shared governance core. Approval requests appear in the Approvals queue. If the request is rejected or expires, the SDK raises a governance exception.

See Error Handling for the exception types and recommended handling patterns.

Next Steps

Configuration - Review all middleware options
Error Handling - Handle governance decisions in code
Troubleshooting - Diagnose missing sessions, identity errors, and telemetry gaps

Prerequisites​

Part 1: Register Your Agent In OpenBox​

Part 2: Install The SDK​

Part 3: Configure Environment​

Part 4: Add Middleware​

Part 5: Verify A Live Run​

How The Integration Works​

Tool Classification​

Human-in-the-Loop Approvals​

Next Steps​