> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体扩展 (Agent Extension)

> 可选的智能体 (Agent) 扩展，将消息、会话 (Session)、Skill 与智能体配方持久化为工作区实体。

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

<br />

## 1. 启用扩展

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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")`。

<br />

## 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) 发现，而非第二真相来源。

<br />

## 3. 记录的 CLI 运行

`hb llm chat` 在响应完成后写入一行 `agent-session` 与有序的 `agent-message` 行。`hb llm session` 在交互式会话 (Session) 启动时创建一个持久会话，随后追加每次完成的 user/assistant/tool 迭代。CLI 输出形态不变。

通过活跃工作区检查已记录的历史：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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，可直接喂回执行会话。

<br />

## 4. Skill

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
skill = hb.Skill.from_path("skills/sql-analyst")
skill.save(ws=ws)
```

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

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
---
name: sql-analyst
description: Analyze SQL-backed product data.
toolkit:
  - analytics/sql-tools:1
---
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
toolkit = hb.Skill.toolkit([skill], ws=ws)
text = toolkit.run("read_skill", skill_name=skill.name, path="SKILL.md")
```

<br />

## 5. 智能体 (Agent) 配方

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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()`。

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

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [智能体 (Agents)](/features/agents) - LLM 会话 (Session)、提示 (Prompt)、工作区记忆与 MCP 工具
  * [扩展 (Extensions)](/features/extensions) - 实体扩展如何注册与启用
  * [会话 (Sessions)](/features/llm/sessions) - 配方构建所用的 `LLMSession`
  * [工具集 (Toolkits)](/features/toolkits) - 配方附着的已注册 Toolkit 引用
</Tip>

<br />