Retrieval and grounded-answer patterns

Build retrieval in two observable parts: find relevant source material, then ask the model to answer from it. Inspecting only the final prose hides whether a failure came from ingestion, search, or generation. For a complete project with installation and a run command, follow the knowledge tutorial. These independent host functions require matching core, a configured text model, and an embedding provider. Remote embedding providers make network requests even when the vector store is in memory.

Retrieve first, then answer

This function owns an in-memory knowledge base and an Agent. It loads two fictional store policies, retrieves evidence, and returns both the answer and source IDs. The supplied model and embedder must already be configured by your application.

import {
  Agent, InMemoryVectorStore, KnowledgeBase,
  type EmbeddingProvider, type ModelProvider,
} from "@agentium/core";

export async function answerPolicy(
  model: ModelProvider,
  embedding: EmbeddingProvider,
  question: string,
) {
  const knowledge = new KnowledgeBase({
    name: "store-policies",
    vectorStore: new InMemoryVectorStore(embedding),
  });
  try {
    await knowledge.initialize();
    await knowledge.addDocuments([
      { id: "returns", content: "Unopened items can be returned within 30 days of delivery." },
      { id: "shipping", content: "Standard shipping takes 3–5 business days." },
    ]);
    const sources = await knowledge.search(question, { topK: 2 });
    if (sources.length === 0) return { text: "No policy evidence found.", sourceIds: [] };
    const evidence = sources.map((source) => `[${source.id}] ${source.content}`).join("\n");
    const agent = new Agent({
      name: "policy-answer", model, register: false,
      instructions: "Use only the supplied policy evidence. Cite its bracketed source IDs. Say when it does not answer the question.",
    });
    try {
      const result = await agent.run(`Question: ${question}\n\nPolicy evidence:\n${evidence}`);
      if (result.status !== "completed") throw new Error(`Policy answer: ${result.status}`);
      return { text: result.text, sourceIds: sources.map((source) => source.id) };
    } finally {
      await agent.close();
    }
  } finally {
    await knowledge.close();
  }
}

Ask “How long do I have to return an unopened item?” Expect the retrieved IDs to include returns and the answer to cite that ID with the 30-day policy. The prompt requests grounding; verify it with application evaluations rather than treating a citation as proof. Change one policy and repeat the question. Also ask about a fact absent from both documents: the answer should acknowledge missing evidence. This small fixture rebuilds its index for each invocation; a service should ingest separately and reuse its owned index.

Let an Agent decide when to search

Host factory: pass an initialized knowledge base populated with documents visible to this caller. This function borrows it. The host closes the Agent after its runs and the knowledge base after all consumers finish.

import { Agent, KnowledgeBase, type ModelProvider } from "@agentium/core";

export function createPolicyAssistant(model: ModelProvider, knowledge: KnowledgeBase) {
  return new Agent({
    name: "policy-assistant", model, register: false,
    instructions: "Search policy evidence before answering policy questions. Cite source IDs; do not invent missing policy.",
    tools: [knowledge.asTool({
      toolName: "search_policy",
      description: "Search policies this caller is allowed to read.",
      topK: 3,
      formatResults: (results) => results.map((item) => `[${item.id}] ${item.content}`).join("\n\n"),
    })],
  });
}

Observe search_policy in the run’s tool events and inspect its result. Giving the model a search tool does not guarantee it will call it. Choose retrieval-before-generation when your application requires evidence to be present on every request.

Choose the storage and retrieval path

Decision	Start with	Verify
Text → vectors	Embedding providers	Model and dimension match the index; changing either can require reindexing
Local development	In-memory vector store	Data disappears with the process
Persistent corpus	Vector-store adapters	Credentials, collection schema, filters, and lifecycle
Exact identifiers plus semantic meaning	Hybrid search	Ranking on representative queries; inspect keyword-index lifetime
Better top results	Reranking	Quality improvement against the same test set
Relationship traversal	Graph retrieval	Evidence paths and user scope
Host-provided request context	Context providers	Where evidence is built and which request owns it
Hierarchical documents	PageIndex	Service setup and citations returned by the toolkit

Metadata filters are part of retrieval configuration, not a substitute for authorizing document ingestion and access. Keep source IDs stable and retain the source revision used by an answer.

More patterns

For ingestion, chunking, vector adapters, and hybrid-search configuration, use the knowledge guides. For a source-oriented harness, run the research project. Add evaluations for retrieval recall, unsupported questions, citation accuracy, and tenant-specific evidence.

Complete projects

Agents & memory

Models & Jev

Tools & knowledge

Teams & jobs

Deploy & devices

Quality & production

Retrieval and grounded-answer patterns

Retrieve first, then answer

Let an Agent decide when to search

Choose the storage and retrieval path

More patterns

​Retrieve first, then answer

​Let an Agent decide when to search

​Choose the storage and retrieval path

​More patterns

Retrieve first, then answer

Let an Agent decide when to search

Choose the storage and retrieval path

More patterns