### Install Dependencies and Setup

Source: https://github.com/copilotkit/opengenerativeui/blob/main/README.md

Use these commands to install dependencies and set up the project environment. Ensure you edit the .env file with your OpenAI API key.

```bash
make setup    # Install deps + create .env template
# Edit apps/agent/.env with your real OpenAI API key
make dev      # Start all services
```

--------------------------------

### Install and Run MCP Server

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Steps to install dependencies and start the development server for the MCP package. Includes a health check command.

```bash
cd apps/mcp
pnpm install
pnpm dev
# → MCP server running on http://localhost:3100/mcp

curl http://localhost:3100/health
# → {"status":"ok"}
```

--------------------------------

### Install Dependencies and Setup

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CONTRIBUTING.md

Use the Makefile to install dependencies and set up the environment, or perform these steps manually. Ensure you add your OpenAI API key to the agent's .env file.

```bash
make setup    # Installs deps + creates .env template
```

```bash
pnpm install
echo 'OPENAI_API_KEY=your-key-here' > apps/agent/.env
```

--------------------------------

### Agent Service Build and Start Commands

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/deployment.md

Commands to install dependencies and start the Python agent service. Ensure the OPENAI_API_KEY environment variable is set.

```bash
cd apps/agent
pip install uv
uv sync
uv run uvicorn main:app --host 0.0.0.0 --port 8123
```

--------------------------------

### Install and Run Monorepo

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Commands to clone the repository, install dependencies, set up environment variables, and start the development servers for the Next.js frontend and FastAPI backend.

```bash
git clone https://github.com/CopilotKit/OpenGenerativeUI.git
cd OpenGenerativeUI

# Install all deps + create apps/agent/.env template
make setup

# Edit apps/agent/.env — add OPENAI_API_KEY and optionally LLM_MODEL
echo "OPENAI_API_KEY=sk-..." > apps/agent/.env
echo "LLM_MODEL=gpt-5.4-2026-03-05" >> apps/agent/.env

# Start all services (Next.js :3000, FastAPI :8123)
make dev

# Start individually
make dev-app     # Next.js frontend only
make dev-agent   # Python agent only
make dev-mcp     # MCP server only (port 3100)
```

--------------------------------

### Build and Start MCP Server for Production

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Commands to build the project for production and start the server.

```bash
pnpm build
pnpm start
```

--------------------------------

### Start Individual Services

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/getting-started.md

Optionally, start only the frontend, agent, or MCP server individually using specific make commands.

```bash
make dev-app     # Frontend only
make dev-agent   # Agent only
make dev-mcp     # MCP server only
```

--------------------------------

### Manual Deployment: Frontend (Node)

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Instructions for manually deploying the frontend service using Node.js and pnpm. This includes installing dependencies, building the application, and starting the server, while setting the `LANGGRAPH_DEPLOYMENT_URL` environment variable.

```bash
# Frontend (Node)
# From repo root:
corepack enable && pnpm install
LANGGRAPH_DEPLOYMENT_URL=http://your-agent-host:8123 \
  pnpm --filter @repo/app build && \
  pnpm --filter @repo/app start
```

--------------------------------

### Install Frontend Packages with npm

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/bring-to-your-app.md

Install the necessary CopilotKit and Zod packages for your React frontend.

```bash
npm install @copilotkit/react-core @copilotkit/runtime zod
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/getting-started.md

Clone the OpenGenerativeUI repository and install all project dependencies using the provided make command. This also sets up the .env file.

```bash
git clone https://github.com/CopilotKit/OpenGenerativeUI.git
cd OpenGenerativeUI

# Install all dependencies and create .env
make setup
```

--------------------------------

### Run the Project

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CONTRIBUTING.md

Start all project services (frontend, agent, mcp) using the Makefile, or run them individually. Alternatively, use pnpm commands for more granular control.

```bash
make dev      # Start all services (frontend + agent + mcp)
```

```bash
make dev-app    # Next.js frontend on http://localhost:3000
```

```bash
make dev-agent  # LangGraph agent on http://localhost:8123
```

```bash
make dev-mcp    # MCP server
```

```bash
pnpm dev          # All services
```

```bash
pnpm dev:app      # Frontend only
```

```bash
pnpm dev:agent    # Agent only
```

--------------------------------

### Frontend Service Build and Start Commands

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/deployment.md

Commands to build and start the Node.js frontend service. The LANGGRAPH_DEPLOYMENT_URL must point to the agent service host and port.

```bash
# From repo root
corepack enable
pnpm install
pnpm --filter @repo/app build
LANGGRAPH_DEPLOYMENT_URL=http://your-agent-host:8123 pnpm --filter @repo/app start
```

--------------------------------

### Start MCP Server

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CLAUDE.md

Starts the MCP (Model Context Protocol) server. This is part of the backend infrastructure.

```bash
pnpm dev:mcp    # MCP server
```

--------------------------------

### Start Next.js Frontend

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CLAUDE.md

Starts the Next.js frontend application, typically accessible on port 3000. Use this command for frontend-specific development.

```bash
# Start individually
pnpm dev:app    # Next.js frontend on port 3000
```

--------------------------------

### Run Development Server

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/getting-started.md

Start the frontend and agent services simultaneously using the make dev command. This makes the application accessible at http://localhost:3000 and the agent at http://localhost:8123.

```bash
# Start all services (frontend + agent)
make dev
```

--------------------------------

### Install Python Agent Dependencies

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/bring-to-your-app.md

Install the required Python packages for setting up the CopilotKit agent and LangGraph.

```bash
pip install copilotkit langgraph langchain langchain-openai fastapi uvicorn ag-ui-langgraph deepagents
```

--------------------------------

### Start MCP HTTP Server

Source: https://github.com/copilotkit/opengenerativeui/blob/main/README.md

Start the standalone Model Context Protocol server for self-hosting. This server provides the design system, skill instructions, and an HTML document assembler.

```bash
cd apps/mcp && pnpm dev
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CLAUDE.md

Installs all project dependencies across the monorepo using pnpm. This command should be run at the root of the project.

```bash
# Install dependencies (all apps)
pnpm install
```

--------------------------------

### Start All Monorepo Apps

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CLAUDE.md

Starts all applications within the monorepo, including the Next.js frontend, LangGraph agent, and MCP server. This is a convenient command for running the entire project.

```bash
# Start all apps (app, agent, mcp)
pnpm dev
```

--------------------------------

### Start MCP Server (Development)

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/mcp-integration.md

Use this command to start the MCP server with hot reload for development. The server will be available at http://localhost:3100.

```bash
make dev-mcp
```

--------------------------------

### Assemble Document Tool Example

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Example of using the `assemble_document` tool to wrap an HTML fragment with OpenGenerativeUI's design system. The output is a complete HTML document.

```javascript
const result = await client.callTool("assemble_document", {
  title: "Interactive Algorithm Visualizer",
  description: "Step-by-step visualization of the quicksort algorithm",
  html: `
    <div id="viz">
      <p>Click to start visualization</p>
      <script>
        // Your visualization code here
      </script>
    </div>
  `
});

// result.content[0].text is a complete HTML document
// Render in: <iframe sandbox="allow-scripts allow-same-origin" srcdoc={result.content[0].text} />
```

--------------------------------

### Install and Run MCP Node.js Application

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Install the MCP package globally or locally and run the server. Environment variables can be used to configure the port and allowed origins.

```bash
# Install globally or locally
npm install -g open-generative-ui-mcp

# Run
MCP_PORT=3100 ALLOWED_ORIGINS="*" open-generative-ui-mcp

# Or with node
node dist/index.js
```

--------------------------------

### Manual Deployment: MCP Server (Optional)

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Steps to build and run the MCP server manually. This involves navigating to the MCP directory, building the project, and starting the Node.js server on a specified port.

```bash
# MCP Server (optional)
cd apps/mcp && pnpm build
MCP_PORT=3100 node dist/index.js
```

--------------------------------

### Manual Deployment: Agent (Python)

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Steps for manually deploying the agent service using Python. This involves navigating to the agent directory, installing dependencies with `uv`, and running the Uvicorn server.

```bash
# Agent (Python)
cd apps/agent
pip install uv && uv sync
OPENAI_API_KEY=sk-... uv run uvicorn main:app --host 0.0.0.0 --port 8123
```

--------------------------------

### Start LangGraph Agent

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CLAUDE.md

Starts the LangGraph agent, typically accessible on port 8123. Use this command for backend agent development.

```bash
pnpm dev:agent  # LangGraph agent on port 8123
```

--------------------------------

### Add a New Weather Tool

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/agent-tools.md

Example of creating a new tool for fetching weather data and registering it with the agent. This demonstrates the process of extending agent capabilities with custom tools.

```python
from langchain.tools import tool

@tool
def get_weather(city: str):
    """Get the current weather for a city."""
    # Your implementation here
    return {"city": city, "temp": 72, "condition": "sunny"}
```

```python
from src.weather import get_weather

agent = create_deep_agent(
    tools=[query_data, plan_visualization, *todo_tools, get_weather],
    ...
)
```

--------------------------------

### MCP Key Files

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/architecture.md

Lists key files in the MCP server, including server implementation, renderer, skill loader, and HTTP server setup.

```markdown
| File | Purpose |
|------|---------|
| `src/server.ts` | MCP resources, prompts, and tools |
| `src/renderer.ts` | HTML document assembly with design system |
| `src/skills.ts` | Skill file loader |
| `src/index.ts` | HTTP server |
| `src/stdio.ts` | Stdio transport for Claude Desktop |

```

--------------------------------

### Read Skill List Resource

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Example using curl to read the list of available skills from the MCP server via the `skills://list` resource URI.

```bash
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "resources/read",
    "params": { "uri": "skills://list" }
  }'
```

--------------------------------

### HTML Buttons for sendPrompt()

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/skills/agent-skills-vol2.txt

Provides example HTML buttons that trigger the `sendPrompt()` function with specific user messages. Use for actions like drill-downs or follow-up questions.

```html
<button onclick="sendPrompt('Break down Q4 revenue by region')">
  Drill into Q4 ↗
</button>
<button onclick="sendPrompt('Explain what shear force is')">
  Learn about shear ↗
</button>
```

--------------------------------

### MCP Server configuration for Claude Desktop (stdio transport)

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Example JSON configuration for Claude Desktop to use the MCP server via stdio transport. Ensure the `cwd` path is absolute.

```json
// Claude Desktop config (claude_desktop_config.json) — stdio transport:
{
  "mcpServers": {
    "open-generative-ui": {
      "command": "node",
      "args": ["dist/stdio.js"],
      "cwd": "/absolute/path/to/apps/mcp"
    }
  }
}
```

--------------------------------

### CopilotKit Provider Setup

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Wrap your entire application with the `<CopilotKit>` provider, specifying the runtime URL for the API route. This enables React hooks to connect to the agent backend and manages the agent's connection lifecycle.

```APIDOC
## CopilotKit Provider Setup

### Description
Wrap the entire app with `<CopilotKit>` pointing at the Next.js API route. Import CopilotKit v2 styles. The provider connects React hooks to the agent backend and manages the agent connection lifecycle.

### Code Example
```tsx
// apps/app/src/app/layout.tsx
"use client";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-core/v2/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CopilotKit runtimeUrl="/api/copilotkit">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}
```
```

--------------------------------

### Chart.js Line Chart

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/skills/master-agent-playbook.txt

An example of creating a responsive line chart using Chart.js. It includes dynamic color adjustments for dark mode and basic chart configuration.

```html
<canvas id="myChart" style="width:100%;max-height:400px"></canvas>
<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js"></script>
<script>
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const textColor = isDark ? '#c2c0b6' : '#3d3d3a';
const gridColor = isDark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.06)';

new Chart(document.getElementById('myChart'), {
  type: 'line',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
    datasets: [{
      label: 'Revenue',
      data: [30, 45, 28, 62],
      borderColor: '#534AB7',
      backgroundColor: 'rgba(83,74,183,0.1)',
      fill: true,
      tension: 0.3
    }]
  },
  options: {
    responsive: true,
    plugins: {
      legend: { labels: { color: textColor } }
    },
    scales: {
      x: { ticks: { color: textColor }, grid: { color: gridColor } },
      y: { ticks: { color: textColor }, grid: { color: gridColor } }
    }
  }
});
</script>
```

--------------------------------

### Get MCP Prompt Template

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Fetch a pre-composed prompt template for a specific task, such as creating an SVG diagram. This prompt includes full skill instructions and can be directly injected into an LLM conversation. Use the `prompts/get` method with the prompt name.

```bash
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"prompts/get","params":{"name":"create_svg_diagram"}}'
```

--------------------------------

### Setup CopilotKit Provider in Next.js Layout

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Wrap your entire application with the `CopilotKit` provider and import its v2 styles. This component connects React hooks to your agent backend and manages the agent's connection lifecycle.

```tsx
"use client";
import { CopilotKit } from "@copilotkit/react-core";
import "@copilotkit/react-core/v2/styles.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <CopilotKit runtimeUrl="/api/copilotkit">
          {children}
        </CopilotKit>
      </body>
    </html>
  );
}
```

--------------------------------

### Deploy OpenGenerativeUI Agent using Render

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Instructions for deploying the OpenGenerativeUI agent to Render using a one-click blueprint. This involves forking the repository, creating a Render blueprint, and adding the OPENAI_API_KEY as a secret. The `render.yaml` file automatically configures the agent and frontend services.

```bash
# 1. Fork https://github.com/CopilotKit/OpenGenerativeUI
# 2. Create a Blueprint on render.com, connect your fork
# 3. Add OPENAI_API_KEY as a secret
# 4. Deploy — render.yaml creates both services automatically

# render.yaml defines:
# - Agent (Python 3.12): uvicorn main:app, health GET /health
# - Frontend (Node 22): pnpm build + start, health GET /api/health
# - LANGGRAPH_DEPLOYMENT_URL auto-injected via fromService
```

--------------------------------

### Build and Lint Project

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/getting-started.md

Utilize make commands to build all applications, lint the code, clean build artifacts, or display all available commands.

```bash
make build   # Build all apps
make lint    # Lint all apps
make clean   # Clean build artifacts
make help    # Show all available commands
```

--------------------------------

### Chart.js Custom Legend Example (HTML)

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/skills/agent-skills-vol2.txt

Provides an example of a custom HTML legend for a Chart.js chart, using flexbox for layout and custom styling for legend items.

```html
<div style="display: flex; flex-wrap: wrap; gap: 16px;
            margin-bottom: 8px; font-size: 12px;
            color: var(--color-text-secondary);">
  <span style="display: flex; align-items: center; gap: 4px;">
    <span style="width: 10px; height: 10px; border-radius: 2px;
                 background: #534AB7;"></span>Series A — 65%
  </span>
  <span style="display: flex; align-items: center; gap: 4px;">
    <span style="width: 10px; height: 10px; border-radius: 2px;
                 background: #0F6E56;"></span>Series B — 35%
  </span>
</div>
```

--------------------------------

### MCP Server HTTP server start and health check

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Commands to start the MCP server in HTTP mode and perform a health check. Ensure you are in the `apps/mcp` directory before running.

```bash
# Start HTTP server
cd apps/mcp && pnpm dev
# → MCP server running at http://localhost:3100/mcp

# Build for production
pnpm build && pnpm start

# Health check
curl http://localhost:3100/health
# → {"status":"ok"}
```

--------------------------------

### Read Specific Skill Resource

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Example using curl to retrieve the full text content of a specific skill, such as `master-agent-playbook`, from the MCP server.

```bash
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "resources/read",
    "params": { "uri": "skills://master-agent-playbook" }
  }'
```

--------------------------------

### Docker Deployment: Frontend

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Build and run the frontend service using Docker. This command builds a Docker image for the application and then runs it as a container, mapping port 3000 and setting the `LANGGRAPH_DEPLOYMENT_URL` environment variable.

```bash
# Docker (frontend only):
docker build -f docker/Dockerfile.app -t open-generative-ui-app .
docker run -p 3000:3000 -e LANGGRAPH_DEPLOYMENT_URL=http://agent:8123 open-generative-ui-app
```

--------------------------------

### Build, Lint, and Clean

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CONTRIBUTING.md

Utilize Makefile commands to build all project applications, run linters, or clean build artifacts.

```bash
make build    # Build all apps
```

```bash
make lint     # Lint all apps
```

```bash
make clean    # Clean build artifacts
```

--------------------------------

### Implement Get Todos Tool

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CLAUDE.md

A tool to retrieve the current list of todos from the agent's state. This is used by the agent to access the todo data.

```python
@tool
def get_todos(runtime: ToolRuntime):
    """Get the current todos."""
    return runtime.state.get("todos", [])
```

--------------------------------

### Configure Claude Desktop (stdio transport)

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Configuration for Claude Desktop to use the OpenGenerativeUI MCP server via stdio transport. Requires building the project first.

```bash
pnpm build
```

```json
{
  "mcpServers": {
    "open-generative-ui": {
      "command": "node",
      "args": ["dist/stdio.js"],
      "cwd": "/absolute/path/to/apps/mcp"
    }
  }
}
```

--------------------------------

### Build MCP Server for Claude Desktop

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/mcp-integration.md

Before using the MCP server with Claude Desktop, build the project by navigating to the MCP application directory and running 'pnpm build'.

```bash
cd apps/mcp && pnpm build
```

--------------------------------

### Example PieChart and BarChart data structures

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

These objects represent the data structures agents use to call the PieChart and BarChart components. They include title, description, and data points.

```typescript
const examplePieChartCall = {
  title: "Browser Market Share 2024",
  description: "Distribution of desktop browser usage globally",
  data: [
    { label: "Chrome", value: 65.2 },
    { label: "Safari", value: 18.9 },
    { label: "Firefox", value: 6.6 },
    { label: "Edge", value: 4.8 },
    { label: "Other", value: 4.5 },
  ],
};

// Agent calls barChart with these parameters — frontend renders BarChart:
const exampleBarChartCall = {
  title: "Monthly Revenue Q1 2024",
  description: "Revenue by product line, January–March",
  data: [
    { label: "Jan", value: 42500 },
    { label: "Feb", value: 38200 },
    { label: "Mar", value: 51800 },
  ],
};
```

--------------------------------

### Single-Line Node SVG Component

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/agent/skills/svg-diagrams/SKILL.md

Example of a basic single-line node component in SVG. It includes a rectangle for the background and text for the title, with specific styling for size, color, and alignment.

```svg
<g>
  <rect x="100" y="20" width="180" height="44" rx="8"
        fill="#EEEDFE" stroke="#534AB7" stroke-width="0.5"/>
  <text x="190" y="42" text-anchor="middle" dominant-baseline="central"
        font-size="14" font-weight="500" fill="#3C3489">Node title</text>
</g>
```

--------------------------------

### MCP prompt templates

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

Retrieve pre-composed prompts that include full skill instructions, useful for easily loading visualization rules in environments like Claude Desktop.

```APIDOC
## MCP prompt templates

### Description
Access pre-composed prompts that inject complete skill instructions into an LLM conversation. These are particularly useful for quickly setting up visualization rules in applications like Claude Desktop.

### Method
`POST /mcp` with `prompts/get` method

### Parameters
#### Prompt Get Parameters
- **name** (string) - Required - The name of the prompt template to retrieve (e.g., `create_widget`, `create_svg_diagram`, `create_visualization`).

### Request Example
```bash
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"prompts/get","params":{"name":"create_svg_diagram"}}'
```

### Response
- **(object)** - An object containing a message with the role and content of the prompt template. Typically:
  ```json
  {
    "role": "user",
    "content": {
      "type": "text",
      "text": "<full skill text>"
    }
  }
  ```
```

--------------------------------

### State Synchronization Flow

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/architecture.md

Illustrates the bidirectional state flow between the frontend and the agent using CopilotKit, showing how state updates are synchronized.

```text
Frontend                          Agent
────────                          ─────
agent.state.todos    ◄────────    AgentState.todos
agent.setState(...)  ────────►    Command(update={...})

```

--------------------------------

### Clone the Repository

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CONTRIBUTING.md

Clone the Open Generative UI repository to your local machine after forking it.

```bash
git clone https://github.com/<your-GitHub-username>/OpenGenerativeUI
```

--------------------------------

### Create FastAPI Python Agent with CopilotKit Middleware

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/bring-to-your-app.md

Set up a FastAPI application with a LangGraph agent, including CopilotKit middleware and a health check endpoint. This example uses `create_deep_agent` and `add_langgraph_fastapi_endpoint`.

```python
# agent/main.py
import os
from dotenv import load_dotenv
from fastapi import FastAPI
from copilotkit import CopilotKitMiddleware, LangGraphAGUIAgent
from ag_ui_langgraph import add_langgraph_fastapi_endpoint
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

load_dotenv()

agent = create_deep_agent(
    model=ChatOpenAI(model=os.environ.get("LLM_MODEL", "gpt-5.4-2026-03-05")),
    tools=[],  # add your tools here
    middleware=[CopilotKitMiddleware()],
    system_prompt="You are a helpful assistant.",
)

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

add_langgraph_fastapi_endpoint(
    app=app,
    agent=LangGraphAGUIAgent(
        name="my_agent",
        description="My agent",
        graph=agent,
    ),
    path="/",
)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="0.0.0.0", port=8123, reload=True)
```

--------------------------------

### Step-Through Explainer UI Template

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/skills/master-agent-playbook.txt

A reusable HTML, CSS, and JavaScript template for creating step-by-step explainers. It manages content display, navigation, and visual indicators for each step.

```html
<style>
  .step-nav {
    display: flex;
    align-items: center;
    gap: 12px;
    margin: 12px 0;
    font-size: 13px;
  }
  .step-nav button {
    padding: 6px 16px;
    border: 1px solid var(--color-border-tertiary, #ddd);
    border-radius: 8px;
    background: var(--color-background-secondary, #f5f5f5);
    color: var(--color-text-primary, #333);
    cursor: pointer;
    font-size: 13px;
  }
  .step-nav button:hover {
    background: var(--color-background-tertiary, #eee);
  }
  .dot { width: 8px; height: 8px; border-radius: 50%;
         background: var(--color-border-tertiary, #ccc);
         transition: background 0.2s; }
  .dot.active { background: var(--color-text-info, #185FA5); }
  .step-content { min-height: 300px; }
</style>

<div class="step-content" id="step-display">
  <!-- SVG or HTML content per step, swapped by JS -->
</div>

<div class="step-nav">
  <button onclick="prevStep()">Previous</button>
  <div id="dots" style="display:flex;gap:6px"></div>
  <button onclick="nextStep()">Next</button>
  <span id="step-label" style="margin-left:auto;
        color:var(--color-text-secondary,#888)">Step 1 of 4</span>
</div>

<script>
const steps = [
  { title: "Step 1", svg: `<svg>...</svg>`, desc: "What happens first" },
  { title: "Step 2", svg: `<svg>...</svg>`, desc: "Then this" },
  // ...
];
let current = 0;

function render() {
  document.getElementById('step-display').innerHTML = steps[current].svg;
  document.getElementById('step-label').textContent =
    `Step ${current + 1} of ${steps.length}`;
  document.querySelectorAll('.dot').forEach((d, i) =>
    d.classList.toggle('active', i === current));
}

function nextStep() { current = (current + 1) % steps.length; render(); }
function prevStep() { current = (current - 1 + steps.length) % steps.length; render(); }

// Build dots
const dotsEl = document.getElementById('dots');
steps.forEach(() => {
  const d = document.createElement('div');
  d.className = 'dot';
  dotsEl.appendChild(d);
});
render();
</script>
```

--------------------------------

### Register a Custom Status Card Component

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/bring-to-your-app.md

Use the `useComponent` hook to register a new UI component that your agent can render. This example registers a `statusCard` component with defined parameters and a React rendering function.

```tsx
import { useComponent } from "@copilotkit/react-core/v2";
import { z } from "zod";

useComponent({
  name: "statusCard",
  description: "Show a status card with a title and message.",
  parameters: z.object({
    title: z.string(),
    message: z.string(),
    type: z.enum(["info", "success", "error"]),
  }),
  render: ({ title, message, type }) => (
    <div className={`card card-${type}`}>
      <h3>{title}</h3>
      <p>{message}</p>
    </div>
  ),
});
```

--------------------------------

### Build Docker Image for MCP Server

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/mcp/README.md

Command to build a Docker image for the OpenGenerativeUI MCP server.

```bash
docker build -t open-generative-ui-mcp .

```

--------------------------------

### Define Todo State Schema and Management Tool (Python)

Source: https://github.com/copilotkit/opengenerativeui/blob/main/CLAUDE.md

Defines the data structure for a todo item and a tool to manage the list of todos within the agent. This is part of the agent's backend setup.

```python
class Todo(TypedDict):
    id: str
    title: str
    description: str
    emoji: str
    status: Literal["pending", "completed"]

class AgentState(TypedDict):
    todos: list[Todo]

@tool
def manage_todos(todos: list[Todo], runtime: ToolRuntime) -> Command:
    """Manage the current todos."""
    return Command(update={"todos": todos, ...})
```

--------------------------------

### Plan Visualization Before Rendering with @tool

Source: https://context7.com/copilotkit/opengenerativeui/llms.txt

This tool must be called before any visual response like `widgetRenderer`, `pieChart`, or `barChart`. It documents the approach, technology choice, and key elements, which are then displayed as a `PlanCard` on the frontend.

```python
from langchain.tools import tool

@tool
def plan_visualization(
    approach: str,
    technology: str,
    key_elements: list[str]
) -> str:
    """Plan a visualization before building it. MUST be called before
    widgetRenderer, pieChart, or barChart. Outlines the approach, technology
    choice, and key elements.

    Args:
        approach: One sentence describing the visualization strategy.
        technology: Primary technology, e.g. "Three.js", "D3.js", "Chart.js",
            "inline SVG", "HTML + Canvas".
        key_elements: 2-4 concise bullet points describing what will be built.
    """
    elements = "\n".join(f"  - {e}" for e in key_elements)
    return f"Plan: {approach}\nTech: {technology}\n{elements}"
```

--------------------------------

### Three.js Aircraft Orientation Example

Source: https://github.com/copilotkit/opengenerativeui/blob/main/apps/agent/skills/advanced-visualization/SKILL.md

Demonstrates correct Three.js object orientation for aircraft components within a right-handed Y-up coordinate system. Pay close attention to the Z-axis for fuselage length and X-axis for wingspan.

```javascript
// Correct aircraft orientation example:
// Fuselage along Z
const fuselage = new THREE.Mesh(
  new THREE.CylinderGeometry(0.15, 0.08, 2.0, 12),
  material
);
fuselage.rotation.x = Math.PI / 2; // CylinderGeometry default is Y-up, rotate to Z-forward

// Wings along X
const wing = new THREE.Mesh(
  new THREE.BoxGeometry(2.5, 0.03, 0.4), // wide X, thin Y, short Z
  material
);

// Vertical stabilizer along Y
const tailFin = new THREE.Mesh(
  new THREE.BoxGeometry(0.03, 0.4, 0.3), // thin X, tall Y, short Z
  material
);
tailFin.position.set(0, 0.2, 0.9); // above and behind
```

--------------------------------

### Use Agent State in React Component

Source: https://github.com/copilotkit/opengenerativeui/blob/main/docs/bring-to-your-app.md

Access and manipulate the agent's state within a React component using the `useAgent` hook. This example displays a list of items and allows toggling their 'done' status.

```tsx
import { useAgent, CopilotChat } from "@copilotkit/react-core/v2";

function MyPage() {
  const { agent } = useAgent();
  const items = agent.state?.items || [];

  return (
    <div>
      <ul>
        {items.map(item => (
          <li key={item.id}>
            <input
              type="checkbox"
              checked={item.done}
              onChange={() => {
                const updated = items.map(i =>
                  i.id === item.id ? { ...i, done: !i.done } : i
                );
                agent.setState({ items: updated });
              }}
            />
            {item.name}
          </li>
        ))}
      </ul>
      <CopilotChat />
    </div>
  );
}
```