# How to Implement RAG with agents-cli: A Complete Guide to Retrieval-Augmented Generation

> Learn to implement RAG with agents-cli by scaffolding a project and using adk-samples. Get a complete guide to Retrieval-Augmented Generation with this workflow.

- Repository: [Google/agents-cli](https://github.com/google/agents-cli)
- Tags: how-to-guide
- Published: 2026-07-01

---

**TLDR:** agents-cli does not ship a dedicated RAG template; instead, you implement Retrieval-Augmented Generation by scaffolding an ADK base project and integrating code from the public adk-samples repository using a clone-and-study workflow.

The google/agents-cli toolchain provides the foundation for building AI agents, but implementing **Retrieval-Augmented Generation (RAG)** requires a specific integration pattern. Rather than offering a managed template, the CLI supports a **clone-and-study recipe** that combines a base ADK agent with reference implementations from the adk-samples repository.

## Understanding the agents-cli RAG Architecture

According to the source code in [`src/google/agents/cli/data/_recipe.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/data/_recipe.py), dedicated RAG commands were removed from the CLI in favor of a flexible recipe approach. This design decision places the heavy lifting—vector index creation, data ingestion pipelines, and Terraform provisioning—inside the public `adk-samples` repository while using `agents-cli` as the glue to integrate these components into an ADK-based agent.

The workflow supports two distinct retrieval strategies:

- **rag-vector-search**: Uses Vertex AI Vector Search 2.0 with a custom ingestion pipeline that handles embeddings and similarity search.
- **rag-agent-search**: Uses Agent Platform Search (Discovery Engine) with a managed GCS Data Connector, eliminating the need for custom ingestion code.

## Prerequisites

Before implementing RAG with agents-cli, ensure you have:

- The `agents-cli` installed and configured for your Google Cloud project.
- Terraform installed locally to provision Vertex AI resources.
- Access to the `adk-samples` repository at https://github.com/google/adk-samples.git.

## Step-by-Step Implementation

### Scaffold the Base ADK Project

Create a foundation using the ADK template, which provides a fully functional ReAct agent with Agent-to-Agent (A2A) protocol support. As documented in [`docs/src/guide/templates.md`](https://github.com/google/agents-cli/blob/main/docs/src/guide/templates.md), this template is the starting point for all RAG implementations.

```bash
agents-cli create my-rag-agent --agent adk

```

### Clone the RAG Samples Repository

Retrieve the reference implementations from the public samples repository. A shallow checkout is sufficient since you will copy specific directories rather than maintaining a full fork.

```bash
git clone --depth 1 https://github.com/google/adk-samples.git
cd adk-samples

```

### Choose Your Retrieval Strategy

Select the sample that matches your infrastructure requirements:

- **rag-vector-search**: Choose this if you need custom embedding control and Vertex AI Vector Search 2.0.
- **rag-agent-search**: Choose this if you prefer managed ingestion via the GCS Data Connector and Discovery Engine.

Copy your chosen sample into the scaffolded project:

```bash

# Example using rag-vector-search

cp -r core/rag-vector-search/* ../my-rag-agent/

```

### Integrate the Retriever Logic

Each sample provides a [`retriever.py`](https://github.com/google/agents-cli/blob/main/retriever.py) (or similar module) that implements the vector-search or document-search logic. Move this file into your agent’s source tree and import it from your tool implementation. This retriever module handles the actual retrieval phase of the RAG pipeline, querying the datastore before the generation phase begins.

### Provision Cloud Infrastructure with Terraform

Each RAG sample ships with an `infra/terraform/` directory containing the infrastructure definitions. Copy this directory into your project and execute the standard Terraform workflow to provision the required Vertex AI resources, including Vector Search indexes, Data Connectors, and IAM configurations.

```bash
cd ../my-rag-agent/infra/terraform
terraform init
terraform apply

```

### Run Data Ingestion

For the `rag-vector-search` implementation, you must populate the vector index. The sample includes a `Makefile` with a `data-ingestion` target that reads documents, creates embeddings, and uploads them to the index. This step is optional for `rag-agent-search` because the managed connector handles ingestion automatically.

```bash
cd ../../my-rag-agent
make data-ingestion

```

### Test the RAG Agent Locally

Verify that retrieval and generation work together by running the agent locally. The ADK runtime will load your integrated retriever and execute the full RAG pipeline.

```bash
agents-cli run

```

## Key Files and Code References

The following files in the google/agents-cli repository explain the RAG implementation strategy and CLI integration points:

- **[`docs/src/guide/templates.md`](https://github.com/google/agents-cli/blob/main/docs/src/guide/templates.md)**: Describes the ADK template and documents the clone-and-study RAG recipe in the "RAG (Retrieval-Augmented Generation)" section.
- **[`src/google/agents/cli/scaffold/commands/enhance.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/commands/enhance.py)**: Implements the `enhance` command, which can add deployment, CI/CD, or RAG scaffolding to existing projects.
- **[`src/google/agents/cli/data/_recipe.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/data/_recipe.py)**: Contains the centralized messaging explaining why RAG commands were removed and directing users to the sample-based recipe.
- **[`skills/google-agents-cli-workflow/references/samples.md`](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/references/samples.md)**: Lists the available RAG samples (`rag-vector-search`, `rag-agent-search`) and their key implementation files.
- **[`skills/google-agents-cli-workflow/SKILL.md`](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/SKILL.md)**: Highlights the clone-and-study approach for RAG implementation.

## Summary

Implementing RAG with agents-cli follows a **scaffold → clone → copy → adapt** workflow:

- agents-cli provides the base ADK agent scaffold, not a dedicated RAG template.
- You must clone the `adk-samples` repository and copy the relevant RAG sample into your project.
- Terraform configurations in `infra/terraform/` provision the required Vertex AI resources.
- The `make data-ingestion` command populates vector indexes for the custom search implementation.
- The `agents-cli run` command executes the integrated agent with full RAG capabilities.

## Frequently Asked Questions

### Does agents-cli have a built-in RAG template?

No. According to [`src/google/agents/cli/data/_recipe.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/data/_recipe.py), dedicated RAG commands were removed from the CLI. Instead, you implement RAG by scaffolding an ADK base project and integrating code from the `adk-samples` repository using the documented clone-and-study recipe.

### What is the difference between rag-vector-search and rag-agent-search?

**rag-vector-search** uses Vertex AI Vector Search 2.0 with a custom ingestion pipeline that requires you to manage embeddings and run `make data-ingestion`. **rag-agent-search** uses Agent Platform Search (Discovery Engine) with a managed GCS Data Connector, eliminating the need for custom ingestion code while handling retrieval through the managed service.

### Where are the RAG infrastructure definitions located?

Each RAG sample in the `adk-samples` repository contains an `infra/terraform/` directory. These Terraform configurations define the Vector Search indexes, Data Connectors, IAM roles, and other Google Cloud resources required to support the retrieval component of your RAG pipeline.

### Can I deploy a RAG agent using the standard agents-cli deployment flow?

Yes. Once you have integrated the retriever logic and verified local functionality with `agents-cli run`, the RAG components do not interfere with the standard deployment flow. You can use `agents-cli scaffold enhance` or other deployment commands to add CI/CD pipelines and production infrastructure, as the RAG recipe integrates seamlessly with the base ADK project structure.