Cookbook & learning paths
The public Cookbook contains runnable examples for adding LibraOS to your application. Choose a learning sequence, a capability, or a complete app. Your application continues to own its business records, authorization, and user experience.
Learn Step by Step
Start with local setup and the shared Python environment and token setup. The documented protocol-test environment uses Python 3.12 and SDK 2.0.0; Mission Client and Console require Node 22.12 or newer.
| Level | Example | What to learn first |
|---|---|---|
| L1 | First Agent — Python, TypeScript or Bash | Running Runtime, model and credentials |
| L1 | Ticket Routing — structured output | First Agent; Python |
| L2 · Knowledge | Document Q&A | First Agent; document ingestion |
| L2 · Tools | Order Lookup | First Agent; kernel v0.3.0 or later; signed callback service and agent definition |
| L2 · Memory | Memory & User Isolation | First Agent; memory enabled; two ordinary users |
| L3 | Customer Support | Knowledge, Tools and trusted user identity mapping |
| L3 | Async Jobs & Recovery | First Agent; PostgreSQL-backed jobs |
| L4 | Personal Assistant | Browser sign-in, Knowledge and Memory |
| L4 | Marketing Team and Mission Console | Native jobs and enabled mission workflows |
L2 has independent branches. You can learn Knowledge, Tools or Memory without completing the other two. Customer Support combines knowledge, tools and identity; cross-session recall is optional. Async Jobs is an independent L3 branch. Difficulty reflects concepts and setup dependencies, not the industry named in an example.
Explore by Capability
Each example should demonstrate an outcome you can inspect and a failure or boundary you can exercise. These are verification targets, not a claim that every live check has already passed.
| Capability | Observable outcome | Failure or boundary |
|---|---|---|
| First Agent | Create an agent and receive a reply | Invalid credentials; model unavailable |
| Structured output | Schema-valid result and separately measured label accuracy | Invalid schema; valid JSON with an incorrect label |
| Knowledge | An answer supported by the supplied documents | A missing policy is not invented |
| Tools | Order status with a signed callback receipt | Unknown order, bad signature, unavailable webhook |
| Memory | A recalls a unique preference in a new conversation | B cannot access A's conversation or recall the preference, including with forged identity headers |
| Async | Persist a recovery receipt and resume observation of the same job | Lost submit response, timeout, failure and cancellation races |
| Mission | Complete tasks and generate a report | Reconnection, replayed events, failed tasks and pending decisions |
An answer that looks like an order status does not prove a tool executed. Check the callback receipt and match the recorded tool result. Likewise, a failed memory lookup does not prove isolation: verify that A can recall the preference and read the conversation before checking B's denial.
Approval has two separate contracts
| Mechanism | Success means | Required boundary |
|---|---|---|
| Mission Decision | An authorized decision resolves a gate and dependent mission work resumes | An unauthorized caller cannot resolve the gate |
| Tool Action Approval | An authorized approval allows a pending business action to execute and produce a receipt | Rejection executes no action; unauthorized approval is denied |
The Marketing examples demonstrate Mission Decisions. A mission decision does not authorize arbitrary business mutations, and job completion does not prove that an approved action executed. A standalone Tool Action Approval tutorial is planned; the permission model must be verified for the selected Runtime version. See the approval contract notes.
See Complete Applications
- Personal Assistant: signed-in chat, documents and memory, with a complete browser application.
- Marketing Team: a multi-task mission with decisions and an attributed report. Mission Console is another interface to that mission, including stream recovery and failure display.
- Existing App Integration — planned: keep an existing customer/order management app and add knowledge, tools and AI-assisted business processing. This is not yet a runnable tutorial.
Finance, Legaltech, Healthcare and Content Moderation remain industry electives in the Cookbook. Running an industry example does not establish the quality or suitability of its decisions for production use.
Setup and compatibility
Read each example's README before running its source. Tools need kernel v0.3.0 or later, a callback secret and an allowed callback host. Memory needs two distinct ordinary-user tokens as well as a setup credential. Complete apps also need registered sign-in redirects and their documented Runtime configuration.
The common Compose setup defaults to kernel v0.3.0. Check /api/version and
the recipe's compatibility notes for the instance you use. Every recipe and app
was run or built on v0.3.0 from fresh Compose volumes; the
verification record
lists what was checked and the results, and the
Tool Calling record compares
models. Roll forward, not back: v0.2.4 boots on a database migrated by 0.3 but
ignores its access rules.
The cookbook's Compose file turns observational memory on
(LIBRA_OS_OBSERVATIONAL_MEMORY=1). The kernel keeps one log per canonical user
and agent, so every caller of one credential shares that credential's log.
Recipes that classify or extract one input at a time send no_memory: true, so
earlier answers are not recalled into later ones. Recipes that keep memory per
customer or patient through one service credential send X-Canonical-User,
which needs an impersonation-capable credential; X-End-User alone leaves every
end user in the same log. See Managing memory.
Async Recovery deliberately uses native HTTP. Its terminal success status is
done; do not mix its response shape with a managed-jobs SDK example. Recovery
of an uncertain submission requires verified server support for the saved
idempotency key. Client reconnection is separate from recovery of execution
after a server restart. See background tasks.
Use each recipe's documented agent registration path and structured output
endpoint. API creation and agent-definition files do not accept identical
fields. A successful create response alone does not prove custom tools were
registered: before v0.3.0, POST /v1/agents returned success while dropping
custom_tools, and custom tools on a persona agent never reached the model.
For Tools, confirm that each lookup adds a receipt for a verified callback.
Match the tool call and result before displaying its answer; see
Call your systems with tools. Verify a job's state after
requesting cancellation; an acknowledgement alone does not establish that
execution stopped.
Using the VS Code extension
The LibraOS VS Code extension can set up a
local Runtime and open examples. Its current Browse Cookbook list is curated
and may omit newer entries; existing entries fetch their source from GitHub
main. Use this page for the full learning path and open the recipe README for
multi-file setup. The extension-managed Runtime does not automatically include
every recipe's feature flags, app mounts or callback configuration.
Verify protocol behavior separately from model quality
From the Cookbook checkout, after installing requirements-dev.txt:
python -m pytest -m 'not live' --junitxml=test-results.xml
node --experimental-strip-types --test shared/mission-client/src/index.test.ts
Offline CI checks request shapes, callback verification, state transitions and
client recovery against fixtures. It does not prove live authorization,
retrieval quality, model recall or server restart durability. Optional live
tests require explicit COOKBOOK_LIVE=1 and the selected recipe's prerequisites.
For model evaluations, check schema validity separately from answer quality, source support and classification accuracy. Avoid exact wording snapshots; record the model, Runtime/SDK versions, configuration and observed pass rate. The validation matrix records coverage and remaining checks.