Skip to content

Commit 699f931

Browse files
copilotkit-devops-bot[bot]copilotkit-devops-bot[bot]
authored
chore: auto-sync docs from main (a009507) (CopilotKit#3931)
Automated docs sync. Clean transforms only.
2 parents a009507 + 068521d commit 699f931

3 files changed

Lines changed: 156 additions & 1 deletion

File tree

‎showcase/shell/.docs-sync-sha‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
db542c59d85faf8b34f53be6deb99df3b8ce8e51
1+
a0095078737a1657c5aec4847fc7ce8243c61905

‎showcase/shell/src/content/docs/troubleshooting/debug-mode.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Debug Mode"
3+
description: "Enable debug mode to get detailed logging of the AG-UI event pipeline on both the server and client."
4+
icon: "lucide/Bug"
5+
---
6+
<DebugMode />

‎showcase/shell/src/content/snippets/shared/troubleshooting/debug-mode.mdx‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Debug Mode
2+
3+
When your agent isn't behaving as expected — events are missing, state isn't updating, or tool calls aren't executing — you need visibility into what's happening in the event pipeline. Debug mode gives you that visibility with detailed logging on both the server (runtime) and client (React) side.
4+
5+
Enable it to see:
6+
- What events your agent is emitting and whether they reach the client
7+
- Where in the pipeline events are being dropped or failing validation
8+
- The full lifecycle of a request from start to finish
9+
10+
<Callout type="info">
11+
For visual error display during local development (error banners, dev console), see [Error Debugging](/troubleshooting/error-debugging). Debug mode focuses on event pipeline logging rather than UI-level error display.
12+
</Callout>
13+
14+
## Enabling Debug Mode
15+
16+
### Server-Side (Runtime)
17+
18+
Pass `debug: true` to the `CopilotRuntime` constructor:
19+
20+
```ts title="app/api/copilotkit/route.ts"
21+
const runtime = new CopilotRuntime({
22+
agents: {
23+
// your agents
24+
},
25+
debug: true, // [!code highlight]
26+
});
27+
```
28+
29+
This produces structured Pino logs (formatted by `pino-pretty`) with a `copilotkit-debug` component label:
30+
31+
```
32+
[14:32:01.123] DEBUG (copilotkit-debug): Agent run started
33+
agentName: "default"
34+
threadId: "abc-123"
35+
[14:32:01.130] DEBUG (copilotkit-debug): SSE stream opened
36+
[14:32:01.145] DEBUG (copilotkit-debug): Event emitted
37+
type: "TEXT_MESSAGE_START"
38+
messageId: "msg-1"
39+
role: "assistant"
40+
[14:32:01.200] DEBUG (copilotkit-debug): Event emitted
41+
type: "TEXT_MESSAGE_CONTENT"
42+
deltaLength: 42
43+
[14:32:01.250] DEBUG (copilotkit-debug): Event emitted
44+
type: "TEXT_MESSAGE_END"
45+
[14:32:01.260] DEBUG (copilotkit-debug): Event emitted
46+
type: "RUN_FINISHED"
47+
[14:32:01.261] DEBUG (copilotkit-debug): SSE stream completed
48+
eventCount: 4
49+
loggedEventCount: 4
50+
```
51+
52+
### Client-Side (React)
53+
54+
Pass `debug={true}` to the `<CopilotKit>` provider:
55+
56+
```tsx
57+
<CopilotKit
58+
runtimeUrl="/api/copilotkit"
59+
debug={true} // [!code highlight]
60+
>
61+
<YourApp />
62+
</CopilotKit>
63+
```
64+
65+
This forwards the debug configuration to the AG-UI client transport layer (`transformChunks`), which may produce transport-level debug output depending on the AG-UI library version. Note that the richest debug logging comes from the **server-side** `CopilotRuntime` — enable `debug: true` there for full structured Pino logs of every AG-UI event.
66+
67+
<Callout type="info">
68+
The server and client debug toggles are independent. Enabling debug on the client does not affect the server, and vice versa.
69+
</Callout>
70+
71+
## Granular Configuration
72+
73+
Instead of `true`, you can pass an object for fine-grained control over what gets logged:
74+
75+
```ts
76+
debug: {
77+
events: true, // Log every event emitted/received
78+
lifecycle: true, // Log request/run lifecycle (start, finish, error)
79+
verbose: false, // Log full payloads instead of summaries
80+
}
81+
```
82+
83+
This works the same way on both the server and client.
84+
85+
### Defaults
86+
87+
| Input | `events` | `lifecycle` | `verbose` |
88+
|-------|----------|-------------|-----------|
89+
| `debug: true` | `true` | `true` | `false` |
90+
| `debug: {}` | `true` | `true` | `false` |
91+
| `debug: { events: false }` | `false` | `true` | `false` |
92+
93+
When `debug` is a boolean (`true`), events and lifecycle logging are enabled but verbose mode is **off** by default (to avoid leaking PII in logs). To get full event payloads, explicitly opt in with `debug: { verbose: true }`.
94+
95+
### Examples
96+
97+
Log only lifecycle events (no per-event logs):
98+
99+
```ts
100+
debug: { events: false, lifecycle: true }
101+
```
102+
103+
Log events with full payloads but skip lifecycle:
104+
105+
```ts
106+
debug: { events: true, lifecycle: false, verbose: true }
107+
```
108+
109+
## Troubleshooting with Debug Mode
110+
111+
### Events Not Reaching the Client
112+
113+
Enable debug on the server side for the most detailed visibility:
114+
1. Check server logs for `Event emitted` — are the expected events being sent?
115+
2. Verify `SSE stream completed` shows the expected `eventCount`.
116+
3. Use the browser Network tab to confirm SSE events are arriving over the wire.
117+
118+
### Tool Calls Not Executing
119+
120+
Enable server-side debug and look for:
121+
1. `TOOL_CALL_START` events being emitted on the server
122+
2. `TOOL_CALL_ARGS` and `TOOL_CALL_END` events following correctly
123+
3. Confirm the events appear in the SSE stream via the browser Network tab
124+
125+
### State Not Updating
126+
127+
Look for `STATE_SNAPSHOT` or `STATE_DELTA` events in server logs. If they appear on the server but not in the browser's SSE stream, there may be a connection issue.
128+
129+
## What Gets Logged
130+
131+
### Server-Side Logs
132+
133+
| Category | Log Message | Description |
134+
|----------|-------------|-------------|
135+
| Lifecycle | `Agent run started` | An agent run was initiated, includes agent name and thread ID |
136+
| Lifecycle | `SSE stream opened` | The SSE response stream was created |
137+
| Lifecycle | `SSE stream completed` | The stream finished, includes total event count |
138+
| Lifecycle | `SSE stream errored` | The stream encountered an error |
139+
| Events | `Event emitted` | Each AG-UI event as it's written to the stream |
140+
141+
In **summary mode** (verbose off), event logs include key identifiers like `messageId`, `toolCallId`, `toolCallName`, `role`, and content lengths instead of full payloads.
142+
143+
### Client-Side
144+
145+
On the client, the `debug` configuration is passed through to the AG-UI transport layer. The AG-UI client library controls what (if any) debug output is produced. CopilotKit itself does not emit `console.debug` calls — the debug flag configures the underlying AG-UI event pipeline.
146+
147+
<Callout type="warn">
148+
Debug mode can produce a large volume of log output, especially in verbose mode. Use it during development and debugging, not in production.
149+
</Callout>

0 commit comments

Comments
 (0)