Configure search on an agent

Ingesting a document set makes it searchable. This step decides which agents may search it, and when they should bother - because retrieving documents for "hello" wastes tokens and adds latency for no benefit.

Create axl-config/agents/assistant/rag.toml:

sources = ["product-guide"]
trigger_mode = "keyword"

sources must match names in docs.toml. The trigger mode controls when retrieval is used:

• keyword (the default when sources are configured) searches when the question matches the document set's keywords.
• always searches the configured sources for every request.
• off disables retrieval without removing the source list.

For a support agent that should always ground answers in the product guide, use:

sources = ["product-guide"]
trigger_mode = "always"

Restart the server after changing the agent config. Then ask a question covered by a document and check that the response uses the guide's terminology and cites or names the relevant source when your response policy requires it.

Tune retrieval only after it works

Retrieval is hybrid by default: vector similarity and keyword search, fused. The main controls are environment variables, shown here at their actual defaults:

RAG_SEARCH_MODE=hybrid        # hybrid | semantic | keyword
RAG_TOP_K=5                   # chunks returned per search
RAG_MAX_DISTANCE=0.8          # semantic-mode distance cut-off
RAG_CHUNK_TOKENS=256          # chunk size at ingest
RAG_CHUNK_OVERLAP_TOKENS=40   # overlap between chunks

Chunk settings apply at ingest, so changing them needs axl rag ingest --reindex. RAG_MAX_DISTANCE is a semantic-mode cut-off; hybrid mode fuses two rankings and does not use it.

Increase RAG_TOP_K when an answer needs several related sections. Before changing anything else, look at what retrieval is actually returning:

axl rag search "your question" -c /path/to/axl-config
axl rag eval -c /path/to/axl-config

search shows every scoring signal for one query; eval scores a whole golden set, so you can tell whether a change helped. See the CLI guide for both.

Common fixes

• No results: ingest the set again and confirm sources exactly matches its docs.toml name.
• Wrong knowledge area: use separate doc sets and list only the relevant source.
• Answers miss a section: split very large pages into task-sized documents and add useful terms to keywords.txt.
• Search is too broad: use keyword mode and tighten the document set rather than immediately changing model settings.

Most of the fixes above address the corpus, not the search parameters. Reach for RAG_TOP_K and distance thresholds last.

Next

• Evaluate agent quality - including axl rag eval for retrieval.
• Give an agent memory - for facts a person tells the agent directly.
• Support agent walkthrough - the whole pattern, end to end.