Inspector

The CopilotKit Inspector overlays your development application so you can verify the connection, investigate a run, and work with Threads and Learning without leaving the page.

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#

In a development build, click the Inspector button in the corner of your application. The first open lands on Home; later opens return to the last pane you used.

1. Open Agent and confirm that your agent is listed.
2. Send a message, then open AG-UI Events and confirm that events arrived.
3. Open Threads and confirm that saved Threads appear. If Intelligence is not connected, the locked pane offers a setup path instead.

When Intelligence is connected, Home shows an Intelligence connected chip. Otherwise, choose Copy setup prompt for your coding agent.

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.

Find the cause of a failed run#

When CopilotKit reports an error, the Inspector launcher turns red and may show a short error pill. Click either one. Inspector routes common failures to the view with the most useful evidence:

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 and reproduce a run#

Use the Inspect panes to answer a specific debugging question:

To reproduce a problem without changing the saved conversation, open a real Rich Thread and choose Try from here. Inspector copies its messages and state into Playground, where you can vary the prompt, state, or next message and run, stop, retry, and continue independently.

When Threads has no real rows, or when it is locked, Inspector keeps a local example flow and guided tour available. The examples do not send real Thread requests.

Inspect or continue a saved Thread#

Open Threads and select a row to inspect its Messages, AG-UI Events, and State.

Selecting a row does not change your live application chat. Choose View in your app to load a real saved Thread into an official CopilotKit chat for the same agent. Choose Stop viewing to restore the previous application Thread. Example Threads do not offer this action.

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

Enable or repair Intelligence#

If Intelligence is not connected, open Home and choose Copy setup prompt. The Intelligence quickstart explains the project, credentials, and Runtime routes that prompt configures. If Threads remains locked after setup, 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.

NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY is a browser-visible publishable key. It is different from the server-side CPK_INTELLIGENCE_API_KEY that copilotkit project select writes into your .env. The Runtime consumes the server-side key; never expose it to the browser.

Review what Learning found#

Open Learning to inspect new Threads ready for analysis, published Skills, their supporting Insights, and the 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 does not approve or publish candidates. If Learning is not configured, choose Copy setup prompt. See Learning for the complete workflow.

Control when Inspector appears#

Inspector appears by default in React, Vue, and Angular development builds. It is never loaded or rendered in a production build or during server-side rendering.

To disable Inspector in React:

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

Vue uses :enable-inspector="false"; Angular uses provideCopilotKit({ enableInspector: false }).

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

Pop-out keeps the same live session in a separate browser window. A temporary hide removes the overlay and launcher on the current domain until the selected period ends.

Understand project and usage information#

An Intelligence-backed Runtime can supply trusted organization, project, plan, Thread usage, retention, and action metadata. Home shows valid project context; the Threads footer shows valid usage and relevant actions.

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.

Finite plans show used / limit Threads and a progress bar. Unlimited plans show the used count without a bar. Limit unavailable means the Runtime sent a used count without a numeric limit. Expiring Soon is a retention threshold within the next 24 hours; it does not mean Inspector locked or deleted a Thread.

Older Runtime, Core, and Inspector versions remain compatible without a synchronized deployment. Explicit threadEndpoints remain authoritative, and metadata never enables Thread work.