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 to 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]

This installs the Agent Spec AG-UI integration (ag_ui_agentspec) from source. To install the published package instead, run:

pip install "ag-ui-agent-spec[wayflow]"

Steps

1. Start a FastAPI endpoint (minimal example)

Use the WayFlow runtime to execute your Agent Spec and stream AG‑UI events. For runtime options, see the Agent Spec WayFlow adapter docs.

backend/app.py
from pathlib import Path

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

# Your Agent Spec config, as a JSON or YAML string
agentspec_json = Path("agent.json").read_text()

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

Create the UI with npx copilotkit@latest create, or copy the Agent Spec starter.

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 quickstart guide.

If you do not have an agent yet, the quickstart shows how to create one.

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.

Send a message in the chat. The reply of the agent streams into the chat.

Bind backend tools

If your Agent Spec declares server-side tools, map each tool name to a Python function in tool_registry:

backend/app.py
from pathlib import Path
from typing import Any, Dict

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

def get_weather(city: str) -> Dict[str, Any]:
    return {"city": city, "temp_c": 22}

agentspec_json = Path("agent.json").read_text()

app = FastAPI()
agent = AgentSpecAgent(
    agent_spec_config=agentspec_json,
    runtime="wayflow",
    tool_registry={"get_weather": get_weather},
)
add_agentspec_fastapi_endpoint(app, agentspec_agent=agent, path="/")

Frontend tools (Agent Spec ClientTool) run in the browser, so they do not go in tool_registry. See Frontend Tools.

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. The event types come from the AG-UI protocol:
    • assistant text: TEXT_MESSAGE_START/CONTENT/END
    • tool calls: TOOL_CALL_START/ARGS/END and TOOL_CALL_RESULT
    • lifecycle: RUN_STARTED/RUN_FINISHED

Troubleshooting

  • If the chat gets no reply, make sure that the runtime can reach the agent. In the starter, set AGENT_URL to the agent URL. The default is http://localhost:8000/.
  • 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)

How is this guide?