CopilotKit Debugging Skill

When to Use

Invoke this skill when:

• The CopilotKit runtime is unreachable or returning errors
• Agents fail to connect, respond, or stream events
• Frontend tools are not executing or returning results
• Transcription (voice) is failing
• Version mismatch errors appear between packages
• AG-UI SSE events are malformed or missing
• CORS errors block browser requests to the runtime

Diagnostic Workflow

Step 1: Gather Information

Before proposing any fix, collect:

1. Package versions -- Run npm ls @copilotkit/runtime @copilotkit/react-core @copilotkit/core @ag-ui/client (or the v1 equivalents). Version mismatches between runtime and React packages are a common root cause.
2. Runtime mode -- Is this SSE mode (CopilotSseRuntime) or Intelligence mode (CopilotIntelligenceRuntime)? Check the runtime constructor.
3. Transport configuration -- What is runtimeUrl set to on the CopilotKit provider (from @copilotkit/react-core/v2)? Does it match the basePath in createCopilotRuntimeHandler?
4. Agent type -- Is the agent a BuiltInAgent, LangGraphAgent, A2AAgent, or custom AbstractAgent?
5. Error messages --…