agent-starter-pack 0.3.3__py3-none-any.whl → 0.21.0__py3-none-any.whl

agent_starter_pack/base_template/README.md

@@ -0,0 +1,267 @@
+# {{cookiecutter.project_name}}
+
+{{cookiecutter.agent_description}}
+Agent generated with [`googleCloudPlatform/agent-starter-pack`](https://github.com/GoogleCloudPlatform/agent-starter-pack) version `{{ cookiecutter.package_version }}`
+
+## Project Structure
+
+This project is organized as follows:
+
+```
+{{cookiecutter.project_name}}/
+├── {{cookiecutter.agent_directory}}/                 # Core application code
+│   ├── agent.py         # Main agent logic
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+│   ├── fast_api_app.py  # FastAPI Backend server
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+│   ├── agent_engine_app.py # Agent Engine application logic
+{%- endif %}
+│   └── app_utils/       # App utilities and helpers
+{%- if cookiecutter.is_a2a and cookiecutter.agent_name == 'langgraph_base' %}
+│       ├── executor/    # A2A protocol executor implementation
+│       └── converters/  # Message converters for A2A protocol
+{%- endif %}
+{%- if cookiecutter.cicd_runner == 'google_cloud_build' %}
+├── .cloudbuild/         # CI/CD pipeline configurations for Google Cloud Build
+{%- elif cookiecutter.cicd_runner == 'github_actions' %}
+├── .github/             # CI/CD pipeline configurations for GitHub Actions
+{%- endif %}
+├── deployment/          # Infrastructure and deployment scripts
+├── notebooks/           # Jupyter notebooks for prototyping and evaluation
+├── tests/               # Unit, integration, and load tests
+├── Makefile             # Makefile for common commands
+├── GEMINI.md            # AI-assisted development guide
+└── pyproject.toml       # Project dependencies and configuration
+```
+
+## Requirements
+
+Before you begin, ensure you have:
+- **uv**: Python package manager (used for all dependency management in this project) - [Install](https://docs.astral.sh/uv/getting-started/installation/) ([add packages](https://docs.astral.sh/uv/concepts/dependencies/) with `uv add <package>`)
+- **Google Cloud SDK**: For GCP services - [Install](https://cloud.google.com/sdk/docs/install)
+- **Terraform**: For infrastructure deployment - [Install](https://developer.hashicorp.com/terraform/downloads)
+- **make**: Build automation tool - [Install](https://www.gnu.org/software/make/) (pre-installed on most Unix-based systems)
+
+
+## Quick Start (Local Testing)
+
+Install required packages and launch the local development environment:
+
+```bash
+make install && make playground
+```
+
+## Commands
+
+| Command              | Description                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------- |
+| `make install`       | Install all required dependencies using uv                                                  |
+{%- if cookiecutter.settings.get("commands", {}).get("extra", {}) %}
+{%- for cmd_name, cmd_value in cookiecutter.settings.get("commands", {}).get("extra", {}).items() %}
+| `make {{ cmd_name }}`       | {% if cmd_value is mapping %}{% if cmd_value.description %}{{ cmd_value.description }}{% else %}{% if cookiecutter.deployment_target in cmd_value %}{{ cmd_value[cookiecutter.deployment_target] }}{% else %}{{ cmd_value.command if cmd_value.command is string else "" }}{% endif %}{% endif %}{% else %}{{ cmd_value }}{% endif %} |
+{%- endfor %}
+{%- endif %}
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+| `make playground`    | Launch local development environment with backend and frontend{%- if cookiecutter.is_adk %} - leveraging `adk web` command. {%- endif %}|
+| `make deploy`        | Deploy agent to Cloud Run (use `IAP=true` to enable Identity-Aware Proxy, `PORT=8080` to specify container port) |
+| `make local-backend` | Launch local development server with hot-reload |
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+| `make playground`    | Launch local development environment for testing agent |
+| `make deploy`        | Deploy agent to Agent Engine |
+{%- if cookiecutter.is_adk_live %}
+| `make local-backend` | Launch local development server with hot-reload |
+| `make ui`            | Start the frontend UI separately for development (requires backend running separately) |
+| `make playground-dev` | Launch dev playground with both frontend and backend hot-reload |
+| `make playground-remote` | Connect to remote deployed agent with local frontend |
+| `make build-frontend` | Build the frontend for production |
+{%- endif %}
+{%- if cookiecutter.is_adk or cookiecutter.is_a2a %}
+| `make register-gemini-enterprise` | Register deployed agent to Gemini Enterprise ([docs](https://googlecloudplatform.github.io/agent-starter-pack/cli/register_gemini_enterprise.html)) |
+{%- endif -%}
+{%- endif -%}
+{%- if cookiecutter.is_a2a %}
+| `make inspector`     | Launch A2A Protocol Inspector to test your agent implementation                             |
+{%- endif %}
+| `make test`          | Run unit and integration tests                                                              |
+| `make lint`          | Run code quality checks (codespell, ruff, mypy)                                             |
+| `make setup-dev-env` | Set up development environment resources using Terraform                         |
+{%- if cookiecutter.data_ingestion %}
+| `make data-ingestion`| Run data ingestion pipeline in the Dev environment                                           |
+{%- endif %}
+
+For full command options and usage, refer to the [Makefile](Makefile).
+
+{%- if cookiecutter.is_a2a %}
+
+## Using the A2A Inspector
+
+This agent implements the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/), enabling interoperability with agents across different frameworks and languages.
+
+The [A2A Inspector](https://github.com/a2aproject/a2a-inspector) provides the following core features:
+- 🔍 View agent card and capabilities
+- ✅ Validate A2A specification compliance
+- 💬 Test communication with live chat interface
+- 🐛 Debug with the raw message console
+
+### Local Testing
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+
+1. Start your agent:
+   ```bash
+   make local-backend
+   ```
+
+2. In a separate terminal, launch the A2A Protocol Inspector:
+   ```bash
+   make inspector
+   ```
+
+3. Open http://localhost:5001 and connect to `http://localhost:8000`
+{%- else %}
+
+> **Note:** For Agent Engine deployments, local testing with A2A endpoints requires deployment first, as `make playground` uses the ADK web interface. For local development, use `make playground`. To test A2A protocol compliance, follow the Remote Testing instructions below.
+{%- endif %}
+
+### Remote Testing
+
+1. Deploy your agent:
+   ```bash
+   make deploy
+   ```
+
+2. Launch the inspector:
+   ```bash
+   make inspector
+   ```
+
+3. Get an authentication token:
+   ```bash
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+   gcloud auth print-identity-token
+{%- else %}
+   gcloud auth print-access-token
+{%- endif %}
+   ```
+
+4. In the inspector UI at http://localhost:5001:
+   - Add an HTTP header with name: `Authorization`
+   - Set the value to: `Bearer <your-token-from-step-3>`
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+   - Connect to your deployed Cloud Run URL
+{%- else %}
+   - Connect to your Agent Engine URL using this format:
+     ```
+     https://us-central1-aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/reasoningEngines/{ENGINE_ID}/a2a/v1/card
+     ```
+     Find your `PROJECT_ID`, `REGION`, and `ENGINE_ID` in the `latest_deployment_metadata.json` file created after deployment.
+{%- endif %}
+{%- endif %}
+
+{% if cookiecutter.is_adk_live %}
+## Usage
+
+This template follows a "bring your own agent" approach - you focus on your business logic in `{{cookiecutter.agent_directory}}/agent.py`, and the template handles the surrounding components (UI, infrastructure, deployment, monitoring).
+
+Here’s the recommended workflow for local development:
+
+1.  **Install Dependencies (if needed):**
+    ```bash
+    make install
+    ```
+
+2.  **Start the Full Stack Server:**
+    The FastAPI server now serves both the backend API and frontend interface:
+    ```bash
+    make local-backend
+    ```
+    The server is ready when you see `INFO:     Application startup complete.` The frontend will be available at `http://localhost:8000`.
+
+    <details>
+    <summary><b>Optional: Use AI Studio / API Key instead of Vertex AI</b></summary>
+
+    By default, the backend uses Vertex AI and Application Default Credentials. If you prefer to use Google AI Studio and an API key:
+
+    ```bash
+    export VERTEXAI=false
+    export GOOGLE_API_KEY="your-google-api-key" # Replace with your actual key
+    make local-backend
+    ```
+    Ensure `GOOGLE_API_KEY` is set correctly in your environment.
+    </details>
+    <br>
+
+    <details>
+    <summary><b>Alternative: Run Frontend Separately</b></summary>
+
+    If you prefer to run the frontend separately (useful for frontend development), you can still use:
+    ```bash
+    make ui
+    ```
+    This launches the frontend application, which connects to the backend server at `http://localhost:8000`.
+    </details>
+    <br>
+
+3.  **Interact and Iterate:**
+    *   Open your browser and navigate to `http://localhost:8000` to access the integrated frontend.
+    *   Click the play button in the UI to connect to the backend.
+    *   Interact with the agent! Try prompts like: *"Using the tool you have, define Governance in the context MLOPs"*
+    *   Modify the agent logic in `{{cookiecutter.agent_directory}}/agent.py`. The backend server (FastAPI with `uvicorn --reload`) should automatically restart when you save changes. Refresh the frontend if needed to see behavioral changes.
+
+
+</details>
+{%- else %}
+## Usage
+
+This template follows a "bring your own agent" approach - you focus on your business logic, and the template handles everything else (UI, infrastructure, deployment, monitoring).
+
+1. **Prototype:** Build your Generative AI Agent using the intro notebooks in `notebooks/` for guidance. Use Vertex AI Evaluation to assess performance.
+2. **Integrate:** Import your agent into the app by editing `{{cookiecutter.agent_directory}}/agent.py`.
+3. **Test:** Explore your agent functionality using the local playground with `make playground`. The playground automatically reloads your agent on code changes.
+4. **Deploy:** Set up and initiate the CI/CD pipelines, customizing tests as necessary. Refer to the [deployment section](#deployment) for comprehensive instructions. For streamlined infrastructure deployment, simply run `uvx agent-starter-pack setup-cicd`. Check out the [`agent-starter-pack setup-cicd` CLI command](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd.html). Currently supports GitHub with both Google Cloud Build and GitHub Actions as CI/CD runners.
+5. **Monitor:** Track performance and gather insights using BigQuery telemetry data, Cloud Logging, and Cloud Trace to iterate on your application.
+
+The project includes a `GEMINI.md` file that provides context for AI tools like Gemini CLI when asking questions about your template.
+{% endif %}
+
+## Deployment
+
+> **Note:** For a streamlined one-command deployment of the entire CI/CD pipeline and infrastructure using Terraform, you can use the [`agent-starter-pack setup-cicd` CLI command](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd.html). Currently supports GitHub with both Google Cloud Build and GitHub Actions as CI/CD runners.
+
+### Dev Environment
+
+You can test deployment towards a Dev Environment using the following command:
+
+```bash
+gcloud config set project <your-dev-project-id>
+make deploy
+```
+{% if cookiecutter.is_adk_live %}
+**Note:** For secure access to your deployed backend, consider using Identity-Aware Proxy (IAP) by running `make deploy IAP=true`.
+{%- endif %}
+
+The repository includes a Terraform configuration for the setup of the Dev Google Cloud project.
+See [deployment/README.md](deployment/README.md) for instructions.
+
+### Production Deployment
+
+The repository includes a Terraform configuration for the setup of a production Google Cloud project. Refer to [deployment/README.md](deployment/README.md) for detailed instructions on how to deploy the infrastructure and application.
+
+{% if not cookiecutter.is_adk_live %}
+## Monitoring and Observability
+
+The application uses [OpenTelemetry GenAI instrumentation](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for comprehensive observability. Telemetry data is automatically captured and exported to:
+
+- **Google Cloud Storage**: GenAI telemetry in JSONL format for efficient querying
+- **BigQuery**: External tables and linked datasets provide immediate access to telemetry data via SQL queries
+- **Cloud Logging**: Dedicated logging bucket with 10-year retention for GenAI operation logs
+
+**Query your telemetry data:**
+
+```bash
+# Example: Query recent completions
+bq query --use_legacy_sql=false \
+  "SELECT * FROM \`{{cookiecutter.project_name}}_telemetry.completions\` LIMIT 10"
+```
+
+For detailed setup instructions, example queries, testing in dev, and optional dashboard visualization, see the [starter pack observability guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html).
+{%- endif %}

agent_starter_pack/base_template/deployment/README.md

@@ -0,0 +1,11 @@
+# Deployment
+
+This directory contains the Terraform configurations for provisioning the necessary Google Cloud infrastructure for your agent.
+
+The recommended way to deploy the infrastructure and set up the CI/CD pipeline is by using the `agent-starter-pack setup-cicd` command from the root of your project.
+
+However, for a more hands-on approach, you can always apply the Terraform configurations manually for a do-it-yourself setup.
+
+For detailed information on the deployment process, infrastructure, and CI/CD pipelines, please refer to the official documentation:
+
+**[Agent Starter Pack Deployment Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment.html)**

{src → agent_starter_pack}/base_template/deployment/terraform/apis.tf

@@ -19,9 +19,9 @@ resource "google_project_service" "cicd_services" {
   disable_on_destroy = false
 }
 
-resource "google_project_service" "shared_services" {
+resource "google_project_service" "deploy_project_services" {
   for_each = {
-    for pair in setproduct(keys(local.deploy_project_ids), local.shared_services) :
+    for pair in setproduct(keys(local.deploy_project_ids), local.deploy_project_services) :
     "${pair[0]}_${replace(pair[1], ".", "_")}" => {
       project = local.deploy_project_ids[pair[0]]
       service = pair[1]

{src → agent_starter_pack}/base_template/deployment/terraform/dev/apis.tf

@@ -24,7 +24,12 @@ locals {
     "bigquery.googleapis.com",
     "serviceusage.googleapis.com",
     "logging.googleapis.com",
-    "cloudtrace.googleapis.com"
+    "cloudtrace.googleapis.com",
+    "telemetry.googleapis.com",
+{%- if cookiecutter.is_adk and cookiecutter.session_type == "cloud_sql" %}
+    "sqladmin.googleapis.com",
+    "secretmanager.googleapis.com"
+{%- endif %}
   ]
 }
 

{src → agent_starter_pack}/base_template/deployment/terraform/dev/iam.tf

@@ -32,18 +32,18 @@ resource "google_project_iam_member" "default_compute_sa_storage_object_creator"
   depends_on = [resource.google_project_service.services]
 }
 
-{% if cookiecutter.deployment_target == 'cloud_run' %}
-resource "google_service_account" "cloud_run_app_sa" {
-  account_id   = "${var.project_name}-cr"
-  display_name = "${var.project_name} Cloud Run App Service Account"
+# Agent service account
+resource "google_service_account" "app_sa" {
+  account_id   = "${var.project_name}-app"
+  display_name = "${var.project_name} Agent Service Account"
   project      = var.dev_project_id
   depends_on   = [resource.google_project_service.services]
 }
 
-# Grant Cloud Run SA the required permissions to run the application
-resource "google_project_iam_member" "cloud_run_app_sa_roles" {
+# Grant application SA the required permissions to run the application
+resource "google_project_iam_member" "app_sa_roles" {
   for_each = {
-    for pair in setproduct(keys(local.project_ids), var.cloud_run_app_roles) :
+    for pair in setproduct(keys(local.project_ids), var.app_sa_roles) :
     join(",", pair) => {
       project = local.project_ids[pair[0]]
       role    = pair[1]
@@ -52,14 +52,15 @@ resource "google_project_iam_member" "cloud_run_app_sa_roles" {
 
   project    = each.value.project
   role       = each.value.role
-  member     = "serviceAccount:${google_service_account.cloud_run_app_sa.email}"
+  member     = "serviceAccount:${google_service_account.app_sa.email}"
   depends_on = [resource.google_project_service.services]
 }
-{% elif cookiecutter.deployment_target == 'agent_engine' %}
-# Grant required permissions to Vertex AI service account
+
+{% if cookiecutter.deployment_target == 'agent_engine' %}
+# Grant required permissions to Vertex AI service account for Agent Engine
 resource "google_project_iam_member" "vertex_ai_sa_permissions" {
   for_each = {
-    for pair in setproduct(keys(local.project_ids), var.agentengine_sa_roles) :
+    for pair in setproduct(keys(local.project_ids), var.app_sa_roles) :
     join(",", pair) => pair[1]
   }
 

{src → agent_starter_pack}/base_template/deployment/terraform/dev/providers.tf

@@ -17,7 +17,11 @@ terraform {
   required_providers {
     google = {
       source  = "hashicorp/google"
-      version = "< 7.0.0"
+      version = "~> 7.10.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "~> 3.7.0"
     }
   }
 }

{src → agent_starter_pack}/base_template/deployment/terraform/dev/storage.tf

@@ -18,7 +18,7 @@ provider "google" {
 }
 
 resource "google_storage_bucket" "logs_data_bucket" {
-  name                        = "${var.dev_project_id}-${var.project_name}-logs-data"
+  name                        = "${var.dev_project_id}-${var.project_name}-logs"
   location                    = var.region
   project                     = var.dev_project_id
   uniform_bucket_level_access = true

{src → agent_starter_pack}/base_template/deployment/terraform/dev/variables.tf

@@ -32,7 +32,7 @@ variable "region" {
 variable "telemetry_logs_filter" {
   type        = string
   description = "Log Sink filter for capturing telemetry data. Captures logs with the `traceloop.association.properties.log_type` attribute set to `tracing`."
-{%- if "adk" in cookiecutter.tags %}
+{%- if cookiecutter.is_adk %}
   default     = "labels.service_name=\"{{cookiecutter.project_name}}\" labels.type=\"agent_telemetry\""
 {%- else %}
   default     = "jsonPayload.attributes.\"traceloop.association.properties.log_type\"=\"tracing\" jsonPayload.resource.attributes.\"service.name\"=\"{{cookiecutter.project_name}}\""
@@ -45,23 +45,23 @@ variable "feedback_logs_filter" {
   default     = "jsonPayload.log_type=\"feedback\" jsonPayload.service_name=\"{{cookiecutter.project_name}}\""
 }
 
-{% if cookiecutter.deployment_target == 'cloud_run' %}
-variable "cloud_run_app_roles" {
-  description = "List of roles to assign to the Cloud Run app service account"
-{% elif cookiecutter.deployment_target == 'agent_engine' %}
-variable "agentengine_sa_roles" {
-  description = "List of roles to assign to the Agent Engine app service account"
-{% endif %}
+variable "app_sa_roles" {
+  description = "List of roles to assign to the application service account"
   type        = list(string)
   default = [
+
     "roles/aiplatform.user",
     "roles/discoveryengine.editor",
     "roles/logging.logWriter",
     "roles/cloudtrace.agent",
-    "roles/storage.admin"
+    "roles/storage.admin",
+    "roles/serviceusage.serviceUsageConsumer",
+{%- if cookiecutter.session_type == "cloud_sql" %}
+    "roles/cloudsql.client",
+    "roles/secretmanager.secretAccessor",
+{%- endif %}
   ]
 }
-
 {% if cookiecutter.data_ingestion %}
 
 variable "pipelines_roles" {

agent_starter_pack/base_template/deployment/terraform/dev/{% if cookiecutter.is_adk %}telemetry.tf{% else %}unused_telemetry.tf{% endif %}

@@ -0,0 +1,193 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# BigQuery dataset for telemetry external tables
+resource "google_bigquery_dataset" "telemetry_dataset" {
+  project       = var.dev_project_id
+  dataset_id    = replace("${var.project_name}_telemetry", "-", "_")
+  friendly_name = "${var.project_name} Telemetry"
+  location      = var.region
+  description   = "Dataset for GenAI telemetry data stored in GCS"
+  depends_on    = [google_project_service.services]
+}
+
+# BigQuery connection for accessing GCS telemetry data
+resource "google_bigquery_connection" "genai_telemetry_connection" {
+  project       = var.dev_project_id
+  location      = var.region
+  connection_id = "${var.project_name}-genai-telemetry"
+  friendly_name = "${var.project_name} GenAI Telemetry Connection"
+
+  cloud_resource {}
+
+  depends_on = [google_project_service.services]
+}
+
+# Wait for the BigQuery connection service account to propagate in IAM
+resource "time_sleep" "wait_for_bq_connection_sa" {
+  create_duration = "10s"
+
+  depends_on = [google_bigquery_connection.genai_telemetry_connection]
+}
+
+# Grant the BigQuery connection service account access to read from the logs bucket
+resource "google_storage_bucket_iam_member" "telemetry_connection_access" {
+  bucket = google_storage_bucket.logs_data_bucket.name
+  role   = "roles/storage.objectViewer"
+  member = "serviceAccount:${google_bigquery_connection.genai_telemetry_connection.cloud_resource[0].service_account_id}"
+
+  depends_on = [time_sleep.wait_for_bq_connection_sa]
+}
+
+# ====================================================================
+# Dedicated Cloud Logging Bucket for GenAI Telemetry
+# ====================================================================
+
+# Create a custom Cloud Logging bucket for GenAI telemetry logs with long-term retention
+resource "google_logging_project_bucket_config" "genai_telemetry_bucket" {
+  project          = var.dev_project_id
+  location         = var.region
+  bucket_id        = "${var.project_name}-genai-telemetry"
+  retention_days   = 3650  # 10 years retention (maximum allowed)
+  enable_analytics = true  # Required for linked datasets
+  description      = "Dedicated Cloud Logging bucket for ${var.project_name} GenAI telemetry with 10 year retention"
+
+  depends_on = [google_project_service.services]
+}
+
+# Log sink to route only GenAI telemetry logs to the dedicated bucket
+# Filter by bucket name in the GCS path (which includes project_name) to isolate this agent's logs
+resource "google_logging_project_sink" "genai_logs_to_bucket" {
+  name        = "${var.project_name}-genai-logs"
+  project     = var.dev_project_id
+  destination = "logging.googleapis.com/projects/${var.dev_project_id}/locations/${var.region}/buckets/${google_logging_project_bucket_config.genai_telemetry_bucket.bucket_id}"
+  filter      = "log_name=\"projects/${var.dev_project_id}/logs/gen_ai.client.inference.operation.details\" AND (labels.\"gen_ai.input.messages_ref\" =~ \".*${var.project_name}.*\" OR labels.\"gen_ai.output.messages_ref\" =~ \".*${var.project_name}.*\")"
+
+  unique_writer_identity = true
+  depends_on             = [google_logging_project_bucket_config.genai_telemetry_bucket]
+}
+
+# Create a linked dataset to the GenAI telemetry logs bucket for querying via BigQuery
+resource "google_logging_linked_dataset" "genai_logs_linked_dataset" {
+  link_id     = replace("${var.project_name}_genai_telemetry_logs", "-", "_")
+  bucket      = google_logging_project_bucket_config.genai_telemetry_bucket.bucket_id
+  description = "Linked dataset for ${var.project_name} GenAI telemetry Cloud Logging bucket"
+  location    = var.region
+  parent      = "projects/${var.dev_project_id}"
+
+  depends_on = [
+    google_logging_project_bucket_config.genai_telemetry_bucket,
+    google_logging_project_sink.genai_logs_to_bucket
+  ]
+}
+
+# Wait for linked dataset to fully propagate
+resource "time_sleep" "wait_for_linked_dataset" {
+  create_duration = "10s"
+
+  depends_on = [google_logging_linked_dataset.genai_logs_linked_dataset]
+}
+
+# ====================================================================
+# Feedback Logs to Cloud Logging Bucket
+# ====================================================================
+
+# Log sink for user feedback logs - routes to the same Cloud Logging bucket
+resource "google_logging_project_sink" "feedback_logs_to_bucket" {
+  name        = "${var.project_name}-feedback"
+  project     = var.dev_project_id
+  destination = "logging.googleapis.com/projects/${var.dev_project_id}/locations/${var.region}/buckets/${google_logging_project_bucket_config.genai_telemetry_bucket.bucket_id}"
+  filter      = var.feedback_logs_filter
+
+  unique_writer_identity = true
+  depends_on             = [google_logging_project_bucket_config.genai_telemetry_bucket]
+}
+
+# ====================================================================
+# Completions External Table (GCS-based)
+# ====================================================================
+
+# External table for completions data (messages/parts) stored in GCS
+resource "google_bigquery_table" "completions_external_table" {
+  project             = var.dev_project_id
+  dataset_id          = google_bigquery_dataset.telemetry_dataset.dataset_id
+  table_id            = "completions"
+  deletion_protection = false
+
+  external_data_configuration {
+    autodetect            = false
+    source_format         = "NEWLINE_DELIMITED_JSON"
+    source_uris           = ["gs://${google_storage_bucket.logs_data_bucket.name}/completions/*"]
+    connection_id         = google_bigquery_connection.genai_telemetry_connection.name
+    ignore_unknown_values = true
+    max_bad_records       = 1000
+  }
+
+  # Schema matching the ADK completions format
+  schema = jsonencode([
+    {
+      name = "parts"
+      type = "RECORD"
+      mode = "REPEATED"
+      fields = [
+        { name = "type", type = "STRING", mode = "NULLABLE" },
+        { name = "content", type = "STRING", mode = "NULLABLE" },
+        { name = "mime_type", type = "STRING", mode = "NULLABLE" },
+        { name = "uri", type = "STRING", mode = "NULLABLE" },
+        { name = "data", type = "BYTES", mode = "NULLABLE" },
+        { name = "id", type = "STRING", mode = "NULLABLE" },
+        { name = "name", type = "STRING", mode = "NULLABLE" },
+        { name = "arguments", type = "JSON", mode = "NULLABLE" },
+        { name = "response", type = "JSON", mode = "NULLABLE" }
+      ]
+    },
+    { name = "role", type = "STRING", mode = "NULLABLE" },
+    { name = "index", type = "INTEGER", mode = "NULLABLE" }
+  ])
+
+  depends_on = [
+    google_storage_bucket.logs_data_bucket,
+    google_bigquery_connection.genai_telemetry_connection,
+    google_storage_bucket_iam_member.telemetry_connection_access
+  ]
+}
+
+# ====================================================================
+# Completions View (Joins Logs with GCS Data)
+# ====================================================================
+
+# View that joins Cloud Logging data with GCS-stored completions data
+resource "google_bigquery_table" "completions_view" {
+  project             = var.dev_project_id
+  dataset_id          = google_bigquery_dataset.telemetry_dataset.dataset_id
+  table_id            = "completions_view"
+  description         = "View of GenAI completion logs joined with the GCS prompt/response external table"
+  deletion_protection = false
+
+  view {
+    query = templatefile("${path.module}/../sql/completions.sql", {
+      project_id                 = var.dev_project_id
+      dataset_id                 = google_bigquery_dataset.telemetry_dataset.dataset_id
+      completions_external_table = google_bigquery_table.completions_external_table.table_id
+      logs_link_id               = google_logging_linked_dataset.genai_logs_linked_dataset.link_id
+    })
+    use_legacy_sql = false
+  }
+
+  depends_on = [
+    google_logging_linked_dataset.genai_logs_linked_dataset,
+    google_bigquery_table.completions_external_table,
+    time_sleep.wait_for_linked_dataset
+  ]
+}