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

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, 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, this template is the starting point for all RAG implementations.

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.

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:

# Example using rag-vector-search

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

Integrate the Retriever Logic

Each sample provides a 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.

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.

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.

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: 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: Implements the enhance command, which can add deployment, CI/CD, or RAG scaffolding to existing projects.
• 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: Lists the available RAG samples (rag-vector-search, rag-agent-search) and their key implementation files.
• 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}