Back to Hello Agents

HelloClaw - 个性化 AI Agent 助手

Co-creation-projects/tino-chen-HelloClaw/main.ipynb

1.0.26.4 KB
Original Source

HelloClaw - 个性化 AI Agent 助手

项目简介

HelloClaw 是一个基于 Hello-Agents 框架构建的个性化 AI Agent 应用。

核心特性:

  • 支持自定义 Agent 身份和个性
  • 长期记忆和每日记忆的自动管理
  • 流式工具调用,实时反馈执行状态
  • 多会话支持,会话历史持久化

作者信息

  • 作者: tino-chen
  • GitHub: @tino-chen
  • 日期: 2025-03

第1部分:环境配置

python
# 安装依赖(如果需要)
# !pip install -q hello-agents fastapi uvicorn python-dotenv pydantic httpx[socks]
python
import os
import sys
from dotenv import load_dotenv

# 添加项目路径
sys.path.insert(0, os.path.dirname(os.path.abspath('__file__')))

# 加载环境变量
load_dotenv()

# 配置 LLM(请替换为你的 API 密钥)
# 方式1: 使用环境变量
# 方式2: 直接设置
# os.environ["LLM_MODEL_ID"] = "glm-4"
# os.environ["LLM_API_KEY"] = "your-api-key"
# os.environ["LLM_BASE_URL"] = "https://open.bigmodel.cn/api/paas/v4/"

print("环境配置完成!")

第2部分:导入模块和核心类

python
from hello_agents import Config
from hello_agents.tools import ToolRegistry, ReadTool, WriteTool, CalculatorTool
from hello_agents.core.llm import HelloAgentsLLM

# 导入 HelloClaw 核心模块
from src.agent.helloclaw_agent import HelloClawAgent

print("模块导入成功!")

第3部分:自定义工具定义

HelloClaw 实现了多个自定义工具,这里展示核心工具的实现。

python
# HelloClawAgent 使用说明
# 
# HelloClawAgent 是项目的核心类,它会自动:
# 1. 初始化工作空间(~/.helloclaw/workspace)
# 2. 从配置文件加载系统提示词(AGENTS.md、IDENTITY.md 等)
# 3. 注册所有内置工具和自定义工具
# 4. 配置记忆管理系统
#
# 主要工具包括:
# - Read/Write/Edit: 文件操作(包括长期记忆 MEMORY.md)
# - python_calculator: 数学计算
# - memory_*: 记忆管理(每日记忆、搜索、列表等)
# - exec_*: 命令执行
# - search_web/fetch_url: 网页搜索和抓取

print("HelloClawAgent 工具说明已加载!")

第4部分:创建智能体

使用 HelloAgents 框架创建一个具备工具调用能力的智能体。

python
# 创建 HelloClawAgent
# 
# HelloClawAgent 会自动:
# - 初始化工作空间 ~/.helloclaw/workspace
# - 加载 LLM 配置(从 .env 或 config.json)
# - 注册所有工具
# - 加载系统提示词

agent = HelloClawAgent()

print(f"智能体 '{agent.name}' 创建成功!")
print(f"工作空间: {agent.workspace_path}")
print(f"可用工具: {list(agent.tool_registry._tools.keys())[:10]}...")  # 只显示前10个

第5部分:功能演示

展示 HelloClaw 的核心功能。

python
# 示例1:身份引导
# HelloClawAgent 支持通过对话来设置身份信息,会自动保存到工作空间
print("="*50)
print("示例1:身份引导 - 设置 Agent 身份")
print("="*50)

# 第一步:问 AI 是谁
print("【用户】: 你是谁?")
response = agent.chat("你是谁?")
print(f"【Teddy】: {response}")

print("\n" + "-"*50 + "\n")

# 第二步:告诉 AI 它的身份
print("【用户】: 你的名字叫 Teddy,你是一个超级智能助理,你友好、专业、乐于助人。")
response = agent.chat("你的名字叫 Teddy,你是一个超级智能助理,你友好、专业、乐于助人。请记住这个身份。")
print(f"【Teddy】: {response}")
python
# 示例2:工具调用 - 计算器
print("="*50)
print("示例2:工具调用 - 计算器")
print("="*50)

response = agent.chat("请帮我计算 (123 + 456) * 2 等于多少")
print(f"\n回复: {response}")
python
# 示例3:记忆管理
print("="*50)
print("示例3:记忆管理")
print("="*50)

# HelloClawAgent 有完整的记忆管理系统:
# - memory_add: 添加每日记忆
# - memory_search: 搜索记忆
# - memory_list: 列出所有记忆文件
# - Read/Write 工具: 操作长期记忆 MEMORY.md

# 添加每日记忆
print("【添加每日记忆】使用 memory_add 工具:")
print("-" * 40)
response = agent.chat("请使用 memory_add 工具,添加一条记忆:今天用户说他有一只猫叫花花")
print(f"结果: {response[:300]}..." if len(response) > 300 else f"结果: {response}")

print("\n" + "="*50)

# 列出记忆文件
print("【列出记忆文件】使用 memory_list 工具:")
print("-" * 40)
response = agent.chat("请使用 memory_list 工具列出所有记忆文件")
print(f"结果: {response[:400]}..." if len(response) > 400 else f"结果: {response}")

第6部分:流式输出演示

展示 HelloClaw 的流式工具调用能力。

python
import asyncio
from hello_agents.core.streaming import StreamEventType

async def demo_streaming():
    """演示流式输出 - 使用 HelloClawAgent 的 achat 方法"""
    print("="*50)
    print("流式输出演示")
    print("="*50)
    
    # 使用 HelloClawAgent 的 achat 方法进行流式对话
    async for event in agent.achat("计算 100 / 4 + 25 的结果"):
        if event.type == StreamEventType.LLM_CHUNK:
            chunk = event.data.get("chunk", "")
            print(chunk, end="", flush=True)
        
        elif event.type == StreamEventType.TOOL_CALL_START:
            tool_name = event.data.get("tool_name")
            print(f"\n[调用工具: {tool_name}]", flush=True)
        
        elif event.type == StreamEventType.TOOL_CALL_FINISH:
            result = event.data.get("result", "")
            preview = result[:100] + "..." if len(result) > 100 else result
            print(f"[工具结果: {preview}]", flush=True)
    
    print("\n" + "="*50)

# 运行流式演示
await demo_streaming()

第7部分:总结与展望

项目总结

实现的功能:

  • 基于 HelloAgents 框架的智能对话
  • 自定义工具系统(命令执行、记忆管理等)
  • 流式工具调用和输出
  • 会话管理和历史持久化

遇到的挑战及解决方案:

  1. 流式工具调用 - 通过扩展 HelloAgentsLLM 实现真正的流式工具调用
  2. 记忆管理 - 设计了分层记忆系统(长期记忆 + 每日记忆)
  3. 身份定制 - 使用 Markdown 配置文件实现灵活的身份定制

未来改进方向

  • 支持多模态输入(图片、文件)
  • 添加更多内置工具
  • 支持 Agent 间协作
  • 添加语音交互能力

感谢 Datawhale 社区和 Hello-Agents 项目!