docs: Document the driver prompt at agent RAG init and the duckdb two-file pairing

Agent startup and graph rag nodes now offer the storage driver choice, so the
RAG page no longer claims it is only asked while creating a RAG with .rag.

Also documents that a duckdb RAG is two files that must travel together, what
Coyote does when only the .yaml arrives, and that a local Qdrant is reached
without going through an ambient proxy.
2026-08-12 12:48:44 -06:00
parent 6ad2c80680
commit ee8b5781be
3 changed files with 24 additions and 4 deletions
+7 -1
@@ -309,6 +309,12 @@ of documents that Coyote supports and how to use custom document loaders, refer
Anytime your agent starts up, it will automatically be using the RAG you've defined here.
The first time an agent starts with documents attached, Coyote offers to build the knowledge base and asks which
[storage driver](RAG#storage-drivers) to store it with — `yaml` (the default, and what Coyote has always done) or
`duckdb`, which keeps the vectors and text on disk so a large corpus doesn't have to be read back into memory on every
start. The choice is fixed once the knowledge base is built: changing it means removing the agent's built knowledge
base and letting it rebuild, which re-embeds every document.
# 4. Building Tools for Agents
Building tools for agents is virtually identical to building custom tools, with one slight difference: instead of
defining a single function that gets executed at runtime (e.g. `main` for bash tools and `run` for Python tools), agent
@@ -932,4 +938,4 @@ path table and the [official sbx mixin reference](https://docs.docker.com/ai/san
installs/domains they bring. Not a bug, just visibility.
- **The `sql` agent's `usql` install is in the base kit, not a per-agent mixin.** Same for `pandoc` (used by
`fetch_url_via_curl`). Both ship with every Coyote sandbox automatically. See `assets/sbx-kit/spec.yaml` for the
full base prereq list.
full base prereq list.
+4 -2
@@ -591,8 +591,10 @@ base is first built):
a `<rag-node-id>.duckdb` file beside the generated knowledge base. An invalid driver is
rejected when the graph is validated, naming the offending node. Like every field in this
section it only applies when the knowledge base is *first* built — changing it later has no
effect until the knowledge base is deleted and rebuilt. The `qdrant` driver is not available
here: attaching a remote collection is an interactive flow (`.rag attach`).
effect until the knowledge base is deleted and rebuilt. When the node omits it and the knowledge
base is built interactively, Coyote asks which driver to use; setting it here answers that
question up front. The `qdrant` driver is not available here: attaching a remote collection is an
interactive flow (`.rag attach`).
Each falls back to the app-level `rag_*` config when omitted. **When
`embedding_model`, `chunk_size`, and `chunk_overlap` are all set, the
+13 -1
@@ -130,7 +130,8 @@ actually live: inside the RAG's own file, in a local database beside it, or in a
| `duckdb` | A `<name>.duckdb` file beside the RAG | The corpus is large enough that re-loading it into memory on every start is annoying |
| `qdrant` | A collection on a Qdrant server you already run | Something else already built and maintains the collection |
Coyote asks which one you want while creating a RAG with `.rag`:
Coyote asks which one you want whenever it builds a knowledge base interactively — creating a RAG with `.rag`, an
[agent](Agents#3-initializing-rag) starting up for the first time, or a [graph agent's](Graph-Agents) `rag` node:
```text
? RAG storage driver:
@@ -168,6 +169,12 @@ Two things are worth knowing before you choose it:
Deleting the RAG removes the `.duckdb` file and its write-ahead log along with it.
A duckdb RAG is **two files**: the `<name>.yaml` and the `<name>.duckdb` beside it. Copy, move or back up both
together. The YAML deliberately holds no vectors, so a RAG that arrives without its store loads without complaint,
still lists every indexed document, and answers every query with nothing. Coyote warns when it sees that combination —
indexed files, empty store — naming the file it expected. If the store is genuinely gone, `.rebuild rag` re-embeds the
corpus from scratch; `.edit rag-docs` will *not* refill it, because unchanged documents are skipped by hash.
## qdrant — attaching an existing collection
The `qdrant` driver connects a RAG to a collection on a Qdrant server you already run. It is **read-only**: Coyote
queries the collection and never writes to it, so whatever populated it stays the sole owner of its contents. This is
@@ -200,6 +207,11 @@ A collection has to meet two requirements:
Point IDs may be integers or UUIDs; both work.
> **A Qdrant on your own machine or network is contacted directly.** If `HTTP_PROXY` or `HTTPS_PROXY` are set in your
> environment, Coyote still reaches a loopback, private-range or `.local` host without going through the proxy — a
> proxy that has never heard of your local server would otherwise refuse the connection outright. A remote Qdrant
> continues to honour whatever your environment configures.
> **Use the same embedding model that built the collection.** Coyote can't detect a mismatch — the dimensions may line
> up perfectly while the vectors mean entirely different things. The symptom is retrieval that returns confident
> nonsense, so it's worth checking rather than discovering later.