Run the Demo
The demo in the SDK release workspace runs a CopilotKit UI with a Mastra weather agent. It shows how @openbox-ai/openbox-copilotkit wraps the CopilotKit runtime route, while @openbox-ai/openbox-mastra-sdk can also wrap the Mastra backend for deeper agent-runtime telemetry.
Reference repository:
Demo path:
demo/mastra
If your cloned SDK checkout does not include demo/mastra yet, use Add OpenBox to CopilotKit until the demo folder is published with the SDK release.
Prerequisites
- Node.js
>=24.10.0 - npm
- an OpenAI API key, or another model/provider configuration supported by the demo
- optional OpenBox Core URL and agent runtime keys if you want to send events to OpenBox
- optional CopilotKit license/intelligence values if you want to run CopilotKit Intelligence instead of the in-memory runner
Clone The Repository
git clone https://github.com/OpenBox-AI/openbox-copilotkit-sdk
cd openbox-copilotkit-sdk/demo/mastra
The demo installs the local SDK from the repository root with file:../.., so you do not need to publish or install the package from npm to run it locally. Run these commands from a checkout that includes demo/mastra.
Install Dependencies
cp .env.example .env
npm install
Fill in OPENAI_API_KEY in .env. Without OpenBox keys, the app still runs as a normal CopilotKit + Mastra demo.
Prepare OpenBox Agents
For basic CopilotKit governance, register one OpenBox agent for the CopilotKit parent/orchestrator:
- Register or open an OpenBox agent.
- Generate an agent runtime key.
- Copy the agent DID and private key unless Require signing is disabled.
- Configure guardrails, policies, and behavior rules in Authorize.
For multi-agent testing, register a second distinct OpenBox agent for the Mastra child/subagent. Do not reuse the same DID for the CopilotKit parent and the Mastra child. OpenBox Core resolves the handoff's receiving agent from the authenticated child request.
Configure Environment
Required to run the demo app:
| Variable | Purpose |
|---|---|
OPENAI_API_KEY | model provider API key used by the Mastra agent |
Required to enable OpenBox on the CopilotKit parent:
| Variable | Purpose |
|---|---|
OPENBOX_URL | OpenBox Core base URL |
OPENBOX_COPILOTKIT_API_KEY | CopilotKit parent OpenBox runtime key, obx_live_* or obx_test_* |
OPENBOX_COPILOTKIT_AGENT_DID | CopilotKit parent DID, required when signing is enabled |
OPENBOX_COPILOTKIT_AGENT_PRIVATE_KEY | CopilotKit parent Ed25519 private key, required when signing is enabled |
Optional values for the Mastra child stream:
| Variable | Purpose |
|---|---|
OPENBOX_MASTRA_API_KEY | Mastra child OpenBox runtime key |
OPENBOX_MASTRA_AGENT_DID | Mastra child DID |
OPENBOX_MASTRA_AGENT_PRIVATE_KEY | Mastra child Ed25519 private key |
OPENBOX_MASTRA_MULTI_AGENT_ENABLED | set to false to disable Mastra child multi-agent stamping |
OPENBOX_MASTRA_MULTI_AGENT_SESSION_ID | fixed multi-agent session id for child-side testing |
The demo route also accepts the generic OPENBOX_API_KEY, OPENBOX_AGENT_DID, and OPENBOX_AGENT_PRIVATE_KEY fallbacks for simple single-agent testing. Use the explicit OPENBOX_COPILOTKIT_* and OPENBOX_MASTRA_* variables when testing parent and child identities together.
Run Locally
npm run dev
This script builds the local @openbox-ai/openbox-copilotkit package, then starts the Next.js UI and Mastra agent server together.
Open the URL printed by Next.js.
Test The Demo Manually
Use the built-in suggestions or enter similar requests:
| Prompt | Expected path |
|---|---|
Get the weather in San Francisco. | CopilotKit frontend tool and Mastra weather tool activity |
Set the theme to green. | frontend tool labelled by the CopilotKit wrapper |
Please go to the moon. | CopilotKit human-in-the-loop UI path |
After each run, check the OpenBox Dashboard for:
- A
workflow_type: "copilotkit"session from the CopilotKit runtime route. WorkflowStarted,SignalReceived(user_input),ActivityStarted,ActivityCompleted,SignalReceived(agent_output), andWorkflowCompletedevents.frontend: trueon tool names configured in the demo route'sfrontendToolNameslist.- A separate Mastra child stream when the Mastra OpenBox SDK credentials are configured.
Multi-Agent Demo Notes
When OPENBOX_COPILOTKIT_AGENT_DID plus the OPENBOX_MASTRA_* child credentials are present, the CopilotKit wrapper enables multi-agent mode and maps the weatherTool / get-weather delegation tools to the Mastra child.
That lets the CopilotKit parent emit a child-authenticated Handoff event with:
from_agent_didset to the CopilotKit parent DIDmulti_agent_session_idset on the parent stream- child metadata such as
child_workflow_type: "weather-agent"andchild_task_queue: "mastra"
The current demo path shows the CopilotKit parent stream and parent-side Handoff. A fully grouped parent and child timeline also requires the Mastra child events to carry the exact same multi_agent_session_id and parent_workflow_id generated by the parent. Setting only OPENBOX_MASTRA_MULTI_AGENT_SESSION_ID does not make it match the parent default mas:${runId} automatically; production apps should forward the parent OpenBoxMultiAgentContext into the child invocation.
Verify The Local Build
Fast local checks from demo/mastra:
npm run build
The script builds the local SDK package first, then builds the Next.js app.