Attach knowledge to an agent

A collection full of well-indexed documents does nothing on its own. An agent can only search collections named in its own configuration, so attaching is the step that connects the two — and the step people most often skip before concluding that retrieval is broken.

Two ways to attach

In the platform. Open the agent on the Agents screen and add the collection under Knowledge collections. Save. The next run uses it; runs already in flight keep the configuration they started with.

In a plugin. List the collection names in the agent’s frontmatter:

---
description: Answers support questions from the handbook, citing sources.
tools: [search]
collections: [handbook, policies]
---

The names must match collections that exist in the tenant you import into — attaching is by name, not by id, precisely so a plugin can move between environments where the same logical collection has different ids.

Both paths write the same field on the same record. Neither is a shortcut for the other.

Attaching is not enough on its own

Three things have to line up before an agent will cite a document. Check them in this order, because each makes the next one meaningful.

The agent needs the search tool. collections says what it may search; tools says whether it can search at all. An agent with collections and no search tool has knowledge it cannot reach. Add search to tools.

Its trust tier must permit that tool. search is permitted at both tiers, so this is rarely the problem — but if the tier strips a tool, the agent is told and will say plainly that it cannot search, rather than failing quietly. An agent that volunteers that it cannot search is telling you the answer.

The documents must have finished ingesting. A document still parsing is not searchable. See Ingest a document and query it.

What attaching several collections does

An agent may have any number. When it searches without naming one, all of its attached collections are searched and the results merged and ranked together — so the agent does not have to decide where to look before it knows what it is looking for.

It can also name one collection to narrow a particular search. Naming narrows within the attached set; it never reaches outside it. There is no value an agent can pass, and no instruction a user can give it, that searches a collection it was not attached to.

That ceiling is enforced server-side and is also why attaching is a deliberate act rather than a default. An agent with every collection attached retrieves worse — more candidates competing, more chances for a plausible passage from the wrong body of knowledge to outrank the right one. Attach what the agent is for.

Verifying it worked

Run a question the documents answer and watch the stream:

curl -N -X POST "$KOVAC_BASE/api/agent/threads/$THREAD_ID/runs/stream" \
  -H "Authorization: Bearer $KOVAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"assistant_id\": \"$ASSISTANT_ID\",
    \"input\": {\"messages\": [{\"role\": \"user\", \"content\": \"What is the expense approval threshold?\"}]},
    \"stream_mode\": [\"messages\", \"values\"]
  }"

You are looking for three things in order: a search tool call, a result array whose entries carry source_uri and metadata, and an answer citing them inline.

If the tool call is there and the result array is empty, the collection is attached to a different agent than the one you are running — the most common outcome of attaching in one place and testing in another. Re-read the agent’s own configuration rather than the collection’s.

Detaching

Remove the collection from the agent’s configuration. This does not delete the collection or its documents; it only stops this agent from reaching them. Another agent with the same attachment is unaffected.

Removing a collection that documents still live in is the right way to take knowledge out of circulation for one agent while keeping it for others.

Next: Read traces and evals.