Retrieval (RAG)

Retrieval-Augmented Generation (RAG) lets agents query external knowledge bases and ground responses in up-to-date or domain-specific content — without hardcoding it into the prompt. When a retrieval fires, the SDK calls Search(ctx, query) on your retriever, collects the returned []Document, and injects the document content into the LLM request — either as a labeled “Relevant Context” message ahead of conversation history (prefetch) or as a tool result the model requested (agentic). The system prompt itself is never modified. The LLM then sees the retrieved text alongside the user prompt when generating its response. Built-in retriever implementations are in pkg/retriever/weaviate and pkg/retriever/pgvector. Bring your own by implementing interfaces.Retriever. Infrastructure setup (local dev):

# Weaviate
docker run --rm -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:latest

# pgvector (Postgres with pgvector extension)
docker run --rm -p 5432:5432 -e POSTGRES_PASSWORD=pass pgvector/pgvector:pg16

Enable

import "github.com/agenticenv/agent-sdk-go/pkg/retriever/weaviate"

r, err := weaviate.NewRetriever("product_knowledge",
    weaviate.WithHost("localhost:8080"),
    weaviate.WithClassName("ProductDocs"),
)
if err != nil {
    return err
}

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithRetrievers(r),
    agent.WithRetrieverMode(agent.RetrieverModeAgentic), // default
)

Pass multiple retrievers — each must have a unique Name():

agent.WithRetrievers(productRetriever, supportRetriever)

Retriever modes

Set with WithRetrieverMode:

Mode	Behavior	Best for
`RetrieverModeAgentic` (default)	LLM calls the retriever as a tool when it decides to search	Multi-step agents where retrieval is not always needed
`RetrieverModePrefetch`	Context injected before every LLM call — no retriever tools exposed	Always-grounded Q&A, enterprise knowledge bases
`RetrieverModeHybrid`	Prefetch context plus retriever exposed as a tool	Grounded defaults with on-demand deeper search

agent.WithRetrieverMode(agent.RetrieverModeAgentic)
agent.WithRetrieverMode(agent.RetrieverModePrefetch)
agent.WithRetrieverMode(agent.RetrieverModeHybrid)

Choosing a mode: use Agentic when retrieval is optional — the model decides when to search. Use Prefetch when every LLM call must be grounded (Q&A bots, customer support). Use Hybrid when you want a baseline of context on every turn but also want the model to be able to search deeper on-demand.

In agentic and hybrid modes, each retriever is registered as a tool the LLM can invoke. Its name must be unique across all tool sources. Use BeforeRetrieveHook to rewrite the query and AfterRetrieveHook to filter or re-rank results — see Hooks.

Backends

Weaviate

r, err := weaviate.NewRetriever("product_knowledge",
    weaviate.WithHost("localhost:8080"),
    weaviate.WithClassName("ProductDocs"),
)

Local Docker, zero auth for development. The first argument is the retriever’s tool name — must be unique.

pgvector

Postgres with pgvector extension — requires an embed function:

import "github.com/agenticenv/agent-sdk-go/pkg/retriever/pgvector"

r, err := pgvector.NewRetriever("support_knowledge", embedFn,
    pgvector.WithDSN("postgres://user:pass@localhost:5432/mydb"),
    pgvector.WithTable("documents"),
)

Custom retriever

Implement interfaces.Retriever:

type Retriever interface {
    Name() string
    Search(ctx context.Context, query string) ([]interfaces.Document, error)
}

Name() doubles as the tool name in agentic and hybrid modes — keep it short and descriptive since the LLM uses it to decide when to call. Search receives the raw query string and returns documents whose Content field is injected into the prompt. Register with WithRetrievers.

Example

Retrieval

Agentic, prefetch, and hybrid RAG

Memory

User-scoped long-term memory

Hooks

Query rewriting and document filtering

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Enable

Retriever modes

Backends

Weaviate

pgvector

Custom retriever

Example

Retrieval

Memory

Hooks

​Enable

​Retriever modes

​Backends

​Weaviate

​pgvector

​Custom retriever

​Example

Retrieval

​Related

Memory

Hooks

Enable

Retriever modes

Backends

Weaviate

pgvector

Custom retriever

Example

Related