blog-image

3 min read

AG-UI

Introduction

There are many products with bad documentation and AG-UI is one of them. A bit harsh but anyways.

LLMs are probabilistic in nature and hence the output we get is nondeterministic. You don’t know what output you’re going to get next.

Therefore building applications on top of LLMs brings a new challenge i.e. how to keep things as deterministic as possible? What interface to show and when?

In the upcoming sections we are going to talk about AG-UI and especially how to build clients with it, the issue I faced a lot when building agents.

AG-UI

AG-UI is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications.

It is not another UI library, it’s a protocol to connect your client with agentic backends. AG-UI is one of three prominent open agentic protocols

Before moving any further, let’s talk why AG-UI even exists? Agentic applications don’t work on traditional request/response model, where everything is deterministic, you make a request, get the response and render the UI.

In agent powered apps you don’t know what’s coming next

  • your request might end up in long-running session
  • model started thinking
  • human in the loop scenarios
  • tool calls etc…

For example

When using ChatGPT or Claude you might have noticed that sometimes 
they render cards to show information, sometimes draw flowcharts, 
for images render different UI, and they do it very cleanly.

Everything is random and hence rendering the UI according to these events is a big challenge.

AG-UI tackles these challenges by making the system typed and event driven . This helps you know what is currently happening with your agent and what should you do.

AG-UI supports many production-used agent frameworks and clients. Check here.

Building Client

So now let’s see how we can integrate AG-UI in our user facing apps and using agent frameworks that AG-UI supports.

In this we’re going to build a conversational CLI agent from scratch using AG-UI and Langchain.

Verify the code once before running.

  1. Project setup
mkdir ag-ui-langchain
cd ag-ui-langchain
bun init -y
bun add @ag-ui/client @ag-ui/core @ag-ui/langchain @langchain/core @langchain/openai
  1. Create src/agent.ts
import { LangChainAgent } from "@ag-ui/langchain";
import { ChatOpenAI } from "@langchain/openai";

export const agent = new LangChainAgent({
  chainFn: async ({ messages, tools, threadId }) => {
    const model = new ChatOpenAI({
      model: "gpt-4o-mini",
      temperature: 0,
    });

    const modelWithTools = model.bindTools(tools);

    return modelWithTools.stream(messages, {
      metadata: { conversation_id: threadId },
    });
  },
});
  1. Create src/index.ts
import { randomUUID } from "@ag-ui/client";
import * as readline from "node:readline";
import { agent } from "./agent";

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

async function chat() {
  console.log("AG-UI + LangChain");
  console.log("Type a message. Press Ctrl+C to exit.\n");

  while (true) {
    const input = await new Promise<string>((resolve) => {
      rl.question("You: ", resolve);
    });

    if (!input.trim()) continue;

    agent.messages.push({
      id: randomUUID(),
      role: "user",
      content: input.trim(),
    });

    await agent.runAgent(
      {},
      {
        onTextMessageStartEvent() {
          process.stdout.write("Assistant: ");
        },
        onTextMessageContentEvent({ event }) {
          process.stdout.write(event.delta);
        },
        onTextMessageEndEvent() {
          console.log("\n");
        },
      },
    );
  }
}

chat().catch(console.error);
  1. Export API Key
export OPENAI_API_KEY="your-api-key-here"
  1. Start the client
bun run src/index.ts

You can view the complete and detailed code using mastra agent here.

Conclusion

AG-UI is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications. It helps in building user interfaces of agentic applications where everything is nondeterministic in nature.

AG-UI is not limited to building clients, you can even make your own integrations via AG-UI server or middleware.

You can even handle complex scenarios like human-in-the-loop, subagents etc…

Subscribe RSS Feed