导航

HTML

CSS

JavaScript

浏览器 & 网络

版本管理

框架

构建工具

TypeScript

性能优化

算法

UI、组件库

Node

业务技能

针对性攻坚

AI

软实力

官方文档：https://docs.ag-ui.com/introduction

一、简述

AG-UI（Agent-User Interaction Protocol）是一种轻量级、事件驱动的开放协议，旨在标准化 AI 智能体（Agent）与前端应用（UI）之间的交互。它由 CopilotKit 团队于 2025 年 5 月开源，解决了不同 AI 智能体和前端应用之间通信方式碎片化的问题。

二、在前后端交互中起什么作用

AG-UI 原本的设计是为了各厂商的 Agent 统一响应标准和响应流程，如:Autogen Agent、LazyLLM Agent等，并不是为了整个系统的前后端交互展示设计。

但我们可以将整个基座看成一个Agent整体，将后端数据推流的响应看成是Agent的响应，并以此协议，实现流式输出的响应事件。

三、AG-UI协议响应事件

生命周期事件

运行开始事件：RUN_STARTED

{
    "type": "RUN_STARTED",    # 事件类型
    "timestamp":10693854,     # 当前时间戳
    "rawEvent":{},            # 原始事件信息（可选）
    "thread_id": "1",         # 会话id，即session_id
    "run_id": "1",            # 处理这个对话的agent_id
}

运行结束事件：RUN_FINISHED

{
    "type": "RUN_FINISHED",   # 事件类型
    "timestamp":10693854,     # 当前时间戳
    "rawEvent":{},            # 原始事件信息（可选）
    "thread_id": "1",         # 会话id，即session_id
    "run_id": "1",            # 处理这个对话的agent_id
    "result":{},              # 运行结果数据（可选）
}

运行错误事件：RUN_ERROR

{
    "type": "RUN_ERROR",          # 事件类型
    "timestamp":10693854,         # 当前时间戳
    "rawEvent":{},                # 原始事件信息（可选）
    "message": "系统错误",  # 错误信息描述
    "code": "400",                # 错误码（可选）
    "result":{},                  # 可选的运行结果数据
}

文本消息事件

文本开始事件：TEXT_MESSAGE_START

{
    "type": "TEXT_MESSAGE_START",    # 事件类型
    "timestamp":10693854,            # 当前时间戳
    "rawEvent":{},                   # 原始事件信息（可选）
    "messageId":"1096311",           # 消息的唯一id
    "role": "助手",                   # 消息发送者的作用（例如，“助手”）
}

文本内容事件：TEXT_MESSAGE_CONTENT

{
    "type": "TEXT_MESSAGE_CONTENT",    # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "messageId":"1096311",             # 消息的唯一id
    "delta": "我正在",                  # 消息内容
}

文本结束事件：TEXT_MESSAGE_END

{
    "type": "TEXT_MESSAGE_END",        # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "messageId":"1096311",             # 消息的唯一id
}

思考过程事件

思考开始事件：THINKING_TEXT_MESSAGE_START

{
    "type": "THINKING_TEXT_MESSAGE_START",    # 事件类型
    "timestamp":10693854,            # 当前时间戳
    "rawEvent":{},                   # 原始事件信息（可选）
    "messageId":"1096319",           # 消息的唯一id
    "role": "助手",                   # 消息发送者的作用（例如，“助手”）
}

思考内容事件：THINKING_TEXT_MESSAGE_CONTENT

{
    "type": "THINKING_TEXT_MESSAGE_CONTENT",    # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "messageId":"1096319",             # 消息的唯一id
    "delta": "我正在",                  # 消息内容
}

思考结束事件：THINKING_TEXT_MESSAGE_END

{
    "type": "THINKING_TEXT_MESSAGE_END",        # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "messageId":"1096319",             # 消息的唯一id
}

工具调用事件

工具调用开始：TOOL_CALL_START

{
    "type": "TOOL_CALL_START",        # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "toolCallId":"1096311",            # 工具调用的唯一id
    "toolCallName":"应用系统查询",      # 工具名称
    "parentMessageId"："1096311"       # 父消息id（可选）
}

工具调用参数：TOOL_CALL_ARGS

{
    "type": "TOOL_CALL_ARGS",        # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "toolCallId":"1096311",            # 工具调用的唯一id
    "delta":{},                        # 参数块
}

工具调用结束：TOOL_CALL_END

{
    "type": "TOOL_CALL_END",        # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "toolCallId":"1096311",            # 工具调用的唯一id
}

工具调用结果：TOOL_CALL_RESULT

{
    "type": "TOOL_CALL_RESULT",        # 事件类型
    "timestamp":10693854,              # 当前时间戳
    "rawEvent":{},                     # 原始事件信息（可选）
    "message_id":"",                   # 对话消息结果所属的ID
    "toolCallId":"1096311",            # 工具调用的唯一id
    "content":"{
        data:数据
        type:'logic_chart'
    }",                                # 工具执行的实际结果/输出内容
    "role":"tool"                      #角色标识符，通常为“tool”用于工具结果（可选）
}

自定义事件

{
    "type": "CUSTOM",                  # 事件类型
    "name":"event_name",               # 描述事件类型名称
    "timestamp":10693854,              # 当前时间戳
    "value":"content",                 # 数据内容
}

全局异常捕获

{
    "type": "CUSTOM",
    "timestamp": 1761819878,
    "raw_event": {
        "name": "系统管理员",
        "raw_event_data": null
    },
    "name": "SYSTEM_EXCEPTION",
    "value": "系统繁忙，请稍后再试。"
}

意图识别失败