# 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_STARTED` flows through `TEXT_MESSAGE_CONTENT` chunks to `RUN_FINISHED`)
- You need to inspect tool call arguments or state deltas for a specific interaction

To debug on the client instead, use the in-app [Inspector](/react-native/ag2/inspector).

## Prerequisites [#prerequisites]

- A CopilotKit runtime running locally with `NODE_ENV` set to `development`, or with `debug` enabled on the runtime
- The [CopilotKit VS Code extension](/react-native/ag2/vs-code-extension) installed

<Callout type="warning">
  The `/cpk-debug-events` endpoint streams every event of every thread, including full message content, to any subscriber. It is served in exactly two cases: `NODE_ENV` is `development`, or the runtime sets `debug`. Everywhere else it returns 404.

  An *unset* `NODE_ENV` counts as everywhere else. A plain `node server.js` sets no value, so a self-hosted runtime does not expose the feed by accident. If you need it on such a host, ask for it explicitly:

  ```ts
  const runtime = new CopilotRuntime({ agents, debug: true });
  ```

  Treat that as you would any other way of reading conversation content, and do not enable it on a runtime the public can reach.
</Callout>

<Callout type="warning">
  This stream carries the AG-UI events a **self-hosted** runtime sends over SSE.
  A runtime configured with `intelligence` does not send them: it answers runs
  over CopilotKit Intelligence's realtime connection instead. On that runtime
  `/cpk-debug-events` still connects and reports `: connected`, then stays
  empty. To trace an Intelligence-backed run, use the in-app
  [Inspector](/react-native/ag2/inspector), which reads the events on the client.
</Callout>

## Connect and inspect [#connect-and-inspect]

<Steps>
<Step>
### Run your runtime in development mode [#run-your-runtime-in-development-mode]

The debug event endpoint is available at `GET {runtimeUrl}/cpk-debug-events`. It activates automatically when `NODE_ENV` is `development`, which `next dev` and most dev servers set for you. No extra configuration is needed. On a host that sets no `NODE_ENV`, set `debug: true` on the runtime instead.

The path is relative to the `basePath` the runtime is mounted at, not to the server's origin. A runtime mounted at `/api/copilotkit` on port 8200 serves the stream at `http://localhost:8200/api/copilotkit/cpk-debug-events`; requesting `http://localhost:8200/cpk-debug-events` returns `404 {"error":"Not found"}`. Confirm the URL before you connect:

```bash
curl -N http://localhost:8200/api/copilotkit/cpk-debug-events
```

A working endpoint responds immediately with `: connected` and then holds the connection open.
</Step>

<Step>
### Open the AG-UI Event Inspector [#open-the-ag-ui-event-inspector]

Open the VS Code command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run:

```
CopilotKit: Open AG-UI Inspector
```

This opens a dedicated webview panel.
</Step>

<Step>
### Enter your runtime URL and connect [#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**. Use the full mounted runtime URL (the same value your frontend passes as `runtimeUrl`, including its base path), not just the origin. The panel status indicator turns green when the SSE connection is established.
</Step>

<Step>
### Trigger an agent interaction [#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 AG-UI Event Inspector immediately.
</Step>

<Step>
### Read the event stream [#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
</Step>

<Step>
### Filter events [#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.
</Step>

<Step>
### Inspect event details [#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.
</Step>
</Steps>

## Event type reference [#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 |
