OpenBox on CopilotKit
OpenBox sits on top of CopilotKit. CopilotKit can connect to multiple backend agent frameworks. This guide documents the LangGraph backend path.
The integration governs CopilotKit runtime prompts, tool input, tool output, assistant output, and approval decisions while preserving the CopilotKit UI and the LangGraph agent shape behind it.
Package exports:
openbox-sdk/copilotkitopenbox-sdk/copilotkit/react
| Guide | Description |
|---|---|
| Run the Demo | Clone and run the OpenBox-on-CopilotKit reference app with LangGraph |
| Add OpenBox to CopilotKit | Add OpenBox above CopilotKit in an app where CopilotKit uses LangGraph as the backend |
| Configuration | Environment variables, adapter options, and runtime behavior |
| Integration Walkthrough | End-to-end guide for wiring the runtime, LangGraph middleware, governed tools, and React renderers |
The integration connects the CopilotKit runtime to OpenBox, then uses the current LangGraph bridge to instrument the backend agent process. Trust policy, approvals, guardrails, dashboards, and operator workflows live on the OpenBox platform, not inside CopilotKit.
Required OpenBox Setup
Before wiring the CopilotKit runtime, register an OpenBox agent, generate its runtime key, and configure its trust controls in Authorize. CopilotKit sends events to the registered agent; OpenBox evaluates the agent's guardrails, policies, and behavior rules.
Recommended Architecture
Use OpenBox above CopilotKit, and use the current LangGraph bridge for backend instrumentation:
| Layer | OpenBox hook | Purpose |
|---|---|---|
| OpenBox on CopilotKit runtime route | createOpenBoxCopilotRuntime() | governs prompt ingress and assistant output around /api/copilotkit |
| OpenBox CopilotKit adapter | createOpenBoxCopilotKitAdapter() | configures Core credentials, gate behavior, session state, and tool names |
| CopilotKit on LangGraph middleware | adapter.createLangChainMiddleware() | governs LangGraph model/tool activity inside the agent process |
| Business tools | createGovernedCopilotTool() | returns OpenBox decisions and releasable artifacts through the same tool result |
| Approval route | createOpenBoxApprovalRoute() | submits human approval decisions back to OpenBox |
| React UI | useOpenBoxCopilotKit() | renders OpenBox decision, interactive review, approval, and action-result components |
Public API Summary
Server-side exports:
createOpenBoxCopilotKitAdapter()createOpenBoxCopilotRuntime()createOpenBoxGovernedRunner()createOpenBoxRuntimeHooks()createGovernedCopilotTool()createOpenBoxApprovalRoute()createOpenBoxReadinessCheck()OPENBOX_COPILOTKIT_RESULT_SCHEMA_VERSION
React exports:
useOpenBoxCopilotKit()createOpenBoxApprovalClient()createOpenBoxCustomMessageRenderer()OpenBoxGovernanceDecisionOpenBoxApprovalReviewOpenBoxInteractiveReviewOpenBoxActionResult
Governance Boundaries
OpenBox can evaluate these CopilotKit gates:
| Gate | What is evaluated |
|---|---|
prompt | user prompt and recent runtime messages before agent execution |
tool_input | normalized tool arguments before business execution |
tool_output | raw tool result before rendering |
assistant_output | final assistant content before it reaches the user |
Governed tool results use schema version openbox.copilotkit.result.v1.
Supported Runtime Conditions
| Requirement | Value |
|---|---|
| Node.js | >=22 for the reference app |
| CopilotKit | @copilotkit/react-core and @copilotkit/runtime ^1.59 in the reference app |
| LangGraph JS | @langchain/langgraph ^1.3 in the reference app |
| OpenBox SDK | openbox-sdk with copilotkit and copilotkit/react exports |
| CopilotKit runtime | Next.js App Router route backed by /api/copilotkit |
Next Steps
- Run the OpenBox-on-CopilotKit demo.
- Add the integration to an existing app with Add OpenBox to CopilotKit.
- Configure OpenBox trust controls in Authorize.
- Configure production behavior in Configuration.