feat(client): add granular debug mode to AG-UI event pipeline by AlemTuzlak · Pull Request #1398 · ag-ui-protocol/ag-ui

AlemTuzlak · 2026-03-31T12:20:42Z

Summary

Expand AbstractAgent.debug from boolean to accept a granular config object with events, lifecycle, and verbose flags
Add debug logging to all AG-UI client pipeline stages: SSE parsing, HTTP transform, chunk transform, event verification, event application, and agent lifecycle
When debug: true, all categories are enabled with full verbose payloads
When using object form (e.g. { events: true, lifecycle: false }), each category can be toggled independently

Changes

agent/types.ts — New ResolvedAgentDebugConfig, AgentDebugConfig types and resolveAgentDebugConfig() resolver
agent/agent.ts — debug property now ResolvedAgentDebugConfig, lifecycle logging in runAgent/catchError/finalize
agent/http.ts — Pass debug config to transformHttpEventStream
transform/sse.ts — Log received SSE events
transform/http.ts — Log stream format detection and event validation
chunks/transform.ts — Expand existing debug logging with verbose/summary branching
verify/verify.ts — Expand existing debug logging with verbose/summary branching
apply/default.ts — Log applied/dropped events with subscriber info

Test plan

All 352 existing tests pass (debug defaults to off, no behavior change)
Manual: set debug: true on an agent and verify console output at each pipeline stage

…e/verbose flags

vercel · 2026-03-31T12:20:51Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ag-ui-dojo	Ready	Preview, Comment	Apr 1, 2026 10:15am

github-actions · 2026-03-31T12:21:46Z

Python Preview Packages

Version 0.0.0.dev1775038397 published to TestPyPI.

Warning: These packages are built from contributor code that may not yet have been vetted for correctness or security. Install at your own risk and do not use in production.

Install with uv

Add the TestPyPI index to your pyproject.toml:

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = true

Then install the packages you need:

# Core SDK
uv add 'ag-ui-protocol==0.0.0.dev1775038397' --index testpypi

# Integrations (each already depends on the matching ag-ui-protocol preview)
uv add 'ag-ui-langgraph==0.0.0.dev1775038397' --index testpypi
uv add 'ag-ui-crewai==0.0.0.dev1775038397' --index testpypi
# NOTE: ag-ui-agent-spec depends on pyagentspec (git-only, not on PyPI).
# You will need to install pyagentspec separately from its git repo.
uv add 'ag-ui-agent-spec==0.0.0.dev1775038397' --index testpypi
uv add 'ag_ui_adk==0.0.0.dev1775038397' --index testpypi
uv add 'ag_ui_strands==0.0.0.dev1775038397' --index testpypi

Install with pip

pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  ag-ui-protocol==0.0.0.dev1775038397

Use --extra-index-url https://pypi.org/simple/ so pip can resolve
transitive dependencies (pydantic, fastapi, etc.) from real PyPI.

Commit: 2e614fa

Replace all scattered console.debug calls across 7 pipeline files with a centralized DebugLogger class that handles verbose vs summary output. Pipeline functions now accept DebugLogger | undefined instead of ResolvedAgentDebugConfig, and console.debug is only called from the single debug-logger.ts module.

pkg-pr-new · 2026-03-31T12:51:02Z

Open in StackBlitz

@ag-ui/a2a-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a-middleware@1398

@ag-ui/a2ui-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2ui-middleware@1398

@ag-ui/mcp-apps-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mcp-apps-middleware@1398

@ag-ui/middleware-starter

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/middleware-starter@1398

@ag-ui/a2a

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a@1398

@ag-ui/adk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/adk@1398

@ag-ui/ag2

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/ag2@1398

@ag-ui/agno

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/agno@1398

@ag-ui/aws-strands

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/aws-strands@1398

@ag-ui/claude-agent-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/claude-agent-sdk@1398

@ag-ui/crewai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/crewai@1398

@ag-ui/langchain

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langchain@1398

@ag-ui/langgraph

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langgraph@1398

@ag-ui/langroid

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langroid@1398

@ag-ui/llamaindex

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/llamaindex@1398

@ag-ui/mastra

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mastra@1398

@ag-ui/pydantic-ai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/pydantic-ai@1398

@ag-ui/server-starter

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/server-starter@1398

@ag-ui/server-starter-all-features

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/server-starter-all-features@1398

@ag-ui/vercel-ai-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/vercel-ai-sdk@1398

create-ag-ui-app

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/create-ag-ui-app@1398

@ag-ui/client

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/client@1398

@ag-ui/core

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/core@1398

@ag-ui/encoder

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/encoder@1398

@ag-ui/proto

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/proto@1398

commit: 6dddd4b

pkg-pr-new · 2026-03-31T12:51:03Z

Open in StackBlitz

@ag-ui/a2a-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a-middleware@1398

@ag-ui/a2ui-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2ui-middleware@1398

@ag-ui/mcp-apps-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mcp-apps-middleware@1398

@ag-ui/middleware-starter

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/middleware-starter@1398

@ag-ui/a2a

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a@1398

@ag-ui/adk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/adk@1398

@ag-ui/ag2

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/ag2@1398

@ag-ui/agno

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/agno@1398

@ag-ui/aws-strands

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/aws-strands@1398

@ag-ui/claude-agent-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/claude-agent-sdk@1398

@ag-ui/crewai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/crewai@1398

@ag-ui/langchain

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langchain@1398

@ag-ui/langgraph

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langgraph@1398

@ag-ui/langroid

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langroid@1398

@ag-ui/llamaindex

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/llamaindex@1398

@ag-ui/mastra

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mastra@1398

@ag-ui/pydantic-ai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/pydantic-ai@1398

@ag-ui/server-starter

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/server-starter@1398

@ag-ui/server-starter-all-features

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/server-starter-all-features@1398

@ag-ui/vercel-ai-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/vercel-ai-sdk@1398

create-ag-ui-app

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/create-ag-ui-app@1398

@ag-ui/client

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/client@1398

@ag-ui/core

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/core@1398

@ag-ui/encoder

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/encoder@1398

@ag-ui/proto

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/proto@1398

commit: 201cc16

…old test changes

marthakelly · 2026-03-31T17:39:54Z

-        if (debug) {
-          console.debug("[VERIFY]:", JSON.stringify(event));
-        }
+        log?.event("VERIFY", "", event, { type: event.type });


The label here is "" so the output comes out as "[VERIFY] " with a trailing space. Every other stage uses a descriptive label ("Event received:", "Event applied:", etc.). Probably wants to be "Event:" or similar to stay consistent.

marthakelly · 2026-03-31T17:41:48Z

-            if (this.debug) {
-              console.debug("[LEGACY]:", JSON.stringify(event));
-            }
+            this.debugLogger?.event("LEGACY", "", event, { type: (event as any).type });


LegacyRuntimeProtocolEvent should have .type typed already. Worth checking if it can come off here.

marthakelly · 2026-03-31T17:44:31Z

+
+    // Either the event is invalid and logged, or the schema was lenient.
+    // If the schema rejects it, we should see the invalid log.
+    if (errorCaught) {


If the schema parser doesn't reject the invalid event type, errorCaught stays false and the expect never runs, the test passes without asserting anything. expect.assertions(1) at the top of the test would catch that and make the intent explicit.

- Add descriptive "Event:" label to VERIFY and LEGACY log calls - Make debugLogger accept boolean for backward compatibility via getter/setter - Remove unnecessary (event as any).type cast on LegacyRuntimeProtocolEvent - Add expect.assertions(1) to ensure invalid event test always asserts

## Summary - Add `debug` option to `CopilotRuntime` constructor and `<CopilotKit>` provider for detailed event pipeline logging - Server-side uses Pino structured logger; client-side uses `console.debug` at each AG-UI pipeline stage - Accepts `true` for full output or a granular config: `{ events, lifecycle, verbose }` - The two toggles are independent — enabling debug on the client does not affect the server ## Changes **`@copilotkit/shared`** - New `DebugConfig` type, `ResolvedDebugConfig` interface, `resolveDebugConfig()` normalizer **`@copilotkit/runtime`** - `debug` option on `CopilotRuntime({ debug: true })` - Lifecycle logging: agent run started, SSE stream opened/completed/errored - Event logging: every emitted event (verbose = full payload, otherwise key fields summary) **`@copilotkit/react-core` + `@copilotkit/core`** - `debug` prop on `<CopilotKit debug={true}>` - Threads config through `CopilotKitCore` → `AgentRegistry` → `ProxiedCopilotRuntimeAgent` **Companion PR:** ag-ui-protocol/ag-ui#1398 (AG-UI client-side debug logging) ## Test plan - [x] All 647 runtime tests pass - [x] All 352 AG-UI client tests pass - [x] Lint clean (0 errors) - [x] All affected packages build successfully - [ ] Manual: set `debug: true` on runtime and provider, verify structured logs on server and console output on client 🤖 Generated with [Claude Code](https://claude.com/claude-code)

AlemTuzlak added 2 commits March 31, 2026 14:17

feat(client): expand debug config to support granular events/lifecycl…

88ae470

…e/verbose flags

feat(client): add debug logging to all AG-UI event pipeline stages

082f943

AlemTuzlak requested a review from a team as a code owner March 31, 2026 12:20

vercel Bot had a problem deploying to Preview March 31, 2026 12:22 Failure

AlemTuzlak changed the title ~~fix(core): remove unused rxjs dependency~~ fix(dojo): package consolidation changes Mar 31, 2026

AlemTuzlak changed the title ~~fix(dojo): package consolidation changes~~ feat(client): add granular debug mode to AG-UI event pipeline Mar 31, 2026

AlemTuzlak mentioned this pull request Mar 31, 2026

feat: add debug mode to runtime and client CopilotKit/CopilotKit#3562

Merged

5 tasks

AlemTuzlak and others added 2 commits March 31, 2026 14:35

Merge branch 'main' into fix/dojo-cpk-package-consolidation

4c30c3f

style: fix prettier formatting

d5ab3b9

vercel Bot had a problem deploying to Preview March 31, 2026 12:39 Failure

vercel Bot deployed to Preview March 31, 2026 12:51 View deployment

test(client): add comprehensive debug logging test suites and revert …

a96eec5

…old test changes

vercel Bot deployed to Preview March 31, 2026 13:21 View deployment

marthakelly previously approved these changes Mar 31, 2026

View reviewed changes

tylerslaton reviewed Mar 31, 2026

View reviewed changes

Comment thread sdks/typescript/packages/client/src/agent/agent.ts Outdated

tylerslaton requested changes Mar 31, 2026

View reviewed changes

AlemTuzlak dismissed marthakelly’s stale review via 6dddd4b April 1, 2026 10:13

vercel Bot deployed to Preview April 1, 2026 10:15 View deployment

tylerslaton approved these changes Apr 1, 2026

View reviewed changes

AlemTuzlak merged commit e285ede into main Apr 2, 2026
29 checks passed

AlemTuzlak deleted the fix/dojo-cpk-package-consolidation branch April 2, 2026 08:55

Navigation Menu

Uh oh!

feat(client): add granular debug mode to AG-UI event pipeline - #1398

feat(client): add granular debug mode to AG-UI event pipeline#1398
AlemTuzlak merged 7 commits into
mainfrom
fix/dojo-cpk-package-consolidation

AlemTuzlak commented Mar 31, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Mar 31, 2026

Uh oh!

marthakelly Mar 31, 2026

Uh oh!

marthakelly Mar 31, 2026

Uh oh!

marthakelly Mar 31, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

AlemTuzlak commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test plan

Uh oh!

vercel Bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Preview Packages

Install with uv

Install with pip

Uh oh!

pkg-pr-new Bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Mar 31, 2026

Uh oh!

marthakelly Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

marthakelly Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

marthakelly Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AlemTuzlak commented Mar 31, 2026 •

edited

Loading

vercel Bot commented Mar 31, 2026 •

edited

Loading

github-actions Bot commented Mar 31, 2026 •

edited

Loading

pkg-pr-new Bot commented Mar 31, 2026 •

edited

Loading