Mike Ryan
d5b804698d
## What 1. Add `suppressHydrationWarning` to `<body>` across **all 14 integration demo templates** (`examples/integrations/*/src/app/layout.tsx`). 2. Fix a pre-existing **double-escaped Windows path** bug in the parity manifest's `packageJsonOverrides`. ## Why (hydration) **Mike Ryan hit a hydration error on first load of a fresh `langgraph-python` init — caused by his Grammarly browser extension.** Grammarly (and similar extensions) inject attributes onto `<body>` *before* React hydrates: ``` data-new-gr-c-s-check-loaded="9.98.0" data-gr-ext-installed="" ``` Those attributes are in the client DOM but absent from the server HTML, so Next.js reports: > A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. It's a **false positive** — the app works, and end users (without dev extensions) never see it — but it's a red console error on the first load of our flagship eval/showcase templates, which is a poor first impression. ## Fix (hydration) `suppressHydrationWarning` on `<body>` is the React/Next.js-recommended escape hatch for this. It is **scoped and one level deep**: it only relaxes the check for `<body>`'s *own* attributes/text — **everything rendered inside `<body>` (the whole app) is still fully hydration-checked** — and `<body>`'s only attribute here is a static `className`, so none of our own markup is masked. An inline comment documents this so a future maintainer who adds dynamic `<body>` attributes knows the check is relaxed. `agent-spec` already had `suppressHydrationWarning` on `<html>`; the Grammarly attributes land on `<body>`, so it needed the body-level relaxation too (the `<html>` one is a level up and doesn't cover `<body>`'s attributes). ## Commits 1. `b1fa482a7` — north-star (`langgraph-python`) + parity instances (`langgraph-js`, `langgraph-fastapi`, `strands-python`) via `pnpm parity:sync`. 2. `9f9c415d9` — the non-parity templates (not tracked by `_parity/manifest.json`): `adk`, `agno`, `crewai-crews`, `crewai-flows`, `llamaindex`, `mastra`, `ms-agent-framework-dotnet`, `ms-agent-framework-python`, `pydantic-ai`, `agent-spec`. *(The repo's `oxfmt` pre-commit hook also collapsed some multiline `<CopilotKit …>` JSX in these files — standard auto-format on touched files; the only semantic change is the suppression.)* 3. `7d60e49de` — parity manifest path-escaping fix (see below). ## The manifest bug (commit 3) While syncing I found the `langgraph-js` and `strands-python` `packageJsonOverrides` double-escaped the Windows `.bat` fallback, producing `scripts\\run-agent.bat` (two backslashes) instead of `scripts\run-agent.bat`: - `langgraph-js/package.json` had already been synced with the broken value. - `strands-python/package.json` was still correct — and `parity:sync` would have **corrupted** it on the next run (which is what surfaced this). Fixed the three overrides and re-ran `parity:sync`, which corrects `langgraph-js/package.json` and leaves `strands-python`'s correct value intact. ## Test plan - [x] `pnpm parity:verify` → 0 errors - [x] lefthook pre-commit green on all 3 commits (lint + `packages/**` tests + commitlint) - [x] All 14 templates confirmed to have body-level `suppressHydrationWarning` - [ ] Reviewer with Grammarly installed: run/`init` a template and confirm no hydration error on first load
CopilotKit <> Agent Spec Starter
This is a starter template for building AI agents using Agent Spec and CopilotKit. It provides a modern Next.js application wired to a FastAPI backend that serves an Agent Spec agent with A2UI-powered frontend tool rendering (calendar, inbox, email compose, daily brief dashboard).
Prerequisites
- OpenAI-compatible API key (for the Agent Spec LLM)
- Python 3.10+
- uv
- Node.js 20+
- Any of the following package managers:
Getting Started
Before installing, please clone the AG-UI repository into the same directory as this repo, with-agent-spec.
- Install dependencies using your preferred package manager:
# Using npm (default)
npm install
# Using pnpm
pnpm install
# Using yarn
yarn install
# Using bun
bun install
Note: This automatically sets up the Python environment for the agent (via
postinstall). If you encounter issues, you can run:npm run install:agent
Note: this install both LangGraph and WayFlow runtimes for running your Agent Spec agents. The runtime can be selected when loading the agent in main.py, setting either langgraph or wayflow.
- (Optional) Set up your LLM environment variables:
Create a .env file inside the agent folder if you need to override defaults:
OPENAI_API_KEY=sk-...your-api-key...
OPENAI_BASE_URL=https://api.your-provider.com/v1 # optional
OPENAI_MODEL=gpt-5.2 # optional
The backend loads this .env automatically (via python-dotenv). You can also set:
PORTto change the FastAPI server port (defaults to8000in this template)- Any provider-specific variables your tools require
- Start the development servers:
# Using npm (default)
npm run dev
# Using pnpm
pnpm dev
# Using yarn
yarn dev
# Using bun
bun run dev
This starts both the UI and the agent concurrently. The agent runs at http://localhost:8000/, and the UI runs at http://localhost:3000. The UI proxies requests to the agent (no extra env required by default).
To run only the UI or only the backend:
# Only UI
npm run dev:ui
# Only backend
npm run dev:agent
Project Structure
src/app/page.tsx- Main chat UI with frontend tool renderers (calendar, inbox, email, daily brief)src/components/- React components for CalendarView, InboxView, EmailComposeViewsrc/app/theme.ts- A2UI theme configurationagent/src/a2ui_agentspec_agent.py- Agent spec definition with system prompt, tools, and demo dataagent/src/main.py- FastAPI server entry point
Available Scripts
You can run these with any package manager:
dev- Starts both UI and agent servers in development modedev:debug- Starts development servers with debug logging enableddev:ui- Starts only the Next.js UI serverdev:agent- Starts only the Agent Spec FastAPI serverbuild- Builds the Next.js application for productionstart- Starts the production serverinstall:agent- Installs Python dependencies for the agent
Documentation
- CopilotKit Documentation: https://docs.copilotkit.ai
- Next.js Documentation: https://nextjs.org/docs
Contributing
Feel free to submit issues and enhancement requests! This starter is designed to be easily extensible.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Troubleshooting
A2UI surfaces clipped (temporary workaround)
If A2UI cards (e.g. those with bottom action buttons) get clipped in the chat UI, we keep a temporary patch under:
src/app/patches/@copilotkit/a2ui-renderer/dist/A2UIMessageRenderer.js
To apply it locally (this edits node_modules and will be overwritten by reinstalling dependencies):
npm run patch:ui
After copying, restart npm run dev.
Custom message key warning (temporary workaround)
If you see React warnings about duplicate keys related to custom message rendering (keys like ${message.id}-custom-before / ${message.id}-custom-after), we keep a temporary patch under:
src/app/patches/@copilotkit/react-core/dist/index.mjs
To apply it locally (this edits node_modules and will be overwritten by reinstalling dependencies):
npm run patch:ui
After copying, restart npm run dev.
Agent Connection Issues
If you see "I'm having trouble connecting to my tools", make sure:
- The Agent Spec backend is running on port 8000
- The UI started successfully on port 3000
- If using a custom backend URL, set
NEXT_PUBLIC_COPILOTKIT_SERVER_URL
Python Dependencies
If you encounter Python import errors:
cd agent
uv sync
uv run src/main.py