langchain-ai/agent-chat-ui

🦜💬 Web app for interacting with any LangGraph agent (PY & TS) via a chat interface.

Agent Chat UI – What it is

Agent Chat UI is a small Next.js web‑app that lets you talk to any LangGraph server (the backend that runs LangChain‑style agent graphs). You point the UI at a LangGraph endpoint, give it the ID of the assistant/graph you want to use, and it opens a chat window where each user turn is sent to the server and the LLM‑generated replies are streamed back.

The project is essentially a front‑end client for LangGraph agents, with a few conveniences:

A quick‑start form (or environment‑variable overrides) to configure the server URL, assistant ID, and optional LangSmith API key.
Support for hiding streamed messages or permanently suppressing messages via special tags (langsmith:nostream, langsmith:do-not-render).
A side‑panel for artifacts – extra data the graph can return (e.g., generated files, visualisations) – exposed through a custom React hook.
Guidance for production deployment, including an API‑passthrough proxy that injects a LangSmith key server‑side, and optional custom authentication for tighter security.

Quick start (local development)

# Create a fresh project (or clone the repo)
npx create-agent-chat-app
# or
git clone https://github.com/langchain-ai/agent-chat-ui.git && cd agent-chat-ui

# Install deps (pnpm is recommended)
pnpm install

# Run the dev server
pnpm dev   # → http://localhost:3000

When the app loads you’ll see a short form. Fill in:

Deployment URL – the HTTP address of your LangGraph server.
Assistant/Graph ID – the name or UUID of the agent you want to talk to.
LangSmith API Key – only needed if the server expects a LangSmith key (e.g., when using the built‑in Agent Builder deployment).
Built with Agent Builder – toggle if the server was created via LangSmith’s Agent Builder; it automatically selects the correct auth scheme.

After hitting Continue you’re taken to the chat view.

Running without the setup form

You can skip the interactive form by setting three environment variables (or adding them to a .env file based on .env.example):

NEXT_PUBLIC_API_URL=http://localhost:2024   # LangGraph endpoint
NEXT_PUBLIC_ASSISTANT_ID=agent            # graph/assistant ID
NEXT_PUBLIC_AUTH_SCHEME=                  # e.g. "langsmith-api-key" for Agent Builder

When these are present the UI connects immediately.

Controlling what the UI shows

Hide streaming output

Add the tag langsmith:nostream to the chat model configuration. The UI listens for on_chat_model_stream events; the tag suppresses those events, so the user only sees the final message.

# Python example
model = ChatAnthropic().with_config({"tags": ["langsmith:nostream"]})

// TypeScript example
const model = new ChatAnthropic().withConfig({ tags: ["langsmith:nostream"] })

Hide a message completely

Prefix the message id with do-not-render- and add the tag langsmith:do-not-render. The UI filters out any message whose ID starts with that prefix, so the content never appears in the chat pane.

result = model.invoke([messages])
result.id = f"do-not-render-{result.id}"
return {"messages": [result]}

const result = await model.invoke([messages])
result.id = `do-not-render-${result.id}`
return { messages: [result] }

Rendering artifacts

LangGraph graphs can return extra data in thread.meta.artifact. The UI provides a hook useArtifact that gives you:

A React component (Artifact) to render the content in a collapsible side panel.
State (open, setOpen) to control panel visibility.
The raw context object containing whatever you stored.

A minimal usage pattern looks like this:

import { useArtifact } from "../utils/use-artifact"

export function Writer({title, content, description}) {
  const [Artifact, {open, setOpen}] = useArtifact()
  return (
    <>
      <div => setOpen(!open)} className="cursor-pointer rounded-lg border p-4">
        <p className="font-medium">{title}</p>
        <p className="text-sm text-gray-500">{description}</p>
      </div>
      <Artifact title={title}>
        <p className="whitespace-pre-wrap p-4">{content}</p>
      </Artifact>
    </>
  )
}

This lets developers surface things like generated files, charts, or any custom UI alongside the chat.

Production deployment

Running the UI directly against a public LangGraph endpoint would expose every user’s LangSmith key. The repo includes two recommended ways to avoid that:

1. API Passthrough (quickest)

Install the langgraph-nextjs-api-passthrough package (already bundled).
Deploy the Next.js app (e.g., Vercel). The built‑in /api route proxies requests to your LangGraph server, injecting the LangSmith key server‑side.

Set the following env vars on the deployment platform:

NEXT_PUBLIC_ASSISTANT_ID=agent
LANGGRAPH_API_URL=https://my-agent.default.us.langgraph.app   # your LangGraph deployment
NEXT_PUBLIC_API_URL=https://my-website.com/api                # URL of this UI + /api
LANGSMITH_API_KEY=lsv2_…                                      # secret, not prefixed with NEXT_PUBLIC_

Important: The passthrough does not authenticate callers. Add your own gate (e.g., Vercel edge middleware) or use the advanced custom‑auth option below.

2. Custom authentication (more secure)

Follow LangGraph’s custom‑auth docs (Python or TypeScript) to make the LangGraph server require a bearer token or other scheme.

In the UI, modify useTypedStream (or the underlying useStream) to attach the token in request headers:

const streamValue = useTypedStream({
  apiUrl: process.env.NEXT_PUBLIC_API_URL,
  assistantId: process.env.NEXT_PUBLIC_ASSISTANT_ID,
  defaultHeaders: { Authentication: `Bearer ${myToken}` },
  // …other options
})

This lets the client talk directly to the LangGraph server without ever exposing a LangSmith key.

Who might use this?

Developers building LangGraph agents who want a ready‑made chat UI for demos or internal testing.
Product teams that need a lightweight front‑end to expose an LLM‑driven assistant to end‑users without building a custom UI from scratch.
Researchers who want to experiment with streaming control or artifact rendering while keeping the front‑end code minimal.

TL;DR

Clone or npx create-agent-chat-app → pnpm dev.
Point the UI at a LangGraph server (URL + assistant ID). Optionally supply a LangSmith key.
Use tags (langsmith:nostream, langsmith:do-not-render) to hide messages.
Render extra data via the useArtifact hook.
For production, either proxy through the built‑in API passthrough (with a secret LangSmith key) or set up custom authentication on the LangGraph side.