智能体 (Agent) - HeavenBase

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

1. 智能体技术栈

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

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

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

要将智能体历史与 recipe 持久化为工作区行，请启用可选的 agent 扩展，并使用 ws.enable_extension("agent")。

2. 工作区记忆

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

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：

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：

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 工作区内保留历史。

3. 提示 (Prompt) 指令

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

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=... 的工作区。

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

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

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

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

5. 智能体冒烟路径

紧凑的智能体冒烟测试：

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

进一步探索

相关资源：

首个 LLM - 预设 (Preset)、提供商 (Provider)、入口 (Gateway) 与会话 (Session)
HeavenBase MCP - 工作区 MCP 提供
提示 (Prompt) - 提示行、翻译与 CLI

​1. 智能体技术栈

​2. 工作区记忆

​3. 提示 (Prompt) 指令

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

​5. 智能体冒烟路径

​进一步探索

1. 智能体技术栈

2. 工作区记忆

3. 提示 (Prompt) 指令

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

5. 智能体冒烟路径

进一步探索