Skip to content

QAChatAgent

RAG-powered question-answering agent. Retrieves relevant context from a Gemini File Search Store via RetrievalService, then generates an answer using Gemini with prompt templates. Supports multi-turn conversation history and optional canonical document grounding.

Import

import { QAChatAgent } from "@modernpath/agent-framework";
import type { QAChatAgentConfig } from "@modernpath/agent-framework";

Constructor

class QAChatAgent extends BaseAgent {
  constructor(
    toolRegistry: ToolRegistry,
    retrieval: RetrievalService,
    gemini: GeminiClient,
    prompts: PromptTemplate,
    cfg?: QAChatAgentConfig,
    canonicalGrounding?: CanonicalGroundingService,
  )
}
Parameter Type Required Description
toolRegistry ToolRegistry Yes Tool registry for the agent.
retrieval RetrievalService Yes Service for searching Gemini File Search Stores (RAG retrieval).
gemini GeminiClient Yes Gemini model client for answer generation.
prompts PromptTemplate Yes Prompt template engine. Must have qa-chat.answer_generation.* templates loaded.
cfg QAChatAgentConfig No Optional configuration.
canonicalGrounding CanonicalGroundingService No Optional service for attaching full canonical documents to the generation prompt.

Configuration

QAChatAgentConfig

interface QAChatAgentConfig {
  defaultStore?: string;
}
Name Type Required Default Description
defaultStore string No undefined Default File Search Store display name to use if parameters.store is not provided in the context.

Context Parameters

The agent reads these keys from AgentContext.parameters:

Parameter Type Required Default Description
store string Yes (or set defaultStore) -- Display name of the Gemini File Search Store to query.
topK number No Determined by RetrievalService Maximum number of chunks to retrieve.
metadataFilter string No undefined Metadata filter expression for narrowing retrieval results.
canonicalGrounding boolean No false When true and a CanonicalGroundingService is provided, attaches full canonical documents to the LLM prompt as ground truth.

Return Value

On success, AgentResult.data contains:

{
  answer: string;
  sources: KnowledgeSource[];
  groundingMetadata?: any;
}
Field Type Description
answer string The generated answer text.
sources KnowledgeSource[] Array of source documents/chunks used for retrieval. Each source includes metadata like file name, chunk text, and relevance score.
groundingMetadata any Optional grounding metadata returned by the retrieval service.

Required Prompt Templates

The agent expects these prompt template keys to be registered:

Template Key Required Description
qa-chat.answer_generation.system No System prompt for answer generation. If not present, no system prompt is used.
qa-chat.answer_generation.user_template Yes User prompt template. Available variables: question, context, sources, conversationHistory.

Template Variables

Variable Type Description
question string The user's prompt from AgentContext.prompt.
context string Retrieved text from the knowledge store.
sources KnowledgeSource[] The source objects for citation rendering.
conversationHistory string Formatted conversation history (each entry as role: content).

Execution Flow

sequenceDiagram
    participant Caller
    participant QAChatAgent
    participant RetrievalService
    participant CanonicalGrounding
    participant GeminiClient

    Caller->>QAChatAgent: execute(context)
    QAChatAgent->>RetrievalService: search(prompt, store, options)
    RetrievalService-->>QAChatAgent: { text, sources, groundingMetadata }
    QAChatAgent->>QAChatAgent: render prompt template
    opt canonicalGrounding enabled
        QAChatAgent->>CanonicalGrounding: prepareFromSources(sources)
        CanonicalGrounding-->>QAChatAgent: prepared documents
        QAChatAgent->>QAChatAgent: attach documents to prompt
    end
    QAChatAgent->>GeminiClient: generateContent(prompt)
    GeminiClient-->>QAChatAgent: answer text
    QAChatAgent-->>Caller: { answer, sources, groundingMetadata }

Graceful Degradation

If the RetrievalService fails (e.g., the store is missing or misconfigured), the agent catches the error and falls back to an empty retrieval context. The LLM will still generate a response, but without RAG-grounded context. This keeps the agent usable in minimal or demo setups.

Fallback behavior

When retrieval fails silently, the answer is generated without grounding context. The sources array will be empty. Monitor the agent's debug logs (set DEBUG=qa-agent or DEBUG=*) to detect retrieval failures.

Code Example

Basic Usage

import {
  QAChatAgent,
  ToolRegistry,
} from "@modernpath/agent-framework";

const registry = new ToolRegistry();

const qaAgent = new QAChatAgent(
  registry,
  retrievalService,  // RetrievalService instance
  geminiClient,      // GeminiClient instance
  promptTemplate,    // PromptTemplate with qa-chat templates loaded
  { defaultStore: "product-knowledge-base" },
);

const result = await qaAgent.execute({
  userId: 42,
  auditingId: 1001,
  prompt: "What is the return policy for electronics?",
  parameters: {
    store: "product-knowledge-base",
    topK: 10,
  },
});

if (result.success) {
  console.log("Answer:", result.data.answer);
  console.log("Sources:", result.data.sources.length);
}

With Conversation History

const result = await qaAgent.execute({
  userId: 42,
  auditingId: 1001,
  prompt: "What about international orders?",
  parameters: { store: "product-knowledge-base" },
  history: [
    { role: "user", content: "What is the return policy?" },
    {
      role: "assistant",
      content: "Our standard return policy allows returns within 30 days...",
    },
  ],
});

With Canonical Grounding

const qaAgent = new QAChatAgent(
  registry,
  retrievalService,
  geminiClient,
  promptTemplate,
  { defaultStore: "legal-docs" },
  canonicalGroundingService, // CanonicalGroundingService instance
);

const result = await qaAgent.execute({
  userId: 42,
  auditingId: 1001,
  prompt: "What are the liability limitations in our service agreement?",
  parameters: {
    store: "legal-docs",
    canonicalGrounding: true, // Enable full document attachment
  },
});

Debug Logging

Set the DEBUG environment variable to enable detailed logging:

# Enable QAChatAgent debug logs
DEBUG=qa-agent node app.js

# Enable all debug logs
DEBUG=* node app.js

Debug logs include retrieval parameters, source counts, context length, and grounding metadata presence.