SDK for Cradle agentsSDK 2.0.0

A Cradle agent is a FastAPI backend that builds a BaseAgent itself, keeps its own users and chat history, and talks to HippoDb through the manager with an API key. This page covers the SDK features such an agent needs, in the order you meet them. It leaves out what the Cradle starter does not use: the Agent Creator, the agent network (the starter is networked: false), and the terminal runner (AgentRunner).

How to read it: section 1 is a map. Sections 2 to 7 are the wiring you do once. Sections 8 to 12 are what happens on every chat request. Sections 13 to 16 are configuration, diagnosis and upgrade notes.

1. At a glance#

2. Install and versions#

• Pin the SDK exactly in backend/pyproject.toml, as the Cradle rules require (make install or make install-sdk installs it, whichever your project uses), and let uv update the lock:

cd backend && uv add hippodb-agent-sdk==2.0.0

• Python 3.12 or newer. LiteLLM comes with the SDK (it needs litellm>=1.104.2); do not pin it yourself. The newest Claude models fail with older LiteLLM versions.
• Check what is installed: backend/.venv/bin/python -c "import hippodb_agent; print(hippodb_agent.__version__)".
• The documentation ships inside the package. python -m hippodb_agent docs prints its folder, and python -m hippodb_agent docs --open opens the release notes in a browser.
• The SDK no longer ships a defaults.env. Settings come from your own Settings class: BaseAgent, ToolDiscovery and the LLM client never read .env. If a comment in your .env.example says the SDK's defaults.env is the lowest precedence, that comment is out of date.

3. Connect to HippoDb#

HippoClient is the only thing that talks to HippoDb. Build every one through a single helper, so the API key cannot be forgotten at a new call site (for example a make_hippo_client(settings, fabric) function in agent/fabric.py, used by the chat handler, account deletion, anchoring and the seed script):

from hippodb_agent.memory.client import HippoClient

def make_hippo_client(settings, fabric: str) -> HippoClient:
    return HippoClient(base_url=settings.hippodb_url, fabric=fabric,
                       api_key=settings.hippodb_api_key or None)

The API key#

• Point HIPPODB_URL at the manager, not at an engine pod. Every request to it carries Authorization: Bearer hdb_live_....
• Pass the key in code. Pydantic reads .env into your Settings object, not into os.environ, so the SDK's fallback to the HIPPODB_API_KEY environment variable does not see a key that only lives in .env.
• No key, or a bad, expired or revoked one, is a 401. The body's error says which (missing_credential, invalid_credential). A key without the scope it needs is a 403.
• The key needs the scopes fabric:read, fabric:write and fabric:delete, and a fabric cap (max_fabrics, 25 by default) that fits your users: a per-user agent creates one fabric per user.
• Only /admin/manager/health is open. /health, /fabrics and every other route answer 401 without a key, so a liveness or readiness probe needs the key or that path.
• A fabric call that fails because of the key is an httpx.HTTPStatusError with status 401 or 403, and the SDK logs a WARNING with the manager's reason (memory.client).

Fabrics#

hippo = make_hippo_client(settings, fabric_name)
await hippo.create_fabric()          # idempotent: 201 whether the fabric is new or not
await hippo.delete_fabric(name)      # permanent, no undo (account deletion)
fabrics = await hippo.list_fabrics() # always a list of dicts: [{"name": ...}, ...]

• create_fabric() cannot tell a new fabric from an existing one. Only a failure is worth reporting.
• delete_fabric() removes the database, the search index and the data files. There is no way to delete a single concept.
• Fabric names come from your own rules (APP_ENV, FABRIC_NAME, the user id). The SDK does not build them.

A lost fabric#

If a user's fabric is deleted while the process runs, the next call raises FabricNotFoundError. It comes out of agent.chat(), discovery.discover() and index_tools() and from the tools' own HippoDb calls. The SDK recognises it from the 404 body, and only when the 404 names your fabric; a missing concept is not mistaken for it.

from hippodb_agent import FabricNotFoundError

try:
    reply = await agent.chat(text)
except FabricNotFoundError:
    await seed_load.run(settings)     # create the fabric again and reseed it
    reply = await agent.chat(text)    # retry the turn once

Data in a deleted fabric is gone. Re-seeding only makes the agent work again.

Timeouts and retries#

HippoClient defaults to a 60 second request timeout and a 10 second connect timeout. A request whose connection cannot be opened is retried twice with a short backoff; nothing else is retried, so a write is never sent twice. Both are arguments (timeout=, connect_retries=).

4. Build the agent#

Build the parts in this order. The full, tested example is in Building an Agent Without AgentRunner; this is the shape.

registry = ToolRegistry()
registry.register_many(get_builtin_tools(include_discover_more=True))   # memory tools + discover_more_tools
registry.register_many(get_manage_task_tools(settings, user_id))        # your business tools
registry.bind_all(hippo=hippo)
registry.bind_hippo(hippo)
await registry.warmup()                                                  # new in 2.0.0

discovery = ToolDiscovery(hippo, registry, extra_always_on=["manage_task"])
await discovery.index_tools()

role = RoleConfig(name=..., display_name=..., tool_scopes=["manage_"],
                  fabric=fabric_name, system_prompt=system_prompt())

agent = BaseAgent(role=role, registry=registry, discovery=discovery,
                  model=settings.model, api_key=llm_key,
                  manifest_fn=hippo.manifest, timeout=45,
                  enable_streaming=settings.enable_streaming)

Things that catch people out:

• tool_scopes is a prefix list. It limits business tools to names starting with those prefixes. The SDK's own memory_, os_, calc_ and network_ tools and discover_more_tools are always in scope. An empty list hides every business tool; it does not mean "no restriction".
• A tool the agent must always have goes in extra_always_on (or RoleConfig.always_on_tools). Always-on tools are sent every turn and are never dropped by the tool limits. Anything else is chosen by discovery for each message.
• await discovery.index_tools() stores your tools in the fabric as TOOL concepts. In 2.0.0 discover() calls it for you, so a per-turn call in the chat handler is no longer needed. It stays harmless: after the first call per fabric it costs nothing.
• {manifest} is empty unless you fill it. If the system prompt has a {manifest} placeholder, pass manifest_fn=hippo.manifest and await agent.refresh_manifest() after building the agent. In 2.0.0 the manifest is one line of fabric statistics (Fabric: x | Concepts: n | Edges: m), so many projects simply leave the placeholder out.
• One turn at a time per agent. An agent keeps state for the turn in progress (which tools it offered and used, last_turn, the event queue). Two turns on the same BaseAgent at the same moment overwrite each other's state. Keep a lock around chat() (an asyncio.Lock), or build one agent per user. A per-user fabric layout suits one agent per user.
• Model routing needs the router object. BaseAgent(model=...) on its own ignores LLM_ROUTING_MODELS. When routing is configured, pass llm=ModelRouter(routing_models=..., router_model=...) instead of model=, in an if/else that covers both cases.

5. Tools#

Your business tools#

A tool is a class with a name, a description for the model, a JSON schema for its input, and an async execute:

from hippodb_agent import BaseTool

class ManageTask(BaseTool):
    name = "manage_task"
    description = "Create, update or close a task for the user"
    input_schema = {"type": "object", "properties": {"action": {"type": "string"}}, "required": ["action"]}
    atomic = True                      # finish even if the turn is cancelled

    async def execute(self, inp: dict) -> dict:
        ...
        return {"task_id": task.id}

• Return a dict. An exception becomes {"error": "..."} for the model, with the exception type when it has no message, so the model can recover. A FabricNotFoundError is the exception to that rule: it propagates to your handler.
• Set atomic = True on a tool that writes to your database: if the client disconnects, the tool still finishes and its result is recorded.
• Optional hints for discovery (never sent to the model): domain (tools of one domain are linked together), related (tools often used together), keywords (synonyms the name and description lack) and examples (phrases a user might say). Changing them reaches fabrics that were indexed earlier.
• A tool added in a later release is found in existing fabrics. A tool whose name sits inside another concept's label (order_list and recurring_order_list) is reported in the log and in discovery.last_index_report instead of being merged.

The SDK's memory tools#

get_builtin_tools(include_discover_more=True) registers these for the model:

In a Cradle project the always-on set is these memory tools (except promote and approve) plus discover_more_tools and your own extra_always_on names.

How many tools one call carries#

Each tool definition costs about 1.2k tokens and is sent again on every LLM round, so the list is bounded:

Always-on tools and the tools discovered for the current message are never dropped, so a call can pass max_total_tools when those alone are over it (the SDK logs one warning). Pass None to remove a limit. The limits apply only when discovery is on.

6. Memory: what the agent reads and writes#

Each fabric is a graph of concepts with facts (attribute and value; a new value supersedes the old one), timeline events and weighted, typed edges.

• Write with ingest() (concepts with nested facts and timeline) or learn() (one concept). Both return what the engine did: the label as the engine resolved it, the identity status, the facts set and superseded. An identity merge can land a write on a different existing label, so use the returned label.
• Recall with think(): spreading activation from a concept or keywords. Also query() (semantic search, facts and timeline), facts(), timeline() and list_concepts().
• Typed edges. link(a, b, edge_type="IS_A") asserts a relation (anchors, seed bridges). delete_edge() is a soft delete: the edge leaves graph() but think(as_of=...) can still reconstruct it.
• Identity. The engine merges duplicate concepts, or files a conflict when it cannot decide (only when it has an LLM configured). The SDK surfaces it: recent_similar hints on writes, and the conflict tools above.
• Point in time. think(as_of="2026-09-15") rebuilds memory as it stood then. as_of is the moment a memory was stored, not a date inside what it says. If a meeting from March was entered in May, asking as_of a March date returns nothing, because nothing existed yet. memory_think tells the model this.
• Retrieval plans. think(plan="exact > spread(2) > reserve(0.4)") picks the strategy; ThinkResult.plan reports what ran. The memory_think tool does not expose plan.

Limits to design around: facts() returns the current value and one previous value, not the full history of an attribute; there is no route to delete a single concept; the engine's identity log lives in its memory and is lost on restart; every fabric stays loaded in the engine, so memory grows with the number of fabrics.

7. Seeding#

A seed gives a new fabric its first knowledge so the agent does not start with an empty graph. A Cradle project writes it as Python modules (agent/seed/concepts.py, intents.py, bridges.py, workflows.py, rules.py, anchors.py) and loads it with scripts/seed_load.py, at registration and again at login (which also recreates a deleted fabric). The parts:

• Concepts: the domain vocabulary (DOMAIN type by default), with facts, aliases and tags.
• Intents: phrases users say, linked to the tools that serve them.
• Bridges: concept to tool links, so a question about a topic finds the right tool.
• Workflows: chains of tools that go together (PRECEDES edges).
• Rules: starter behavioural guidance with when and then.

Rules to follow:

• Index the tools first. A link to a tool name that does not exist yet makes the engine create a plain concept with no type, and discovery only finds TOOL concepts. Run await discovery.index_tools() before loading a seed that names tools. (load_seed(hippo, "seed.yaml") also creates the TOOL concepts it needs, but a hand-written seed script does not.)
• Names must match exactly. A misspelled tool name does not raise an error; the edge points at a tool that is not registered.
• A concept label that contains a tool name (a concept called manage_task notes) captures the links meant for the tool. Keep tool names unique inside labels.
• Seed once. should_seed(hippo) judges from the fabric statistics whether it looks unseeded; the loader is meant for a fresh fabric.

The YAML seed format and design guidance are in Pre-Education.

8. A chat turn#

reply = await agent.chat(text, conversation_id=thread_id, reasoning_effort=effort)

• History. The agent keeps one history per conversation_id, each turn with its full tool trace, up to history_window turns (default 5). Always pass your own conversation or user id: without one, every caller shares one history. Some projects control history themselves instead: they set agent.history = list(prior) before each turn, with the last few exchanges of the current conversation, and keep their own setting for how many exchanges to include. That still works in 2.0.0: the list is stored as one turn in the default conversation, replacing what was there, so history_window hardly matters in that mode.
• Why full traces matter. A history that shows only the final prose teaches the model to imitate prose and stop calling tools. Keep the trace, and keep the window small.
• Rounds. One turn runs up to max_rounds (20) LLM rounds. At the limit chat() returns a fixed "max tool rounds exceeded" message and last_turn.status is max_rounds.
• Images. chat_with_image(image_b64, media_type, text="", conversation_id=...) sends an image through the same loop; the image is replaced by a short note in history afterwards.
• How it ended. agent.last_turn has status (completed, stopped, max_rounds, cancelled, failed), rounds, tools_used, duration_ms, error and reasoning_effort.
• Timeouts. Two levels, and both are worth setting. BaseAgent(timeout=45) bounds one LLM call (with ModelRouter(..., timeout=45) when routing), so a stalled round fails in 45 seconds instead of LiteLLM's 600. Wrapping the whole chat() in asyncio.wait_for(..., timeout=...) bounds all rounds and the tool time between them. This replaces the older litellm.request_timeout global.

9. Streaming to the chat UI#

Turn streaming on in the agent, attach a queue, and drain it while chat() runs:

agent = BaseAgent(..., enable_streaming=True)
queue = asyncio.Queue()
agent.event_queue = queue
task = asyncio.create_task(agent.chat(text, conversation_id=thread_id))
while True:
    getter = asyncio.ensure_future(queue.get())
    done, _ = await asyncio.wait({getter, task}, return_when=asyncio.FIRST_COMPLETED)
    if getter not in done:               # the turn ended without another event
        getter.cancel()
        break
    event = getter.result()
    ...                                  # forward to the browser as an SSE item
    if event["type"] == "turn_end":
        break
reply = await task                       # also raises anything the turn raised

Streaming needs both the flag and a queue; without either the agent uses the plain call. Events carry no conversation id, so run one turn at a time per agent. Detach the queue (agent.event_queue = None) when you stop reading. There is no error event: errors come out of chat().

Stop and disconnect#

• Stop button: agent.stop(conversation_id) ends the running turn gracefully. It aborts the in-flight LLM call, lets a running tool finish, skips the rest, saves the turn so far with a note for each tool call that did not run, and makes chat() return the text produced so far (last_turn.status == "stopped").
• Client disconnects: cancelling the task that runs chat() now cancels the LLM call too, for every provider. The turn ends with status cancelled, and a turn that had already run tools stays in history so the next turn does not repeat the writes. Tools marked atomic = True finish first.
• Before the next turn, wait for the previous task to finish, or your lock will let two turns overlap.

Details: Events and Streaming.

10. Reasoning effort in the UI#

A reasoning model can think before it answers: slower and more expensive, better on hard questions. To offer it in the chat UI:

1. Ask once whether to show the control: agent.supports_reasoning_effort() (or hippodb_agent.core.llm.supports_reasoning_effort(model) before an agent exists). It follows LiteLLM's model table, so a brand-new model may report false until LiteLLM is upgraded.
2. Let the user pick Low, Medium, High or Off, and send it with the message. The chat request model (ChatStreamRequest in agent/routes/chat_routes.py) gets reasoning_effort: Literal["low", "medium", "high", "off"] | None = None, and your handler carries it to the agent (an extra parameter on respond(), or a field on the per-turn context object if your project has one).
3. Pass it on: agent.chat(text, reasoning_effort=effort). None uses the agent's default (BaseAgent(reasoning_effort=...), from your LLM_REASONING_EFFORT setting); "off" turns the default off for this message. Any other value raises ValueError before the turn starts.

What to know: the SDK adds room for the thinking to the output limit and keeps Claude's signed thinking blocks with the tool calls of the turn, so it works in tool loops and with streaming. A model that cannot reason ignores the setting with one warning. The newest Claude models decide for themselves whether to think, so an easy question may show no thinking. On Anthropic, changing the effort between messages makes that one message re-read the conversation uncached.

11. Models, keys and errors#

• Model and key. BaseAgent(model="provider/model", api_key=...). Use the LiteLLM form (anthropic/claude-sonnet-4-5-20250929, openai/gpt-5, gemini/...). Pass the key; a key that only lives in .env is not in the environment.
• Routing. ModelRouter(routing_models={model: when_to_use}, router_model=...) lets a small model choose a model for each message. A message routed to a model without reasoning support ignores the effort setting.
• Retries and caching. The SDK retries rate limits, overload and connection errors up to twice with backoff, honouring the provider's Retry-After. It marks prompt-cache points for Anthropic models. To change either, build LlmClient(max_retries=..., prompt_caching=...) and pass it as llm=.

What chat() can raise#

All the Llm...Error classes derive from LlmError (and from HippoDbError); each has model, provider, status_code, retry_after and retryable, and the LiteLLM exception is its __cause__. agent.last_turn.status is failed after any of them.

12. Behaviour worth knowing#

• memory_think hides the SDK's own scaffolding. TOOL, INTENT and WORKFLOW concepts share the fabric with the user's memory and used to leak into recall results. They are filtered out unless the model asks for those types by name.
• A tool error is never an empty string. A failure with no message (a timeout) reaches the model with the exception's type.
• A turn that is cut short is remembered. The model does not repeat the writes of a stopped or cancelled turn.
• Tools are sent in a fixed order, which helps provider-side prompt caching. Within one turn the list changes only when discover_more_tools adds tools; across turns it changes with discovery.
• discover_more_tools adds at most 5 tools per turn, and adds nothing (instead of everything) when nothing matches.
• Hard rules and the data gateway are available, but only if you wire them. Rules the model saves with memory_learn_rule are soft guidance. Enforcement in code (RuleEnforcer) and PII masking (DataGateway) have to be added to the registry by the host. See Compliance and the host-integration guide.

13. Settings: your Cradle Settings to the SDK#

The SDK does not read your .env. Your Settings reads it, and the handler passes the values on.

Already in the Cradle starter's Settings:

Add these to your Settings and pass them on if you want them (the SDK defaults apply until you do):

Anything your project does not forward keeps the SDK default. The full list is in the technical reference, section 17.

14. Seeing what the agent did#

• agent.last_turn after each turn: status, rounds, tools used, duration, error, reasoning effort. Also the log line CHAT TURN n END status=... (logger sdk.agent).
• Memory traffic. Every think, query, ingest and link is one INFO line on the sdk.memory logger, tagged with the turn and fabric. The full request and response bodies are DEBUG records. A host that wants them in a file calls setup_memory_logging(log_dir, include_payloads=True) from hippodb_agent.logging.setup.
• HippoDb errors. The memory.client logger writes a WARNING with the response body for every status of 400 or more. That is where a 401 reason or a 404 on a lost fabric shows up.
• Tool discovery. sdk.discovery logs which tools it found, which phase found them, and the index summary. discovery.last_index_report lists tools learned, repaired, refreshed, skipped or in conflict.
• A health report for a fabric. python -m hippodb_agent.monitor.brain_report --fabric <name> --api-key ... (or with HIPPODB_API_KEY set) prints concept counts by type, the most and least activated concepts, edge strength, orphans and fact coverage.

15. Upgrading a Cradle project from 1.x#

1. Bump the pin (uv add hippodb-agent-sdk==2.0.0) and run the test suite. A search of a wired project found nothing it uses that 2.0.0 removed.
2. Pass the HippoDb key at every HippoClient(...) through one helper (section 3).
3. Remove the once-per-turn index_tools() call from the chat handler if you like; discover() does it now.
4. Replace the litellm.request_timeout global with BaseAgent(timeout=...), and update the test that asserts the global.
5. Handle LlmError where you used to catch LiteLLM exceptions. Code that caught litellm.RateLimitError no longer sees it.
6. Expect a smaller history window default (5, was 20) if you rely on conversation_id history. A handler that sets agent.history itself is not affected.
7. Add the new features you want: reasoning effort (section 10), a stop button (section 9), tool limits (section 5).
8. Update the stale >=1.2.4 notes in comments and in SDK-LINKAGE.md, and the "SDK defaults.env" line in .env.example.

The complete list, including each removed call, is in the release notes.

16. Quick troubleshooting#

17. Reference documents#

• Building an Agent Without AgentRunner: the tested wiring example
• Technical Reference: every class, method and setting
• LLM Routing: models, keys, routing, retries, typed errors, caching, reasoning effort
• Events and Streaming: the event queue, stop and cancel
• Pre-Education: seed design
• Compliance: the data gateway and rules, if you add them
• Release notes 2.0.0: what changed and how to upgrade