Inspector

The CopilotKit Inspector is a debugging overlay for the live connection between your frontend and agents. Use it while developing to follow a run from the application UI through the AG-UI event stream, tools, state, and saved Threads.

Reach for Inspector after a quickstart to verify that the pieces are connected, while adding tools or shared state, or when you need to reproduce an issue from a real conversation. Inspector shows what the browser received; Runtime Debug Mode adds the server-side view, and Error Debugging & Observability covers production error reporting.

Choose what you need to do#

Show Inspector and confirm your setup#

Inspector appears by default in development builds of React, Vue, and Angular browser applications. Open your application and click the Inspector button in the corner. The first open lands on Home; later opens return to the last pane you used.

Confirm the connection before debugging anything else:

1. Open Agent. Your connected agent should be listed.
2. Send a message in your application, then open AG-UI Events. You should see events arrive while the run is active.
3. Open Threads. A connected Intelligence setup shows your saved Threads. Without Intelligence, the pane is locked and offers a setup path instead.

Home summarizes project, Runtime, and service status. When Intelligence is connected, it shows an Intelligence connected chip. Otherwise, choose Copy setup prompt to give the setup task to your coding agent. If the Runtime supplies a trusted setup URL, you can also choose Set it up yourself.

If the agent is missing or no events arrive, first confirm the Copilot Runtime connection. If Threads is the only missing piece, follow the Intelligence quickstart instead of changing the agent connection.

Find the cause of a failed run#

When CopilotKit reports an error, the Inspector launcher turns red. When there is room, an error pill briefly names the failure. Click either one to open the pane with the most useful evidence:

A RUN_ERROR is highlighted and expanded while it remains in the event buffer. A tool call is highlighted when the error includes its call id; a missing tool has no call to highlight.

Learning data is fetched the first time you open Learning, so a Learning load error can only be routed there after that first visit.

Inspector is best for locating the failing layer during development. If the event stream stops before it reaches the browser, enable Runtime Debug Mode to inspect the server-side pipeline. Use onError on CopilotKit or CopilotChat when the application UI or your production observability system should also receive the error. See Error Debugging & Observability for that setup.

Follow a run from input to result#

Send a message in your application, then use these views to answer the next debugging question:

In an official React CopilotChat, open an assistant message's toolbar and choose View in Inspector to jump directly to that message in its Thread. This local development shortcut is useful when you already know which response you need to explain. See the CopilotChat reference for its configuration.

Frontend Tools appears only after your application registers a frontend tool. Capabilities appears only when an A2UI catalog is present; use it to toggle tools and catalog components while experimenting.

On narrow windows, or when Inspector is docked left, the sidebar collapses to icons. Talk to an Engineer remains in the sidebar footer.

Reproduce an issue without changing the saved Thread#

Use Playground when you have already observed a problem and want to vary the prompt, state, or next message without touching the original Rich Thread. Its messages and state stay separate from your application chat and stored Threads, so you can run, stop, retry, and continue an experiment safely.

To reproduce a problem from a real conversation:

1. Open Threads and select the saved Thread.
2. Choose Try from here.
3. Continue the copied conversation in Playground.

Inspector copies the Thread's messages and state but leaves the original untouched. If the copy fails, neither the saved Thread nor the existing Playground session changes.

When Threads has no real rows, or when it is locked, Inspector shows an overview video, three local example Threads, their detail tabs, and a guided tour. These examples do not send real Thread requests. With reduced motion enabled, the video starts paused. If the video fails, the examples and tour still work.

Continue a saved Thread in your application#

Selecting a Thread in Inspector does not change the live chat. To continue the conversation in an official CopilotChat, sidebar, or popup:

1. Open a real saved Thread.
2. Choose View in your app in its detail header.
3. Send messages in the application chat on that Thread.
4. Choose Stop viewing to restore the previous application Thread.

The Thread list marks the conversation currently open in the application. If you select another Thread in the application, the Inspector override ends. Example Threads do not offer this action.

If no official chat for the agent is present, Inspector shows an error. The action addresses the chat by agentId, regardless of the backend framework.

A custom chat can use the bridge exported by @copilotkit/core. Return true from onInspectorViewThread only when the chat accepts the request, and include the same requestId in every lifecycle event:

• onInspectorViewThread receives { requestId, threadId, agentId }
• onInspectorStopViewing receives { requestId, agentId }
• emitInspectorActiveThread sends { requestId, threadId, agentId, source }
• emitInspectorViewThreadResult sends { requestId, threadId, agentId, ok }

If you are building the Thread picker and conversation surface yourself, see Headless Threads for the persistence and lifecycle APIs.

Enable or repair Intelligence#

Intelligence unlocks real Threads and Learning. When it is not connected, open Home and choose Copy setup prompt. Give that prompt to your coding agent, then return to Inspector to follow setup through the first eligible Thread. The Intelligence quickstart explains the project, credentials, and Runtime routes that prompt configures.

If Threads remains locked, Inspector shows one Rich Threads setup view with Copy setup prompt and Talk to an Engineer. The view is based on Runtime Threads capability rather than license metadata. To configure incomplete routes, use the Runtime route guide. Enable Rich Threads routes explains how to configure application-user identity, mount every required HTTP method, and verify the capability response.

Review what Learning found#

Open Learning to trace completed Threads into evidence-backed Insights and reviewed Skills. A configured pane shows:

• new Threads ready for analysis;
• published Skills and their SKILL.md content;
• the Insights supporting each Skill; and
• the source Thread evidence behind each pattern.

Select evidence to open the matching Thread and message. Use Open in web app to run an analysis or review pending Skill candidates. Inspector lets you inspect the evidence, but does not approve or publish a candidate.

If Learning is not configured, choose Copy setup prompt. If the Runtime cannot select one Learning container for the active agent, Inspector sends you to the web app to choose it. See Learning for the complete workflow.

Control when Inspector appears#

Use the option that matches what you are trying to do:

Pop-out opens the same live Inspector session in a separate browser window and hides the overlay and floating button on the application page. Close the extra window to return Inspector to its previous floating or docked position. If no window opens, allow popups and try again. Refreshing closes the extra window; Inspector does not restore pop-out mode after a refresh.

A temporary hide removes the overlay and launcher only on the current domain. They return automatically after the selected period.

To disable Inspector in a React development build:

<CopilotKit
  publicLicenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
  enableInspector={false}
>
  {children}
</CopilotKit>

Vue uses the template prop :enable-inspector="false". Angular uses provideCopilotKit({ enableInspector: false }). An explicit true keeps Inspector enabled in development but cannot override production or server-rendering guards. Legacy showDevConsole props no longer control it.

See the CopilotKit provider reference for the complete React provider API.

Inspector is never loaded or rendered in a production build or during server-side rendering.

Understand project and usage information#

An Intelligence-backed Runtime can send trusted organization, project, plan, Thread usage, retention, and action metadata. Home shows valid project context; the Threads footer shows valid usage and relevant actions. Missing identity data does not hide valid usage, and missing usage does not hide a valid action.

Inspector opens only action URLs supplied by the Runtime. It never constructs a project URL or uses a fixed signup fallback. If metadata and Runtime license states conflict, Runtime status wins and Inspector hides the incompatible action.

Expiring Soon means a Thread is within a retention threshold in the next 24 hours. It does not mean Inspector locked or deleted that Thread.

Older Runtime, Core, and Inspector versions remain compatible without a synchronized deployment. Newer components feature-detect optional metadata; older components ignore fields they do not understand. Explicit threadEndpoints remain authoritative, and metadata never enables Thread work.

Where Inspector runs#

Inspector is a browser overlay: it mounts a custom element into the page's DOM. It runs on React, Next.js, React SPA, Vue, and Angular.

There is no React Native build of Inspector, and @copilotkit/react-native does not ship it. Channels such as Slack and Teams do not have a browser surface either.

Use these alternatives for React Native:

Inspector telemetry has its own browser identity and direct delivery path. It works whether or not the Runtime has CPK_TELEMETRY_ID and follows the existing telemetry opt-outs.