​
Messages

Messages form the backbone of communication in the AG-UI protocol. They represent the conversation history between users and AI agents, and provide a standardized way to exchange information regardless of the underlying AI service being used.

​
Message Structure

AG-UI messages follow a vendor-neutral format, ensuring compatibility across different AI providers while maintaining a consistent structure. This allows applications to switch between AI services (like OpenAI, Anthropic, or custom models) without changing the client-side implementation.

The basic message structure includes:

interface BaseMessage {
  id: string // Unique identifier for the message
  role: string // The role of the sender (user, assistant, system, tool)
  content?: string // Optional text content of the message
  name?: string // Optional name of the sender
}

​
Message Types

AG-UI supports several message types to accommodate different participants in a conversation:

​
User Messages

Messages from the end user to the agent:

interface UserMessage {
  id: string
  role: "user"
  content: string // Text input from the user
  name?: string // Optional user identifier
}

​
Assistant Messages

Messages from the AI assistant to the user:

interface AssistantMessage {
  id: string
  role: "assistant"
  content?: string // Text response from the assistant (optional if using tool calls)
  name?: string // Optional assistant identifier
  toolCalls?: ToolCall[] // Optional tool calls made by the assistant
}

​
System Messages

Instructions or context provided to the agent:

interface SystemMessage {
  id: string
  role: "system"
  content: string // Instructions or context for the agent
  name?: string // Optional identifier
}

​
Tool Messages

Results from tool executions:

interface ToolMessage {
  id: string
  role: "tool"
  content: string // Result from the tool execution
  toolCallId: string // ID of the tool call this message responds to
}

​
Developer Messages

Internal messages used for development or debugging:

interface DeveloperMessage {
  id: string
  role: "developer"
  content: string
  name?: string
}

​
Vendor Neutrality

AG-UI messages are designed to be vendor-neutral, meaning they can be easily mapped to and from proprietary formats used by various AI providers:

// Example: Converting AG-UI messages to OpenAI format
const openaiMessages = agUiMessages
  .filter((msg) => ["user", "system", "assistant"].includes(msg.role))
  .map((msg) => ({
    role: msg.role as "user" | "system" | "assistant",
    content: msg.content || "",
    // Map tool calls if present
    ...(msg.role === "assistant" && msg.toolCalls
      ? {
          tool_calls: msg.toolCalls.map((tc) => ({
            id: tc.id,
            type: tc.type,
            function: {
              name: tc.function.name,
              arguments: tc.function.arguments,
            },
          })),
        }
      : {}),
  }))

This abstraction allows AG-UI to serve as a common interface regardless of the underlying AI service.

​
Message Synchronization

Messages can be synchronized between client and server through two primary mechanisms:

​
Complete Snapshots

The MESSAGES_SNAPSHOT event provides a complete view of all messages in a conversation:

interface MessagesSnapshotEvent {
  type: EventType.MESSAGES_SNAPSHOT
  messages: Message[] // Complete array of all messages
}

This is typically used:

  • When initializing a conversation
  • After connection interruptions
  • When major state changes occur
  • To ensure client-server synchronization

​
Streaming Messages

For real-time interactions, new messages can be streamed as they’re generated:

  1. Start a message: Indicate a new message is being created

    interface TextMessageStartEvent {
  type: EventType.TEXT_MESSAGE_START
  messageId: string
  role: string
}

  2. Stream content: Send content chunks as they become available

    interface TextMessageContentEvent {
  type: EventType.TEXT_MESSAGE_CONTENT
  messageId: string
  delta: string // Text chunk to append
}

  3. End a message: Signal the message is complete

    interface TextMessageEndEvent {
  type: EventType.TEXT_MESSAGE_END
  messageId: string
}

This streaming approach provides a responsive user experience with immediate feedback.

​
Tool Integration in Messages

AG-UI messages elegantly integrate tool usage, allowing agents to perform actions and process their results:

​
Tool Calls

Tool calls are embedded within assistant messages:

interface ToolCall {
  id: string // Unique ID for this tool call
  type: "function" // Type of tool call
  function: {
    name: string // Name of the function to call
    arguments: string // JSON-encoded string of arguments
  }
}

Example assistant message with tool calls:

{
  id: "msg_123",
  role: "assistant",
  content: "I'll help you with that calculation.",
  toolCalls: [
    {
      id: "call_456",
      type: "function",
      function: {
        name: "calculate",
        arguments: '{"expression": "24 * 7"}'
      }
    }
  ]
}

​
Tool Results

Results from tool executions are represented as tool messages:

{
  id: "result_789",
  role: "tool",
  content: "168",
  toolCallId: "call_456" // References the original tool call
}

This creates a clear chain of tool usage:

  1. Assistant requests a tool call
  2. Tool executes and returns a result
  3. Assistant can reference and respond to the result

​
Streaming Tool Calls

Similar to text messages, tool calls can be streamed to provide real-time visibility into the agent’s actions:

  1. Start a tool call:

    interface ToolCallStartEvent {
  type: EventType.TOOL_CALL_START
  toolCallId: string
  toolCallName: string
  parentMessageId?: string // Optional link to parent message
}

  2. Stream arguments:

    interface ToolCallArgsEvent {
  type: EventType.TOOL_CALL_ARGS
  toolCallId: string
  delta: string // JSON fragment to append to arguments
}

  3. End a tool call:

    interface ToolCallEndEvent {
  type: EventType.TOOL_CALL_END
  toolCallId: string
}

This allows frontends to show tools being invoked progressively as the agent constructs its reasoning.

​
Practical Example

Here’s a complete example of a conversation with tool usage:

// Conversation history
;[
  // User query
  {
    id: "msg_1",
    role: "user",
    content: "What's the weather in New York?",
  },

  // Assistant response with tool call
  {
    id: "msg_2",
    role: "assistant",
    content: "Let me check the weather for you.",
    toolCalls: [
      {
        id: "call_1",
        type: "function",
        function: {
          name: "get_weather",
          arguments: '{"location": "New York", "unit": "celsius"}',
        },
      },
    ],
  },

  // Tool result
  {
    id: "result_1",
    role: "tool",
    content:
      '{"temperature": 22, "condition": "Partly Cloudy", "humidity": 65}',
    toolCallId: "call_1",
  },

  // Assistant's final response using tool results
  {
    id: "msg_3",
    role: "assistant",
    content:
      "The weather in New York is partly cloudy with a temperature of 22°C and 65% humidity.",
  },
]

​
Conclusion

The message structure in AG-UI enables sophisticated conversational AI experiences while maintaining vendor neutrality. By standardizing how messages are represented, synchronized, and streamed, AG-UI provides a consistent way to implement interactive human-agent communication regardless of the underlying AI service.

This system supports everything from simple text exchanges to complex tool-based workflows, all while optimizing for both real-time responsiveness and efficient data transfer.