Hermes WebUI Agent调用机制：深入理解_run_agent_streaming函数的工作原理

史琼鸽Power

887人浏览 · 2026-06-01 08:50:17

史琼鸽Power · 2026-06-01 08:50:17 发布

Hermes WebUI Agent调用机制：深入理解_run_agent_streaming函数的工作原理

【免费下载链接】hermes-webui Hermes WebUI: The best way to use Hermes Agent from the web or from your phone! 项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui

Hermes WebUI作为Hermes Agent的Web界面，其核心功能是提供流畅的AI对话体验。今天我们将深入探讨这个开源项目中最重要的函数之一——_run_agent_streaming，它负责处理所有的Agent调用和实时流式响应。无论你是想了解Hermes WebUI的内部机制，还是想学习如何构建类似的大语言模型应用，这篇文章都会为你提供完整的解析。

什么是Hermes WebUI？

Hermes WebUI是一个轻量级的Web应用程序，让你可以通过浏览器界面使用Hermes Agent，获得与CLI终端完全相同的功能体验。它采用三面板设计：左侧是会话管理侧边栏，中间是聊天区域，右侧是按需打开的工作区文件浏览器。

Hermes WebUI的会话管理界面，展示项目、标签和工具调用卡片

_run_agent_streaming函数的核心作用

_run_agent_streaming函数位于api/streaming.py文件的第3843行，是整个Hermes WebUI流式处理引擎的心脏。这个函数负责：

启动后台Agent线程 - 在单独的线程中运行AI Agent
处理实时流式响应 - 通过Server-Sent Events（SSE）向浏览器推送token
管理会话状态 - 更新会话消息和元数据
处理工具调用 - 协调Agent与外部工具的交互
实现取消机制 - 允许用户随时中断长时间运行的任务

函数签名和参数

def _run_agent_streaming(
    session_id,      # 会话唯一标识符
    msg_text,        # 用户输入的文本消息
    model,           # 使用的AI模型
    workspace,       # 工作区路径
    stream_id,       # 流式连接ID
    attachments=None, # 附件文件
    *,               # 关键字参数分隔符
    ephemeral=False,  # 是否为临时会话
    model_provider=None, # 模型提供商
    goal_related=False,  # 是否与目标相关
):

流式处理架构解析

1. 初始化阶段

当用户发送消息时，WebUI前端会调用/api/chat/start端点，该端点：

创建一个queue.Queue对象
将其存储在全局的STREAMS[stream_id]字典中
启动一个守护线程执行_run_agent_streaming函数
立即返回{stream_id}给前端

2. SSE连接建立

前端随后通过GET /api/chat/stream?stream_id=...建立长连接，从队列中读取事件并实时推送到浏览器界面。

工作区文件浏览器和内联预览功能，右侧面板按需打开

关键技术实现细节

环境变量管理

由于Hermes Agent依赖环境变量来确定工作目录和执行权限，_run_agent_streaming函数需要精心管理这些变量：

# 保存当前环境变量
old_cwd = os.getcwd()
old_hermes_home = os.environ.get('HERMES_HOME')

# 设置会话特定的环境变量
os.environ['TERMINAL_CWD'] = workspace
os.environ['HERMES_EXEC_ASK'] = '1'
os.environ['HERMES_SESSION_KEY'] = session_id
os.environ['HERMES_HOME'] = profile_home

# 在finally块中恢复原始环境
os.chdir(old_cwd)
if old_hermes_home:
    os.environ['HERMES_HOME'] = old_hermes_home
else:
    os.environ.pop('HERMES_HOME', None)

取消机制实现

Hermes WebUI实现了完善的取消机制，让用户可以随时中断长时间运行的Agent任务：

# 创建取消事件
cancel_event = threading.Event()
with STREAMS_LOCK:
    CANCEL_FLAGS[stream_id] = cancel_event
    
# 在Agent执行过程中检查取消状态
if cancel_event.is_set():
    put('cancel', {'reason': 'user_cancelled'})
    return

实时token流式传输

on_token回调函数负责将AI生成的文本分块推送到前端：

def on_token(text):
    if text is None:  # 流结束标记
        return
    put('token', {'text': text})
    # 累积部分文本用于UI显示
    STREAM_PARTIAL_TEXT[stream_id] += text

会话状态管理

消息持久化

当Agent完成响应后，_run_agent_streaming函数会：

将新的对话回合添加到会话消息列表中
自动生成或更新会话标题
将会话状态保存到磁盘
发送done事件通知前端

工具调用集成

Hermes Agent支持丰富的工具调用功能，_run_agent_streaming通过回调机制实时处理：

工具开始：显示工具卡片和预览信息
工具完成：显示执行结果和输出
审批请求：暂停执行等待用户确认

错误处理和恢复机制

异常处理策略

函数采用了多层异常处理来确保稳定性：

try:
    # 主要执行逻辑
    result = agent.run_conversation(...)
except Exception as e:
    # 分类错误类型
    error_type = _classify_provider_error(str(e), e)
    put('error', {
        'message': str(e),
        'type': error_type,
        'hint': _provider_error_hint(error_type)
    })
finally:
    # 确保资源清理
    _cleanup_stream_resources(stream_id)