--- name: ag-ui-copilotkit description: Build agentic UIs using AG-UI protocol with Pydantic AI (Python backend) and CopilotKit (React/Next.js frontend). Use when creating AI-powered applications that need bidirectional agent-UI communication, shared state between frontend and backend, human-in-the-loop workflows, tool-based generative UI, or predictive state updates. Triggers on requests involving CopilotKit hooks (useCoAgent, useCopilotAction, useCoAgentStateRender), pydantic_ai with ag_ui adapters, or building chat interfaces with backend AI agents. --- # AG-UI + CopilotKit Development Build agentic UIs with bidirectional communication between AI agents and React frontends. ## Architecture Overview ``` ┌─────────────────────┐ AG-UI Protocol ┌─────────────────────┐ │ Next.js Frontend │ ◄──────────────────────►│ FastAPI Backend │ │ (CopilotKit) │ SSE Event Stream │ (Pydantic AI) │ │ │ │ │ │ • useCoAgent │ Events: │ • Agent + tools │ │ • useCopilotAction │ - TextMessageStart │ • to_ag_ui() │ │ • useCopilotReadable│ - ToolCallStart │ • StateDeps │ │ • useCoAgentState │ - StateSnapshot │ • StateSnapshot │ │ Render │ - StateDelta │ • StateDelta │ └─────────────────────┘ └─────────────────────┘ ``` ## Quick Start ### Backend (Python with Pydantic AI) ```python from pydantic_ai import Agent from ag_ui.core import EventType, StateSnapshotEvent agent = Agent('openai:gpt-4o-mini') app = agent.to_ag_ui() # Creates FastAPI app @agent.tool_plain async def my_tool(param: str) -> StateSnapshotEvent: return StateSnapshotEvent( type=EventType.STATE_SNAPSHOT, snapshot={"result": param} ) ``` ### Frontend (React with CopilotKit) ```tsx // layout.tsx - Wrap app with CopilotKit {children} // page.tsx - Use hooks const { state, setState } = useCoAgent({ name: "myAgent", initialState: { /* ... */ } }); useCopilotAction({ name: "my_action", parameters: [{ name: "param", type: "string" }], renderAndWaitForResponse: ({ args, respond, status }) => ( respond("accepted")} /> ) }); ``` ## Core Patterns ### 1. Shared State Backend sends state updates; frontend renders and can modify. **Backend:** Return `StateSnapshotEvent` or `StateDeltaEvent` from tools **Frontend:** Use `useCoAgent` to receive and manage state ### 2. Human-in-the-Loop Agent proposes actions; user approves/rejects via UI. **Backend:** Define tools that the frontend will render **Frontend:** Use `useCopilotAction` with `renderAndWaitForResponse` ### 3. Tool-Based Generative UI Agent calls tools; frontend renders custom components for tool output. **Backend:** Tools return structured data **Frontend:** `useCopilotAction` renders components based on tool parameters ### 4. Predictive State Updates Stream partial state while agent is processing. **Backend:** Return `CustomEvent` with `PredictState` configuration **Frontend:** UI updates optimistically as agent generates ## Detailed References - **Backend patterns**: See [references/backend-pydantic-ai.md](references/backend-pydantic-ai.md) - **Frontend patterns**: See [references/frontend-copilotkit.md](references/frontend-copilotkit.md) - **State management**: See [references/state-patterns.md](references/state-patterns.md) ## Common Pitfalls 1. **Missing CORS**: Backend must allow frontend origin 2. **State sync**: Always use `useCoAgent` name matching backend agent name 3. **Tool names**: Must match between `useCopilotAction` and backend tools 4. **SSE handling**: CopilotKit runtime must proxy to backend correctly ## See also (related skills — AG-UI family) If your issue relates to: - **AG-UI protocol with Pydantic AI (Python backend)** — check `ag-ui-pydantic` if appropriate.