{/* [!code highlight:8] */} {agent.isRunning ? (

Agent is processing...

) : ( Ready )}

); } ``` ### Run the agent Use `copilotkit.runAgent()` to trigger your agent programmatically: ```tsx title="page.tsx" import { useAgent } from "@copilotkit/react-core/v2"; import { useCopilotKit } from "@copilotkit/react-core/v2"; import { randomUUID } from "@copilotkit/shared"; export function RunAgent() { const { agent } = useAgent(); // [!code highlight:1] const { copilotkit } = useCopilotKit(); const handleRun = async () => { agent.addMessage({ id: randomUUID(), role: "user", content: "Hello, agent!", }); // [!code highlight:1] await copilotkit.runAgent({ agent }); }; return ; } ``` `copilotkit.runAgent()` orchestrates the full agent lifecycle — executing frontend tools, handling follow-up runs, and streaming results. This is the same method `` uses internally. ## Working with State Agents expose their state through the `agent.state` property. This state is shared between your application and the agent - both can read and modify it. ### Reading State Access your agent's current state: ```tsx title="page.tsx" export function StateDisplay() { const { agent } = useAgent(); return (

Agent State

{/* [!code highlight:1] */}

{JSON.stringify(agent.state, null, 2)}

{/* Access specific properties */} {/* [!code highlight:2] */} {agent.state.user_name &&

User: {agent.state.user_name}

} {agent.state.preferences && (

Preferences: {JSON.stringify(agent.state.preferences)}

)}

); } ``` Your component automatically re-renders when the agent's state changes. ### Updating State Update state that your agent can access: ```tsx title="page.tsx" export function ThemeSelector() { const { agent } = useAgent(); const updateTheme = (theme: string) => { // [!code highlight:4] agent.setState({ ...agent.state, user_theme: theme, }); }; return (

{/* [!code highlight:2] */}

Current: {agent.state.user_theme || "default"}

); } ``` State updates are immediately available to your agent in its next execution. ## Subscribing to Agent Events You can subscribe to agent events using the `subscribe()` method. This is useful for logging, monitoring, or responding to specific agent behaviors. ### Basic Event Subscription ```tsx title="page.tsx" import { useEffect } from "react"; import { useAgent } from "@copilotkit/react-core/v2"; import type { AgentSubscriber } from "@ag-ui/client"; export function EventLogger() { const { agent } = useAgent(); useEffect(() => { // [!code highlight:15] const subscriber: AgentSubscriber = { onCustomEvent: ({ event }) => { console.log("Custom event:", event.name, event.value); }, onRunStartedEvent: () => { console.log("Agent started running"); }, onRunFinalized: () => { console.log("Agent finished running"); }, onStateChanged: (state) => { console.log("State changed:", state); }, }; // [!code highlight:2] const { unsubscribe } = agent.subscribe(subscriber); return () => unsubscribe(); }, [agent]); return null; } ``` ### Available Events The `AgentSubscriber` interface provides: - **`onCustomEvent`** - Custom events emitted by the agent - **`onRunStartedEvent`** - Agent starts executing - **`onRunFinalized`** - Agent completes execution - **`onStateChanged`** - Agent's state changes - **`onMessagesChanged`** - Messages are added or modified ## Rendering Tool Calls You can customize how agent tool calls are displayed in your UI. First, define your tool renderers: ```tsx title="components/weather-tool.tsx" import { defineToolCallRenderer } from "@copilotkit/react-core/v2"; // [!code highlight:6] export const weatherToolRender = defineToolCallRenderer({ name: "get_weather", render: ({ args, status }) => { return ; }, }); function WeatherCard({ location, status, }: { location?: string; status: string; }) { return (

Weather in {location}

70°F

{status === "executing" &&

}

); } ``` Register your tool renderers with CopilotKit: ```tsx title="layout.tsx" import { CopilotKit } from "@copilotkit/react-core/v2"; import { weatherToolRender } from "./components/weather-tool"; export default function RootLayout({ children }) { return ( {children} ); } ``` Then use `useRenderToolCall` to render tool calls from agent messages: ```tsx title="components/message-list.tsx" import { useAgent, useRenderToolCall } from "@copilotkit/react-core/v2"; export function MessageList() { const { agent } = useAgent(); const renderToolCall = useRenderToolCall(); return (

{agent.messages.map((message) => (

{/* Display message content */} {message.content &&

{message.content}

} {/* Render tool calls if present */} {/* [!code highlight:9] */} {message.role === "assistant" && message.toolCalls?.map((toolCall) => { const toolMessage = agent.messages.find( (m) => m.role === "tool" && m.toolCallId === toolCall.id, ); return (

{renderToolCall({ toolCall, toolMessage })}

); })}

))}

); } ``` ## Building a Complete Dashboard Here's a full example combining all concepts into an interactive agent dashboard: ```tsx title="page.tsx" "use client"; import { useAgent } from "@copilotkit/react-core/v2"; export default function AgentDashboard() { const { agent } = useAgent(); return (

{/* Status */}

Agent Status

{/* [!code highlight:6] */}

{agent.isRunning ? "Running" : "Idle"}

Thread: {agent.threadId}

Messages: {agent.messages.length}

{/* State */}

Agent State

{/* [!code highlight:3] */}

          {JSON.stringify(agent.state, null, 2)}

{/* Messages */}

Conversation

{/* [!code highlight:11] */} {agent.messages.map((msg) => (

{msg.role === "user" ? "You" : "Agent"}

{msg.content}

))}

); } ``` ## Running the Agent Programmatically Use `copilotkit.runAgent()` to trigger your agent from any component — no chat UI required. This is the same method CopilotKit's built-in `` uses internally. ```tsx title="page.tsx" import { useAgent } from "@copilotkit/react-core/v2"; import { useCopilotKit } from "@copilotkit/react-core/v2"; import { randomUUID } from "@copilotkit/shared"; export function AgentTrigger() { const { agent } = useAgent(); // [!code highlight:1] const { copilotkit } = useCopilotKit(); const handleRun = async () => { // Add a user message to the agent's conversation agent.addMessage({ id: randomUUID(), role: "user", content: "Summarize the latest sales data", }); // [!code highlight:2] // Run the agent — handles tool execution, follow-ups, and streaming await copilotkit.runAgent({ agent }); }; return ; } ``` ### `copilotkit.runAgent()` vs `agent.runAgent()` Both methods trigger the agent, but they operate at different levels: - **`copilotkit.runAgent({ agent })`** — The recommended approach. Orchestrates the full agent lifecycle: executes frontend tools, handles follow-up runs when tools request them, and manages errors through the subscriber system. - **`agent.runAgent()`** — Low-level method on the agent instance. Sends the request to the runtime but does **not** execute frontend tools or handle follow-ups. Use this only when you need direct control over the agent execution (e.g., resuming from an interrupt with `forwardedProps`). ### Stopping a Run You can stop a running agent using `copilotkit.stopAgent()`: ```tsx title="page.tsx" const handleStop = () => { copilotkit.stopAgent({ agent }); }; ``` --- ## Source: https://docs.showcase.copilotkit.ai/ag2/quickstart # Quickstart > Turn your AG2 Agents into an agent-native application in 5 minutes. ## Introduction This quickstart guide shows how to build a **Weather Agent** using AG2 and CopilotKit. In just minutes, you'll have a working application where users can ask for real-time weather conditions in any city worldwide — powered by AG2's `AGUIStream` over the AG-UI protocol and rendered with CopilotKit's chat UI. CopilotKit consumes AG-UI protocol events streamed by AG2 over /chat. See the AG2 AG-UI integration docs. ## AG2 Bootstrap Template If you prefer a generated starter instead of cloning the repo, use the CopilotKit bootstrap template and select **AG2** during setup. This wires up an AG2 backend over AG-UI and a ready-to-run frontend. ```bash npx copilotkit@latest init ``` Follow the prompts to pick AG2 and the features you want, then run the install/start commands it prints. ## Prerequisites Before you begin, you'll need the following: - **Python 3.10–3.13** for running the AG2 backend - uv (for Python dependency management) - Node.js 18.18.0 or newer (specifically: ^18.18.0 || ^19.8.0 || >= 20.0.0) - pnpm (for frontend package management) - OpenAI API key ## Getting started ### Create a free account Sign up for a free developer account on our Enterprise Intelligence Platform to get a license key. You'll use it later to enable persistent threads and the inspector. ### Clone the AG2 Samples Repository ```bash git clone https://github.com/ag2ai/ag2-samples.git cd ag2-samples ``` ### Set Up the AG2 Backend #### Install the dependencies: ```bash uv sync ``` #### Set your `OPENAI_API_KEY`: ```sh export OPENAI_API_KEY="your_openai_api_key" ``` #### Launch the AG2 weather agent: ```bash uv run python weather.py ``` The backend server will start at http://localhost:8000 and serve the agent at `/weather`. ### Set Up the CopilotKit UI The last step is to use CopilotKit's UI components to render the chat interaction with your agent. In a new terminal: ```bash cd ui pnpm install pnpm dev ``` The frontend application will start at http://localhost:3000. ### 🎉 Talk to your agent! Congrats! You've successfully integrated an AG2 Agent chatbot into your application. Try asking a few questions: ``` What's the weather in London? ``` ``` Weather in Tokyo ``` ``` What's the weather here? ``` Asking "What's the weather here?" will use your browser's location if you allow it. If location access is denied, the agent will ask you for a city name instead. --- ## What's next? You've now got a Weather Agent running with CopilotKit! This demonstrates how quickly you can build practical AI applications by combining AG2's `AGUIStream` with CopilotKit's user interface components. } />

Connection	Protocol	Purpose
Agent ↔ User Interaction	AG-UI (Agent–User Interaction Protocol)	The open, event-based standard that connects agents to user-facing applications — enabling real-time, multimodal, interactive experiences.
Agent ↔ Tools & Data	MCP (Model Context Protocol)	Open standard that lets agents securely connect to external systems — tools, workflows, and data sources.
Agent ↔ Agent	A2A (Agent to Agent)	Defines how agents coordinate and share work across distributed agentic systems.
Agent ↔ Generative UI	[A2UI](/generative-ui/a2ui) (Google) [MCP Apps](/generative-ui/mcp-apps) (MCP Ecosystem) Open-JSON-UI (OpenAI)	Declarative, LLM-friendly [generative UI specs](/generative-ui) that define what to render and how to structure agent responses visually. CopilotKit fully supports all of these.

} > } > ### Run the CLI Just run this following command in your Next.js application to get started! No problem! Just use `create-next-app` to make one quickly. ```bash npx create-next-app@latest ``` ```bash npx copilotkit@latest init -m MCP ``` } > #### Set up the CopilotKit Provider Wrap your application with the `CopilotKit` provider: ```tsx "use client"; import { CopilotKit } from "@copilotkit/react-core/v2"; export default function App() { return ( {/* Your app content */} ); } ``` #### Connect to MCP Servers Create a component to manage MCP server connections: ```tsx "use client"; import { useEffect } from "react"; import { useCopilotKit } from "@copilotkit/react-core/v2"; function McpServerManager() { const { setMcpServers } = useCopilotKit(); useEffect(() => { setMcpServers([ { // Try a sample MCP server at https://mcp.composio.dev/ endpoint: "your_mcp_sse_url", }, ]); }, [setMcpServers]); return null; } export default McpServerManager; ``` #### Add the Chat Interface Add the `CopilotChat` component to your page: ```tsx "use client"; import { CopilotChat } from "@copilotkit/react-core/v2"; export default function ChatInterface() { return (

); } ``` #### Visualize MCP Tool Calls (Optional) Create a component to display MCP tool calls in your UI: ```tsx "use client"; import { useFrontendTool, CatchAllActionRenderProps, } from "@copilotkit/react-core/v2"; export function ToolRenderer() { useFrontendTool({ /** * The asterisk (*) matches all tool calls */ name: "*", render: ({ name, status, args, result }: CatchAllActionRenderProps<[]>) => ( ), }); return null; } ``` #### Complete Implementation Combine all components together: ```tsx "use client"; import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2"; export default function Page() { return (

); } ``` ## Advanced Usage ### Implementing the McpToolCall Component

Click to see the McpToolCall component implementation

```tsx "use client"; interface ToolCallProps { status: "complete" | "inProgress" | "executing"; name?: string; args?: any; result?: any; } export default function MCPToolCall({ status, name = "", args, result, }: ToolCallProps) { const [isOpen, setIsOpen] = React.useState(false); // Format content for display const format = (content: any): string => { if (!content) return ""; const text = typeof content === "object" ? JSON.stringify(content, null, 2) : String(content); return text .replace(/\\n/g, "\n") .replace(/\\t/g, "\t") .replace(/\\"/g, '"') .replace(/\\\\/g, "\\"); }; return (

setIsOpen(!isOpen)} > {name || "MCP Tool Call"}

{isOpen && (

{args && (

Parameters:

                {format(args)}

)} {status === "complete" && result && (

Result:

                {format(result)}

)}

); } ```

### Self-Hosting Option

Click here to learn how to use MCP with self-hosted runtime

The Copilot Runtime handles communication with LLMs, message history, and state. You can self-host it or use{" "} Copilot Cloud{" "} (recommended). Learn more in our [Self-Hosting Guide](/backend/copilot-runtime). To configure your self-hosted runtime with MCP servers, you'll need to implement the `createMCPClient` function that matches this interface: ```typescript type CreateMCPClientFunction = ( config: MCPEndpointConfig, ) => Promise; ``` For detailed implementation guidance, refer to the [official MCP SDK documentation](https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#writing-mcp-clients). Here's a basic example of configuring the runtime: ```tsx import { CopilotRuntime, OpenAIAdapter, copilotRuntimeNextJSAppRouterEndpoint, } from "@copilotkit/runtime"; import { NextRequest } from "next/server"; const serviceAdapter = new OpenAIAdapter(); const runtime = new CopilotRuntime({ createMCPClient: async (config) => { // Implement your MCP client creation logic here // See the MCP SDK docs for implementation details }, }); export const POST = async (req: NextRequest) => { const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({ runtime, serviceAdapter, endpoint: "/api/copilotkit", }); return handleRequest(req); }; ```

--- ## Source: https://docs.showcase.copilotkit.ai/agno # Introduction > Bring your Agno agents to your users with CopilotKit via AG-UI. } header="Bring your Agno agents to your users" subheader="Give your Agno agents real user-interactivity using CopilotKit and AG-UI. Build rich, interactive, agent-powered applications." bannerVideo="https://cdn.copilotkit.ai/docs/copilotkit/videos/coagents/overview.mp4" guideLink="/agno/quickstart" initCommand="npx copilotkit@latest init" featuresLink="https://feature-viewer.copilotkit.ai/agno/feature/agentic_chat" supportedFeatures={[ { title: "Generative UI", description: "Render your agent's state, progress, outputs, and tool calls with custom UI components in real-time. Bridges the gap between AI agents and user interfaces.", documentationLink: "/agno/generative-ui", demoLink: "https://feature-viewer.copilotkit.ai/agno/feature/tool_based_generative_ui", videoUrl: "https://cdn.copilotkit.ai/docs/copilotkit/videos/coagents/haiku.mp4" }, { title: "Human in the Loop", description: "Empower users to guide agents at key checkpoints. Combine the best of AI and human judgment for more reliable and controllable agent behavior.", documentationLink: "/agno/human-in-the-loop", demoLink: "https://examples-coagents-ai-travel-app.vercel.app/", videoUrl: "https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/human-in-the-loop-example.mp4" }, ]} architectureImage="https://cdn.copilotkit.ai/docs/copilotkit/images/generic-agui-architecture.png" liveDemos={[ { type: "saas", title: "SaaS Copilot", description: "A traditional SaaS application enhanced with AI agents. These copilots integrate seamlessly into existing workflows, providing intelligent assistance for specific business processes. Perfect for customer service, sales automation, project management, and domain-specific tasks where users need guided, step-by-step AI assistance.", iframeUrl: "https://examples-coagents-ai-travel-app.vercel.app?copilotOpen=true" }, { type: "canvas", title: "Canvas Copilot", description: "An infinite canvas interface where users collaborate with AI agents in a spatial, visual environment. These copilots excel at research, brainstorming, content creation, and complex problem-solving where information needs to be organized, connected, and explored in a non-linear, creative way.", iframeUrl: "https://examples-coagents-research-canvas-ui.vercel.app/" } ]} /> --- ## Source: https://docs.showcase.copilotkit.ai/agno/ag-ui # AG-UI > The AG-UI protocol connects your frontend to your Agno agents via event-based Server-Sent Events (SSE). CopilotKit is built on the [AG-UI protocol](https://ag-ui.com), a lightweight, event-based standard that defines how AI agents communicate with user-facing applications over Server-Sent Events (SSE). Messages, state updates, tool calls, and agent lifecycle events all flow through AG-UI. Understanding this layer helps you debug and extend any CopilotKit integration. ## Accessing your agent with `useAgent` `useAgent` returns the AG-UI `AbstractAgent` behind your copilot: ```tsx import { useAgent } from "@copilotkit/react-core/v2"; function AgentStatus() { const { agent } = useAgent({ agentId: "research-agent" }); // agent.messages — conversation history // agent.state — current shared state // agent.isRunning — whether the agent is running } ``` The resolved agent is a standard AG-UI `AbstractAgent`. You can read its state, invoke protocol methods, and subscribe to its event stream. ### Subscribing to AG-UI events Subscribe in an effect and unsubscribe when the component unmounts: ```tsx import { useEffect } from "react"; import { useAgent } from "@copilotkit/react-core/v2"; function EventLog() { const { agent } = useAgent({ agentId: "research-agent" }); useEffect(() => { const subscription = agent.subscribe({ onTextMessageContentEvent({ textMessageBuffer }) { console.log("Streaming text:", textMessageBuffer); }, onToolCallEndEvent({ toolCallName, toolCallArgs }) { console.log("Tool called:", toolCallName, toolCallArgs); }, onStateChanged({ agent }) { console.log("State changed:", agent.state); }, }); return () => subscription.unsubscribe(); }, [agent]); } ``` The callback names map directly to the [AG-UI event types](https://docs.ag-ui.com/concepts/events): | Event | Callback | | --- | --- | | Run lifecycle | `onRunStartedEvent`, `onRunFinishedEvent`, `onRunErrorEvent` | | Steps | `onStepStartedEvent`, `onStepFinishedEvent` | | Text messages | `onTextMessageStartEvent`, `onTextMessageContentEvent`, `onTextMessageEndEvent` | | Tool calls | `onToolCallStartEvent`, `onToolCallArgsEvent`, `onToolCallEndEvent`, `onToolCallResultEvent` | | State | `onStateSnapshotEvent`, `onStateDeltaEvent` | | Messages | `onMessagesSnapshotEvent` | | Custom | `onCustomEvent`, `onRawEvent` | | High-level changes | `onMessagesChanged`, `onStateChanged` | ## The proxy pattern When you use CopilotKit with a runtime, your frontend does not talk directly to the backend agent. CopilotKit discovers agents through the runtime's `/info` endpoint and represents each one with a proxy that implements the same `AbstractAgent` interface. ```tsx title="What your component sees" const { agent } = useAgent(); agent.messages; agent.state; agent.subscribe({ /* … */ }); ``` ```tsx title="What happens underneath" // useAgent() → registry checks /info → resolves a proxy agent // agent.runAgent() → runtime POST → agent execution → SSE events ``` This indirection lets the runtime provide authentication, middleware, agent routing, and CopilotKit Enterprise Intelligence without changing how the frontend interacts with agents. ## How agents slot into the runtime On the server, `CopilotRuntime` accepts a map of AG-UI `AbstractAgent` instances. A framework adapter, an `HttpAgent` pointing at a remote server, and a custom implementation all use the same request path: 1. The runtime resolves the target agent by ID. 2. It clones the agent for request isolation and supplies messages, state, and thread context. 3. `AgentRunner` executes the agent and receives AG-UI events. 4. The runtime encodes those events as SSE and streams them to the frontend proxy. The backend framework can change without forcing a corresponding change to the frontend AG-UI contract. --- ## Source: https://docs.showcase.copilotkit.ai/agno/build-with-agents # Build with agents > Use our MCP server to connect your Agno agents to CopilotKit. {/* Every "Build with agents" page renders the full guide — CopilotKit Skills (the recommended path) followed by the MCP Docs Server setup. This snippet is kept as a thin alias so the framework integration pages that reference CodingAgents show the same Skills + MCP content as the top-level page, rather than MCP only. */} AI coding agents may not have up-to-date knowledge of CopilotKit's APIs, patterns, and best practices. The resources on this page give them accurate, current knowledge directly in their context. ## CopilotKit Skills Skills are folders of instructions, references, and scripts that coding agents can discover and use to work with CopilotKit accurately. Installing them gives your agent authoritative guidance on setup, development, debugging, integration, and upgrades — without relying on potentially outdated training data. Skills are the recommended way to give your agent CopilotKit knowledge. They work natively in Claude Code, Cursor, Codex, Gemini CLI, and any tool supporting the [agentskills.io](https://agentskills.io) standard. Most of these skills help you **build with** CopilotKit. If you're just getting started, these three cover the most common tasks: | Skill | Use it to | | --- | --- | | `copilotkit-setup` | Add CopilotKit to a project and get a chat working | | `copilotkit-develop` | Build AI features — chat UI, frontend tools, and shared agent context | | `copilotkit-integrations` | Connect an agent framework (LangGraph, CrewAI, Mastra, and more) | The full [skills directory](https://github.com/CopilotKit/CopilotKit/tree/main/skills) adds more for specific tasks — like `copilotkit-debug` and `copilotkit-upgrade` — plus `copilotkit-contribute`, which is for working on the CopilotKit project itself rather than building with it. You don't need to memorize the list; your agent discovers the installed skills and picks the right one for each task. ### Install the skills Run this from the root of the project you're building in: ```bash npx skills add CopilotKit/CopilotKit/skills -y ``` This installs the skills into your project, where any coding agent working there (Claude Code, Codex, Cursor, or Gemini CLI) discovers them automatically. There's no per-agent configuration to do. Want to choose what gets installed? Run `npx skills add CopilotKit/CopilotKit/skills` without `-y` to pick specific skills, target agents, and scope interactively — or add `-g` to install globally for every project. ### Start building Open a new agent session and use a starter prompt to put the skills to work: ``` Help me build a CopilotKit app. Use the copilotkit-setup skill to get started. ``` Your agent will discover the installed skills and use the right one for each task — setup, development, debugging, or integration. ## MCP Docs Server The CopilotKit MCP server equips AI coding agents with deep knowledge about CopilotKit's APIs, patterns, and best practices. When connected to your development environment, it enables AI assistants to: - Provide expert guidance - Generate accurate code - Give your AI agents a user interface - Help you implement CopilotKit features correctly ### Cursor [Cursor](https://cursor.sh/) is an AI-powered code editor built for productivity. It features built-in AI assistance and supports MCP for extending AI capabilities with external tools. ### Open MCP Settings in Cursor 1. Press `Shift+Command+J` (Mac) or `Shift+Ctrl+J` (Windows/Linux) to open Cursor's settings. 2. Look for "MCP Tools" in the left sidebar categories. 3. Click "Add Custom MCP". This will open the mcp.json file in the editor, which you need to edit. ### Add MCP Server to Cursor Copy CopilotKit MCP's configuration and paste it under the mcpServers key in the mcp.json file. ```json { "mcpServers": { "CopilotKit MCP": { "command": "npx", "args": [ "mcp-remote", "https://mcp.copilotkit.ai" ] } } } ``` ```json { "mcpServers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai/sse" } } } ``` ### Claude Web [Claude](https://claude.ai/) is Anthropic's AI assistant accessible through a web interface. It supports MCP integrations, called Connectors, to connect with external tools and services. Navigate to the [Connectors](https://claude.ai/settings/connectors) settings page in Claude. 1. Click on your user in the bottom left of the chat box and then select "Settings" from the menu options that appear. 2. In the menu along the left side of the Settings page, select "Connectors" Click "Add custom connector" 1. In the Name field, enter a memorable name for the CopilotKit connector, like `CopilotKit` 2. In the URL field, enter the following: ``` https://mcp.copilotkit.ai/sse ``` Click "Add" ### Claude Desktop [Claude Desktop](https://claude.ai/download) is the desktop application version of Claude, offering the same AI capabilities with local system integration and MCP support.

These steps are the same as those for Claude Web, above. The only difference is that the Connectors link below navigates to the Connectors settings in the Claude desktop app, instead of the Claude web app.

Navigate to the [Connectors](claude://claude.ai/settings/connectors) settings page in Claude. 1. Click on your user in the bottom left of the chat box and then select "Settings" from the menu options that appear. 2. In the menu along the left side of the Settings page, select "Connectors" Click "Add custom connector" 1. In the Name field, enter a memorable name for the CopilotKit connector, like `CopilotKit` 2. In the URL field, enter the following: ``` https://mcp.copilotkit.ai/sse ``` Click "Add" ### Claude Code [Claude Code](https://docs.claude.com/en/docs/claude-code) is Anthropic's official CLI for Claude. It supports MCP integrations to connect with external tools and services, enhancing AI capabilities with specialized knowledge. ### Add MCP Server to Claude Code Use the Claude Code CLI to add the CopilotKit MCP server: ```bash claude mcp add --transport sse copilotkit-mcp https://mcp.copilotkit.ai/sse ``` **Expected Output:** ``` Added SSE MCP server copilotkit-mcp with URL: https://mcp.copilotkit.ai/sse to local config File modified: /home/[username]/.claude.json [project: /path/to/your/project] ``` ### Verify Connection Check that the server is properly connected: ```bash claude mcp list ``` **Expected Output:** ``` Checking MCP server health... copilotkit-mcp: https://mcp.copilotkit.ai/sse (SSE) - ✓ Connected ```

💡 Server Name Requirements

Server names can only contain letters, numbers, hyphens, and underscores. Avoid spaces in server names.

### Using MCP Tools in Claude Code Once configured, the CopilotKit MCP server tools are automatically available when you interact with Claude Code for CopilotKit-related development tasks. The AI will intelligently use these tools when relevant to your queries. **What the MCP Server Provides:** - Expert guidance for CopilotKit development - Accurate code generation for CopilotKit features - Best practices and implementation patterns - Deep understanding of CopilotKit APIs **Management Commands:** ```bash # View server details claude mcp get copilotkit-mcp # Remove server if needed claude mcp remove copilotkit-mcp -s local ``` ### Windsurf [Windsurf](https://codeium.com/windsurf) is Codeium's agentic IDE that combines AI-powered coding assistance with traditional development tools. It features the Cascade AI assistant with MCP integration. ### Access Windsurf MCP Settings 1. Open Windsurf Settings (click the settings button in the bottom right) 2. Navigate to the "Cascade" section 3. Look for "Model Context Protocol" or "MCP" settings 4. Enable MCP support if not already enabled ### Add MCP Server to Windsurf You can add CopilotKit MCP in several ways: 1. In the Cascade section, click "Add Server" 2. Select "Add custom server" 3. Choose the transport type: - **SSE/HTTP** for remote servers - **stdio** for local command-based servers Add the server configuration to your mcp_config.json file: ```json { "mcpServers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai", "disabled": false, "timeout": 30 } } } ``` ```json { "mcpServers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai/sse", "disabled": false, "timeout": 30 } } } ``` ```json { "mcpServers": { "CopilotKit MCP": { "command": "npx", "args": ["mcp-remote", "https://mcp.copilotkit.ai"] } } } ``` ### Configuration File Location The MCP configuration is typically stored at: ``` ~/.codeium/windsurf/mcp_config.json ``` ``` %APPDATA%\.codeium\windsurf\mcp_config.json ``` ``` ~/.config/codeium/windsurf/mcp_config.json ``` ### Using MCP Tools in Windsurf Once configured, CopilotKit MCP tools will be available in Windsurf's Cascade AI assistant: - Open the Cascade panel (AI chat interface) - The MCP tools are automatically available to the AI - You can reference specific tools using `@CopilotKit MCP` in your conversations - Windsurf will intelligently choose which tools to use based on your requests ### Managing Your MCP Servers In the Windsurf MCP settings, you can: - Enable/Disable individual servers - View server status and connection health - Configure tool permissions and auto-approval settings - Monitor server logs for debugging - Restart servers if they become unresponsive The AI will seamlessly integrate CopilotKit MCP functionality into your development workflow! ### Cline [Cline](https://github.com/cline/cline) is a VS Code extension that provides autonomous AI coding assistance. It can perform complex tasks using MCP tools to interact with external systems. ### Open Cline MCP Settings 1. Open the Cline extension panel in VS Code 2. Click the menu (⋮) in the top right corner of the Cline panel 3. Select "MCP Servers" from the dropdown menu This will open the MCP Servers interface where you can manage your server connections. ### Add MCP Server to Cline In the MCP Servers interface, you have three main options: 1. Click on the "Remote Servers" tab 2. Enter a Server Name (e.g., "CopilotKit MCP") 3. Enter the Server URL: ``` https://mcp.copilotkit.ai/sse ``` 4. Click "Add Server" to connect Alternatively, you can configure via the advanced settings: 1. In the "Installed" tab, click "Configure MCP Servers" 2. Add the following configuration to your settings file: ```json { "mcpServers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai/sse", "disabled": false, "timeout": 30 } } } ``` ### Using MCP Tools in Cline Once connected, Cline can automatically use the tools provided by CopilotKit MCP when you interact with the AI assistant. The MCP tools will be available without requiring manual selection - Cline's AI will intelligently choose which tools to use based on your requests. **Server Status Indicators:** - Green dot: Connected and ready to use - Yellow dot: Connecting in progress - Red dot: Connection error You can manage server settings, restart connections, or disable servers from the "Installed" tab in the MCP Servers interface. ### GitHub Copilot [GitHub Copilot](https://github.com/features/copilot) is Microsoft's AI pair programmer integrated into VS Code and other editors. It supports MCP to extend its capabilities with external tools and services. ### Enable MCP Support in VS Code 1. Open VS Code Settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux) 2. Search for "MCP" in the settings search bar 3. Enable the `chat.mcp.enabled` setting ### Add MCP Server to GitHub Copilot You can configure MCP servers for GitHub Copilot in several ways: Create a `.vscode/mcp.json` file in your project root: ```json { "servers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai/sse" } } } ``` Add to your VS Code `settings.json`: ```json { "mcp": { "servers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai/sse" } } } } ``` 1. Open the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`) 2. Type "MCP: Add Server" and select the command 3. Choose "HTTP (sse)" as the server type 4. Enter the server URL: `https://mcp.copilotkit.ai/sse` 5. Provide a name for the server: `CopilotKit MCP` ### Using MCP Tools with GitHub Copilot 1. Open Copilot Chat in VS Code (click the Copilot icon in the activity bar) 2. Switch to Agent mode from the chat dropdown menu 3. Click the Tools (🔧) button to view available MCP tools 4. Your CopilotKit MCP tools will be listed and can be used automatically GitHub Copilot will intelligently use the MCP tools when relevant to your queries. You can also reference tools directly using `#` followed by the tool name. ### Managing MCP Servers Use the "MCP: List Servers" command to view and manage your configured servers: - Start/Stop/Restart servers - View server logs for debugging - Browse available tools and resources ### Codex [Codex](https://developers.openai.com/codex) is OpenAI's coding agent. Its CLI reads MCP servers from `~/.codex/config.toml`, where each server is defined under an `[mcp_servers.]` table. ### Add MCP Server to Codex Add CopilotKit MCP to `~/.codex/config.toml`. Codex launches command-based (stdio) servers, so bridge the remote server with `mcp-remote`: ```toml title="~/.codex/config.toml" [mcp_servers.copilotkit] command = "npx" args = ["mcp-remote", "https://mcp.copilotkit.ai"] ``` Or add it from the terminal with the Codex CLI: ```bash codex mcp add copilotkit -- npx mcp-remote https://mcp.copilotkit.ai ``` ### Verify Connection List the configured MCP servers to confirm CopilotKit is registered: ```bash codex mcp list ``` Once configured, the CopilotKit MCP tools are available to Codex and are used automatically when relevant to your CopilotKit development tasks. ### Other For MCP-compatible applications not listed above, use these universal integration patterns. MCP (Model Context Protocol) is an open standard that allows AI applications to connect with external tools and data sources. #### Connection Methods Most MCP-compatible applications support one or both of these connection methods: For web-based or remote integrations: ``` https://mcp.copilotkit.ai/sse ``` For local command-line integrations: ```json { "command": "npx", "args": ["mcp-remote", "https://mcp.copilotkit.ai"] } ``` #### Integration Steps 1. **Find MCP Settings** - Look for "MCP," "Model Context Protocol," or "Tools" in your application settings 2. **Add Server** - Use the SSE URL: `https://mcp.copilotkit.ai/sse` 3. **Test Connection** - Restart your application and verify the server appears in available tools #### Common Configuration Patterns Many applications use a configuration file (locations vary by app): ```json { "servers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai/sse" } } } ``` Some apps integrate MCP into their main settings: ```json { "mcp": { "enabled": true, "servers": { "CopilotKit MCP": { "url": "https://mcp.copilotkit.ai/sse" } } } } ``` --- ## Source: https://docs.showcase.copilotkit.ai/agno/cli # CopilotKit CLI > Use the CopilotKit CLI to create apps, sign in to Cloud-Hosted Enterprise Intelligence, select projects, provision runtime API keys, import historical conversations, and install agent skills. ## What is this? The CopilotKit CLI helps you create CopilotKit apps connected to Enterprise Intelligence, whether cloud-hosted or self-hosted. It handles browser sign-in, project selection, project-scoped runtime API keys, historical thread import, and local project configuration so your app can use durable threads and conversation history. Use the CLI when you want to start a new app, import historical ADK or LangGraph conversations, or install CopilotKit agent skills for your coding agent. ## Prerequisites - Node.js 20+ - A CopilotKit account for Cloud-Hosted Enterprise Intelligence - An OpenAI API key or another model provider key for the starter app you choose ## Start a new app `create` (aliased as `init`) scaffolds a brand-new project in its own directory — it prompts for an app name and does not detect or bootstrap an app you already have. To add CopilotKit to an existing app, follow the manual installation in the [Quickstart](/agno/quickstart) instead. ### Run create ```bash title="Terminal" npx copilotkit@latest create ``` The CLI prompts for the app name and framework, opens browser sign-in when needed, scaffolds the starter, and connects the app to a cloud-hosted Enterprise Intelligence project. ### Sign in If you are not already signed in, the CLI opens a browser login flow. Complete login in the browser, then return to the terminal. If the browser does not open, the CLI prints a login URL and supports a manual paste fallback. ### Select a project Choose an existing cloud-hosted project or create a new one. A project is where your app's threads, messages, and platform metadata are stored. The CLI writes the selected project to `.copilotkit/project.json`: ```json title=".copilotkit/project.json" { "projectId": "proj_...", "projectSlug": "support-assistant", "clerkOrgId": "org_..." } ``` ### Use the generated environment The CLI writes the hosted platform URLs and project-scoped runtime API key to `.env`. ```bash title=".env" INTELLIGENCE_API_URL=https://... INTELLIGENCE_GATEWAY_WS_URL=wss://... INTELLIGENCE_API_KEY=cpk_... ``` Keep `INTELLIGENCE_API_KEY` on the server side. It is a runtime key for the selected project, not a frontend token. ### Start development ```bash title="Terminal" npm run dev ``` The starter runs your local app and runtime while storing durable threads in the cloud-hosted project selected by the CLI. ## Import and synchronize historical conversations Use `import` from a CopilotKit app created with the CLI and Enterprise Intelligence enabled. The importer targets the Enterprise Intelligence project already selected for the current directory. ```bash npx copilotkit@latest import --source adk --dry-run ``` ```bash npx copilotkit@latest import --source langgraph --dry-run ``` The command runs interactively by default. Start with `--dry-run` to discover source agent keys, conversation counts, skips, and the estimated upload size without opening an import batch. If you need to import into a different project, select it before continuing with the real import: ```bash title="Terminal" npx copilotkit@latest project select ``` This changes the project selected for the current directory and writes its project-scoped runtime key to the starter's generated `.env`. Before the real import, export the destination values from that `.env`: ```bash title="Terminal" export INTELLIGENCE_API_URL="https://..." export INTELLIGENCE_API_KEY="cpk_..." ``` The importer reads `--api-url` and `--api-key` or the current process environment. It does not load `.env` or `.copilotkit/project.json` automatically. `COPILOTKIT_API_KEY` is also accepted for the key. Project selection updates the app configuration; the importer still receives its destination through flags or exported environment variables. For the full adoption flow, see [Import & Synchronize Thread History](/agno/threads-import). Source-specific setup lives in [Synchronize ADK threads](/google-adk/threads-import) and [Synchronize LangGraph threads](/langgraph-python/threads-import). ## Auth commands | Command | What it does | |---|---| | `npx copilotkit@latest login` | Opens the browser sign-in flow and stores a local CLI session. | | `npx copilotkit@latest whoami` | Shows the signed-in user and active organization. | | `npx copilotkit@latest logout` | Clears the local CLI session. | ## Project commands | Command | What it does | |---|---| | `npx copilotkit@latest project select` | Selects or creates a cloud-hosted Enterprise Intelligence project for the current directory. | | `npx copilotkit@latest import --source adk --dry-run` | Previews historical Google ADK conversation threads before import. | | `npx copilotkit@latest import --source langgraph --dry-run` | Previews historical LangGraph conversation threads before import. | | `npx copilotkit@latest license create` | Issues a CopilotKit license token for flows that require one. | | `npx copilotkit@latest license list` | Lists license metadata for the current user or organization. | Re-running `project select` is safe when you need to move a CLI-created app to a different cloud-hosted project. The command updates `.copilotkit/project.json` and provisions a project-scoped API key for the selected project. ## Skills commands | Command | What it does | |---|---| | `npx copilotkit@latest skills install` | Installs CopilotKit agent skills for supported coding agents. | | `npx copilotkit@latest skills onboard` | Installs skills, then starts agent-assisted onboarding for an existing app. | ## Next steps - **Cloud-hosted platform:** [Cloud-Hosted Enterprise Intelligence](/agno/premium/managed-intelligence-platform) — login, projects, API keys, threads, and plans in the hosted web app - **Add threads:** use the [Threads Drawer](/agno/prebuilt-components/copilot-threads-drawer) for a drop-in thread switcher, or [Headless Threads](/agno/headless-threads) to build your own thread UI - **Synchronize thread history:** [Import & Synchronize Thread History](/agno/threads-import) — import existing ADK or LangGraph conversations and keep future CopilotKit runs synchronized - **Self-hosting:** [Self-Hosting Enterprise Intelligence](/agno/premium/self-hosting) — run the Enterprise Intelligence Platform in your own Kubernetes cluster --- ## Source: https://docs.showcase.copilotkit.ai/agno/contributing/code-contributions # Code Contributions We are grateful for your interest in contributing to CopilotKit. We welcome new contributors and appreciate your help in making CopilotKit better. This guide will help you get started as smoothly as possible. ## Step 1: Install Prerequisites - [Node.js](https://nodejs.org/en/) 20.x or later - [pnpm](https://pnpm.io/) v10.x installed globally (`npm i -g pnpm@^10`) ## Step 2: Repository Setup ### Fork The Repository First, head over to the [CopilotKit repository](https://github.com/CopilotKit/CopilotKit) and create a fork. Then, clone your fork to your local machine: ```bash git clone https://github.com//CopilotKit cd CopilotKit ``` ### Install Dependencies The CopilotKit repository is a monorepo using a [pnpm](https://pnpm.io/) workspace. Tasks across packages are orchestrated with [Nx](https://nx.dev/). Install the dependencies using pnpm: ```bash pnpm install ``` ### Build Packages To make sure everything works, let's build all packages once: ```bash pnpm run build ``` ## Step 3: Development Mode Now that everything is set up and works as expected, you can get started developing: ```bash # Start all packages in development mode pnpm run dev # Start a specific package in development mode pnpm exec nx watch --projects=packages/package-name -- pnpm run build ``` Now you can start making changes to the code. You can find all `@copilotkit/*` packages under the `packages` folder of the monorepo. ## Step 4: Test Changes in Real-Time In most cases, you want to seamlessly be able to test your changes in real-time as you develop. We have an `examples` folder in the monorepo with a few different examples using CopilotKit. You can run these examples to test your changes, as they are linked to the `@copilotkit/*` packages in the monorepo. For this tutorial, we'll use the `next-openai` example, specifically the Presentation Demo (`/presentation`). In a separate terminal, run the following command to start the example: ```bash cd examples/v1/next-openai export OPENAI_API_KEY= pnpm run example-dev ``` We use the `pnpm run example-dev` command to run examples, which is different from the `pnpm run dev` command we use to work on the individual packages. Now navigate to http://localhost:3000/presentation and you should see the example running. Any changes you make to the CopilotKit packages will immediately be reflected here. ## Step 5: Formatting and Linting Before committing your changes, ensure your files are formatted properly by running the following at the root of the monorepo: ```bash pnpm run format ``` Additionally, ensure you have no linting errors: ```bash pnpm run lint ``` ## Step 6: Submit a Pull Request Now that you've made your changes, commit and push them. Then, simply head over to the [Pull Requests page](https://github.com/CopilotKit/CopilotKit/pulls) and create a pull request. Well done! ## Starting a dev environment with hot reload CopilotKit contains a ready-made script for starting a development environment based on one of the CoAgent examples. It lets you work on CopilotKit internals in the core Typescript and Python code while seeing your changes applied to the chosen example. As a prerequisite, make sure you have GNU parallel and langgraph CLI installed. Next, go to the `CopilotKit/` directory and run the `example.sh` script for the example you want to work on: ```bash ./scripts/develop/example.sh coagents-starter ``` This will start a development environment with hot reload. You can optionally run the same example on LangGraph platform by running: ```bash ./scripts/develop/example.sh coagents-starter langgraph-platform ``` ## Debugging Every time you run CopilotKit on localhost, you will be able to see the **CopilotKit Dev Console** in the chat window. The Dev Console provides you with useful functionality to debug your copilot (e.g. see what state the copilot is aware of, actions it can perform, etc).

If you'd like to disable the Dev Console locally, simply set `showDevConsole` to `false` in your `` provider. ## (Advanced) Package Linking In some cases, you want to test your CopilotKit changes in your own project. For example, you tried to integrate CopilotKit into your own codebase and encountered a bug you want to fix. Conveniently, you can link your local CopilotKit packages to your own project to test your changes. Check out the [Advanced: Package Linking](/agno/contributing/code-contributions/package-linking) guide to learn how to do that. ## Need help? If you need help with anything, please don't hesitate to reach out to us on [Discord](https://discord.gg/6dffbvGU3D). We have a dedicated [#contributing](https://discord.com/channels/1122926057641742418/1183863183149117561) channel. --- ## Source: https://docs.showcase.copilotkit.ai/agno/contributing/code-contributions/package-linking # Advanced: Package Linking In this guide, we'll teach you how to link the CopilotKit packages to your own project to test your changes. This way, you can run `pnpm run dev` in the CopilotKit monorepo, and see changes in your own project immediately. ## Global Package Linking With `pnpm` We will use pnpm's [global linking feature](https://pnpm.io/cli/link#pnpm-link---global) to link the CopilotKit packages to your own project. ### In The CopilotKit Monorepo Assuming you followed all steps in the contribution guide, you should have everything set up properly and ready to go. Navigate to the CopilotKit monorepo and run the following command to link the packages globally: ```bash pnpm exec nx run-many -t link:global ``` ### In Your Project In your project, ensure you have pnpm configured. This will not prevent you from using npm or yarn as well. But for the purpose of global linking, you must use pnpm. ```bash cd your-project pnpm i ``` Next, link the desired package in your project: ```bash # For example, to link the @copilotkit/react-core package: pnpm link --global @copilotkit/react-core ``` You can run this for all packages, or just the ones you need. Your changes will now be synced. ### Unlinking Once you are done, you can undo the global linking by running the following command in the CopilotKit monorepo: ```bash pnpm exec nx run-many -t unlink:global ``` And then in your project: ```bash pnpm install ``` That's it, everything is now back to normal! ## Need help? If you need help with anything, please don't hesitate to reach out to us on [Discord](https://discord.gg/6dffbvGU3D). We have a dedicated [#contributing](https://discord.com/channels/1122926057641742418/1183863183149117561) channel. --- ## Source: https://docs.showcase.copilotkit.ai/agno/contributing/docs-contributions # Documentation Contributions We understand that as we move quickly, sometimes our documentation website can be a bit outdated. Therefore, we highly value contributions to our documentation. ## Prerequisites - [Node.js](https://nodejs.org/en/) 20.x or later - [pnpm](https://pnpm.io/) v10.x installed globally (`npm i -g pnpm@^10`) ## How To Contribute ### Fork The Repository First, head over to the [CopilotKit GitHub repository](https://github.com/CopilotKit/CopilotKit) and create a fork. Then, clone the forked repository to your local machine: ```shell git clone https://github.com//CopilotKit cd CopilotKit/docs ``` ### Run the Documentation Site Locally To run the documentation site locally, install the dependencies and then start the docs in development mode: ```shell pnpm install pnpm run dev ``` The documentation site should be available at [http://localhost:3000](http://localhost:3000). ### Make Your Changes Now, you can make your changes to the documentation website. - All documentation-related files are located in the docs repository - You may want to familiarize yourself with [Nextra](https://nextra.site/) to understand how the documentation website is structured. Please ensure you review your changes for grammar, spelling and formatting errors. Also, ensure that links and images are working. ### Review Changes & Submit Pull Request Once you are happy with your changes, you can commit and push them. Then, head over to the [Pull Requests page](https://github.com/CopilotKit/CopilotKit/pulls) and create a pull request. Thank you for your contribution! ## Need help? If you need help with anything, please don't hesitate to reach out to us on [Discord](https://discord.gg/6dffbvGU3D). We have a dedicated [#contributing](https://discord.com/channels/1122926057641742418/1183863183149117561) channel. --- ## Source: https://docs.showcase.copilotkit.ai/agno/copilot-runtime # Copilot Runtime > The Copilot Runtime is the backend that connects your frontend to your AI agents, providing authentication, middleware, routing, and more. The Copilot Runtime is the backend layer that connects your frontend application to your AI agents. It's set up during the [quickstart](/agno/quickstart) and is the recommended way to use CopilotKit. ## Setting Up the Runtime The runtime is a lightweight server endpoint that you add to your backend. Here's a minimal example using Next.js: ```ts title="app/api/copilotkit/route.ts" import { CopilotRuntime, ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint, } from "@copilotkit/runtime"; import { NextRequest } from "next/server"; const serviceAdapter = new ExperimentalEmptyAdapter(); const runtime = new CopilotRuntime({ agents: { // your agents go here }, }); export const POST = async (req: NextRequest) => { const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({ runtime, serviceAdapter, endpoint: "/api/copilotkit", }); return handleRequest(req); }; ``` Then point your frontend at the endpoint: ```tsx ``` For setup with other backend frameworks (Express, NestJS, Node.js HTTP), see the [quickstart](/agno/quickstart). ## The Default Agent If you register an agent with the name `"default"`, CopilotKit's prebuilt UI components will use it automatically without any additional configuration on the frontend. This is useful when you have one primary agent and don't want to specify an `agentId` everywhere. ```ts title="app/api/copilotkit/route.ts" const runtime = new CopilotRuntime({ agents: { // Frontend APIs use this agent when no other agent id is selected. default: new HttpAgent({ url: "https://my-agent.example.com" }), }, }); ``` When you register multiple agents, the `"default"` agent powers the chat unless a specific agent is selected. Other agents remain addressable through the frontend agent API. ## What the Runtime Provides ### Authentication and Security The runtime runs on your server, which means agent communication stays server-side. This gives you a trusted environment to enforce authentication, validate requests, and keep API keys secure. When you use the runtime, safe defaults are put in place so your agent endpoints are not exposed to unauthenticated access. ### AG-UI Middleware The [AG-UI protocol](/ag-ui-protocol) supports a middleware layer (`agent.use`) for logging, guardrails, request transformation, and more. Because the runtime runs server-side, this middleware executes in a trusted environment where it cannot be tampered with by the client. ### Agent Routing When you register multiple agents with the runtime, it handles discovery and routing automatically. Your frontend doesn't need to know the details of where each agent lives or how to reach it. ### Enterprise Intelligence Platform Features like [threads](/agno/threads) and the [inspector](/agno/inspector) are provided through the runtime and the Enterprise Intelligence Platform. These give you conversation persistence and debugging capabilities out of the box. ## Built-in Middleware The runtime supports two first-class middleware options you can enable directly on `CopilotRuntime` without calling `.use()` on each agent manually. ### A2UI Pass `a2ui: {}` to automatically apply `A2UIMiddleware` to all registered agents: ```ts title="app/api/copilotkit/route.ts" const runtime = new CopilotRuntime({ agents: { default: myAgent }, a2ui: {}, // enables A2UI rendering for all agents }); ``` To scope it to specific agents only, pass an `agents` list: ```ts a2ui: { agents: ["my-agent"]; } ``` On the frontend, the A2UI renderer activates automatically. Configure `a2ui` only when you want to override its defaults: ```tsx {children} ``` ### mcpApps Pass `mcpApps` to configure MCP servers for all agents from a single place: ```ts title="app/api/copilotkit/route.ts" const runtime = new CopilotRuntime({ agents: { default: myAgent }, mcpApps: { servers: [ { type: "http", url: "http://localhost:3108/mcp", serverId: "my-server" }, ], }, }); ``` Each server entry optionally accepts an `agentId` field to scope that server to a single agent. Without it, the server is available to all agents. ## What If I Want to Connect to My AG-UI Agent Directly? CopilotKit is built on the [AG-UI protocol](/ag-ui-protocol), which is an open standard. If you want to connect your frontend directly to an AG-UI-compatible agent without the runtime, pass the agent instance in your frontend configuration: ```tsx import { HttpAgent } from "@ag-ui/client"; const myAgent = new HttpAgent({ url: "https://my-agent.example.com", }); ; ``` Direct agent connections are intended for development and prototyping. This approach is not recommended for production unless you are confident in your setup, and is not officially supported by CopilotKit. If you run into issues with a direct connection, you will need to troubleshoot on your own. There are important things to understand before going this route: 1. **Authentication is your responsibility.** When you use the Copilot Runtime, safe defaults are put in place so that your agent endpoints are not exposed to unauthenticated access. When you connect directly, it is entirely up to you to secure your agent endpoint and manage authentication. 2. **Many ecosystem features won't work.** The AG-UI protocol supports a middleware layer designed to run on the backend. Many features in the CopilotKit ecosystem depend on this server-side middleware. Without the runtime, these features — including [threads](/agno/threads) and other capabilities — will not be available. ### Comparison | | With Runtime | Direct Connection | | ---------------------- | --------------------------- | ----------------- | | **Authentication** | Safe defaults provided | You manage it | | **AG-UI Middleware** | Runs server-side | Not available | | **Agent Routing** | Automatic | Manual | | **Ecosystem Features** | Full support | Limited | | **CopilotKit Support** | Supported | Not supported | | **Setup** | Requires a backend endpoint | Frontend-only | --- ## Source: https://docs.showcase.copilotkit.ai/agno/custom-look-and-feel/headless-ui # Fully Headless UI > Fully customize your Copilot's UI from the ground up using headless UI ## What is this? A headless UI gives you full control over the chat experience — you bring your own components, layout, and styling while CopilotKit handles agent communication, message management, and streaming. This is built on top of the same primitives (`useAgent` and `useCopilotKit`) covered in Programmatic Control. ## When should I use this? Use headless UI when the slot system isn't enough — for example, when you need a completely different layout, want to embed the chat into an existing UI, or are building a non-chat interface that still communicates with an agent. ## Implementation ### Access the agent and CopilotKit Use `useAgent` to get the agent instance (messages, state, execution status) and `useCopilotKit` to run the agent. ```tsx title="components/custom-chat.tsx" import { useAgent } from "@copilotkit/react-core/v2"; import { useCopilotKit } from "@copilotkit/react-core/v2"; import { randomUUID } from "@copilotkit/shared"; export function CustomChat() { // [!code highlight:2] const { agent } = useAgent(); const { copilotkit } = useCopilotKit(); return

{/* Your custom UI */}

; } ``` ### Display messages The agent's messages are available via `agent.messages`. Each message has an `id`, `role` (`"user"` or `"assistant"`), and `content`. ```tsx title="components/custom-chat.tsx" export function CustomChat() { const { agent } = useAgent(); const { copilotkit } = useCopilotKit(); return (

{/* [!code highlight:12] */}

{agent.messages.map((msg) => (

{msg.role}

{msg.content}

))} {agent.isRunning &&

Thinking...

}

); } ``` ### Send messages and run the agent Add a message to the agent's conversation, then call `copilotkit.runAgent()` to trigger execution. This is the same method CopilotKit's built-in `` uses internally. ```tsx title="components/custom-chat.tsx" import { useState, useCallback } from "react"; export function CustomChat() { const { agent } = useAgent(); const { copilotkit } = useCopilotKit(); const [input, setInput] = useState(""); // [!code highlight:14] const sendMessage = useCallback(async () => { if (!input.trim()) return; agent.addMessage({ id: randomUUID(), role: "user", content: input, }); setInput(""); await copilotkit.runAgent({ agent }); }, [input, agent, copilotkit]); return (

{agent.messages.map((msg) => (

{msg.content}

))} {agent.isRunning &&

Thinking...

}

{/* [!code highlight:12] */}

); } ``` ### Stop the agent Use `copilotkit.stopAgent()` to cancel a running agent: ```tsx title="components/custom-chat.tsx" const stopAgent = useCallback(() => { // [!code highlight:1] copilotkit.stopAgent({ agent }); }, [agent, copilotkit]); // In your JSX: { agent.isRunning && ( ); } ``` --- ## Source: https://docs.showcase.copilotkit.ai/agno/custom-look-and-feel/slots # Slots > Customize any part of the chat UI by overriding individual sub-components via slots for Agno. ## What is this? Every CopilotKit chat component is built from composable **slots** — named sub-components that you can override individually. The slot system gives you three levels of customization without needing to rebuild the entire UI: 1. **Tailwind classes** — pass a string to add/override CSS classes 2. **Props override** — pass an object to override specific props on the default component 3. **Custom component** — pass your own React component to fully replace a slot Slots are recursive — you can drill into nested sub-components at any depth. ## Tailwind Classes The simplest way to customize a slot. Pass a Tailwind class string and it will be merged with the default component's classes. ```tsx title="page.tsx" import { CopilotChat } from "@copilotkit/react-core/v2"; export function Chat() { return ( ); } ``` ## Props Override Pass an object to override specific props on the default component. This is useful for adding `className`, event handlers, data attributes, or any other prop the default component accepts. ```tsx title="page.tsx" ``` ## Custom Components For full control, pass your own React component. It receives all the same props as the default component. ```tsx title="page.tsx" import { CopilotChat } from "@copilotkit/react-core/v2"; // [!code highlight:8] const CustomMessageView = ({ messages, isRunning }) => (

{messages?.map((msg) => (

{msg.content}

))} {isRunning &&

Thinking...

}

); export function Chat() { return ( // [!code highlight:1] ); } ``` ## Nested Slots (Drill-Down) Slots are recursive. You can customize sub-components at any depth by nesting objects. ### Two levels deep Override the assistant message's toolbar within the message view: ```tsx title="page.tsx" ``` ### Three levels deep Override a specific button inside the assistant message toolbar: ```tsx title="page.tsx" , }, }} /> ``` ### Input sub-slots ```tsx title="page.tsx" ``` ### Scroll view sub-slots ```tsx title="page.tsx" ``` ### Suggestion view sub-slots ```tsx title="page.tsx" ``` ## Children Render Function For complete layout control, use the `children` render function pattern. This gives you pre-built slot elements that you can arrange however you want. ```tsx title="page.tsx" import { CopilotChat } from "@copilotkit/react-core/v2"; export function Chat() { return ( {/* [!code highlight:8] */} {({ messageView, input, scrollView, suggestionView }) => (

My Agent

{scrollView}

{input}

)} ); } ``` ## Labels Customize any text string in the UI via the `labels` prop. This does not use the slot system — it's a separate convenience prop on `CopilotChat`, `CopilotSidebar`, and `CopilotPopup`. ```tsx title="page.tsx" ``` ## Available Slots ### `CopilotChat` / `CopilotSidebar` / `CopilotPopup` These are the root-level slot props available on all chat components: | Slot | Description | | ---------------- | --------------------------------------------------------- | | `messageView` | The message list container. | | `scrollView` | The scroll container with auto-scroll behavior. | | `input` | The text input area with send/transcribe controls. | | `suggestionView` | The suggestion pills shown below messages. | | `welcomeScreen` | The initial empty-state screen (pass `false` to disable). | `CopilotSidebar` and `CopilotPopup` also have: | Slot | Description | | -------------- | ----------------------------- | | `header` | The modal header bar. | | `toggleButton` | The open/close toggle button. | ### `messageView` sub-slots Available via `messageView={{ ... }}`: | Slot | Description | | ------------------ | -------------------------------------------------------------------------- | | `assistantMessage` | Renders assistant responses. Has its own sub-slots (see below). | | `userMessage` | Renders user messages. Has its own sub-slots (see below). | | `reasoningMessage` | Renders model reasoning/thinking steps. Has its own sub-slots (see below). | | `cursor` | The streaming cursor indicator shown while the agent is responding. | ### `assistantMessage` sub-slots Available via `messageView={{ assistantMessage: { ... } }}`: | Slot | Description | | ------------------ | ---------------------------------- | | `markdownRenderer` | The markdown rendering component. | | `toolbar` | The action toolbar below messages. | | `copyButton` | Copy message button. | | `thumbsUpButton` | Thumbs up feedback button. | | `thumbsDownButton` | Thumbs down feedback button. | | `readAloudButton` | Read aloud button. | | `regenerateButton` | Regenerate response button. | | `toolCallsView` | Tool call visualization. | ### `userMessage` sub-slots Available via `messageView={{ userMessage: { ... } }}`: | Slot | Description | | ------------------ | ---------------------------------------------------- | | `messageRenderer` | The text rendering component for user messages. | | `toolbar` | The action toolbar on hover. | | `copyButton` | Copy message button. | | `editButton` | Edit message button. | | `branchNavigation` | Navigation between message branches (after editing). | ### `reasoningMessage` sub-slots Available via `messageView={{ reasoningMessage: { ... } }}`: | Slot | Description | | ------------- | -------------------------------------------------- | | `header` | The collapsible header (click to expand/collapse). | | `contentView` | The reasoning content area. | | `toggle` | The expand/collapse toggle wrapper. | ### `input` sub-slots Available via `input={{ ... }}`: | Slot | Description | | ------------------------ | ------------------------------------ | | `textArea` | The text input element. | | `sendButton` | The send/submit button. | | `addMenuButton` | The attachment/tools menu button. | | `startTranscribeButton` | Button to start voice transcription. | | `cancelTranscribeButton` | Button to cancel transcription. | | `finishTranscribeButton` | Button to finish transcription. | | `audioRecorder` | The audio recorder component. | | `disclaimer` | The disclaimer text below the input. | ### `scrollView` sub-slots Available via `scrollView={{ ... }}`: | Slot | Description | | ---------------------- | ------------------------------------------------------ | | `feather` | The gradient overlay at the bottom of the scroll area. | | `scrollToBottomButton` | The button that appears when scrolled up. | ### `suggestionView` sub-slots Available via `suggestionView={{ ... }}`: | Slot | Description | | ------------ | -------------------------------------------- | | `suggestion` | Individual suggestion pill/button. | | `container` | The container wrapping all suggestion pills. | ### `welcomeScreen` sub-slots Available via `welcomeScreen={{ ... }}`: | Slot | Description | | ---------------- | ------------------------------------------ | | `welcomeMessage` | The welcome text shown on the empty state. | ### `header` sub-slots (Sidebar/Popup only) Available via `header={{ ... }}`: | Slot | Description | | -------------- | ----------------------------- | | `titleContent` | The title text in the header. | | `closeButton` | The close/minimize button. | ### `toggleButton` sub-slots (Sidebar/Popup only) Available via `toggleButton={{ ... }}`: | Slot | Description | | ----------- | ----------------------------------- | | `openIcon` | Icon shown when the chat is closed. | | `closeIcon` | Icon shown when the chat is open. | --- ## Source: https://docs.showcase.copilotkit.ai/agno/frontend-tools # Frontend Tools > Create frontend tools and use them within your Agno agent. ## What is this? Frontend tools enable you to define client-side functions that your Agno agent can invoke, with execution happening entirely in the user's browser. When your agent calls a frontend tool, the logic runs on the client side, giving you direct access to the frontend environment. This can be utilized for to let [your agent control the UI](/agno/frontend-tools), [generative UI](/agno/frontend-tools), or for [Human-in-the-loop](/agno/human-in-the-loop) interactions. In this guide, we cover the use of frontend tools driving and interacting with the UI. ## When should I use this? Use frontend tools when you need your agent to interact with client-side primitives such as: - Reading or modifying React component state - Accessing browser APIs like localStorage, sessionStorage, or cookies - Triggering UI updates or animations - Interacting with third-party frontend libraries - Performing actions that require the user's immediate browser context ## Implementation ### Run and connect your agent You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already, you can follow the instructions in the [Getting Started](/langgraph/quickstart) guide. If you don't already have an agent, you can use the [coagent starter](https://github.com/copilotkit/copilotkit/tree/main/examples/coagents-starter) as a starting point as this guide uses it as a starting point. ### Create a frontend tool First, you'll need to create a frontend tool using the [useFrontendTool](/reference/v1/hooks/useFrontendTool) hook. Here's a simple one to get you started that says hello to the user. ```tsx title="page.tsx" import { z } from "zod"; import { useFrontendTool } from "@copilotkit/react-core/v2" // [!code highlight] export function Page() { // ... {/* [!code highlight:12] */} useFrontendTool({ name: "sayHello", description: "Say hello to the user", parameters: z.object({ name: z.string().describe("The name of the user to say hello to"), }), handler: async ({ name }) => { alert(`Hello, ${name}!`); return `Said hello to ${name}!`; }, }); // ... } ``` ### Define the frontend tool in your Agno agent Now, we'll need to modify the agent to access these frontend tools. In your Agno agent, define a tool with the `@tool(external_execution=True)` decorator. This tells Agno that the tool will be executed externally (on the frontend). ```python title="tools/frontend.py" from agno.tools import tool @tool(external_execution=True) def sayHello(name: str): """ Say hello to the user. Args: name: The name of the user to say hello to """ ``` Register the tool with your agent: ```python title="agent.py" from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.os import AgentOS from agno.os.interfaces.agui import AGUI from tools.frontend import sayHello agent = Agent( model=OpenAIChat(id="gpt-5.4"), tools=[sayHello], description="A helpful assistant that can answer questions and provide information.", instructions="Be helpful and friendly. Format your responses using markdown where appropriate.", ) agent_os = AgentOS(agents=[agent], interfaces=[AGUI(agent=agent)]) app = agent_os.get_app() ``` ### Give it a try! You've now given your agent the ability to directly call any frontend tools you've defined. These tools will be available to the agent where they can be used as needed.

--- ## Source: https://docs.showcase.copilotkit.ai/agno/generative-ui/a2ui # A2UI > Render declarative UI components using the A2UI specification. # A2UI - Google's Generative UI Spec **A2UI** is Google's declarative, LLM-friendly Generative UI specification that enables agents to generate dynamic user interfaces. Generative UI Specs

## What is A2UI? A2UI is a declarative generative UI specification launched by Google. It's designed to be: - **JSONL-based** - Uses JSON Lines format for streaming - **LLM-friendly** - Easy for language models to generate - **Platform-agnostic** - Can be rendered on any platform - **Streaming-first** - Built for real-time, progressive rendering ## Why A2UI? ### Declarative Approach A2UI allows agents to describe UI components declaratively, making it easier for LLMs to generate dynamic interfaces without needing to understand implementation details. ### Streaming Support Built with streaming in mind, A2UI enables progressive rendering as the agent generates responses, providing a better user experience. ### Platform Agnostic A2UI specifications can be rendered on web, mobile, or any other platform, making your agent's UI truly universal. ## Setup with CopilotKit ### Backend Enable A2UI in `CopilotRuntime` by passing `a2ui: {}`: ```ts title="app/api/copilotkit/route.ts" import { CopilotRuntime, ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint, } from "@copilotkit/runtime"; const runtime = new CopilotRuntime({ agents: { default: myAgent }, a2ui: {}, }); ``` This automatically applies `A2UIMiddleware` to all registered agents. To scope it to specific agents, you can specify agents with the `agents` property: `a2ui: { agents: ["my-agent"] }`. Once configured, any A2UI output returned from your agent will automatically be rendered in the chat interface — no additional frontend code required. ### Frontend The A2UI renderer activates automatically — no extra configuration needed on the frontend. Optionally, pass a custom theme: ```tsx import { CopilotKit } from "@copilotkit/react-core/v2"; import { myCustomTheme } from "@copilotkit/a2ui-renderer"; {children} ; ``` The `a2ui` prop on `` is only needed if you want to override the default theme provided. ## Using A2UI with CopilotKit [Get started with A2UI](/a2a/generative-ui/declarative-a2ui) and A2A with CopilotKit Check out the [A2UI Composer](https://a2ui-editor.ag-ui.com/gallery) to create and find widgets ## Learn More - [Generative UI Specs Overview](/agno/concepts/generative-ui-overview) - Compare all supported specifications - [Generative UI Guide](/agno/generative-ui/tool-based) - Build with Generative UI in CopilotKit - [A2UI Site](https://a2ui.org/) - Visit the A2UI site - [AG-UI Protocol](/agno/agentic-protocols/ag-ui) - Learn about the protocol that supports A2UI - [Open-JSON-UI](/agno/generative-ui/open-json-ui) - OpenAI's alternative approach - [MCP Apps](/agno/generative-ui/mcp-apps) - Iframe-based Generative UI extending MCP --- ## Source: https://docs.showcase.copilotkit.ai/agno/generative-ui/mcp-apps # MCP Apps > Render interactive UI components from MCP servers directly in your chat interface. ## Prerequisites Before you begin, you'll need the following: - An OpenAI API key (or API key for your preferred LLM provider) - Node.js 20+ - Your favorite package manager - An MCP server running (see [Example MCP Servers](#example-mcp-servers) below) ## What are MCP Apps? MCP Apps are MCP servers that expose tools with associated UI resources. When the agent calls one of these tools, CopilotKit automatically fetches and renders the UI component in the chat - no additional frontend code required. Key benefits: - **Zero frontend code** - UI components are served by the MCP server - **Full interactivity** - Components can use HTML, CSS, and JavaScript - **Secure sandboxing** - Content runs in isolated iframes - **Direct server communication** - The middleware securely proxies communication between the rendered UI and the MCP server, enabling real-time interactions - **Thread persistence** - MCP Apps are stored in conversation history and restored on reconnect ## Quickstart Want to try MCP Apps out with a new application? We have a pre-built example app you can use via our CLI. ```bash npx copilotkit create -f mcp-apps ``` ## Getting started If you're looking to add an MCP App into an existing application, let's walk through the process. ### (Optional) Create a new application We'll be starting from scratch for this example, but feel free to skip this step if you already have an application. For the sake of this example, we'll be using Next.js but the process will slot into any frontend React framework. ```bash npx create-next-app@latest ``` ### Add the dependencies ```npm npm install @copilotkit/react-core @copilotkit/runtime @ag-ui/mcp-apps-middleware ``` ### Configure your agent Add your agent configuration to CopilotRuntime with your MCP server configurations: This same process will work with any agent configuration. ```bash touch app/api/copilotkit/route.ts ``` ```typescript title="app/api/copilotkit/route.ts" import { CopilotRuntime, ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint, } from "@copilotkit/runtime"; import { BuiltInAgent } from "@copilotkit/runtime/v2"; import { NextRequest } from "next/server"; // 1. Create your agent const agent = new BuiltInAgent({ model: "openai/gpt-5.4", prompt: "You are a helpful assistant.", }); // 2. Create a service adapter, empty if not relevant const serviceAdapter = new ExperimentalEmptyAdapter(); // 3. Create the runtime with mcpApps configured const runtime = new CopilotRuntime({ agents: { default: agent, }, mcpApps: { servers: [ { type: "http", url: "http://localhost:3108/mcp", serverId: "my-server", // Recommended: stable identifier }, ], }, }); // 4. Create the API route export const POST = async (req: NextRequest) => { const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({ runtime, serviceAdapter, endpoint: "/api/copilotkit", }); return handleRequest(req); }; ``` Always provide a `serverId` for production deployments. Without it, CopilotKit generates a hash from the server URL. If your URL changes (e.g., different environments), previously stored MCP Apps in conversation history won't load correctly. Alternatively, if you want to scope MCP Apps to specific agents, you can use `MCPAppsMiddleware` directly on the agent via `.use()`: ```typescript title="app/api/copilotkit/route.ts" import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware"; const agent = new BuiltInAgent({ model: "openai/gpt-5.4", prompt: "You are a helpful assistant.", }).use( new MCPAppsMiddleware({ mcpServers: [ { type: "http", url: "http://localhost:3108/mcp", serverId: "my-server", }, ], }), ); ``` ### Configure environment Create a `.env.local` file in your frontend directory and add your API key: ```plaintext title=".env.local" OPENAI_API_KEY=your_openai_api_key ``` The example is configured to use OpenAI's GPT-4o by default, but you can modify the BuiltInAgent to use any language model supported by CopilotKit. ### Configure CopilotKit Provider Wrap your application with the CopilotKit provider: ```tsx title="app/layout.tsx" // [!code highlight:2] import { CopilotKit } from "@copilotkit/react-core/v2"; import "@copilotkit/react-core/v2/styles.css"; // ... export default function RootLayout({ children }: {children: React.ReactNode}) { return ( {/* [!code highlight:3] */} {children} ); } ``` ### Add the chat interface Add the CopilotSidebar component to your page: ```tsx title="app/page.tsx" "use client"; import { CopilotSidebar } from "@copilotkit/react-core/v2"; export default function Page() { return (

Your App

); } ``` ### Start your UI Start the development server: ```bash npm run dev ``` ```bash pnpm dev ``` ```bash yarn dev ``` ```bash bun dev ``` Your application will be available at `http://localhost:3000`. That's it! MCP Apps will now render automatically when the agent uses tools that have associated UI resources. ## Transport Types The middleware supports two transport types: ### HTTP Transport For MCP servers using HTTP-based communication: ```typescript { type: "http", url: "http://localhost:3101/mcp", serverId: "my-http-server" } ``` ### SSE Transport For MCP servers using Server-Sent Events: ```typescript { type: "sse", url: "https://mcp.example.com/sse", headers: { "Authorization": "Bearer token" }, serverId: "my-sse-server" } ``` ## Threading Support MCP Apps integrate fully with CopilotKit's threading system: - **Persistence** - When you save a thread, MCP Apps are stored as part of the conversation history - **Restoration** - Loading a thread restores all MCP Apps with their original state - **Server ID stability** - Using consistent `serverId` values ensures MCP Apps load correctly across sessions ## Example MCP Servers Try these open-source MCP Apps servers to get started: https://github.com/modelcontextprotocol/ext-apps This repo contains multiple demo servers with tools like budget allocators, data visualizations, and interactive dashboards. --- ## Source: https://docs.showcase.copilotkit.ai/agno/generative-ui/tool-rendering # Tool Rendering > Render your agent's tool calls with custom UI components. This example demonstrates the [implementation](#implementation) section applied in the CopilotKit feature viewer. ## What is this? Tools are a way for the LLM to call predefined, typically, deterministic functions. CopilotKit allows you to render these tools in the UI as a custom component, which we call **Generative UI**. ## When should I use this? Rendering tools in the UI is useful when you want to provide the user with feedback about what your agent is doing, specifically when your agent is calling tools. CopilotKit allows you to fully customize how these tools are rendered in the chat. ## Implementation ### Run and connect your agent You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already, you can follow the instructions in the [Getting Started](/langgraph/quickstart) guide. If you don't already have an agent, you can use the [coagent starter](https://github.com/copilotkit/copilotkit/tree/main/examples/coagents-starter) as a starting point as this guide uses it as a starting point. ### Give your agent a tool to call ```python title="agent.py" from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.tools import tool # ... # [!code highlight:6] @tool def get_weather(location: str): """ Get the weather for a given location. """ return f"The weather for {location} is 70 degrees." # ... agent = Agent( model=OpenAIChat(id="gpt-5.4"), tools=[get_weather], # [!code highlight] description="A helpful assistant that can answer questions and provide information.", instructions="Be helpful and friendly. Format your responses using markdown where appropriate.", ) ``` ### Render the tool call in your frontend At this point, your agent will be able to call the `get_weather` tool. Now we just need to add a `useRenderTool` hook to render the tool call in the UI. In order to render a tool call in the UI, the name of the action must match the name of the tool. ```tsx title="app/page.tsx" import { useRenderTool } from "@copilotkit/react-core/v2"; // [!code highlight] // ... const YourMainContent = () => { // ... {/* [!code highlight:12] */} useRenderTool({ name: "get_weather", render: ({status, args}) => { return (

{status !== "complete" && "Calling weather API..."} {status === "complete" && `Called the weather API for ${args.location}.`}

); }, }); // ... } ``` ### Give it a try! Try asking the agent to get the weather for a location. You should see the custom UI component that we added render the tool call and display the arguments that were passed to the tool. ## Default Tool Rendering `useDefaultRenderTool` provides a catch-all renderer for **any tool** that doesn't have a specific `useRenderToolCall` defined. This is useful for: - Displaying all tool calls during development - Rendering MCP (Model Context Protocol) tools - Providing a generic fallback UI for unexpected tools ```tsx title="app/page.tsx" import { useDefaultRenderTool } from "@copilotkit/react-core/v2"; // [!code highlight] // ... const YourMainContent = () => { // ... // [!code highlight:15] useDefaultRenderTool({ render: ({ name, args, status, result }) => { return (

{status === "complete" ? "✓" : "⏳"} {name} {status === "complete" && result && (

{JSON.stringify(result, null, 2)}

)}

); }, }); // ... }; ``` Unlike `useRenderToolCall`, which targets a specific tool by name, `useDefaultRenderTool` catches **all** tools that don't have a dedicated renderer. In v2, use [`useDefaultRenderTool`](/reference/v2/hooks/useDefaultRenderTool) for wildcard fallback rendering, and [`useRenderTool`](/reference/v2/hooks/useRenderTool) for named or wildcard renderer registration. --- ## Source: https://docs.showcase.copilotkit.ai/agno/generative-ui/your-components/display-only # Display-only > Register React components that your agent can render in the chat for Agno. ## What is this? `useComponent` lets you register a React component as a tool your agent can invoke. When the agent calls the tool, CopilotKit renders your component directly in the chat with the tool's arguments as props. This is the simplest form of Generative UI — your agent decides when to show a component, and CopilotKit renders it. No handler logic, no user interaction required. ## When should I use this? Use `useComponent` when you want to: - Display rich UI (cards, charts, tables) inline in the chat - Show structured data from agent responses - Render previews, status indicators, or visual feedback - Let the agent present information beyond plain text For components that need user interaction, see the Interactive or Interrupt-based guides. ## Register a component Use the `useComponent` hook to register a React component. The agent will be able to call it by name, and CopilotKit will render it with the tool arguments as props. ```tsx title="app/page.tsx" import { useComponent } from "@copilotkit/react-core/v2"; // [!code highlight] import { z } from "zod"; const weatherSchema = z.object({ city: z.string().describe("City name"), temperature: z.number().describe("Temperature in Fahrenheit"), condition: z.string().describe("Weather condition"), }); function WeatherCard({ city, temperature, condition, }: z.infer) { return (

{city}

{temperature}°F

{condition}

); } function YourMainContent() { // [!code highlight:9] useComponent({ name: "showWeather", description: "Display a weather card for a city.", parameters: weatherSchema, render: WeatherCard, }); return

{/* ... */}

; } ``` ## Without parameters For simple components that don't need typed parameters: ```tsx useComponent({ name: "showGreeting", render: ({ message }: { message: string }) => (

{message}

), }); ``` ## Scoping to an agent In multi-agent setups, scope a component to a specific agent: ```tsx useComponent({ name: "renderProfile", parameters: z.object({ userId: z.string() }), render: ProfileCard, agentId: "support-agent", }); ``` --- ## Source: https://docs.showcase.copilotkit.ai/agno/generative-ui/your-components/interactive # Interactive > Create components that your agent can use to interact with the user for Agno. --- ## Source: https://docs.showcase.copilotkit.ai/agno/headless-threads # Headless Threads > Build a custom thread UI with useThreads while CopilotKit handles persistence, replay, synchronization, and lifecycle infrastructure. ## What is this? CopilotKit Rich Threads enable persistent, resumable multi-turn conversations. The `useThreads` hook lists, creates, renames, archives, and deletes Enterprise Intelligence Platform threads with realtime synchronization via WebSocket. Threads work with any agent framework — the Enterprise Intelligence Platform stores conversation history server-side, so users can close their browser and pick up where they left off. It does not list or mutate native LangGraph, ADK, or other framework stores unless your backend explicitly bridges those systems. Thread metadata updates (renames, archives, new threads) appear on connected clients without polling. If your app came from a CopilotKit CLI starter, it already includes the prebuilt **[Threads Drawer](/agno/prebuilt-components/copilot-threads-drawer)**. Keep it for the shortest path to a production thread switcher. Use the `useThreads` steps below when adding a custom thread UI to an existing app or replacing the Drawer with your own layout and interactions (including thread **rename**, which the prebuilt Drawer doesn't surface). ## When should I use this? - Your app needs multiple saved conversations per user (like a chat history sidebar) - Users should be able to resume a prior conversation across sessions or devices - You want realtime sync so threads created on one tab appear on another - You need to let users organize conversations by renaming or archiving them ## Prerequisites - A CopilotKit application connected to Enterprise Intelligence - `@copilotkit/react-core` v1.56 or later - A model provider key supported by your runtime For multi-user applications, configure the Runtime to [scope Rich Threads to the signed-in user](/agno/threads-lifecycle#scope-rich-threads-to-the-signed-in-user) before exposing thread lists or lifecycle actions. ## Implementation Threads capture new CopilotKit conversations once your app is connected to Enterprise Intelligence. To move historical Google ADK or LangGraph conversations into the same thread store, start with [Import & Synchronize Thread History](/agno/threads-import), or jump to [Synchronize ADK threads](/google-adk/threads-import) or [Synchronize LangGraph threads](/langgraph-python/threads-import). ### Configure your Runtime with Enterprise Intelligence Your `CopilotRuntime` must be connected to Enterprise Intelligence before the thread UI can list and resume conversations. If your app came from a CLI starter, this Runtime configuration is generated for you. Otherwise, keep your existing Enterprise Intelligence Runtime configuration while adding the headless UI. Thread names are automatically generated by the LLM after the first message — you can disable this with `generateThreadNames: false`. ```typescript title="server.ts" import { CopilotRuntime } from "@copilotkit/runtime"; const runtime = new CopilotRuntime({ agents: { default: agent, }, // Thread names are auto-generated by default. // Set to false to disable: // generateThreadNames: false, // Optional: tune thread lock behavior // lockTtlSeconds: 20, // Lock TTL (default 20s, max 3600s) // lockHeartbeatIntervalSeconds: 15, // Heartbeat interval (default 15s, max 3000s) // lockKeyPrefix: "my-app", // Custom Redis key prefix for the lock }); ``` CLI-created starters write the cloud-hosted platform URLs and project-scoped `INTELLIGENCE_API_KEY` to `.env`; keep that key server-side. Existing Intelligence-enabled apps should keep their current server-side Runtime configuration. Production self-hosting uses the same React APIs and is deployed with CopilotKit Engineering through [Self-Hosting Enterprise Intelligence](/agno/premium/self-hosting). **Thread lock options:** When an agent run starts, the runtime acquires a lock on the thread to prevent concurrent runs. You can tune this behavior: | Option | Default | Max | Description | |--------|---------|-----|-------------| | `lockTtlSeconds` | `20` | `3600` (1 hour) | How long the lock is held before it expires automatically. | | `lockHeartbeatIntervalSeconds` | `15` | `3000` (50 min) | How often the runtime renews the lock during a run. | | `lockKeyPrefix` | — | — | Custom Redis key prefix for the thread lock. Useful when multiple apps share a Redis instance. | ### List and manage threads with useThreads Use the `useThreads` hook to fetch and manage threads for a specific agent. The hook returns the thread list, loading state, and mutation methods. ```tsx title="ThreadSidebar.tsx" import { useThreads } from "@copilotkit/react-core/v2"; // [!code highlight] function ThreadSidebar() { const { // [!code highlight:6] threads, isLoading, renameThread, archiveThread, deleteThread, } = useThreads({ agentId: "my-agent" }); if (isLoading) return

; return (

{threads.map((thread) => (

{thread.name ?? "New conversation"}

))}

); } ``` The `threads` array is sorted by most recently updated first and stays synchronized in realtime — new threads from other tabs or devices appear automatically. **Archive vs. delete:** `archiveThread` is a soft delete — the thread stays in the database but is hidden from the list by default. Pass `includeArchived: true` to show archived threads. `deleteThread` is permanent and irreversible. Neither has a built-in confirmation dialog — add your own if needed. ### Switch between threads When a user selects a thread, pass its `threadId` to your chat component. The chat clears the current messages, fetches the selected thread's history, and replays it. If the agent is still running on that thread, the chat picks up the live stream. ```tsx title="App.tsx" import { CopilotChat } from "@copilotkit/react-core/v2"; // [!code highlight] import { useState } from "react"; function App() { const [activeThreadId, setActiveThreadId] = useState(); return (

{/* [!code highlight] */}

); } ``` When `threadId` changes, the chat component automatically loads the selected thread's history and reconnects to the agent's stream. If the agent is still running on that thread, the chat picks up the live stream. When you pass an explicit CopilotKit `threadId`, CopilotKit forwards it to your backend as the AG-UI `threadId`. A LangGraph backend can use that value directly, or map it to its own checkpoint/thread identifier, when you implement that mapping. LangGraph Platform thread IDs must be UUIDs. CopilotKit `useThreads` manages Enterprise Intelligence Platform thread records; rename, archive, and delete operations do not update LangGraph stores unless your backend adds that bridge. When you pass an explicit CopilotKit `threadId`, CopilotKit forwards it to your backend as the AG-UI `threadId`. An ADK backend can map that value to an ADK session ID, but the current showcase uses in-memory ADK services, so those sessions are not durable by default. Durable ADK session persistence requires configuring a separate ADK session service. CopilotKit `useThreads` manages Enterprise Intelligence Platform thread records, not ADK's native session store. ### Add pagination for large thread lists For users with many conversations, use the `limit` parameter to enable cursor-based pagination. ```tsx title="ThreadSidebar.tsx" const { threads, hasMoreThreads, isFetchingMoreThreads, fetchMoreThreads, } = useThreads({ agentId: "my-agent", limit: 20, // [!code highlight] }); // In your JSX: {hasMoreThreads && ( )} ``` ## Next steps - **Prebuilt UI:** [Threads Drawer](/agno/prebuilt-components/copilot-threads-drawer) — the drop-in thread switcher ([React reference](/reference/components/CopilotThreadsDrawer)) - **Thread architecture:** [Threads & Persistence Architecture](/agno/premium/threads-explained) — event replay model and WebSocket sync - **Production self-hosting:** [Self-Hosting Enterprise Intelligence](/agno/premium/self-hosting) — run the Threads platform inside your infrastructure with CopilotKit Engineering - **API reference:** [useThreads](/reference/hooks/useThreads) — parameters, return values, types --- ## Source: https://docs.showcase.copilotkit.ai/agno/human-in-the-loop # Human-in-the-Loop > Create frontend tools and use them within your Agno agent for human-in-the-loop interactions. ## What is this? Frontend tools enable you to define client-side functions that your Agno agent can invoke, with execution happening entirely in the user's browser. When your agent calls a frontend tool, the logic runs on the client side, giving you direct access to the frontend environment. This can be utilized to let [your agent control the UI](/agno/frontend-tools), [generative UI](/agno/frontend-tools), or for Human-in-the-loop interactions. In this guide, we cover the use of frontend tools for Human-in-the-loop. ## When should I use this? Use frontend tools when you need your agent to interact with client-side primitives such as: - Reading or modifying React component state - Accessing browser APIs like localStorage, sessionStorage, or cookies - Triggering UI updates or animations - Interacting with third-party frontend libraries - Performing actions that require the user's immediate browser context ## Implementation ### Define the frontend tool in your Agno agent In your Agno agent, define a tool with the `@tool(external_execution=True)` decorator: ```python title="tools/frontend.py" from agno.tools import tool @tool(external_execution=True) def offerOptions(option_1: str, option_2: str): """ Give the user a choice between two options and have them select one. Args: option_1: str: The first option option_2: str: The second option """ ``` Register the tool with your agent: ```python title="agent.py" from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.os import AgentOS from agno.os.interfaces.agui import AGUI from tools.frontend import offerOptions agent = Agent( model=OpenAIChat(id="gpt-5.4"), tools=[offerOptions], description="A helpful assistant that can answer questions and provide information.", instructions="Be helpful and friendly. Format your responses using markdown where appropriate.", ) agent_os = AgentOS(agents=[agent], interfaces=[AGUI(agent=agent)]) app = agent_os.get_app() if __name__ == "__main__": agent_os.serve(app="main:app", port=8000, reload=True) ``` ### Create a frontend human-in-the-loop tool Frontend tools can be leveraged in a variety of ways. One of those ways is to have a human-in-the-loop flow where the response of the tool is gated by a user's decision. In this example we will simulate an "approval" flow for executing a command. Use the `useHumanInTheLoop` hook to create a tool that prompts the user for approval. ```tsx title="page.tsx" import { useHumanInTheLoop } from "@copilotkit/react-core/v2" // [!code highlight] import { z } from "zod" export function Page() { // ... useHumanInTheLoop({ name: "offerOptions", description: "Give the user a choice between two options and have them select one.", parameters: z.object({ option_1: z.string().describe("The first option"), option_2: z.string().describe("The second option"), }), render: ({ args, respond }) => { if (!respond) return <>; return (

{/* [!code highlight:2] */}

); }, }); // ... } ``` ### Try it out! You've now given your agent the ability to show the user two options and have them select one. The agent will then be aware of the user's choice and can use it in subsequent steps. ``` Can you show me two good options for a restaurant name? ```` --- ## Source: https://docs.showcase.copilotkit.ai/agno/inspector # Inspector > Inspector for debugging actions, readables, agent status, messages, and context.

{meta.title}

Your App

{city}

Your App

Your App

Agent State

Weather in {location}

Agent Status

Agent State

Conversation

Your main content

Your main content

Your App

Your App

{city}

Agent State

Weather in {location}

Agent Status

Agent State

Conversation

Your App

Approve {{ call.args.action ?? "this action" }}?

{{ request.title ?? "Review required" }}