CopilotKit integration

Overview of how React frontends, hydrotrek-copilot-server, and FastAPI agent backends fit together, plus a quick checklist for adding CopilotKit UI and ChatClient to a new project.

Related repositories

1. hydrotrek-ai-fastapi — reusable FastAPI boilerplate for HydroTrek CopilotKit / MAF agents. It exposes POST /agent for the copilot server.
2. hydrotrek-copilot-server — minimal CopilotKit Runtime server. It does not host UI or a chat sidebar; it only exposes the runtime API used by the frontend.

System overview

Multiple HydroTrek React apps can share one hydrotrek-copilot-server instance. Each frontend connects to its own copilot-server instance (or shared instance, depending on deployment), which proxies agent traffic to that project's FastAPI backend.

Project	Frontend	FastAPI backend
DWD	dwd-frontend-react	dwd-api-fastapi
SWMM	swmm-frontend-react	swmm-api-fastapi

For a new project x, the generic pattern is:

x-frontend-react  →  hydrotrek-copilot-server  →  hydrotrek-ai-api-fastapi

note

DWD and SWMM include additional FastAPI functionality beyond the plain hydrotrek-ai-api-fastapi template (forecasting, MCP tools, project-specific agent logic, and so on). Do not assume a stock template instance is enough for those projects.

For DWD deployment on MSI Laptop 3 (Docker, Nginx, MCP), see 14-sprint-copilot-mcp-docker.md.

Repository roles

hydrotrek-copilot-server

The copilot server is a runtime bridge between a suite frontend and a suite FastAPI agent backend:

suite-frontend (:3000)  →  POST /api/copilotkit  →  hydrotrek-copilot-server (:PORT)
                                                 →  suite-api-fastapi /agent

Run one instance per suite with a different .env for agent id, backend URL, port, and CORS origins.

Basic local setup:

node -v   # should be v22.22.2
npm install
cp .env.example .env.local
npm run dev

Important endpoints:

Endpoint	Purpose
POST /api/copilotkit	CopilotKit runtime endpoint used by the frontend
OPTIONS /api/copilotkit	CORS preflight from the suite frontend
GET /	Stub status page

hydrotrek-ai-fastapi

The FastAPI repo is the reusable boilerplate for a new HydroTrek AI API. It has no domain-specific routes, storage, or simulation code by default; it only provides the agent plumbing.

suite-frontend (:3000)
  → hydrotrek-copilot-server (:PORT)
      POST /api/copilotkit
  → hydrotrek-ai-fastapi (:8000)
      POST /agent
  → OpenAI API

Basic local setup:

cd hydrotrek-ai-fastapi
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
python server.py

Open http://localhost:8000/docs for Swagger UI and http://localhost:8000/health to confirm agent_enabled: true.

Important endpoints:

Method	Path	Description
GET	/	Stub message
GET	/health	Agent and MCP status
GET	/docs	Swagger UI
POST	/agent	MAF / AG-UI agent endpoint used by hydrotrek-copilot-server

Quick integration (CopilotKit UI + ChatClient)

1. Frontend (index.jsx)

Set agent to the agent id registered on the copilot server. It must match AGENT_ID in the copilot-server .env.

<CopilotKit agent="agent_name" runtimeUrl={...}>

2. Copilot server (.env)

Variable	Purpose
AGENT_ID	Must match agent="..." in the React app's index.jsx
AGUI_AGENT_URL	URL of the FastAPI agent endpoint, e.g. http://localhost:8001/agent
OPENAI_API_KEY	OpenAI API key for the agent
OPENAI_CHAT_MODEL_ID	Model id, e.g. gpt-4o-mini
OPENAI_RESPONSES_STORE	e.g. false
AGENT_INSTRUCTIONS	Project-specific system instructions for agent x

Example:

AGENT_ID=agent_name
AGUI_AGENT_URL=http://localhost:8001/agent
PORT=3001
CORS_EXTRA=https://your-frontend-url
OPENAI_API_KEY=
OPENAI_CHAT_MODEL_ID=gpt-4o-mini
OPENAI_RESPONSES_STORE=false
AGENT_INSTRUCTIONS=

Frontend .env example:

VITE_COPILOT_RUNTIME_URL=http://localhost:3001/api/copilotkit

FastAPI .env basics:

Variable	Purpose
OPENAI_API_KEY	Required for /agent
OPENAI_CHAT_MODEL_ID	Chat model, default gpt-4o-mini
OPENAI_RESPONSES_STORE	Keep false for CopilotKit multi-turn tool loops
AGENT_INSTRUCTIONS	Full system prompt for the agent
MCP_SERVER_URL	Optional MCP server URL for live tools
MCP_SERVER_NAME	Optional display name for MCP tools
FASTAPI_PORT	Local dev port, default 8000
ROOT_PATH	Optional public URL prefix for reverse proxy deployments
CORS_EXTRA	Optional comma-separated frontend origins

3. How the chain works

swmm-frontend-react     hydrotrek-copilot-server     hydrotrek-ai-api-fastapi
  agent="agent"    ←→    AGENT_ID=agent          →    POST /agent
       must match

On the copilot server, agents are registered like this:

const runtime = new CopilotRuntime({
  agents: {
    [agentId]: new HttpAgent({ url: agentUrl }),
  },
});

agentId comes from AGENT_ID; agentUrl comes from AGUI_AGENT_URL.