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.

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/python

Install 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 both

Configure your environment

export OPENAI_API_KEY=...
export OPENAI_MODEL=gpt-6-luna

To 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 select

project 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 install

Run your project

pnpm dev
# or npm run dev / yarn dev / bun dev

Start 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?

Open Inspector and confirm setup

On localhost, click the Inspector button in the corner of the app.

  1. Open Inspect, then Agent. Your agent is listed.
  2. Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
  3. 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?