← Home

REVIEWED & READY TO INSTALL

ag-ui

ag-ui-protocol/ag-ui

AG-UI is an open, event-based protocol that brings AI agents into user-facing apps: real-time streaming chat, two-way state sync, frontend tools, agent-built UI and human-in-the-loop approval. Supported by LangGraph, CrewAI, Google ADK, Pydantic AI, Mastra and more. Free, MIT license.

STEP BY STEP

How to install ag-ui

The step-by-step guide is right on this page, written for people who have never installed anything from GitHub.

Updated 11/16/2026
GitHub preview image of ag-ui
GitHub stars
21,037
Language
TypeScript
Trending rank
#10
Added
11/16/2026

How to install ag-ui, step by step

Work from top to bottom. Each grey box is one command: copy the whole line, paste it into the terminal window and press Enter.

Never used a terminal? Read this first (1 minute)

A terminal is a window where you type commands for your computer. You do not need to understand them, just copy and paste them exactly.

  1. Windows: press the Windows key, type "PowerShell", then press Enter.
  2. macOS: press Command + Space, type "Terminal", then press Enter.
  3. Linux: press Ctrl + Alt + T.
  4. Copy a command from the guide, right-click inside the window you just opened to paste it (macOS: Command + V), then press Enter.
  5. Wait for the command to finish (the cursor blinks again on a new line) before running the next one.

Lines starting with # are notes; you do not need to copy them. If red error text appears, check the common errors section at the end of the guide.

1. What is AG-UI?

AG-UI (the Agent-User Interaction Protocol, repo ag-ui-protocol/ag-ui) is an open protocol: a shared set of rules for how an AI agent (an AI program that works through several steps, calls tools and makes decisions) talks to the interface a person actually sees, such as the chat panel inside your web app. Instead of every agent framework sending data in its own format, the agent emits one standard stream of events: the run started, here is the next piece of the answer, a tool is being called, the state changed, the run finished. The interface only has to understand that one language to display any agent the same way.

The README places AG-UI next to two protocols you may already know: MCP gives agents tools, A2A lets agents talk to other agents, and AG-UI brings agents into user-facing applications. The project is free and MIT-licensed. Version 1.0 was released on 17 September 2026 and is the first release with a formal specification behind it.

To be clear: this is a tool for developers. AG-UI is not an app you download and use. If you do not write software, the easiest way to see it in action is the web demo in Step 1 below.

A good fit if:

  • You already have (or plan to build) an AI agent with LangGraph, CrewAI, Mastra, Pydantic AI, Google ADK, Microsoft Agent Framework, LlamaIndex, Agno, AG2, the Claude Agent SDK and so on, and you want to put it inside a web interface.
  • You want ready-made building blocks: chat that streams text in real time, state kept in sync both ways between the agent and the interface, agent calls to tools that run in the browser, agent-generated UI, and a step where the agent pauses for a person to approve.
  • You are comfortable running npx and npm commands.

Not a good fit if:

  • You are looking for a finished chatbot for everyday use. AG-UI is the plumbing underneath, not the end product.
  • You do not want to use a paid API key from a model provider. The starter apps need one for the agent to answer.

2. What you need

  • A computer running Windows, macOS or Linux, with an internet connection.
  • Node.js 20.9.0 or newer. Node.js runs programs written in JavaScript and comes with the npm and npx commands. The CopilotKit project generator that AG-UI calls requires at least this version. Download it free from https://nodejs.org (pick the LTS release).
  • An API key from a model provider, usually OpenAI. The LangGraph Python starter, for example, asks you to put OPENAI_API_KEY in a .env file. You pay for that key at the provider's prices, not AG-UI's. Get an OpenAI key at https://platform.openai.com/api-keys.
  • (Only for a Python agent) Python 3.12 or newer (https://www.python.org/downloads/) and uv, a Python package manager (https://docs.astral.sh/uv/). Starters built on Mastra or LangGraph JavaScript do not need Python.

No AG-UI account is required. The web demo in Step 1 needs no installation at all.

3. Step-by-step setup

Step 1: Try the web demo first (no install)

Open https://dojo.ag-ui.com in your browser. This is the "Dojo", the project's official demo site, where each AG-UI feature is shown as its own small example.

What you should see: a left column with a framework picker (under "Integrations") and a list of examples such as "Beautiful Chat", "Frontend Tools" and "Generative UI"; on the right, a chat box that says "How can I help you today?". Click "Code" to see the source of the example that is open.

Step 2: Check Node.js

Open Terminal (macOS/Linux) or PowerShell (Windows) and type:

node --version

What you should see: a line such as v22.x.x or v24.x.x (anything from v20.9.0 up). If the command is not found or the number is lower, install the Node.js LTS release from https://nodejs.org and open a new terminal window.

Step 3: Create an AG-UI project

Go to the folder where you want the project (for example Documents) and run:

npx create-ag-ui-app@latest

The first time, npm may ask whether to download create-ag-ui-app; type y and press Enter. The tool then asks two questions:

  1. "What client do you want to use?" Choose CopilotKit/Next.js for a web app with a chat panel. CLI client creates an app that runs in the terminal instead.
  2. "What would you like to name your project?" The default is my-ag-ui-app. Names may only contain letters, numbers, hyphens and underscores.

The tool then hands over to CopilotKit's project generator, which may ask you to pick an agent template. If you already know your framework, you can choose it up front with a flag, for example:

npx create-ag-ui-app@latest --langgraph-py

Available flags: --langgraph-py, --langgraph-js, --crewai-flows, --mastra, --pydantic-ai, --llamaindex, --agno, --ag2, --adk.

What you should see: a new folder named after your project, containing a package.json and the template's README.md.

Step 4: Add your API key

Move into the project folder and create a .env file from the example.

macOS / Linux:

cd my-ag-ui-app
cp .env.example .env

Windows (PowerShell):

cd my-ag-ui-app
Copy-Item .env.example .env

Open .env in a text editor (Notepad, VS Code…), fill in your key on the matching line, for example OPENAI_API_KEY=..., and save. The exact variable name can differ between templates; the README in your project folder says what to fill in.

What you should see: the key line in .env holds your real key, not placeholder text such as your-openai-api-key-here.

Note: never share your .env file or push it to GitHub. Anyone with the key can spend money on your account.

Step 5: Install and run

npm install
npm run dev

For a Python agent template, npm install also installs the Python side with uv, as described in the template README.

What you should see: the terminal does not return to the prompt; it keeps printing logs, including the address http://localhost:3000.

4. First use

  1. Open your browser at http://localhost:3000.
  2. You will see the starter page with a CopilotKit chat panel. Type a short question, for example "Hi, what can you do?".
  3. The answer appears word by word: those are AG-UI text events emitted by the agent and rendered by the interface in real time.
  4. Try the demo features the template includes (they vary, for example changing the background colour or adding items to a list just by asking). When the agent calls a tool or changes state, the interface updates straight away.

To stop the app, go back to the terminal and press Ctrl + C.

To go deeper, read the Concepts section of the official docs at https://docs.ag-ui.com (the Events page lists every event type).

5. Common problems and fixes

SymptomCauseFix
npx or node is not foundNode.js is not installed, or the terminal was opened before installing itInstall Node.js LTS from https://nodejs.org, then close and reopen Terminal/PowerShell
The tool stops and says Node.js 20.9.0 or later is requiredNode.js is too oldInstall a current LTS release and check again with node --version
"Project name can only contain letters, numbers, hyphens, and underscores"The name has spaces, accents or special charactersUse a name like my-ag-ui-app or agent_demo
The page loads but the chat errors or never answersMissing or wrong API key in .env, or no credit left with the providerCheck .env, save it, stop the app (Ctrl + C) and run npm run dev again
uv or python not found (Python templates)Python 3.12+ or uv is not installedInstall them from the links in section 2 and open a new terminal
Port 3000 is already in useAnother app is using port 3000Close that app, or open the other address printed in the logs
npm reports EALLOWSCRIPTSnpm 12 refuses to install while the npm_config_allow_scripts environment variable is setRun the replacement command the CopilotKit tool prints on screen

6. Uninstall / update

  • Uninstall: AG-UI installs nothing system-wide. Stop the app (Ctrl + C) and delete the project folder. If you are done for good, you can also revoke the API key on your provider's site.
  • Update the project generator: npx create-ag-ui-app@latest always fetches the newest release; nothing else to do.
  • Update the libraries in a project you already created: in the project folder, run:
npm update

Moving to 1.0: projects created before September 2026 may use AG-UI 0.x libraries. Read "Migrating to 1.0" in the official docs (https://docs.ag-ui.com) before a major upgrade.

7. FAQ

Does AG-UI cost money? No. It is open source under the MIT license. You only pay the AI model provider your agent uses.

Does it need the internet? Yes, to download the libraries and for the agent to reach the AI model through your API key.

Where does my chat data go? What you type goes to your agent and then to the model provider you configured (for example OpenAI). The AG-UI protocol itself is only the format used between the agent and the interface.

How is AG-UI different from MCP? MCP lets an agent use outside tools and data. AG-UI lets an agent show up and interact with people inside an application. You can use both together.

My framework is not on the list. What now? The README lists SDKs for TypeScript and Python plus community SDKs for Go, Rust, Java, Kotlin, .NET, Dart, Ruby and C++. You can also emit events yourself following the specification at https://docs.ag-ui.com.

Written by GitHot and checked against the project's official documentation. If a step is wrong or unclear, message GitHot through the channels at the bottom of the page.

SEE WHY IT'S HOT

Watch the original review

Go back to the video that brought you here.

Watch on TikTok ↗

Don't miss the next repo

Every new repo gets a video review, with its install guide right here.

Follow on TikTok ↗

HISTORY

Seen on GitHub Trending

  1. Nov 17#1019,854
  2. Nov 16#118,585
  3. Nov 15#217,646
  4. Nov 14#817,239