Agent Spec LangGraph Integration with AG-UI
Install pyagentspec with the LangGraph adapter and expose a FastAPI endpoint that streams AG‑UI events for CopilotKit.
What is this?
Wire an Agent Spec agent backed by LangGraph 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 LangGraph-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 the Agent Spec AG-UI integration
From the AG‑UI repo’s Agent Spec integration package:
git clone https://github.com/ag-ui-protocol/ag-ui.git
cd ag-ui/integrations/agent-spec/python
uv pip install -e .[langgraph]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[langgraph]"Steps
1. Start a FastAPI endpoint (minimal example)
Use the LangGraph runtime to execute your Agent Spec and stream AG‑UI events. For runtime options, see the Agent Spec LangGraph adapter docs.
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="langgraph")
add_agentspec_fastapi_endpoint(app, agentspec_agent=agent, path="/")Run locally:
uvicorn backend.app:app --reload --port 80002. 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:
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="langgraph",
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="langgraph")executes your Agent Spec agent with the LangGraph framework.- In the
AgentSpecAgentwrapper,AgUiSpanProcessormaps 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/ENDandTOOL_CALL_RESULT - lifecycle:
RUN_STARTED/RUN_FINISHED
- assistant text:
Troubleshooting
- If the chat gets no reply, make sure that the runtime can reach the agent. In the starter, set
AGENT_URLto the agent URL. The default ishttp://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 WayFlow runtime
Starter template: https://github.com/CopilotKit/CopilotKit/tree/main/examples/integrations/agent-spec (see the README for installation options)
How is this guide?