Tutorial: a documentation assistant

In this tutorial you build docs-assistant, a service that answers questions about a set of Markdown documents and, with approval, edits them in a git repository. Each step adds one Riverbeam capability to the same project.

Step	You add	Riverbeam pieces
1. A first agent	A model-backed agent you can invoke	RiverBeam, RigAgentRunner, OpenAiCompatible
2. Tools	A tool the model can call	Tool, ToolSpec, json_params
3. Knowledge	Answers grounded in your documents	KnowledgeManager, retrieval
4. An HTTP API with streaming	/invoke, /astream and server-sent events	BeamDomain, LocalWorkerClient, BroadcastTransport
5. Editing with approval	An agent that commits changes and asks before pushing	sandbox_tools, WorkingTree, resume
6. Production	Separate worker and API processes on NATS and Postgres	NatsWorkerServer, NatsWorkerClient, PgBeamStore

Before you start

• Check out the workspace as described in Installation.
• Read the quick start; this tutorial builds on it.
• Optional: an API key for an OpenAI-compatible endpoint. Without one, the agent uses an echo client, so every step still runs, but the model never calls tools.
• For step 6: a running NATS server and a Postgres database.

The finished project

riverbase-workspace/
├── riverbase/
├── river-reed/
├── riverbeam/
└── docs-assistant/
    ├── Cargo.toml
    ├── policy.csv          # step 6
    ├── docs/               # the documents the assistant answers from
    └── src/
        ├── main.rs         # steps 1–5: one process
        ├── agents.rs
        ├── tools.rs
        ├── knowledge.rs
        ├── api.rs
        └── bin/
            ├── worker.rs   # step 6
            └── server.rs   # step 6

Start with step 1.