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

# Agents

> Build agents on HeavenBase with LLM sessions, prompts, workspace memory, and MCP tools.

<Note>
  HeavenBase treats agent memory as a workspace, agent actions as MCP tools, and agent instructions as prompt rows.
</Note>

<br />

## 1. Agent stack

A HeavenBase-backed agent usually has four parts:

* `hb.LLM` for the model route, 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, translated instructions
* `hb.HeavenBase(...).to_mcp(profile="agent")` for workspace tools the model can inspect and mutate

This keeps the user interface small: the agent receives one prompt, one workspace MCP, and optional task-specific tools.

<Tip>
  To persist agent history and recipes as workspace rows, enable the optional
  [agent extension](/features/agent-extension) with `ws.enable_extension("agent")`.
</Tip>

<br />

## 2. Workspace memory

Use a workspace preset instead of hand-writing backend config for first-run agents:

```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()
```

The `agent` MCP profile intentionally exposes fewer tools than the full workspace toolkit. Start with it, then pass `tools=[...]` only when a specific agent needs a narrower allowlist.

If the agent only needs persistent notes, start even smaller with the memory profile:

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

If the agent needs versioned project memory, use the memstate profile:

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

The `memstate` profile exposes `memstate_remember`, `memstate_set`, `memstate_get`, `memstate_search`, `memstate_history`, and `memstate_delete`. It uses `project.<project_id>.<keypath>` rows and preserves history inside the HeavenBase workspace.

<br />

## 3. Prompt instructions

Register prompts in the same workspace so agent instructions travel with the task state:

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

<br />

## 4. LLM session with tools

Attach workspace MCP and external MCP servers to one 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,
)
```

Tool-name collisions fail early so the model never sees ambiguous function names.

<br />

## 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, or `profile="memstate"` when it needs versioned project keypaths.
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.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [First LLM](/quickstart/first-llm) - Presets, providers, gateways, and sessions
  * [HeavenBase MCP](/quickstart/heavenbase-mcp) - Workspace MCP serving
  * [Prompt](/features/utilities/prompt) - Prompt rows, translations, and CLI
</Tip>

<br />