> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenticenv.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval (RAG)

> Connect agents to external knowledge bases with agentic, prefetch, or hybrid retriever modes

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`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/interfaces#Retriever).

**Infrastructure setup (local dev):**

```bash theme={null}
# 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

```go theme={null}
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()`:

```go theme={null}
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 |

```go theme={null}
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.

<Note>
  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](/features/hooks).
</Note>

## Backends

### Weaviate

```go theme={null}
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:

```go theme={null}
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`](https://pkg.go.dev/github.com/agenticenv/agent-sdk-go/pkg/interfaces#Retriever):

```go theme={null}
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

<CardGroup cols={2}>
  <Card title="Retrieval" icon="play" href="/examples/retrieval" horizontal>
    Agentic, prefetch, and hybrid RAG
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="Memory" icon="brain" href="/features/memory" horizontal>
    User-scoped long-term memory
  </Card>

  <Card title="Hooks" icon="code-branch" href="/features/hooks" horizontal>
    Query rewriting and document filtering
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.