AG-UI Event Inspector
Inspect AG-UI events in real time with the VSCode extension
The AG-UI Event Inspector gives you a live view of every event flowing between your CopilotKit runtime and client. Instead of sprinkling console.log statements through your agent code, you can watch the full AG-UI event stream in a filterable, color-coded panel inside VS Code.
Use it when:
- An agent interaction isn't behaving as expected and you need to see which events the runtime is actually emitting
- You want to understand the AG-UI event lifecycle (e.g., how
RUN_STARTEDflows throughTEXT_MESSAGE_CONTENTchunks toRUN_FINISHED) - You need to inspect tool call arguments or state deltas for a specific interaction
Prerequisites#
- A CopilotKit runtime running locally in development mode (
NODE_ENVis notproduction) - The CopilotKit VS Code extension installed
The /cpk-debug-events endpoint is disabled when NODE_ENV=production. This is intentional — it streams internal event data that should not be exposed in production environments.
Connect and inspect#
Ensure your runtime is running in development mode#
The debug event endpoint is available at GET /cpk-debug-events on your CopilotKit runtime. It activates automatically when NODE_ENV !== 'production' — no extra configuration needed. If you're using the default dev setup, you're already good to go.
Open the AG-UI Inspector#
Open the VS Code command palette (Ctrl+Shift+P / Cmd+Shift+P) and run:
CopilotKit: Open AG-UI InspectorThis opens a dedicated webview panel.
Enter your runtime URL and connect#
Type your runtime URL in the input field at the top of the panel (default: http://localhost:4000) and click Connect. The panel status indicator turns green when the SSE connection is established.
Trigger an agent interaction#
Go to your app and perform an action that triggers an agent run — send a chat message, invoke a tool, or interact with any CopilotKit-powered component. Events start streaming into the inspector immediately.
Read the event stream#
Each event row shows:
- Timestamp — relative time since the first event (e.g.,
+0.142s) - Event type badge — color-coded by category (see table below)
- Summary — key fields like message ID, tool name, or a text preview
Filter events#
Use the category filter buttons at the top of the panel to show or hide event categories. You can also search event payloads with the search field to find specific tool names, message IDs, or content.
Inspect event details#
Click any event row to expand the full JSON payload in the detail panel. This shows every field the runtime emitted for that event, including agentId, threadId, runId, and the complete event data.
Event type reference#
| Category | Color | Event Types | Description |
|---|---|---|---|
| Lifecycle | Purple | RUN_STARTED, RUN_FINISHED | Marks the start and end of an agent run |
| Errors | Red | RUN_ERROR | An error occurred during the agent run |
| Text Messages | Blue | TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END, TEXT_MESSAGE_CHUNK | Text streamed from the agent to the client |
| Tool Calls | Orange | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_CHUNK, TOOL_CALL_RESULT | Tool invocation lifecycle — name, arguments, and result |
| Reasoning | Green | REASONING_START, REASONING_MESSAGE_START, REASONING_MESSAGE_CONTENT, REASONING_MESSAGE_END, REASONING_END | Model reasoning/chain-of-thought events |
| State | Teal | STATE_SNAPSHOT, STATE_DELTA | Agent state snapshots and incremental updates |
| Activity/UI | Yellow | ACTIVITY_SNAPSHOT, ACTIVITY_DELTA | UI activity indicators and progress updates |
For console-level debug logging and programmatic error handling in your app, see Error Debugging. If you're debugging a render prop rather than a runtime event stream, the Hook Explorer is the offline, render-first complement to this tool.
