Customizing Agent Behaviors
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Customizing agent behaviors in RAGAPPv3 involves configuring the RAG (Retrieval-Augmented Generation) engine's interaction with diverse knowledge sources, including raw documents, user memories, and compiled wiki claims. The system utilizes a multi-layered retrieval strategy where agent behavior is shaped by query classification, specific citation namespaces, and the optional integration of an LLM Wiki Curator for structured knowledge synthesis.
Sources: specs/wire-wiki-chat/SPEC.md:5-15, AGENTS.md:1-10
RAG Engine and Retrieval Logic
The core of agent behavior is dictated by the RAGEngine, which orchestrates how an agent accesses information. When a user submits a query, the agent performs a classification step to determine the most effective retrieval path.
Query Classification and Routing
The agent utilizes a QueryClassifier to detect "entity-heavy" queries. If a query is identified as entity-heavy, the agent prioritizes the WikiRetrievalService over standard raw document RAG. This "wiki-first" ranking ensures higher-fidelity, structured domain knowledge is utilized when appropriate.
Sources: specs/wire-wiki-chat/SPEC.md:145-155
Citation Namespaces
Agents are configured to use three independent, 1-indexed citation namespaces to distinguish the provenance of information in their responses. This prevents label collisions and provides clear evidence lineage.
| Namespace | Description | Label Format |
|---|---|---|
| Document Sources | Standard RAG retrieval from uploaded files | [S#] |
| Memory Records | Durable user context and preferences | [M#] |
| Wiki Claims | Compiled, verified knowledge from the wiki | [W#] |
Sources: specs/wire-wiki-chat/SPEC.md:160-170, frontend/src/lib/api.ts:710-720
LLM Wiki Curator
The agent's knowledge-gathering behavior can be further customized through the LLM Wiki Curator. This optional component allows the agent to propose wiki updates from a local model.
Curator Configuration
The curator behavior is defined by several parameters that control its operation, such as whether it requires exact source-quote matches or specific chunk IDs before a claim is considered valid.
| Parameter | Type | Description |
|---|---|---|
wiki_llm_curator_enabled | Boolean | Toggles the automated curation system. |
wiki_llm_curator_mode | String | Sets behavior to draft (always needs review) or active_if_verified. |
wiki_llm_curator_require_quote_match | Boolean | Requires exact text matches for claim validation. |
wiki_llm_curator_temperature | Float | Controls randomness (0.0–1.0) of curator proposals. |
Sources: frontend/src/lib/api.ts:400-430, frontend/src/components/settings/WikiCuratorSettings.tsx:240-270
Curator Workflow
The curator can be triggered during different stages of the document lifecycle, which is configurable via the WikiCuratorSettings.
Chat Interaction Modes
Agent responses are generated using two primary modes that adjust the underlying LLM processing behavior.
Instant vs. Thinking Mode
Agents can operate in instant or thinking modes. Instant mode (often paired with LM Studio) focuses on low-latency responses, while thinking mode allows for more complex reasoning. The backend reports the resolved mode at the start of every SSE stream via a mode event.
Sources: frontend/src/lib/api.ts:365-385, specs/chat-ui-ux-premiumization/SPEC.md:120-130
Streaming and Content Repair
Agent behavior during streaming is strictly controlled. Reasoning or thinking content (e.g., <think> tags) is explicitly stripped by the backend. If an agent generates invalid citations, the system performs "citation-repair" and sends the final cleaned content via the repaired_content field in the SSE done event.
Sources: frontend/src/lib/api.ts:880-910, specs/chat-ui-ux-premiumization/SPEC.md:40-50
Development Guidelines for Agents
For AI agents working within the repository, behaviors are governed by CLAUDE.md. Key principles include:
- Simplicity First: No speculative features or unnecessary abstractions.
- Surgical Changes: Match existing styles and only modify what is requested.
- Goal-Driven Execution: Define success criteria and verify through tests.
Sources: CLAUDE.md:15-60, AGENTS.md:30-45
Conclusion
Customizing agent behaviors in RAGAPPv3 is a multi-faceted process involving query routing logic, the use of distinct citation namespaces for evidence transparency, and the configuration of automated curation via the LLM Wiki Curator. By toggling specific settings and modes, developers can fine-tune how agents retrieve, synthesize, and present information to the user.