CopilotKit Frontend for a 10xGraph Agent over AG-UI

{
  "agent": "graph.agent:app",
  "env": ".env",
  "auth": null,
  "remote_tools": [],
  "ag_ui": {
    "enabled": true,
    "allow_client_tools": true
  },
  "thread_name_generator": null
}

"""Main assistant (OpenAI gpt-5-mini): a task-board agent served over AG-UI.

Loaded by 10xgraph.json ("agent": "graph.agent:app"). The tools change `state`, and the API
server sends the changed fields to CopilotKit as STATE_SNAPSHOT events.
"""

from dotenv import load_dotenv

from graph.planner import plan_steps
from graph.state import BoardState
from tenxgraph.prebuilt.agent import ReactAgent
from tenxgraph.storage.checkpointer import InMemoryCheckpointer
from tenxgraph.utils import interrupt


load_dotenv()

_STATUSES = ("todo", "doing", "done")


def _new_task(state: BoardState, title: str, priority: str) -> dict:
    task = {"id": state.next_id, "title": title, "status": "todo", "priority": priority}
    state.next_id += 1
    state.tasks.append(task)
    return task


def add_task(title: str, priority: str = "medium", state: BoardState | None = None) -> str:
    """Add one task to the board. priority is low, medium or high."""
    if state is None:
        return "No board state available."
    task = _new_task(state, title, priority)
    return f"Added task #{task['id']}: {title}"


def set_task_status(task_id: int, status: str, state: BoardState | None = None) -> str:
    """Move a task to todo, doing or done."""
    if state is None:
        return "No board state available."
    if status not in _STATUSES:
        return f"Status must be one of {', '.join(_STATUSES)}."
    for task in state.tasks:
        if task["id"] == task_id:
            task["status"] = status
            return f"Task #{task_id} is now {status}."
    return f"No task with id {task_id}."


async def plan_goal(goal: str, state: BoardState | None = None) -> str:
    """Ask the planner agent to split a goal into steps and add them as tasks."""
    if state is None:
        return "No board state available."
    steps = await plan_steps(goal)
    for step in steps:
        _new_task(state, step, "medium")
    return f"Planner added {len(steps)} tasks: " + "; ".join(steps)


def clear_done_tasks(state: BoardState | None = None) -> str:
    """Delete every task marked done. Asks the user for approval first."""
    if state is None:
        return "No board state available."
    done = [t for t in state.tasks if t["status"] == "done"]
    if not done:
        return "There are no finished tasks to clear."
    # interrupt() pauses the run. The AG-UI endpoint ends it with an interrupt outcome, and
    # CopilotKit's useInterrupt renders the approval. The tool runs again on resume, so nothing
    # with side effects may come before this call.
    decision = interrupt(
        value={"count": len(done), "titles": [t["title"] for t in done]},
        message=f"Delete {len(done)} finished task(s)?",
        reason="clear_done_approval",
        response_schema={
            "type": "object",
            "properties": {"approved": {"type": "boolean"}},
            "required": ["approved"],
        },
    )
    if not decision or not decision.get("approved"):
        return "The user declined. No tasks were deleted."
    state.tasks = [t for t in state.tasks if t["status"] != "done"]
    return f"Deleted {len(done)} finished task(s)."


react_agent = ReactAgent(
    model="gpt-5-mini",
    state=BoardState(),
    system_prompt=[
        {
            "role": "system",
            "content": (
                "You manage a task board shown next to the chat. Use add_task for a single "
                "task and plan_goal when the user states a larger goal. Use set_task_status "
                "to move tasks and clear_done_tasks to delete finished ones. After you add or "
                "change a task, call the browser tool focus_task with its id so the user sees "
                "it. Keep replies short."
            ),
        }
    ],
    tools=[add_task, set_task_status, plan_goal, clear_done_tasks],
)

app = react_agent.compile(checkpointer=InMemoryCheckpointer())

"""Helper agent: breaks a goal into short task titles, served by DeepSeek.

It is a second, separate 10xGraph graph, called from a tool of the main assistant. Using a
model from another company shows that agents in one app do not have to share a provider.
"""

import os
import uuid

from dotenv import load_dotenv

from tenxgraph.core.state import Message
from tenxgraph.prebuilt.agent import ReactAgent


load_dotenv()

# No tools, so ReactAgent wires a single MAIN node. base_url and api_key are forwarded to the
# Agent; unknown model names use the OpenAI-compatible client.
_planner = ReactAgent(
    model="deepseek-chat",
    base_url="https://api.deepseek.com",
    api_key=os.environ["DEEPSEEK_API_KEY"],
    system_prompt=[
        {
            "role": "system",
            "content": (
                "You are a task planner. Break the user's goal into 3 to 5 concrete steps. "
                "Reply with one step per line, no numbering, no extra text. "
                "Keep each step under 8 words."
            ),
        }
    ],
).compile()


async def plan_steps(goal: str) -> list[str]:
    """Ask the DeepSeek planner for steps. Each call uses a fresh thread."""
    result = await _planner.ainvoke(
        {"messages": [Message.text_message(goal)]},
        {"thread_id": f"planner-{uuid.uuid4()}"},
    )
    text = result["messages"][-1].text() if result.get("messages") else ""
    steps = [line.strip(" -*\t") for line in text.splitlines()]
    return [s for s in steps if s][:5]

"""Shared board state. Every field here is sent to the browser as an AG-UI STATE_SNAPSHOT."""

from typing import Any

from pydantic import Field

from tenxgraph.core.state import AgentState


class BoardState(AgentState):
    """Task board. CopilotKit reads these fields with useAgent(...).state."""

    board_title: str = "My task board"
    # Each task: {"id": int, "title": str, "status": "todo" | "doing" | "done", "priority": str}
    tasks: list[dict[str, Any]] = Field(default_factory=list)
    next_id: int = 1

10xgraph[openai]
10xgraph-api[ag-ui]
python-dotenv

// CopilotKit runtime. It runs on the Next.js server, so the 10xGraph API token (if any)
// never reaches the browser.
import { HttpAgent } from "@ag-ui/client";
import {
  CopilotRuntime,
  createCopilotRuntimeHandler,
  InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";

const GRAPH_URL = process.env.GRAPH_API_URL || "http://localhost:8000";

const runtime = new CopilotRuntime({
  agents: {
    // The key ("graph") is the agentId the React side refers to.
    graph: new HttpAgent({
      url: `${GRAPH_URL}/v1/ag-ui`,
      headers: process.env.GRAPH_API_TOKEN
        ? { authorization: `Bearer ${process.env.GRAPH_API_TOKEN}` }
        : {},
    }),
  },
  runner: new InMemoryAgentRunner(),
});

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handler;
export const POST = handler;
export const PATCH = handler;
export const DELETE = handler;

import type { ReactNode } from "react";

export const metadata = { title: "10xGraph + CopilotKit task board" };

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body style={{ margin: 0, fontFamily: "system-ui, sans-serif" }}>{children}</body>
    </html>
  );
}

"use client";

import { useState } from "react";
import { CopilotChat, CopilotKitProvider, useFrontendTool } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";
import { z } from "zod";

import { Approval } from "@/components/Approval";
import { Board } from "@/components/Board";

// Frontend tool: the model calls it, the run ends with the call unanswered, this handler runs
// in the browser, and CopilotKit starts a new run with the result.
function FocusTool({ onFocus }: { onFocus: (id: number) => void }) {
  useFrontendTool({
    name: "focus_task",
    description: "Highlight a task on the board in the user's browser.",
    parameters: z.object({ task_id: z.number().describe("The task id to highlight") }),
    handler: async ({ task_id }) => {
      onFocus(task_id);
      return `Highlighted task ${task_id}`;
    },
  });
  return null;
}

export default function Page() {
  const [focusedId, setFocusedId] = useState<number | null>(null);

  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit" agentId="graph">
      <FocusTool onFocus={setFocusedId} />
      <Approval />
      <div style={{ display: "grid", gridTemplateColumns: "320px 1fr", height: "100vh" }}>
        <aside style={{ borderRight: "1px solid #eee", overflow: "auto" }}>
          <Board focusedId={focusedId} />
        </aside>
        <CopilotChat agentId="graph" labels={{ title: "Task assistant" }} />
      </div>
    </CopilotKitProvider>
  );
}

"use client";

import { useInterrupt } from "@copilotkit/react-core/v2";

// Renders the approval requested by interrupt() in the clear_done_tasks tool.
// resolve(payload) resumes the graph and interrupt() returns payload; cancel() returns None.
export function Approval() {
  useInterrupt({
    render: ({ interrupt, resolve, cancel }) => {
      if (!interrupt) return null;
      return (
        <div
          style={{
            position: "fixed",
            bottom: 20,
            left: 20,
            background: "white",
            border: "1px solid #ccc",
            borderRadius: 8,
            padding: 16,
            boxShadow: "0 2px 8px rgba(0,0,0,0.15)",
            maxWidth: 300,
          }}
        >
          <p style={{ marginTop: 0 }}>{interrupt.message}</p>
          <div style={{ display: "flex", gap: 8 }}>
            <button onClick={() => resolve({ approved: true })} style={{ flex: 1 }}>
              Approve
            </button>
            <button onClick={() => resolve({ approved: false })} style={{ flex: 1 }}>
              Reject
            </button>
            <button onClick={() => cancel()}>Cancel</button>
          </div>
        </div>
      );
    },
  });
  return null;
}

"use client";

import { useAgent } from "@copilotkit/react-core/v2";

type Task = { id: number; title: string; status: "todo" | "doing" | "done"; priority: string };
type BoardState = { board_title?: string; tasks?: Task[] };

const COLUMNS: Task["status"][] = ["todo", "doing", "done"];

// Reads the graph's BoardState. Each STATE_SNAPSHOT from the server updates agent.state.
export function Board({ focusedId }: { focusedId: number | null }) {
  const { agent } = useAgent({ agentId: "graph" });
  const state = (agent.state ?? {}) as BoardState;
  const tasks = state.tasks ?? [];

  return (
    <div style={{ padding: 16 }}>
      <h2 style={{ marginTop: 0 }}>{state.board_title ?? "My task board"}</h2>
      {COLUMNS.map((status) => (
        <section key={status} style={{ marginBottom: 16 }}>
          <h3 style={{ textTransform: "uppercase", fontSize: 12, color: "#666" }}>{status}</h3>
          {tasks
            .filter((t) => t.status === status)
            .map((t) => (
              <div
                key={t.id}
                style={{
                  padding: 8,
                  marginBottom: 6,
                  borderRadius: 6,
                  border: "1px solid #ddd",
                  background: t.id === focusedId ? "#fff3b0" : "white",
                }}
              >
                #{t.id} {t.title} <small style={{ color: "#888" }}>({t.priority})</small>
              </div>
            ))}
        </section>
      ))}
      {tasks.length === 0 && <p style={{ color: "#888" }}>No tasks yet. Ask the assistant.</p>}
    </div>
  );
}

/** @type {import('next').NextConfig} */
const nextConfig = { output: "standalone" };

export default nextConfig;

{
  "name": "copilotkit-agui-frontend",
  "private": true,
  "version": "0.1.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "@ag-ui/client": "^0.0.40",
    "@copilotkit/react-core": "^1.50.0",
    "@copilotkit/runtime": "^1.50.0",
    "next": "^15.1.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "zod": "^3.24.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "typescript": "^5.6.0"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": false,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": { "@/*": ["./*"] }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

services:
  backend:
    build: ./backend
    env_file: .env
    ports:
      - "8000:8000"

  frontend:
    build: ./frontend
    environment:
      GRAPH_API_URL: http://backend:8000
    ports:
      - "3000:3000"
    depends_on:
      - backend

# Backend (read by the 10xGraph API server and the agents)
OPENAI_API_KEY=
DEEPSEEK_API_KEY=

# Frontend (Next.js server side only). Docker Compose sets GRAPH_API_URL itself.
GRAPH_API_URL=http://localhost:8000
# Only needed if you enable auth in 10xgraph.json
GRAPH_API_TOKEN=

FROM python:3.13-slim

WORKDIR /app
ENV PYTHONUNBUFFERED=1 PYTHONPATH=/app GRAPH_PATH=/app/10xgraph.json

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000
# One process on purpose: the demo keeps threads in InMemoryCheckpointer, so an
# interrupt and its resume must reach the same worker. For multiple workers, switch
# to PgCheckpointer and use the gunicorn image `10xgraph build` generates.
CMD ["uvicorn", "tenxgraph_api.src.app.main:app", "--host", "0.0.0.0", "--port", "8000"]

.env
__pycache__

FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production PORT=3000 HOSTNAME=0.0.0.0
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
EXPOSE 3000
CMD ["node", "server.js"]

node_modules
.next
.env*