LangGraph Integration

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 -f agent-spec

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.9+
• Node.js 20+
• An Agent Spec file that targets a LangGraph runtime (JSON/YAML)

Steps

1. Start the Agent Spec FastAPI server

Use the provided example server and select the LangGraph runtime.

export AGENT_SPEC_PATH=/absolute/path/to/your-agent-spec.json
export AGENT_SPEC_RUNTIME=langgraph
python ag-ui/integrations/agent-spec/python/examples/server.py

What it does:

• Loads your Agent Spec from AGENT_SPEC_PATH.
• Constructs an AgentSpecAgent(runtime="langgraph").
• Mounts the AG‑UI endpoint at /copilotkit using add_agentspec_fastapi_endpoint(...).

Endpoint implementation reference:

def add_agentspec_fastapi_endpoint(app, agentspec_agent, path="/"):
    @app.post(path)
    async def agentic_chat_endpoint(input_data: RunAgentInput, request: Request):
        # Bridges Agent‑Spec telemetry to AG‑UI events via EVENT_QUEUE and streams SSE
        ...

2. Scaffold and connect the UI

You'll need to run your agent and connect it to CopilotKit before proceeding.

If you don't already have CopilotKit and your agent connected, choose one of the following options:

If you already have the starter, set your backend endpoint in .env.local:

COPILOTKIT_REMOTE_ENDPOINT=http://localhost:8000/copilotkit

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

How it works

• The Agent Spec adapter converts LangGraph callbacks into Agent‑Spec telemetry.
• AgUiSpanProcessor translates spans/events into AG‑UI events and enqueues them onto a per‑request queue (EVENT_QUEUE).
• The FastAPI endpoint drains that queue and streams SSE to the browser. CopilotKit consumes these to render:
  • assistant text: TEXT_MESSAGE_START/CONTENT/END
  • tool call lifecycle: TOOL_CALL_START/ARGS/END
  • tool results: TOOL_CALL_RESULT
  • run lifecycle: RUN_STARTED/RUN_FINISHED

Troubleshooting

• Ensure AGENT_SPEC_RUNTIME=langgraph is set when starting the server.
• The endpoint path must match your UI’s COPILOTKIT_REMOTE_ENDPOINT (default /copilotkit).
• The endpoint asserts a queue is bound (no print fallback). If you get queue errors, check that requests go through the provided FastAPI route.

Next steps

• Build richer UIs with agentic chat and generative UI.
• Pass full chat history between turns. The adapter and processor handle message_id and tool‑call lifecycle for you.

Learn more

• Agent Spec docs home: https://oracle.github.io/agent-spec/development/docs_home.html
• Specification overview: https://oracle.github.io/agent-spec/development/agentspec/index.html