> ## 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)

> 在 HeavenBase 上构建智能体：LLM 会话、提示 (Prompt)、工作区记忆与 MCP 工具。

<Note>
  HeavenBase 将智能体记忆视为工作区，将智能体动作视为 MCP 工具，将智能体指令视为提示 (Prompt) 行。
</Note>

<br />

## 1. 智能体技术栈

基于 HeavenBase 的智能体通常包含四部分：

* `hb.LLM` 负责模型路由、预设 (Preset)、提供商 (Provider)、入口 (Gateway) 与缓存策略
* `heavenbase.utils` 中的 `LLMSession` 负责多轮历史与自动工具循环
* `hb.Prompt` 与 `hb.fast_prompt_section` 负责持久化、可翻译的指令
* `hb.HeavenBase(...).to_mcp(profile="agent")` 提供模型可检查与变更的工作区工具

这使面向用户的接口保持精简：智能体接收一个提示 (Prompt)、一个工作区 MCP，以及可选的任务专用工具。

<Tip>
  要将智能体历史与 recipe 持久化为工作区行，请启用可选的
  [agent 扩展](/features/agent-extension)，并使用 `ws.enable_extension("agent")`。
</Tip>

<br />

## 2. 工作区记忆

首次运行的智能体请使用工作区预设 (Preset)，而非手写后端 (Backend) 配置：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

ws = hb.HeavenBase("agent-memory", preset="debug")
workspace_mcp = ws.to_mcp(name="agent-memory-mcp", profile="agent").to_fastmcp()
```

`agent` MCP profile 有意比完整工作区工具集 (Toolkit) 暴露更少工具。从它开始，仅当特定智能体需要更窄的 allowlist 时再传入 `tools=[...]`。

若智能体只需持久笔记，可用更小的 memory profile：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
memory_mcp = ws.to_mcp(name="agent-memory-notes", profile="memory").to_fastmcp()
```

`memory` profile 暴露 `remember`、`recall`、`search_memory`、`list_memory` 与 `set_memory`。它适用于 Memstate 风格笔记存储，同时仍将数据保留在同一 HeavenBase 工作区内。用 `remember` 记录摘要或决策，用 `recall`/`list_memory` 做精确检索与浏览，用 `search_memory` 做模糊查找，用 `set_memory` 做精确键修正。在应用具备保留策略之前，history 与 delete 不在此首次运行 profile 中。

若智能体需要版本化项目记忆，使用 memstate profile：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
memstate_mcp = ws.to_mcp(name="agent-versioned-memory", profile="memstate").to_fastmcp()
```

`memstate` profile 暴露 `memstate_remember`、`memstate_set`、`memstate_get`、`memstate_search`、`memstate_history` 与 `memstate_delete`。它使用 `project.<project_id>.<keypath>` 行，并在 HeavenBase 工作区内保留历史。

<br />

## 3. 提示 (Prompt) 指令

在同一工作区注册提示 (Prompt)，使智能体指令与任务状态一起迁移：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def system_prompt(task: str, *, tr=str) -> str:
    messages = hb.fast_prompt_section(
        system=tr("You are a task agent using HeavenBase as memory."),
        descriptions={"Task": task},
        instructions=["Inspect before mutating.", "Write structured results to the workspace."],
        tr=tr,
    )
    return messages[-1]["content"]


hb.Prompt(system_prompt, name="agent.system", ws=ws).register(ws=ws)
system = hb.Prompt.load("agent.system", ws=ws)(task="Summarize README.md")
```

提示 (Prompt) 名称、版本、翻译与删除均作用于传入 `ws=...` 的工作区。

<br />

## 4. 带工具的 LLM 会话 (Session)

将工作区 MCP 与外部 MCP 服务器挂到同一会话 (Session)：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils import LLMSession

llm = hb.LLM(preset="chat", gateway="portkey", cache=False, temperature=0)
session = LLMSession(llm)
session.add_mcp(workspace_mcp, name="agent-memory-client")
session.add_mcp("http://127.0.0.1:7001/mcp", name="task-tools")

answer = session.send(
    "Inspect the task, write the result to HeavenBase, then answer.",
    system=system,
    max_tool_turns=10,
)
```

工具名冲突会尽早失败，避免模型看到模糊的函数名。

<br />

## 5. 智能体冒烟路径

紧凑的智能体冒烟测试：

1. 使用 `hb.HeavenBase("task", preset="debug")`。
2. 使用 `ws.to_mcp(profile="agent")`。
3. 任务只需笔记记忆时用 `ws.to_mcp(profile="memory")`；需要版本化项目 keypath 时用 `profile="memstate"`。
4. 使用 `hb.LLM(preset="chat", gateway="portkey", cache=False)`。
5. 除非 provider 特定失败证明否则，GLM 工具调用保持原生 OpenAI JSON tools。
6. 在 live 调用前用 `hb.LLM(...).spec.materialize()` 检查路由。

<br />

## 进一步探索

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

  * [首个 LLM](/quickstart/first-llm) - 预设 (Preset)、提供商 (Provider)、入口 (Gateway) 与会话 (Session)
  * [HeavenBase MCP](/quickstart/heavenbase-mcp) - 工作区 MCP 提供
  * [提示 (Prompt)](/features/utilities/prompt) - 提示行、翻译与 CLI
</Tip>

<br />