Skip to main content

Introduction

A server implementation allows you to emit AG-UI events directly from your agent or server. This approach is ideal when you’re building a new agent from scratch or want a dedicated service for your agent capabilities.

When to use a server implementation

Server implementations allow you to directly emit AG-UI events from your agent or server. If you are not using an agent framework or haven’t created a protocol for your agent framework yet, this is the best way to get started. Server implementations are also great for:
  • Building a new agent frameworks from scratch
  • Maximum control over how and what events are emitted
  • Exposing your agent as a standalone API

What you’ll build

In this guide, we’ll create a standalone HTTP server that:
  1. Accepts AG-UI protocol requests
  2. Connects to OpenAI’s GPT-4o model
  3. Streams responses back as AG-UI events
  4. Handles tool calls and state management
Let’s get started!

Prerequisites

Before we begin, make sure you have:
  • Python 3.12 or later
  • Poetry for dependency management
  • An OpenAI API key

1. Provide your OpenAI API key

First, let’s set up your API key:

2. Install build utilities

Install the following tools:

Step 1 – Scaffold your server

Start by cloning the repo:
Copy the server-starter template to create your OpenAI server:

Update metadata

Open integrations/openai-server/package.json and update the fields to match your new folder:
Next, update the class name inside integrations/openai-server/src/index.ts:
Finally, introduce your integration to the dojo by adding it to apps/dojo/src/menu.ts:
And apps/dojo/src/agents.ts:

Step 2 – Add package to dojo dependencies

Open apps/dojo/package.json and add "@ag-ui/openai-server": "workspace:*" to the dependencies object:

Step 3 – Start the dojo and server

Now let’s see your work in action. First, start your Python server:
In another terminal, start the dojo:
Head over to http://localhost:3000 and choose OpenAI from the drop-down. You’ll see the stub server replies with Hello world! for now. Here’s what’s happening with that stub server:
Awesome! We are already sending a RunStartedEvent, which is the first step toward an AG-UI compliant endpoint. Now let’s make it do something useful.

Implementing Basic Chat

Let’s enhance our endpoint to call OpenAI’s API and stream the responses back as AG-UI events:

Step 4 – Bridge OpenAI with AG-UI

Let’s transform our stub into a real server that streams completions from OpenAI.

Install the OpenAI SDK

First, we need the OpenAI SDK:

AG-UI recap

An AG-UI server implements the endpoint and emits a sequence of events to signal:
  • lifecycle events (RUN_STARTED, RUN_FINISHED, RUN_ERROR)
  • content events (TEXT_MESSAGE_*, TOOL_CALL_*, and more)

Implement the streaming server

Now we’ll transform our stub server into a real OpenAI integration. The key difference is that instead of sending a hardcoded “Hello world!” message, we’ll connect to OpenAI’s API and stream the response back through AG-UI events. The implementation follows the same event flow as our stub, but we’ll add the OpenAI client initialization and replace our mock response with actual API calls. We’ll also handle tool calls if they’re present in the response, making our server fully capable of using functions when needed.

What happens under the hood?

Let’s break down what your server is doing:
  1. Setup – We create an OpenAI client and emit RUN_STARTED
  2. Request – We send the user’s messages to chat.completions with stream=True
  3. Streaming – We forward each chunk as either TEXT_MESSAGE_CHUNK or TOOL_CALL_CHUNK
  4. Finish – We emit RUN_FINISHED (or RUN_ERROR if something goes wrong)
Test your endpoint with:
This implementation creates a fully functional AG-UI endpoint that processes messages and streams back the responses in real-time.

Step 5 – Chat with your server

Reload the dojo page and start typing. You’ll see GPT-4o streaming its answer in real-time, word by word. Tools like CopilotKit already understand AG-UI and provide plug-and-play React components. Point them at your server endpoint and you get a full-featured chat UI out of the box.

Share your integration

Did you build a custom server that others could reuse? We welcome community contributions!
  1. Fork the AG-UI repository
  2. Add your package under integrations/. See Contributing for more details and naming conventions.
  3. Open a pull request describing your use-case and design decisions
If you have questions, need feedback, or want to validate an idea first, start a thread in the GitHub Discussions board: AG-UI GitHub Discussions board. Your integration might ship in the next release and help the entire AG-UI ecosystem grow.

Conclusion

You now have a fully-functional AG-UI server for OpenAI and a local playground to test it. From here you can:
  • Add tool calls to enhance your server
  • Deploy your server to production
  • Bring AG-UI to any other model or service
Happy building!