OpenBox CopilotKit SDK
@openbox-ai/openbox-copilotkit is the standalone OpenBox SDK for CopilotKit Runtime v2. It attaches at the CopilotKit / AG-UI boundary, so your existing CopilotKit runtime route and agents stay in place while OpenBox records workflow events, tool calls, assistant output, governance verdicts, and optional multi-agent handoff markers.
The SDK is server-only. It targets Node.js and CopilotKit Runtime v2; it does not publish React renderers or the older openbox-sdk/copilotkit adapter helpers.
Package Exports
Install the npm package in the app that owns your CopilotKit runtime route:
npm install @openbox-ai/openbox-copilotkit
Primary exports from @openbox-ai/openbox-copilotkit:
| Export | Purpose |
|---|---|
withOpenBoxRuntime() | recommended entry point; wraps CopilotRuntimeOptions, constructs a CopilotRuntime, and returns { runtime, shutdown } |
createOpenBoxMiddleware() | advanced AG-UI middleware factory for manual per-agent attachment |
OpenBoxClient | OpenBox Core HTTP client used by the runtime wrapper |
parseOpenBoxConfig() | resolves OPENBOX_* environment variables and explicit config |
runWithOpenBoxExecutionContext() | advanced request/context scoping helper |
| public types | OpenBoxMiddlewareOptions, OpenBoxMultiAgentOptions, OpenBoxRuntimeController, OpenBoxMultiAgentContext, and related SDK types |
Published subpaths include:
@openbox-ai/openbox-copilotkit/client@openbox-ai/openbox-copilotkit/config@openbox-ai/openbox-copilotkit/copilotkit@openbox-ai/openbox-copilotkit/governance@openbox-ai/openbox-copilotkit/identity@openbox-ai/openbox-copilotkit/types
Guide Set
| Guide | Description |
|---|---|
| Run the Demo | Run the CopilotKit + Mastra demo from an SDK checkout that includes demo/mastra |
| Add OpenBox to CopilotKit | Add the SDK to an existing CopilotKit Runtime v2 route |
| Configuration | Environment variables, wrapper config, middleware options, and multi-agent settings |
| Integration Walkthrough | Detailed Runtime v2 integration flow with frontend-tool labelling and optional handoff wiring |
Recommended Architecture
Use withOpenBoxRuntime() in the server route that creates your CopilotKit runtime:
import { CopilotRuntime, createCopilotEndpoint } from "@copilotkit/runtime/v2";
import { withOpenBoxRuntime } from "@openbox-ai/openbox-copilotkit";
export const runtime = "nodejs";
const options = {
agents,
} satisfies ConstructorParameters<typeof CopilotRuntime>[0];
const { runtime: copilotRuntime, shutdown } = await withOpenBoxRuntime(
options,
{
middlewareOptions: {
frontendToolNames: ["setThemeColor"],
enforceApprovals: false,
},
},
);
const app = createCopilotEndpoint({
runtime: copilotRuntime,
basePath: "/api/copilotkit",
});
withOpenBoxRuntime() accepts the same CopilotRuntimeOptions that you would pass to new CopilotRuntime(...). Passing an already constructed CopilotRuntime is not supported because OpenBox needs to wrap the runtime options, compose request middleware, and proxy agent clones before serving requests.
What The SDK Emits
| CopilotKit / AG-UI boundary | OpenBox event |
|---|---|
| run start | WorkflowStarted and SignalReceived(user_input) |
| tool-call args complete | ActivityStarted with parsed activity_input |
| tool-call result available | ActivityCompleted with activity_output |
| final assistant text | SignalReceived(agent_output) and WorkflowCompleted |
| run error | WorkflowFailed |
| mapped delegation tool | optional child-authenticated Handoff |
Every event uses workflow_type: "copilotkit" and task_queue: "copilotkit".
Governance Boundaries
The SDK is telemetry-first. With default options, it records CopilotKit runtime activity and OpenBox verdicts without stopping the user stream.
Set middlewareOptions.enforceApprovals: true to stop the AG-UI stream when OpenBox returns a block or halt verdict after full tool-call input is known. The client receives a redacted governance_blocked error frame with only a correlation id.
Output-side enforcement after the response has streamed is not part of this SDK version. Assistant output is recorded for governance visibility, and final output policy should be designed with that timing in mind.
Supported Runtime Conditions
| Requirement | Value |
|---|---|
| Node.js | >=24.10.0 |
| CopilotKit | @copilotkit/runtime ^1.61.0, Runtime v2 APIs |
| AG-UI | @ag-ui/client ^0.0.57 |
| Runtime | server-side Node route; edge runtimes are unsupported |
| OpenBox SDK | @openbox-ai/openbox-copilotkit |
Multi-Agent Scope
By default, a CopilotKit request is one OpenBox session. Enable middlewareOptions.multiAgent only when a CopilotKit tool delegates to a distinct OpenBox-governed child agent and you want one grouped timeline.
Multi-agent grouping needs three things:
- The CopilotKit parent stamps
multi_agent_session_idon its events. - A mapped delegation tool emits one
Handoff, authenticated as the child when child credentials are provided. - The child runtime stamps the same
multi_agent_session_idandparent_workflow_idon its own events.
The SDK can build and surface the parent-side context; your application owns forwarding that context into the child runtime invocation.
Next Steps
- Start with Add OpenBox to CopilotKit for the short path.
- Use Configuration for environment variables and SDK options.
- Use Integration Walkthrough for a longer end-to-end setup.