Skip to main content

AG-UI Protocol

CloudBase Agents are fully compatible with the AG-UI Protocol, a standardized front-end and back-end communication protocol for real-time interaction between Agents and clients.

Protocol Overview​

The AG-UI protocol implements streaming communication based on SSE (Server-Sent Events) and supports:

  • Real-time transmission of Agent execution processes
  • Tool invocation and result returns
  • Human-machine interaction scenarios
  • State synchronization

Request Format​

HTTP Request​

POST /agent HTTP/1.1
Content-Type: application/json
Accept: text/event-stream

{
  "threadId": "thread-xxx",
  "runId": "run-xxx",
  "messages": [
    {
      "id": "msg-1",
      "role": "user",
      "content": "Hello"
    }
  ],
  "tools": [],
  "context": [],
  "forwardedProps": {}
}

Request Parameters​

ParameterTypeRequiredDescription
threadIdstringNoSession ID for multi-turn conversations
runIdstringNoRun ID for this invocation
messagesarrayYesMessage list
toolsarrayNoFront-end tool definitions
contextarrayNoContext information
forwardedPropsobjectNoPass-through parameters

Message Format​

interface Message {
  id: string;           // Message ID
  role: "user" | "assistant" | "system" | "tool";
  content: string;      // Message content
  name?: string;        // Tool name (when role is "tool")
  toolCallId?: string;  // Tool call ID (when role is "tool")
}

Response Format​

Responses use SSE format, with each event starting with data::

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-1"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"Hello"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-1"}

data: {"type":"RUN_FINISHED"}

Event Types​

Lifecycle Events​

Event TypeDescription
RUN_STARTEDAgent starts running
RUN_FINISHEDAgent finishes running
RUN_ERRORAgent encounters an error

Message Events​

Event TypeDescription
TEXT_MESSAGE_STARTText message starts
TEXT_MESSAGE_CONTENTText message content (incremental)
TEXT_MESSAGE_ENDText message ends

Tool Call Events​

Event TypeDescription
TOOL_CALL_STARTTool call starts
TOOL_CALL_ARGSTool call arguments (incremental)
TOOL_CALL_ENDTool call ends

State Events​

Event TypeDescription
STATE_SNAPSHOTState snapshot
STATE_DELTAState incremental update
MESSAGES_SNAPSHOTMessages snapshot

Step Events​

Event TypeDescription
STEP_STARTEDStep starts
STEP_FINISHEDStep finishes

Tool Invocation​

Server-Side Tools​

Server-side tools are executed directly by the Agent backend:

Front-End Tools​

Front-end tools require the client to execute and return results:

Front-end tool definition example:

const tools = [
  {
    name: "get_location",
    description: "Get user's current location",
    parameters: {
      type: "object",
      properties: {},
      required: []
    }
  }
];

Human-Machine Interaction​

The AG-UI protocol supports various human-machine interaction scenarios:

User Confirmation​

An Agent can request user confirmation before executing an operation:

// Server sends confirmation request
{
  type: "TOOL_CALL_START",
  toolCallId: "call-1",
  toolCallName: "confirm_action"
}

// Client returns confirmation result
{
  role: "tool",
  toolCallId: "call-1",
  content: JSON.stringify({ confirmed: true })
}

User Input​

An Agent can request additional input from the user:

// Server requests input
{
  type: "TOOL_CALL_START",
  toolCallId: "call-2",
  toolCallName: "request_input",
  args: { prompt: "Please enter your email address" }
}

// Client returns input
{
  role: "tool",
  toolCallId: "call-2",
  content: JSON.stringify({ input: "user@example.com" })
}

State Management​

State Snapshot​

An Agent can send a complete state snapshot:

{
  type: "STATE_SNAPSHOT",
  snapshot: {
    currentStep: "analyzing",
    progress: 50,
    results: []
  }
}

State Delta​

An Agent can send incremental state updates:

{
  type: "STATE_DELTA",
  delta: [
    { op: "replace", path: "/progress", value: 75 }
  ]
}

Error Handling​

Error Events​

{
  type: "RUN_ERROR",
  error: {
    code: "TOOL_EXECUTION_ERROR",
    message: "Tool execution failed"
  }
}

Common Error Codes​

Error CodeDescription
INVALID_REQUESTRequest format error
TOOL_NOT_FOUNDTool not found
TOOL_EXECUTION_ERRORTool execution failed
MODEL_ERRORModel invocation failed
TIMEOUTRequest timeout

Best Practices​

1. Message ID Management​

Ensure each message has a unique ID for easy tracking and debugging:

const messageId = `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;

2. Session Management​

Use threadId to manage multi-turn conversations:

// New session
const threadId = `thread-${Date.now()}`;

// Subsequent requests use the same threadId
{
  threadId: threadId,
  messages: [...]
}

3. Timeout Handling​

Set reasonable timeout durations:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 60000);

fetch('/agent', {
  signal: controller.signal,
  // ...
});

4. Retry Mechanism​

Implement exponential backoff retry:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fetch(url, options);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}