跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

This page mirrors the English Agents page. Technical identifiers stay in English so examples can be copied directly.

​
1. Agent stack

A HeavenBase-backed agent usually has four parts:
  • hb.LLM for model preset, provider, gateway, and cache policy
  • LLMSession from heavenbase.utils for multi-turn history and automatic tool loops
  • hb.Prompt and hb.fast_prompt_section for persisted instructions
  • hb.HeavenBase(...).to_mcp(profile="agent") for workspace tools

​
2. Workspace memory

Use a workspace preset for first-run agents: 
import heavenbase as hb

ws = hb.HeavenBase("agent-memory", preset="debug")
workspace_mcp = ws.to_mcp(name="agent-memory-mcp", profile="agent").to_fastmcp()
The agent MCP profile is smaller than the full workspace toolkit. Use it first, then pass tools=[...] when an agent needs a narrower allowlist. If the agent only needs persistent notes, start even smaller with the memory profile: 
memory_mcp = ws.to_mcp(name="agent-memory-notes", profile="memory").to_fastmcp()
The memory profile exposes remember, recall, search_memory, list_memory, and set_memory. It is useful for Memstate-style note storage while still keeping the data inside the same HeavenBase workspace. Use remember for summaries or decisions, recall/list_memory for exact retrieval and browsing, search_memory for fuzzy lookup, and set_memory for exact-key correction. History and delete stay out of this first-run profile until the application has a retention policy.

​
3. Prompt instructions

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 names, versions, translations, and deletes are scoped to the workspace passed with ws=....

​
4. LLM session with tools

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,
)
Tool-name collisions fail early.

​
5. Agent smoke path

For a compact agent smoke test:
  1. Use hb.HeavenBase("task", preset="debug").
  2. Use ws.to_mcp(profile="agent").
  3. Use ws.to_mcp(profile="memory") when the task only needs note memory.
  4. Use hb.LLM(preset="chat", gateway="portkey", cache=False).
  5. Keep GLM tool calls on native OpenAI JSON tools unless a provider-specific failure proves otherwise.
  6. Use hb.LLM(...).spec.materialize() for route inspection before live calls.

​
Further Exploration

Related resources: