Skip to content

Custom Instructions

Every deployment has domain-specific rules the generic agent can't know: formal tone for legal docs, Swiss-German spellings for a product catalog, always-cite-SKU for an ERP integration. retrievalagent exposes two hooks for this.

instructions= — one-time constructor argument

Appended to the generation system prompt. Use it for answer-style rules:

from retrievalagent import init_agent

rag = init_agent(
    "legal_docs",
    model="openai:gpt-5.4",
    backend="qdrant",
    instructions=(
        "You are a legal assistant. Answer in formal language. "
        "Always cite the article number when referencing a law. "
        "If the context is insufficient, say so explicitly."
    ),
)

custom_instructions — config-file hook

RAGConfig.custom_instructions appends text to the retrieval-side prompts (preprocess, filter-intent, close-match grader). Use it for query-shaping rules:

from retrievalagent import AgenticRAG, RAGConfig

config = RAGConfig(
    custom_instructions=(
        "This is a Swiss hardware store catalog. "
        "Brand names are important — always preserve them. "
        "Treat 'Schraubenzieher' and 'Schraubendreher' as synonyms."
    )
)
rag = AgenticRAG(index="products", backend=backend, config=config)

Or set it per collection in retrievalagent.config.toml:

[retrievalagent]
top_k = 10

[retrievalagent.collections.legal]
custom_instructions = "Cite article numbers. Formal language only."

[retrievalagent.collections.products]
custom_instructions = "Preserve brand names. Accept informal product names."

Or via environment variable:

export RAG_CUSTOM_INSTRUCTIONS="Respond only in French."

Per-collection descriptions

When using multi-collection routing, pass human-readable descriptions so the routing LLM can pick the right index:

rag = init_agent(
    index="ignored",
    collections={"legal": backend_legal, "products": backend_products},
    collection_descriptions={
        "legal": "Laws, contracts, regulatory documents",
        "products": "Product catalog, SKUs, pricing",
    },
)

What goes where

Hook Affects When to use
instructions= Answer generation prompt Tone, citation format, language style
custom_instructions Retrieval prompts (preprocess, filter, grader) Synonym hints, brand handling, domain vocabulary
collection_descriptions Collection routing LLM Multi-collection disambiguation