Inspector
Inspector for debugging actions, readables, agent status, messages, and context.
What it shows#
The CopilotKit Inspector is a built-in debugging tool that overlays on your app, giving you full visibility into what's happening between your frontend and your agents in real time.
| Feature | Description |
|---|---|
| Threads | Inspect real Threads and their messages, AG-UI events, and state. |
| AG-UI Events | View the raw AG-UI event stream between your frontend and agent in real time. |
| Available Agents | See which agents are connected and available to your app. |
| Agent State | Inspect your agent's current state as it updates. |
| Frontend Tools | See what tools you've defined on the frontend and their parameter schemas. |
| Context | View the context you've provided to the agent, including readables and document context. |
| Project Context | See trusted organization, project, plan, Thread usage, expiry, and license-aware actions when the Runtime supplies them. |
Navigation and Threads#
The primary navigation groups the Inspector into Threads, Agents, and Learning. Threads is the default. Open a real Thread to inspect its Messages, AG-UI Events, and State. Metadata updates do not change the selected Thread.
When Threads has no real rows, or when Threads is locked, the Inspector keeps the overview video, three local example threads, their detail tabs, and the guided tour. The examples do not send real Thread requests. With reduced motion enabled, the video starts paused with a labelled Play control. If the media fails, fallback text appears while the examples, details, and tour stay usable.
Project context and usage#
An Intelligence-backed Runtime can supply optional trusted project metadata. Valid organization and project names and the plan label appear in the account strip. Each module is independent, so missing or invalid identity data does not hide valid usage or action data.
Trusted Thread usage and a compatible supplied action appear only in the Threads footer. They render independently: usage can appear without identity, plan, license, or action metadata, and action-only metadata does not invent usage.
| Usage state | Inspector behavior |
|---|---|
| Finite | Shows used / limit Threads and a native progress bar. An overage shows limit+ / limit Threads and caps the bar at 100%. |
| Unlimited | Shows the trusted used count with Unlimited and no progress bar. |
| Unknown limit | Shows the trusted used count with Limit unavailable, but invents no numeric limit or progress. |
| Known expiry count | Shows the count, including 0 Expiring Soon. |
| Missing or malformed expiry | Hides the expiry value without hiding valid base usage. |
Expiring Soon describes a future retention-policy threshold in the next 24
hours. It does not prove that the thread culler ran or that the Inspector locked
or deleted a Thread.
When Threads is locked, the Runtime's license state controls the copy and any action:
| License state | Inspector behavior |
|---|---|
| Active | Explains that the Runtime has no Threads endpoints and shows no locked action. |
| Not enabled | Shows Enable Intelligence only for a matching trusted action. |
| Expired | Shows Renew or Manage Your Plan only for a matching trusted action. |
| Unknown | Shows neutral unavailable copy without an action. |
A valid managed footer can show Manage Your Plan only for a matching trusted action. Managed Enterprise has no manage-plan action, and Team Self-Hosted has no hosted action; either can keep valid usage visible.
The Inspector opens the exact trusted URL supplied by the Runtime. It does not build a URL from project details and has no hard-coded signup fallback. If metadata license state conflicts with the Runtime's license status, the Runtime status controls the copy and the Inspector hides the action without hiding valid usage.
Older Runtime, Core, and Inspector versions remain compatible without a
synchronized deployment. Older V1 producers leave
usage.expiringSoonCount absent, while pre-expiry Shared and Runtime versions
ignore or remove the additive leaf from newer producers. Older Inspectors ignore
metadata they do not render; newer Inspectors feature-detect older Core and
Runtime support and use a safe missing-metadata fallback. Explicit
threadEndpoints remain the authority in every mix, and metadata never enables
Thread work.
Showing or hiding the Inspector#
By default, the Inspector appears only on localhost, 127.0.0.1, and
0.0.0.0. Set enableInspector to false to hide it on those hosts:
<CopilotKit
publicLicenseKey={process.env.NEXT_PUBLIC_COPILOTKIT_LICENSE_KEY}
enableInspector={false}
>
{children}
</CopilotKit>Set enableInspector to true to show it on another host, including in a
production build. CopilotKit always uses an explicit true or false value.