智能体扩展 (Agent Extension)

智能体历史与配方只是行。agent 扩展存储你的执行流程已产出的内容。

1. 启用扩展

可选的内置 agent 扩展将智能体执行历史与配方持久化为普通工作区实体。它不会取代 hb.LLM、LLMSession、提示 (Prompt)、工具集 (Toolkit) 或 MCP——它存储这些系统已在使用的组件。

import heavenbase as hb

ws = hb.HeavenBase("agent-memory", preset="debug")
ws.enable_extension("agent")

规则：类（hb.Agent、hb.Session、hb.Message、hb.Skill）可在任意处导入，但工作区行需要启用扩展。类的 save/load helper 会自动在目标工作区上启用扩展，因此只有当你想先自行查询这些行时，才需要显式调用 enable_extension("agent")。

2. 持久化实体

该扩展注册四个实体：

实体 id	Class	存储内容
`agent-message`	`hb.Message`	一个 OpenAI 格式的 `payload`，以及 `role`、`content_text` 与 `tool_call_count` 查询投影
`agent-session`	`hb.Session`	有序的 `message_ids`、`turn_count`、`tool_call_count`、执行 `state` 与聚合的 `usage`
`agent-skill`	`hb.Skill`	解析后的 `SKILL.md` `frontmatter`、`skill_body`、`toolkit_refs` 与确定性 zip `archive`
`agent-agent`	`hb.Agent`	配方：`llm_preset`、`prompt_ref`、`skill_refs`、`toolkit_refs` 与执行 `args`

存储的 Message.payload 是规范的 OpenAI 格式字典。投影用于查询与目录 (Catalog) 发现，而非第二真相来源。

3. 记录的 CLI 运行

hb llm chat 在响应完成后写入一行 agent-session 与有序的 agent-message 行。hb llm session 在交互式会话 (Session) 启动时创建一个持久会话，随后追加每次完成的 user/assistant/tool 迭代。CLI 输出形态不变。通过活跃工作区检查已记录的历史：

sessions = ws.rows(hb.Session)
messages = ws.rows(hb.Message)
payloads = hb.Session.load(sessions[0]["object_id"], ws=ws).messages()

Session.messages() 按会话顺序返回 OpenAI 格式 payload，可直接喂回执行会话。

4. Skill

从包含 SKILL.md 的文件夹创建 Skill：

skill = hb.Skill.from_path("skills/sql-analyst")
skill.save(ws=ws)

SKILL.md frontmatter 可用 toolkit: 声明工具集 (Toolkit) 引用：

---
name: sql-analyst
description: Analyze SQL-backed product data.
toolkit:
  - analytics/sql-tools:1
---

Skill 文件夹以确定性 zip 字节存储在 archive 下。当智能体需要文件内容时，使用执行工具 read_skill：

toolkit = hb.Skill.toolkit([skill], ws=ws)
text = toolkit.run("read_skill", skill_name=skill.name, path="SKILL.md")

5. 智能体 (Agent) 配方

hb.Agent 行是配方，而非第二套执行栈：

agent = hb.Agent(
    name="demo-agent",
    llm_preset="chat",
    prompt_ref="demo.agent.system",
    skill_refs=["sql-analyst"],
    toolkit_refs=["analytics/sql-tools:-1"],
    args={"max_steps": 8},
    ws=ws,
)
agent.save()

runtime = hb.Agent.load("demo-agent", ws=ws).build()
runtime.session.send("Use the available skills.", max_tool_turns=8)

build() 解析 hb.LLM、hb.Prompt、hb.Skill 与已注册的 hb.Toolkit 引用，然后返回 AgentRuntime，其 session 是附带工具的普通 LLMSession。若希望为后续运行保留持久的 hb.Session 行，请使用 agent.new_session()。

该扩展目前覆盖单智能体配方。多智能体编排是未来工作。

进一步探索

相关资源：

智能体 (Agents) - LLM 会话 (Session)、提示 (Prompt)、工作区记忆与 MCP 工具
扩展 (Extensions) - 实体扩展如何注册与启用
会话 (Sessions) - 配方构建所用的 LLMSession
工具集 (Toolkits) - 配方附着的已注册 Toolkit 引用

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

智能体扩展 (Agent Extension)

1. 启用扩展

2. 持久化实体

3. 记录的 CLI 运行

4. Skill

5. 智能体 (Agent) 配方

进一步探索

​1. 启用扩展

​2. 持久化实体

​3. 记录的 CLI 运行

​4. Skill

​5. 智能体 (Agent) 配方

​进一步探索

1. 启用扩展

2. 持久化实体

3. 记录的 CLI 运行

4. Skill

5. 智能体 (Agent) 配方

进一步探索