RFP Answer Assistant

Internal Devoteam tool for generating RFP responses. It takes an RFP document, analyzes the requirements, and produces a structured DOCX proposal, with multi-agent AI review and per-user session persistence.

---

Architecture

The system has two independent services that communicate via Vertex AI Agent Engine:

User (browser)
       │
       ▼
Chainlit (Cloud Run)          ← frontend, IAP authentication, file upload/download
       │
       │  Vertex AI Agent Engine
       ▼
ADK Multi-Agent Backend       ← orchestration, content generation and review
   ├── Root Agent              ← coordinates flow and global state
   ├── Writer Agent            ← writes each section of the proposal
   ├── Supervisor Agent        ← reviews and validates Writer output
   ├── Stylist Agent           ← extracts writing style from reference documents
   └── External Agents         ← specialized agents injected by the client
       │
       ├── Gemini (Vertex AI)  ← LLM
       ├── GCS                 ← storage for RFPs, outputs, logs
       └── PostgreSQL          ← Chainlit sessions + vector store (pgvector)

The backbone (backbones/backbone.json) defines the mandatory sections of the proposal and the questions the Writer must answer in each one.

---

Repository Structure

rfp-answer-assistant/
├── adk/                  # Backend — ADK agents + tools
│   ├── app/
│   │   ├── agent.py              # Agent definition and orchestration
│   │   └── app_utils/
│   │       ├── tools.py          # Tools exposed to agents (GCS, RAG, compilation)
│   │       ├── structures.py     # Pydantic schemas + CloudStorageHandler + VectorSearch
│   │       ├── prompts.py        # Agent system prompts
│   │       ├── doc_compiler.py   # Markdown → DOCX / Google Docs conversion
│   │       ├── runner_helper.py  # Utilities for invoking agents in sync mode
│   │       └── deploy.py         # Agent Engine deployment helpers
│   ├── tests/
│   └── pyproject.toml
│
├── chainlit/             # Frontend — Chainlit UI
│   ├── app.py            # Main app, IAP auth, session management
│   ├── ai_func.py        # Helpers for calling Agent Engine and managing GCS
│   └── gc_storage.py     # GCS data layer for Chainlit
│
├── backbones/            # Proposal templates (sections, questions, external agents)
├── external_agents/      # Specialized agents prompts and registration
├── data_prep/            # Document ingestion pipeline for vector store
├── eda/                  # Exploratory notebooks
├── terraform/            # GCP Infrastructure (Cloud Run, IAP, LB, secrets)
├── docs/
│   └── deploying-to-gcp.md  # Full deployment guide
├── Dockerfile
└── cloudbuild.yaml

---

Local Development

Backend (ADK)

Requires uv and Google Cloud SDK with gcloud auth login.

cd adk
make install      # install dependencies
make playground   # open ADK Playground in localhost (auto-reload)
make lint         # ruff + ty + codespell
make test         # pytest

To deploy the backend to Vertex AI Agent Engine:

gcloud config set project <PROJECT_ID>
make deploy

Frontend (Chainlit)

cd chainlit
pip install -r requirements.txt

Required environment variables (can use a .env):

PROJECT_ID=<gcp-project-id>
REGION=europe-west1
REASONING_ENGINE=projects/<project-number>/locations/europe-west1/reasoningEngines/<id>
BUCKET_NAME=<gcs-bucket>
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname

chainlit run app.py --host 0.0.0.0 --port 8080

---

Environment Variables

Backend (adk/)

Variable	Required	Description
BUCKET_NAME	Yes	GCS bucket for RFP files
PROJECT_NAME	Yes	GCP project ID
RFP_PATH	Yes	GCS prefix for session files
BACKBONE_GS_PATH	Yes	GCS path to backbone.json
GEMINI_MODEL	No	Gemini model to use (default: gemini-3-flash-preview)
GCP_LOCATION	No	Vertex AI region (default: europe-west1)
EXTERNAL_AGENTS_GS_PATH	No	GCS path to external agents registry
LOGS_BUCKET_NAME	No	Enables OpenTelemetry export to GCS

Frontend (chainlit/)

Variable	Required	Description
PROJECT_ID	Yes	GCP project ID
REGION	Yes	GCP region
REASONING_ENGINE	Yes	Agent Engine full Resource ID
BUCKET_NAME	Yes	GCS bucket (same as backend)
DATABASE_URL	Yes	PostgreSQL async connection string

Secrets (Secret Manager)

Secret ID	Content
rfp-oauth-client-id	Google OAuth Client ID
rfp-oauth-client-secret	Google OAuth Client Secret
rfp-chainlit-auth-secret	32-byte random string for session signing
rfp-database-url	PostgreSQL connection string

---

Bill of Materials

This project provides a comprehensive overview of the software dependencies and infrastructure components that constitute the DGC Internal RFP Agent project.

📦 Software Components

The project is structured as a multi-service application with two primary Python-based services:

1. Frontend UI (chainlit/): Provides the interactive conversational interface, handles asynchronous file uploads/downloads securely, and manages user sessions and authentication via IAP.
2. Backend AI Engine (adk/): Based on Google's Agent Development Kit, this service orchestrates the multi-agent LLM reasoning pipeline (Root Agent, Writer, Supervisor), compiles final documents, and manages RAG vector search operations.

☁️ GCP Infrastructure & Services

Component	GCP Service	Purpose
Frontend UI	Cloud Run	Hosts the Chainlit application in a scalable, serverless container environment.
Agent Runtime	Vertex AI Agent Engine	Serverless execution environment for the ADK multi-agent orchestration. Provides managed sessions.
LLMs & Embeddings	Vertex AI Models	Uses gemini-3-flash-preview for agent reasoning and text-embedding-004 for semantic RAG.
Vector DB & Sessions	Cloud SQL (PostgreSQL)	Stores Chainlit user sessions and RAG vectors using the pgvector extension.
Artifact Storage	Cloud Storage (GCS)	Centralized storage for uploaded RFP documents, generated DOCX proposals, backbones, and system logs.
Authentication	Identity-Aware Proxy	Enforces zero-trust access to the application, restricting it to authorized Devoteam users.
Networking	Private Service Connect	Enables secure, internal-only IP communication between the Cloud Run frontend, Agent Engine, and Cloud SQL.

🧠 Backend (Agent Engine) Libraries

The backend is built around Google's Agent Development Kit (ADK) and uses uv for modern dependency management.

Library	Version / Scope	Purpose
google-adk	Core Framework	The Agent Development Kit used to orchestrate the multi-agent architecture (Root, Writer, Supervisor).
google-genai	Core SDK	Official Google GenAI SDK used to interact with Gemini models and generate multimodal embeddings.
pydantic	Data Validation	Strictly enforces the JSON schemas returned by the Writer and Supervisor agents.
python-docx	Document Generation	Compiles the final Markdown outputs from the agents into a formatted Microsoft Word document.
asyncpg	Database Driver	High-performance, asynchronous PostgreSQL driver used by the RAG system to query pgvector.
opentelemetry-*	Observability	Traces LLM calls, latency, and token usage, exporting telemetry directly to Google Cloud Trace/Logging.

🖥️ Frontend (Chainlit) Libraries

The frontend is a lightweight, asynchronous UI built with Chainlit.

Library	Version / Scope	Purpose
chainlit	UI Framework	Provides the ChatGPT-like conversational interface, file upload components, and Markdown rendering.
sqlalchemy	Data Layer	ORM used to map Chainlit's conversation threads and user sessions into the PostgreSQL database.
asyncpg	Database Driver	Powers SQLAlchemy's async engine to prevent connection blocking under high concurrent load.
gcloud-aio-storage	Storage	Fully asynchronous Google Cloud Storage client. Crucial for fast, non-blocking file uploads from the UI.

---

Deployment

Production deployment is done via Cloud Build (automatic trigger on push to main) and Terraform for GCP infrastructure.

See docs/deploying-to-gcp.md for the complete guide, including manual IAP configuration that Terraform cannot do on its own.