Last updated on Aug 27, 2026

Tags:

Getting Started with OpenBox on CopilotKit

OpenBox integrates with CopilotKit through the standalone @openbox-ai/openbox-copilotkit SDK. Wrap the same CopilotRuntimeOptions you already pass to CopilotKit, and OpenBox observes the Runtime v2 / AG-UI boundary without rewriting your agents or React UI.

Use this path when your application already has a CopilotKit runtime route. CopilotKit may talk to Mastra, LangGraph, or another AG-UI compatible backend. OpenBox attaches at the CopilotKit layer and can optionally group delegated backend agents into a multi-agent OpenBox timeline.

Server runtime

The SDK is server-only and targets CopilotKit Runtime v2. Run the CopilotKit endpoint on the Node runtime, not an edge runtime.

Integration Stack

Layer	Role
OpenBox	records CopilotKit workflow events, tool activity, assistant output, verdicts, and optional handoff markers
CopilotKit	owns the assistant UI, runtime route, AG-UI stream, frontend tools, and agent bridge
Backend agent framework	runs the actual agent, for example Mastra, LangGraph, or another AG-UI agent

One Runtime Change

The core integration is one import plus one wrapper around your CopilotKit runtime options:

CopilotKit
OpenBox

src/app/api/copilotkit/[[...slug]]/route.ts
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpoint,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";

const options = {
  agents,
  runner: new InMemoryAgentRunner(),
} satisfies ConstructorParameters<typeof CopilotRuntime>[0];

const runtime = new CopilotRuntime(options);

const app = createCopilotEndpoint({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);

src/app/api/copilotkit/[[...slug]]/route.ts
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpoint,
} from "@copilotkit/runtime/v2";
import { withOpenBoxRuntime } from "@openbox-ai/openbox-copilotkit";
import { handle } from "hono/vercel";

export const runtime = "nodejs";

const options = {
  agents,
  runner: new InMemoryAgentRunner(),
} satisfies ConstructorParameters<typeof CopilotRuntime>[0];

const { runtime: copilotRuntime, shutdown } = await withOpenBoxRuntime(
  options,
  {
    apiKey: process.env.OPENBOX_API_KEY,
    apiUrl: process.env.OPENBOX_URL,
    agentDid: process.env.OPENBOX_AGENT_DID,
    agentPrivateKey: process.env.OPENBOX_AGENT_PRIVATE_KEY,
    middlewareOptions: {
      frontendToolNames: ["setThemeColor"],
      enforceApprovals: false,
    },
  },
);

process.on("SIGTERM", async () => {
  await shutdown();
});

const app = createCopilotEndpoint({
  runtime: copilotRuntime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);

withOpenBoxRuntime() expects CopilotRuntimeOptions, not an already constructed CopilotRuntime. It builds the runtime, attaches OpenBox request middleware, and proxies each CopilotKit agent clone so OpenBox can observe AG-UI events for every request.

Before You Run

CopilotKit does not create OpenBox agents or rules for you. Prepare the OpenBox agent and controls before sending live CopilotKit traffic:

Register or open an OpenBox agent.
Generate an agent runtime key.
Copy the agent DID and private key unless Require signing is disabled.
Configure the OpenBox controls you want this CopilotKit app to evaluate in Authorize: guardrails, policies, and behavior rules.
Install the SDK and route one CopilotKit request through the OpenBox-wrapped runtime.

Newly created OpenBox agents require DID signing by default. If signing is disabled for the agent, omit agentDid and agentPrivateKey.

Choose Your Path

Run the Demo

Run the SDK repository's CopilotKit + Mastra demo and see the CopilotKit parent stream, optional Mastra child stream, and multi-agent handoff behavior.

Add OpenBox to CopilotKit

Add @openbox-ai/openbox-copilotkit to an existing CopilotKit Runtime v2 route.

SDK Reference

Review the SDK installation, integration patterns, API reference, and troubleshooting docs.

What OpenBox Captures

From the CopilotKit boundary, OpenBox can capture:

WorkflowStarted, WorkflowCompleted, and WorkflowFailed events for each CopilotKit request
SignalReceived(user_input) and SignalReceived(agent_output) for the visible conversation
ActivityStarted and ActivityCompleted for AG-UI tool calls, including parsed tool input and tool output when CopilotKit exposes a result event
frontend-tool labels when you provide frontendToolNames or isFrontendTool
optional function_call span records when you configure a SpanBuffer
optional multi-agent Handoff events and multi_agent_session_id fields when a CopilotKit tool delegates to a child OpenBox agent

By default the SDK is telemetry-only. Set middlewareOptions.enforceApprovals: true only when you want block or halt verdicts to stop the AG-UI stream with a redacted governance_blocked error frame.

What To Expect In The UI

After integration, the CopilotKit UI continues to behave like your existing app. OpenBox adds the operational view:

a CopilotKit session in the OpenBox Dashboard with workflow, signal, and tool events
policy and guardrail decisions linked to each governed boundary
frontend versus backend tool labels when configured
a grouped parent and child timeline when multi-agent mode is enabled and the child runtime stamps the same multi_agent_session_id
a redacted CopilotKit stream error when enforcement blocks or halts a tool call

Next Steps

Use Run the Demo to verify the SDK in a working CopilotKit app.
Use Add OpenBox to CopilotKit for an existing Runtime v2 route.
Configure trust controls in Authorize.
Continue to the CopilotKit SDK reference for configuration and runtime details.

Integration Stack​

One Runtime Change​

Before You Run​

Choose Your Path​

Run the Demo​

Add OpenBox to CopilotKit​

SDK Reference​

What OpenBox Captures​

What To Expect In The UI​

Next Steps​