ContextQMD
Back to Copilotkit

Agent Spec WayFlow Integration with AG-UI

showcase/shell-docs/src/content/docs/integrations/agent-spec/wayflow.mdx

1.57.03.5 KB
Original Source

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:

bash
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:

bash
pip install wayflowcore

Steps

<Steps> <Step> ### 1. Start a FastAPI endpoint (minimal example)

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

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

bash
uvicorn backend.app:app --reload --port 8000
</Step> <Step> ### 2. Scaffold and connect the UI <RunAndConnect />

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.

</Step> </Steps>

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