CopilotKit

Agent Spec WayFlow Integration with AG-UI

Connect an Agent Spec (WayFlow runtime) to CopilotKit via the AG‑UI endpoint and stream agent runs to the UI.

What is this?#

Wire an Agent Spec agent backed by WayFlow to CopilotKit’s UI via the AG‑UI event protocol. You’ll run a FastAPI endpoint that emits AG‑UI events and point your Next.js app at it.

Key pieces:

  • Backend endpoint: ag-ui/integrations/agent-spec/python/ag_ui_agentspec/endpoint.py
  • Example server: ag-ui/integrations/agent-spec/python/examples/server.py
  • Template UI: npx copilotkit@latest create

When should I use this?#

Use this integration when you already have a WayFlow-based agent described by an Agent Spec and want a turnkey UI that streams assistant text, tool calls/results, and run lifecycle with minimal wiring.

Prerequisites#

  • Python 3.10–3.14
  • Node.js 20+
  • An Agent Spec config JSON/YAML file (or Python code via pyagentspec)

Install runtime adapter#

From the AG‑UI repo’s Agent Spec adapter package:

git clone https://github.com/ag-ui-protocol/ag-ui.git
cd ag-ui/integrations/agent-spec/python
uv pip install -e .[wayflow]

Note that this installs wayflowcore from source. Alternatively, you may install it with pip:

pip install wayflowcore

Steps#

1. Start a FastAPI endpoint (minimal example)#

Use the WayFlow runtime to execute your Agent Spec and stream AG‑UI events.

from fastapi import FastAPI
from ag_ui_agentspec.agent import AgentSpecAgent
from ag_ui_agentspec.endpoint import add_agentspec_fastapi_endpoint

agentspec_json = <loaded json/yaml of your Agent Spec config>

app = FastAPI()
agent = AgentSpecAgent(agentspec_json, runtime="wayflow")
add_agentspec_fastapi_endpoint(app, agentspec_agent=agent, path="/")

Run locally:

uvicorn backend.app:app --reload --port 8000

2. Scaffold and connect the UI#

You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already, you can follow the instructions in the Getting Started guide.

If you don't already have an agent, you can use the coagent starter as a starting point as this guide uses it as a starting point.

If you already have the starter, make sure your agent runs on port 8000.

Then run the app (for example with pnpm dev) and open http://localhost:3000.

How it works#

  • AgentSpecAgent(runtime="wayflow") executes your Agent Spec agent with the WayFlow framework.
  • AgUiSpanProcessor maps Agent Spec tracing spans to AG‑UI events on a per‑request queue (EVENT_QUEUE).
  • The FastAPI endpoint streams those events as SSE for CopilotKit to render:
    • assistant text: TEXT_MESSAGE_START/CONTENT/END
    • tool calls: TOOL_CALL_START/ARGS/END and TOOL_CALL_RESULT
    • lifecycle: RUN_STARTED/RUN_FINISHED

Troubleshooting#

  • The endpoint path must match your UI’s expected agent endpoint (port 8000 in our starter repo).
  • The endpoint asserts a queue is bound. If you get queue errors, check that requests go through the provided FastAPI route.
  • If you are not receiving any events, make sure the agent is running and did not crash.

Next steps#

  • Build richer UIs with agentic chat and generative UI.
  • Pass full chat history between turns. The adapter and processor handle messages and tool‑call lifecycle for you.
  • Check out the LangGraph runtime

Starter template: https://github.com/CopilotKit/CopilotKit/tree/main/examples/integrations/agent-spec (see the README for installation options)

Learn more#

On this page

What is this?When should I use this?PrerequisitesInstall runtime adapterSteps1. Start a FastAPI endpoint (minimal example)2. Scaffold and connect the UIHow it worksTroubleshootingNext stepsLearn more