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.
+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.
|
||||
|
||||
Reference in New Issue
Block a user