HelloClaw基于 hello-agents 构建的个性化 AI Agent 实战解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agentsHelloClaw 是 hello-agents 社区共创项目中的一个完整示例它基于 hello-agents 的SimpleAgent框架实现了支持身份定制、长期/每日双轨记忆、真正的流式工具调用、多会话持久化与 Vue3 FastAPI 全栈界面的个性化 AI 助手。阅读本文后你将掌握如何继承 hello-agents 框架核心类做深度扩展、如何设计以 Markdown 文件为配置中心的 Agent 工作空间、如何用 SSE 把 ReAct 式工具调用流程流式呈现给前端以及如何构建一套规则驱动的自动记忆捕获与上下文保护机制。项目定位与核心特性HelloClaw 由社区开发者 tino-chen 基于 hello-agents 框架构建目标类似于一个认识你、记住你、随需求不断成长的个性化 AI 伙伴而不是一个普通的问答机器人。项目官方 README 中明确列出的核心能力包括智能对话基于 ReActAgent / SimpleAgent 的推理对话能力记忆系统长期记忆MEMORY.md与按日期组织的每日记忆自动管理工具调用内置文件读写、命令执行、网页搜索、网页抓取等多种工具会话管理多会话支持与会话历史持久化身份定制通过 Markdown 配置文件自定义 Agent 身份与个性流式输出基于 SSE 的实时回复与工具调用状态推送Web 界面Vue3 TypeScript Ant Design Vue 现代化前端。从项目结构看其技术选型可以归纳为一张清晰的表层级技术Agent 框架hello-agentsSimpleAgent/ReActAgent体系后端框架Python FastAPI前端框架Vue 3 TypeScript Ant Design Vue流式通信SSEServer-Sent Events包管理uv / pipPython、pnpm / npm前端后端入口与 Agent 封装集中在 src/agenthelloclaw_agent.py、enhanced_simple_agent.py、enhanced_llm.pyFastAPI 路由位于 src/api前端页面位于 frontend/src/views。快速开始从安装到跑通对话环境要求Python 3.10Node.js 18仅在运行 Web 前端时需要一个 OpenAI 兼容的 API 服务README 中提到如智谱 AI、ModelScope 等。安装依赖与启动后端依赖由 requirements.txt 声明核心包括hello-agents1.0.0、fastapi0.109.0、uvicorn[standard]0.27.0、sse-starlette2.0.0、python-dotenv、pydantic2.0.0、click、rich、httpx[socks]等。# 安装 Python 依赖 pip install -r requirements.txt运行方式有两种方式一Jupyter Notebook推荐用于快速演示jupyter lab # 打开 main.ipynb 并运行方式二运行完整 Web 服务# 启动后端 cd Co-creation-projects/tino-chen-HelloClaw pip install uvicorn uvicorn src.main:app --reload --port 8000 # 启动前端新终端 cd frontend npm install npm run dev前端默认运行在 http://localhost:5173Vite 开发服务器端口可在 frontend/vite.config.ts 中调整通过代理访问后端的 8000 端口。LLM 配置四种来源的优先级HelloClaw 的模型配置不采用单一入口而是按照构造函数参数 ~/.helloclaw/config.json 环境变量 默认值的优先级解析这一点在 src/agent/helloclaw_agent.py 的_init_llm和 src/workspace/manager.py 的get_llm_config中都有直接体现全局配置文件位于~/.helloclaw/config.json结构为{llm: {model_id: , api_key: , base_url: }}模板见 src/workspace/templates/config.json环境变量为LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL默认模型为glm-4。HelloClawAgent的构造函数还直接暴露了workspace_path、name、model_id、api_key、base_url、max_tool_iterations默认 10等参数便于在代码中覆盖配置。特别值得一提的是热加载每次chat()/achat()调用前都会执行_reload_llm_if_changed()helloclaw_agent.py对比config.json中的模型配置与当前实例是否一致不一致则重建 LLM 并替换_agent.llm引用因此修改配置文件无需重启服务即可生效。工作空间以 Markdown 文件为配置中心的身份定制体系HelloClaw 最具特色的设计是工作空间Workspace所有身份、记忆、系统提示词都以普通 Markdown 文件存放在~/.helloclaw/workspace/下由 WorkspaceManager 统一管理。目录布局如下~/.helloclaw/ ├── config.json # 全局 LLM 配置 └── workspace/ # Agent 工作空间 ├── IDENTITY.md # 身份配置名称、物种、风格、表情符号、头像 ├── MEMORY.md # 长期记忆 ├── SOUL.md # 灵魂/个性 ├── USER.md # 用户信息 ├── AGENTS.md # 系统提示词必须存在 ├── BOOTSTRAP.md # 入职引导身份确定后自动删除 ├── HEARTBEAT.md # 心跳配置 ├── memory/ # 每日记忆YYYY-MM-DD.md └── sessions/ # 会话历史JSONWorkspaceManager在初始化时会通过ensure_workspace_exists()自动创建上述目录并从 src/workspace/templates 读取模板生成缺失的配置文件CONFIG_FILES列表见 manager.py。它还提供完整的配置读写 APIload_config/save_config/list_configs以及记忆与会话的增删查改方法。系统提示词的动态拼装HelloClawAgent._build_system_prompt()helloclaw_agent.py以AGENTS.md为基础提示词然后按以下顺序把其他配置文件拼接为上下文若入职未完成BOOTSTRAP.md仍存在注入## 初始化引导内容注入## 你的身份信息IDENTITY注入## 用户信息USER注入## 人格模板SOUL注入## 长期记忆MEMORY。由于每次对话都会重建系统提示词因此编辑任何一个 Markdown 配置文件都会在下一次对话中立即生效这正是热加载配置的另一层含义。入职Onboarding机制工作空间还内置了一套新颖的入职流程当用户还没有告诉 Agent 它是什么时BOOTSTRAP.md会作为引导脚本注入系统提示词引导 Agent 与用户聊天、弄清自己的名字、物种、风格、表情符号并写入IDENTITY.md与USER.md。BOOTSTRAP.md 模板 中甚至有完成之后删除这个文件你不再需要引导脚本了的设计。实现上_is_identity_established()manager.py通过正则\*\*名称[:]\*\*\s*(.?)(?:\n|$)解析IDENTITY.md中的名称字段只要名称非空、不以_开头、不包含选一个或等占位符特征就判定身份已确立并自动删除BOOTSTRAP.md。Agent 自身的名字也会在初始化时用同样的解析逻辑从IDENTITY.md读取helloclaw_agent.py未设置时回退到HelloClaw。增强版流式工具调用从流式文本到流式工具README 强调 HelloClaw 的技术亮点之一是真正的流式工具调用——不是简单的流式文本输出而是完整的流式工具调用流程。这一能力由两个自研类协作完成代码分别在src/agent/enhanced_llm.pyEnhancedHelloAgentsLLM继承 hello-agents 的HelloAgentsLLMsrc/agent/enhanced_simple_agent.pyEnhancedSimpleAgent继承 hello-agents 的SimpleAgent。底层流式 Function Calling 的统一事件模型EnhancedHelloAgentsLLM.astream_invoke_with_tools()enhanced_llm.py直接使用openai.AsyncOpenAI客户端发起streamTrue的 chat completions 请求并把响应流统一封装为四种StreamToolEventType定义见 enhanced_llm.py事件类型含义CONTENT文本内容增量TOOL_CALL_START收到工具调用的 ID 与名称TOOL_CALL_DELTA工具调用参数arguments的增量FINISH流结束携带finish_reason每个 delta 分片都会同步累积进StreamToolCallResult对象提供add_content、add_tool_call_start、add_tool_call_delta等方法enhanced_llm.py最终通过get_last_stream_tool_result()取回完整结果。该结果可以转换为符合 OpenAI 规范的 assistant 消息to_assistant_message()包含tool_calls数组可直接追加回消息历史供下一轮迭代继续使用。上层Agent 循环中的工具调用编排EnhancedSimpleAgent.arun_stream_with_tools()enhanced_simple_agent.py实现了一个完整的 ReAct 式循环发送AGENT_START/STEP_START事件调用llm.astream_invoke_with_tools(messages, tools, tool_choiceauto)把CONTENT事件转发为LLM_CHUNK实时推给前端从累积结果中取出get_complete_tool_calls()若没有工具调用则直接产出最终回答并跳出循环若有工具调用把 assistant 消息追加到消息历史逐个执行工具并在执行前后分别发出TOOL_CALL_START与TOOL_CALL_FINISH事件其中await asyncio.sleep(0)用于让出控制权确保 SSE 先推送 start 事件再执行工具工具结果以role: tool消息回填到历史进入下一轮迭代直到达到max_tool_iterations默认 10若达到上限仍未结束会再调用一次astream_invoke兜底获取最终回答。该 Agent 还做了良好的降级处理如果传入的是普通HelloAgentsLLM不支持流式工具调用会发出UserWarning并回退到基类SimpleAgent.run()的非流式同步模式enhanced_simple_agent.py纯对话场景无工具则走_stream_without_tools()直接流式输出文本。SSE 透传从 Agent 事件到前端消息后端通过 src/api/chat.py 的POST /chat/send/stream接口用sse-starlette的EventSourceResponse把 Agent 事件逐条映射为 SSE 事件session、step_start、chunk、tool_start、tool_finish、step_finish、done、error。前端收到tool_start时即可渲染正在调用工具 X的状态卡片收到chunk时增量渲染文本实现接近 ChatGPT 的实时交互体验。记忆系统长期记忆、每日记忆与上下文保护HelloClaw 的记忆体系是文件即记忆思想的具体实现核心模块位于 src/memory长期记忆MEMORY.md跨会话持久保存的重要信息通过MemoryTool的memory_update_longterm动作追加内容每日记忆memory/YYYY-MM-DD.md按日期自动分类通过memory_add动作或自动捕获写入Memory Flush上下文接近压缩阈值时自动提醒 Agent 保存重要信息。MemoryCaptureManager规则驱动的自动记忆捕获src/memory/capture.py 定义了一套中文友好的触发正则MEMORY_TRIGGERS将信息自动归类为四类分类触发示例正则片段fact记住\|记下\|remember\|keep in mind、事实上\|实际上\|the fact ispreference我喜欢\|我偏好\|prefer\|like\|love\|hate\|讨厌\|不喜欢decision决定了\|decision\|用这个\|选定\|确定用\|就用entity电话号码、邮箱地址、我的\w是\|is my\|我的电话\|我的邮箱\|我的地址处理流程为按中英文句号/问号/感叹号/换行切分句子 → 匹配触发规则获取分类 → 清理前缀用户/我/你/assistant/user:与引号 → 偏好类统一补上用户主语 → 与已有记忆做去重WorkspaceManager.check_duplicate_memory通过中文停用词过滤 关键词重叠率计算默认阈值 0.7→ 以- [category] content的带标签格式追加到当日记忆文件manager.py。整个捕获在achat()的对话流程末尾异步执行_capture_memorieshelloclaw_agent.py不阻塞用户。MemoryFlushManager压缩前的最后抢救src/memory/memory_flush.py 实现触发判定当估算 token 数达到context_window × compression_threshold − soft_threshold_tokens时触发。在HelloClawAgent中对应的配置为context_window128000、compression_threshold0.8、soft_threshold_tokens4000即约 98400 token 时触发。触发后Agent 会执行一个对用户不可见的静默回合_check_and_run_memory_flushhelloclaw_agent.py注入get_flush_prompt()生成的提示词指示 Agent 用memory_add把重要事实/决策/偏好写入当日记忆、用memory_update_longterm写入长期记忆若没有值得保存的内容则回复[SILENT]由is_silent_response()识别后跳过。token 估算采用字符数 / 3的保守近似_estimate_tokenshelloclaw_agent.py兼顾中英文差异。MemoryTool让 Agent 自己管理记忆src/tools/builtin/memory.py 定义了一个可展开expandableTrue的MemoryTool为 LLM 暴露了五个记忆动作memory_search按关键词搜索长期/每日记忆返回带行号与上下文的代码块格式复用search_memory_enhancedmemory_get读取指定记忆文件或行范围如lines10-20memory_add向今日记忆追加内容可选preference/decision/entity/fact分类memory_update_longterm向MEMORY.md追加长期记忆memory_list/memory_cleanup列出记忆文件、按天数默认 30 天清理过期每日记忆。工具集内置工具与安全边界HelloClawAgent._setup_tools()helloclaw_agent.py将 hello-agents 内置工具与 HelloClaw 自定义工具注册到同一个ToolRegistry工具来源说明ReadTool/WriteTool/EditToolhello-agents 内置文件读写project_root限定在工作空间CalculatorToolhello-agents 内置计算器MemoryToolHelloClaw 自定义记忆管理见上文ExecuteCommandToolHelloClaw 自定义安全命令执行WebSearchToolHelloClaw 自定义网页搜索README 标注需要BRAVE_API_KEYWebFetchToolHelloClaw 自定义网页抓取其中ExecuteCommandToolsrc/tools/builtin/execute_command.py值得单独说明它体现了 Agent 工具的安全设计命令白名单仅允许ls、cat、echo、pwd、git、npm、pnpm、uv、python、node、pip、mkdir、grep、find、head、tail等基础命令execute_command.py危险模式拦截用正则拦截rm -rf、sudo、chmod 777、mkfs、dd if、shutdown、reboot、fork 炸弹等execute_command.py目录限制在HelloClawAgent中构造时传入allowed_directories[workspace_path]把命令执行限制在工作空间内_validate_workdir用startswith做路径前缀校验超时与输出截断默认 30 秒超时输出超过 10000 字符自动截断并标注。会话管理持久化与多会话会话由 hello-agents 框架层的Config启用session_enabledTrue、session_dirworkspace/sessions每次对话结束后通过save_session落盘为 JSON。HelloClawAgent在此基础上封装了完整的管理 APIhelloclaw_agent.pycreate_session()生成 8 位 UUID 会话 IDlist_sessions()按最后更新时间倒序列出所有会话delete_session()/get_session_history()删除会话、读取历史支持user/assistant/tool三种角色并保留metadata中的tool_calls会话历史中还记录了完整工具调用记录工具名、参数、结果、状态前端 SessionsView.vue 与 MemoryView.vue 可分别展示会话列表与记忆文件。每次对话的调用链还会做两件保洁工作LLM 调用参数固定加入frequency_penalty0.5与presence_penalty0.3用于降低重复、鼓励新话题helloclaw_agent.py。使用示例同步对话与流式对话基础对话同步from src.agent.helloclaw_agent import HelloClawAgent # 创建 Agent agent HelloClawAgent() # 同步对话 response agent.chat(你好请介绍一下你自己) print(response)流式对话异步import asyncio async def chat_stream(): agent HelloClawAgent() async for event in agent.achat(帮我搜索一下今天的新闻): if event.type.value llm_chunk: print(event.data.get(chunk, ), end, flushTrue) elif event.type.value tool_call_start: print(f\n[调用工具: {event.data.get(tool_name)}]) elif event.type.value tool_call_finish: print(f[工具执行完成]) asyncio.run(chat_stream())流式事件的核心是StreamEventType枚举AGENT_START/STEP_START/LLM_CHUNK/TOOL_CALL_START/TOOL_CALL_FINISH/STEP_FINISH/AGENT_FINISH/ERROR无论是 Python 客户端直接消费还是经 src/api/chat.py 的 SSE 接口透传给浏览器遵循的都是同一套事件契约。项目结构速览Co-creation-projects/tino-chen-HelloClaw/ ├── README.md # 项目说明文档 ├── requirements.txt # Python 依赖列表 ├── main.ipynb # 快速演示 Notebook ├── data/ # 数据文件 ├── outputs/helloclaw.png # 项目界面截图 ├── src/ # 后端源代码 │ ├── agent/ # Agent 封装helloclaw_agent / enhanced_simple_agent / enhanced_llm │ ├── tools/builtin/ # 自定义工具memory / execute_command / web_search / web_fetch │ ├── memory/ # 记忆管理capture / memory_flush / session_summarizer │ ├── workspace/ # 工作空间管理manager templates │ ├── api/ # FastAPI 路由chat / session / config / memory │ ├── cli/ # CLI 入口 │ └── channels/ # 渠道封装cli_channel └── frontend/ # Vue3 前端views / components / api / router / stores小结与扩展方向HelloClaw 完整地展示了在 hello-agents 框架之上构建生产级个性化 Agent的典型路径用EnhancedHelloAgentsLLMEnhancedSimpleAgent解决流式工具调用的体验问题用WorkspaceManager Markdown 模板体系解决Agent 人格/记忆可配置、可持久化、可热加载的问题用规则驱动 关键词重叠去重的轻量方案解决记忆自动捕获问题用 Memory Flush 静默回合缓解长对话上下文压缩带来的信息丢失再用 FastAPI SSE Vue3 把整个流程变成可交互的 Web 产品。从项目结构看作者还为后续演进预留了明确方向多模态输入、更多内置工具代码解释器、数据库查询等、Agent 间协作与语音交互。如果你正在基于 hello-agents 做自己的 Agent 应用这个仓库的工作空间设计、流式工具事件模型和记忆管理方案都值得直接借鉴。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/18 20:10:15 · 阅读 1.2k HelloClaw：基于 hello-agents 构建的个性化 AI Agent 实战解析
HelloClaw基于 hello-agents 构建的个性化 AI Agent 实战解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agentsHelloClaw 是 hello-agents 社区共创项目中的一个完整示例它基于 hello-agents 的SimpleAgent框架实现了支持身份定制、长期/每日双轨记忆、真正的流式工具调用、多会话持久化与 Vue3 FastAPI 全栈界面的个性化 AI 助手。阅读本文后你将掌握如何继承 hello-agents 框架核心类做深度扩展、如何设计以 Markdown 文件为配置中心的 Agent 工作空间、如何用 SSE 把 ReAct 式工具调用流程流式呈现给前端以及如何构建一套规则驱动的自动记忆捕获与上下文保护机制。项目定位与核心特性HelloClaw 由社区开发者 tino-chen 基于 hello-agents 框架构建目标类似于一个认识你、记住你、随需求不断成长的个性化 AI 伙伴而不是一个普通的问答机器人。项目官方 README 中明确列出的核心能力包括智能对话基于 ReActAgent / SimpleAgent 的推理对话能力记忆系统长期记忆MEMORY.md与按日期组织的每日记忆自动管理工具调用内置文件读写、命令执行、网页搜索、网页抓取等多种工具会话管理多会话支持与会话历史持久化身份定制通过 Markdown 配置文件自定义 Agent 身份与个性流式输出基于 SSE 的实时回复与工具调用状态推送Web 界面Vue3 TypeScript Ant Design Vue 现代化前端。从项目结构看其技术选型可以归纳为一张清晰的表层级技术Agent 框架hello-agentsSimpleAgent/ReActAgent体系后端框架Python FastAPI前端框架Vue 3 TypeScript Ant Design Vue流式通信SSEServer-Sent Events包管理uv / pipPython、pnpm / npm前端后端入口与 Agent 封装集中在 src/agenthelloclaw_agent.py、enhanced_simple_agent.py、enhanced_llm.pyFastAPI 路由位于 src/api前端页面位于 frontend/src/views。快速开始从安装到跑通对话环境要求Python 3.10Node.js 18仅在运行 Web 前端时需要一个 OpenAI 兼容的 API 服务README 中提到如智谱 AI、ModelScope 等。安装依赖与启动后端依赖由 requirements.txt 声明核心包括hello-agents1.0.0、fastapi0.109.0、uvicorn[standard]0.27.0、sse-starlette2.0.0、python-dotenv、pydantic2.0.0、click、rich、httpx[socks]等。# 安装 Python 依赖 pip install -r requirements.txt运行方式有两种方式一Jupyter Notebook推荐用于快速演示jupyter lab # 打开 main.ipynb 并运行方式二运行完整 Web 服务# 启动后端 cd Co-creation-projects/tino-chen-HelloClaw pip install uvicorn uvicorn src.main:app --reload --port 8000 # 启动前端新终端 cd frontend npm install npm run dev前端默认运行在 http://localhost:5173Vite 开发服务器端口可在 frontend/vite.config.ts 中调整通过代理访问后端的 8000 端口。LLM 配置四种来源的优先级HelloClaw 的模型配置不采用单一入口而是按照构造函数参数 ~/.helloclaw/config.json 环境变量 默认值的优先级解析这一点在 src/agent/helloclaw_agent.py 的_init_llm和 src/workspace/manager.py 的get_llm_config中都有直接体现全局配置文件位于~/.helloclaw/config.json结构为{llm: {model_id: , api_key: , base_url: }}模板见 src/workspace/templates/config.json环境变量为LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL默认模型为glm-4。HelloClawAgent的构造函数还直接暴露了workspace_path、name、model_id、api_key、base_url、max_tool_iterations默认 10等参数便于在代码中覆盖配置。特别值得一提的是热加载每次chat()/achat()调用前都会执行_reload_llm_if_changed()helloclaw_agent.py对比config.json中的模型配置与当前实例是否一致不一致则重建 LLM 并替换_agent.llm引用因此修改配置文件无需重启服务即可生效。工作空间以 Markdown 文件为配置中心的身份定制体系HelloClaw 最具特色的设计是工作空间Workspace所有身份、记忆、系统提示词都以普通 Markdown 文件存放在~/.helloclaw/workspace/下由 WorkspaceManager 统一管理。目录布局如下~/.helloclaw/ ├── config.json # 全局 LLM 配置 └── workspace/ # Agent 工作空间 ├── IDENTITY.md # 身份配置名称、物种、风格、表情符号、头像 ├── MEMORY.md # 长期记忆 ├── SOUL.md # 灵魂/个性 ├── USER.md # 用户信息 ├── AGENTS.md # 系统提示词必须存在 ├── BOOTSTRAP.md # 入职引导身份确定后自动删除 ├── HEARTBEAT.md # 心跳配置 ├── memory/ # 每日记忆YYYY-MM-DD.md └── sessions/ # 会话历史JSONWorkspaceManager在初始化时会通过ensure_workspace_exists()自动创建上述目录并从 src/workspace/templates 读取模板生成缺失的配置文件CONFIG_FILES列表见 manager.py。它还提供完整的配置读写 APIload_config/save_config/list_configs以及记忆与会话的增删查改方法。系统提示词的动态拼装HelloClawAgent._build_system_prompt()helloclaw_agent.py以AGENTS.md为基础提示词然后按以下顺序把其他配置文件拼接为上下文若入职未完成BOOTSTRAP.md仍存在注入## 初始化引导内容注入## 你的身份信息IDENTITY注入## 用户信息USER注入## 人格模板SOUL注入## 长期记忆MEMORY。由于每次对话都会重建系统提示词因此编辑任何一个 Markdown 配置文件都会在下一次对话中立即生效这正是热加载配置的另一层含义。入职Onboarding机制工作空间还内置了一套新颖的入职流程当用户还没有告诉 Agent 它是什么时BOOTSTRAP.md会作为引导脚本注入系统提示词引导 Agent 与用户聊天、弄清自己的名字、物种、风格、表情符号并写入IDENTITY.md与USER.md。BOOTSTRAP.md 模板 中甚至有完成之后删除这个文件你不再需要引导脚本了的设计。实现上_is_identity_established()manager.py通过正则\*\*名称[:]\*\*\s*(.?)(?:\n|$)解析IDENTITY.md中的名称字段只要名称非空、不以_开头、不包含选一个或等占位符特征就判定身份已确立并自动删除BOOTSTRAP.md。Agent 自身的名字也会在初始化时用同样的解析逻辑从IDENTITY.md读取helloclaw_agent.py未设置时回退到HelloClaw。增强版流式工具调用从流式文本到流式工具README 强调 HelloClaw 的技术亮点之一是真正的流式工具调用——不是简单的流式文本输出而是完整的流式工具调用流程。这一能力由两个自研类协作完成代码分别在src/agent/enhanced_llm.pyEnhancedHelloAgentsLLM继承 hello-agents 的HelloAgentsLLMsrc/agent/enhanced_simple_agent.pyEnhancedSimpleAgent继承 hello-agents 的SimpleAgent。底层流式 Function Calling 的统一事件模型EnhancedHelloAgentsLLM.astream_invoke_with_tools()enhanced_llm.py直接使用openai.AsyncOpenAI客户端发起streamTrue的 chat completions 请求并把响应流统一封装为四种StreamToolEventType定义见 enhanced_llm.py事件类型含义CONTENT文本内容增量TOOL_CALL_START收到工具调用的 ID 与名称TOOL_CALL_DELTA工具调用参数arguments的增量FINISH流结束携带finish_reason每个 delta 分片都会同步累积进StreamToolCallResult对象提供add_content、add_tool_call_start、add_tool_call_delta等方法enhanced_llm.py最终通过get_last_stream_tool_result()取回完整结果。该结果可以转换为符合 OpenAI 规范的 assistant 消息to_assistant_message()包含tool_calls数组可直接追加回消息历史供下一轮迭代继续使用。上层Agent 循环中的工具调用编排EnhancedSimpleAgent.arun_stream_with_tools()enhanced_simple_agent.py实现了一个完整的 ReAct 式循环发送AGENT_START/STEP_START事件调用llm.astream_invoke_with_tools(messages, tools, tool_choiceauto)把CONTENT事件转发为LLM_CHUNK实时推给前端从累积结果中取出get_complete_tool_calls()若没有工具调用则直接产出最终回答并跳出循环若有工具调用把 assistant 消息追加到消息历史逐个执行工具并在执行前后分别发出TOOL_CALL_START与TOOL_CALL_FINISH事件其中await asyncio.sleep(0)用于让出控制权确保 SSE 先推送 start 事件再执行工具工具结果以role: tool消息回填到历史进入下一轮迭代直到达到max_tool_iterations默认 10若达到上限仍未结束会再调用一次astream_invoke兜底获取最终回答。该 Agent 还做了良好的降级处理如果传入的是普通HelloAgentsLLM不支持流式工具调用会发出UserWarning并回退到基类SimpleAgent.run()的非流式同步模式enhanced_simple_agent.py纯对话场景无工具则走_stream_without_tools()直接流式输出文本。SSE 透传从 Agent 事件到前端消息后端通过 src/api/chat.py 的POST /chat/send/stream接口用sse-starlette的EventSourceResponse把 Agent 事件逐条映射为 SSE 事件session、step_start、chunk、tool_start、tool_finish、step_finish、done、error。前端收到tool_start时即可渲染正在调用工具 X的状态卡片收到chunk时增量渲染文本实现接近 ChatGPT 的实时交互体验。记忆系统长期记忆、每日记忆与上下文保护HelloClaw 的记忆体系是文件即记忆思想的具体实现核心模块位于 src/memory长期记忆MEMORY.md跨会话持久保存的重要信息通过MemoryTool的memory_update_longterm动作追加内容每日记忆memory/YYYY-MM-DD.md按日期自动分类通过memory_add动作或自动捕获写入Memory Flush上下文接近压缩阈值时自动提醒 Agent 保存重要信息。MemoryCaptureManager规则驱动的自动记忆捕获src/memory/capture.py 定义了一套中文友好的触发正则MEMORY_TRIGGERS将信息自动归类为四类分类触发示例正则片段fact记住\|记下\|remember\|keep in mind、事实上\|实际上\|the fact ispreference我喜欢\|我偏好\|prefer\|like\|love\|hate\|讨厌\|不喜欢decision决定了\|decision\|用这个\|选定\|确定用\|就用entity电话号码、邮箱地址、我的\w是\|is my\|我的电话\|我的邮箱\|我的地址处理流程为按中英文句号/问号/感叹号/换行切分句子 → 匹配触发规则获取分类 → 清理前缀用户/我/你/assistant/user:与引号 → 偏好类统一补上用户主语 → 与已有记忆做去重WorkspaceManager.check_duplicate_memory通过中文停用词过滤 关键词重叠率计算默认阈值 0.7→ 以- [category] content的带标签格式追加到当日记忆文件manager.py。整个捕获在achat()的对话流程末尾异步执行_capture_memorieshelloclaw_agent.py不阻塞用户。MemoryFlushManager压缩前的最后抢救src/memory/memory_flush.py 实现触发判定当估算 token 数达到context_window × compression_threshold − soft_threshold_tokens时触发。在HelloClawAgent中对应的配置为context_window128000、compression_threshold0.8、soft_threshold_tokens4000即约 98400 token 时触发。触发后Agent 会执行一个对用户不可见的静默回合_check_and_run_memory_flushhelloclaw_agent.py注入get_flush_prompt()生成的提示词指示 Agent 用memory_add把重要事实/决策/偏好写入当日记忆、用memory_update_longterm写入长期记忆若没有值得保存的内容则回复[SILENT]由is_silent_response()识别后跳过。token 估算采用字符数 / 3的保守近似_estimate_tokenshelloclaw_agent.py兼顾中英文差异。MemoryTool让 Agent 自己管理记忆src/tools/builtin/memory.py 定义了一个可展开expandableTrue的MemoryTool为 LLM 暴露了五个记忆动作memory_search按关键词搜索长期/每日记忆返回带行号与上下文的代码块格式复用search_memory_enhancedmemory_get读取指定记忆文件或行范围如lines10-20memory_add向今日记忆追加内容可选preference/decision/entity/fact分类memory_update_longterm向MEMORY.md追加长期记忆memory_list/memory_cleanup列出记忆文件、按天数默认 30 天清理过期每日记忆。工具集内置工具与安全边界HelloClawAgent._setup_tools()helloclaw_agent.py将 hello-agents 内置工具与 HelloClaw 自定义工具注册到同一个ToolRegistry工具来源说明ReadTool/WriteTool/EditToolhello-agents 内置文件读写project_root限定在工作空间CalculatorToolhello-agents 内置计算器MemoryToolHelloClaw 自定义记忆管理见上文ExecuteCommandToolHelloClaw 自定义安全命令执行WebSearchToolHelloClaw 自定义网页搜索README 标注需要BRAVE_API_KEYWebFetchToolHelloClaw 自定义网页抓取其中ExecuteCommandToolsrc/tools/builtin/execute_command.py值得单独说明它体现了 Agent 工具的安全设计命令白名单仅允许ls、cat、echo、pwd、git、npm、pnpm、uv、python、node、pip、mkdir、grep、find、head、tail等基础命令execute_command.py危险模式拦截用正则拦截rm -rf、sudo、chmod 777、mkfs、dd if、shutdown、reboot、fork 炸弹等execute_command.py目录限制在HelloClawAgent中构造时传入allowed_directories[workspace_path]把命令执行限制在工作空间内_validate_workdir用startswith做路径前缀校验超时与输出截断默认 30 秒超时输出超过 10000 字符自动截断并标注。会话管理持久化与多会话会话由 hello-agents 框架层的Config启用session_enabledTrue、session_dirworkspace/sessions每次对话结束后通过save_session落盘为 JSON。HelloClawAgent在此基础上封装了完整的管理 APIhelloclaw_agent.pycreate_session()生成 8 位 UUID 会话 IDlist_sessions()按最后更新时间倒序列出所有会话delete_session()/get_session_history()删除会话、读取历史支持user/assistant/tool三种角色并保留metadata中的tool_calls会话历史中还记录了完整工具调用记录工具名、参数、结果、状态前端 SessionsView.vue 与 MemoryView.vue 可分别展示会话列表与记忆文件。每次对话的调用链还会做两件保洁工作LLM 调用参数固定加入frequency_penalty0.5与presence_penalty0.3用于降低重复、鼓励新话题helloclaw_agent.py。使用示例同步对话与流式对话基础对话同步from src.agent.helloclaw_agent import HelloClawAgent # 创建 Agent agent HelloClawAgent() # 同步对话 response agent.chat(你好请介绍一下你自己) print(response)流式对话异步import asyncio async def chat_stream(): agent HelloClawAgent() async for event in agent.achat(帮我搜索一下今天的新闻): if event.type.value llm_chunk: print(event.data.get(chunk, ), end, flushTrue) elif event.type.value tool_call_start: print(f\n[调用工具: {event.data.get(tool_name)}]) elif event.type.value tool_call_finish: print(f[工具执行完成]) asyncio.run(chat_stream())流式事件的核心是StreamEventType枚举AGENT_START/STEP_START/LLM_CHUNK/TOOL_CALL_START/TOOL_CALL_FINISH/STEP_FINISH/AGENT_FINISH/ERROR无论是 Python 客户端直接消费还是经 src/api/chat.py 的 SSE 接口透传给浏览器遵循的都是同一套事件契约。项目结构速览Co-creation-projects/tino-chen-HelloClaw/ ├── README.md # 项目说明文档 ├── requirements.txt # Python 依赖列表 ├── main.ipynb # 快速演示 Notebook ├── data/ # 数据文件 ├── outputs/helloclaw.png # 项目界面截图 ├── src/ # 后端源代码 │ ├── agent/ # Agent 封装helloclaw_agent / enhanced_simple_agent / enhanced_llm │ ├── tools/builtin/ # 自定义工具memory / execute_command / web_search / web_fetch │ ├── memory/ # 记忆管理capture / memory_flush / session_summarizer │ ├── workspace/ # 工作空间管理manager templates │ ├── api/ # FastAPI 路由chat / session / config / memory │ ├── cli/ # CLI 入口 │ └── channels/ # 渠道封装cli_channel └── frontend/ # Vue3 前端views / components / api / router / stores小结与扩展方向HelloClaw 完整地展示了在 hello-agents 框架之上构建生产级个性化 Agent的典型路径用EnhancedHelloAgentsLLMEnhancedSimpleAgent解决流式工具调用的体验问题用WorkspaceManager Markdown 模板体系解决Agent 人格/记忆可配置、可持久化、可热加载的问题用规则驱动 关键词重叠去重的轻量方案解决记忆自动捕获问题用 Memory Flush 静默回合缓解长对话上下文压缩带来的信息丢失再用 FastAPI SSE Vue3 把整个流程变成可交互的 Web 产品。从项目结构看作者还为后续演进预留了明确方向多模态输入、更多内置工具代码解释器、数据库查询等、Agent 间协作与语音交互。如果你正在基于 hello-agents 做自己的 Agent 应用这个仓库的工作空间设计、流式工具事件模型和记忆管理方案都值得直接借鉴。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考