# 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? [#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? [#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 [#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 [#install-the-agent-spec-ag-ui-integration]

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

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

```bash
pip install "ag-ui-agent-spec[langgraph]"
```

## Steps [#steps]

<Steps>

<Step>
### 1. Start a FastAPI endpoint (minimal example) [#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](https://oracle.github.io/agent-spec/26.1.0/adapters/langgraph/index.html).

```python title="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="langgraph")
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 [#2-scaffold-and-connect-the-ui]

Create the UI with `npx copilotkit@latest create`, or copy the [Agent Spec starter](https://github.com/CopilotKit/CopilotKit/tree/main/examples/integrations/agent-spec).

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](/agent-spec/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.

</Step>

</Steps>

## Bind backend tools [#bind-backend-tools]

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

```python title="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="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](/agent-spec/frontend-tools).

## How it works [#how-it-works]

- `AgentSpecAgent(runtime="langgraph")` executes your Agent Spec agent with the LangGraph framework.
- In the `AgentSpecAgent` wrapper, `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](https://docs.ag-ui.com/introduction):
  - assistant text: `TEXT_MESSAGE_START/CONTENT/END`
  - tool calls: `TOOL_CALL_START/ARGS/END` and `TOOL_CALL_RESULT`
  - lifecycle: `RUN_STARTED/RUN_FINISHED`

## Troubleshooting [#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 [#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](/agent-spec/wayflow)

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