Quickstart
Set up Agent Spec + AG‑UI and connect a CopilotKit UI. Includes per‑adapter install steps and a minimal endpoint.
Agent Spec is a specification language that declares the structure of your agents and workflows. You can run an Agent Spec agent on LangGraph or on WayFlow (the Oracle reference framework for Agent Spec). This page connects that agent to a CopilotKit chat.
Start with your coding agent
Use this prompt to connect your Agent Spec agent to CopilotKit and verify a working conversation. Your coding agent will follow this guide in your project, or you can work through the manual steps below.
Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.
Prerequisites
- Node.js 20+
- Python 3.10 to 3.13
Getting started
Set up CopilotKit Intelligence
Sign in to cloud-hosted Intelligence. You will connect the app after you create or clone it below.
Choose your starting point
You can either start fresh with our starter template or connect CopilotKit to an existing Agent Spec agent.
Install the Agent Spec AG‑UI adapter (backend)
The AG‑UI integration for Agent Spec lives in ag-ui/integrations/agent-spec/python. The starter uses it to set up the agent environment. Clone it:
# Clone the adapter and move into the Python package
git clone --depth 1 --filter=blob:none --sparse https://github.com/ag-ui-protocol/ag-ui.git
cd ag-ui
git sparse-checkout set integrations/agent-spec/python
cd integrations/agent-spec/pythonInstall the extra for the framework that runs your agent:
uv sync --extra langgraph # for LangGraph
uv sync --extra wayflow # for WayFlow
uv sync --extra langgraph --extra wayflow # for bothConfigure your environment
export OPENAI_API_KEY=...
export OPENAI_MODEL=gpt-6-lunaTo use another OpenAI-compatible provider, such as a local vLLM server or Together AI, also set OPENAI_BASE_URL to its endpoint.
See the Agent Spec AG-UI tutorial.
Scaffold the UI
Use our starter repo template: https://github.com/CopilotKit/with-agent-spec. It includes an example definition of an Agent Spec agent here. Run the following commands
Go to your root directory
# If you are in the path integrations/agent-spec/python, then run the following command to go to root
cd ../../../../Clone the starter template
git clone https://github.com/CopilotKit/with-agent-spec.git
cd with-agent-spec
npx copilotkit@latest project selectproject select writes the server-side project API key to .env as CPK_INTELLIGENCE_API_KEY.
Install Dependencies
Run the following commands to install your dependencies in the start repository
pnpm installRun your project
pnpm dev
# or npm run dev / yarn dev / bun devStart chatting
Your AI agent is now ready to use. Navigate to localhost:3000 and try asking it some questions:
- Can you tell me a joke?
- Can you help me understand AI?
- What do you think about React?
- If the chat shows a connection error, make sure that the agent runs on port 8000.
- If the connection error stays, use
127.0.0.1or0.0.0.0in place oflocalhostin the agent URL. - If the agent does not reply, make sure that
OPENAI_API_KEYis set in the terminal that runs the agent. - If the frontend cannot import
@ag-ui/client, install the package in your frontend.
Open Inspector and confirm setup
On localhost, click the Inspector button in the corner of the app.
- Open Inspect, then Agent. Your agent is listed.
- Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
- Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Copy setup prompt (Intelligence is off).
More detail: Inspector.
Next steps
Follow per-adapter tutorials: LangGraph integration and WayFlow integration. To bind backend tools to your agent, see "Bind backend tools" on the LangGraph or WayFlow page.
How is this guide?