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/2026SIGNUP BONUS
Sign up and get 5 xu to try the AI tools
Every new GitHot account gets 5 xu — enough to run the AI Repo Explainer, MCP Config Generator or Repo Health Check. Free, just an email or Google.
- 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.
- Windows: press the Windows key, type "PowerShell", then press Enter.
- macOS: press Command + Space, type "Terminal", then press Enter.
- Linux: press Ctrl + Alt + T.
- Copy a command from the guide, right-click inside the window you just opened to paste it (macOS: Command + V), then press Enter.
- 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
npxandnpmcommands.
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
npmandnpxcommands. 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_KEYin a.envfile. 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:
- "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.
- "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
.envfile 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
- Open your browser at http://localhost:3000.
- You will see the starter page with a CopilotKit chat panel. Type a short question, for example "Hi, what can you do?".
- The answer appears word by word: those are AG-UI text events emitted by the agent and rendered by the interface in real time.
- 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
| Symptom | Cause | Fix |
|---|---|---|
npx or node is not found | Node.js is not installed, or the terminal was opened before installing it | Install 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 required | Node.js is too old | Install 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 characters | Use a name like my-ag-ui-app or agent_demo |
| The page loads but the chat errors or never answers | Missing or wrong API key in .env, or no credit left with the provider | Check .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 installed | Install them from the links in section 2 and open a new terminal |
| Port 3000 is already in use | Another app is using port 3000 | Close that app, or open the other address printed in the logs |
npm reports EALLOWSCRIPTS | npm 12 refuses to install while the npm_config_allow_scripts environment variable is set | Run 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@latestalways 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.
Don't miss the next repo
Every new repo gets a video review, with its install guide right here.
HISTORY
Seen on GitHub Trending
- Nov 17#1019,854
- Nov 16#118,585
- Nov 15#217,646
- Nov 14#817,239