Skip to content

README.md

Latest commit

 

History

History
128 lines (92 loc) · 4.82 KB

README.md

File metadata and controls

128 lines (92 loc) · 4.82 KB

Claude Agent 示例

用 Python 从零构建 AI Agent。包含两部分：

  1. agent/ — 一个完整可用的多轮对话 Agent，带三层记忆系统、自动压缩、可插拔技能。
  2. build-agent-example/ — 6 个渐进式教学示例（agent1 → agent6），从单次对话到 Tool Use + Skills。

配套讲解 PPT 见 ppt/。

快速开始

python -m venv .venv
source .venv/bin/activate                 # Windows: .venv\Scripts\activate
pip install anthropic python-dotenv pyyaml jinja2

cp .env.example .env                      # 填入 ANTHROPIC_API_KEY

python agent.py                           # 启动主 Agent
# —— 或 ——
python build-agent-example/agent1.py      # 从最简单的教学示例开始

主 Agent（agent.py + agent/ 包）

启动后是一个"大内总管 / 皇上"角色的命令行对话循环。

目录结构

agent.py                    入口（4 行）
agent/
├── loop.py                 主循环
├── runner.py               单轮 messages.create + tool_use 循环
├── memory.py               三层记忆存储
├── compactor.py            历史压缩 → 情景记忆 + MEMORY.md
├── context.py              system prompt 组装（Jinja2）
├── skills.py               技能加载器
├── telemetry.py            token 用量记录与压缩触发判断
└── tools/                  内置工具（shell / web / 文件 / glob / grep / load_skill）

templates/
├── SOUL.md                 Agent 灵魂档案（人格 / 使命 / 边界，只读）
├── USER.md                 用户偏好档案（压缩时按信号更新）
└── agent/
    ├── identity.md         工作区路径声明（Jinja2 模板）
    ├── skills_section.md   技能清单注入
    └── compact_prompt.md   压缩 LLM 的提示词

memory/                     运行期产物（已 gitignore）
├── MEMORY.md               长期记忆，每轮注入 system prompt
├── history.jsonl           原始对话日志
├── tokens.jsonl            按调用记录 token 用量
└── YYYY-MM-DD.md           每日情景记忆，压缩时生成

skills/                     可插拔技能包
└── {name}/SKILL.md         技能描述（YAML frontmatter + Markdown）

三层记忆系统

层 载体 何时写 何时读
工作记忆 history 列表（内存） 每轮追加 全量传给 LLM
情景记忆 memory/YYYY-MM-DD.md 压缩触发时 按需 grep
长期记忆 memory/MEMORY.md 压缩 / 启动归档时 每轮注入 system prompt

自动压缩：上一次调用的 input_tokens 超过 200_000 × 0.7 = 140K 时，把 history[:-10] 喂给 LLM 提炼成情景段落 + 更新 MEMORY.md，只保留最近 10 轮。

启动归档：上次会话未达压缩阈值就退出 → 通过 history.jsonl 中的 compact_event 标记，启动时把未归档对话补归档，跨会话不丢上下文。

内置工具

工具 说明
run_command 执行 shell 命令
web_fetch 抓取 URL
read_file / write_file / edit_file 工作区文件读写
glob / grep 工作区搜索
load_skill 按需加载 skills/{name}/SKILL.md 进上下文

教学示例 build-agent-example/

文件 能力 新增概念
agent1.py 单次对话 API 调用基础
agent2.py 连续对话 循环交互
agent3.py 多轮记忆 messages[] 历史
agent4.py 角色设定 system prompt
agent5.py Tool Use 工具调用循环
agent6.py 多工具 + Skills 动态加载技能包

Skills 系统

skills/{name}/SKILL.md 用 YAML frontmatter 描述触发条件，Markdown 写知识内容。Agent 在需要时通过 load_skill 工具按需加载，避免占用上下文窗口。

当前内置技能：

  • clawhub — 技能库搜寻与安装
  • ddg-web-search — DuckDuckGo 搜索
  • github — GitHub CLI 交互
  • skill-creator — 创建 / 更新技能
  • summarize — URL / 播客 / 文件总结
  • weather — 天气查询
  • web-ppt — 生成网页式技术演讲稿

环境变量

变量 说明
ANTHROPIC_API_KEY Anthropic API Key
ANTHROPIC_BASE_URL API 代理地址（可选）

配套 PPT

ppt/第一期:什么是agent.html · ppt/第二期:手搓agent.html · ppt/第三期:记忆系统.html