botWebWars/botagent_gear/SETUP.md

Google Cloud Vertex AI Setup Guide

This guide walks you through setting up Google Cloud authentication and Vertex AI access for botagent_gear.

Since you have not authenticated to a Google Cloud project yet and have not created a key, choose the method that best fits your workflow below.

---

Quick Navigation

• Option 1: Google Cloud CLI & User Authentication (Recommended)
• Option 2: Service Account Key (Headless / Automated Servers)
• Option 3: Gemini API Key (Fastest Setup via Google AI Studio)
• Verification & Troubleshooting

---

Prerequisites

• A Google Cloud account (Google Cloud Free Tier includes $300 in credits).
• A Google Cloud Project (or permission to create one).

---

Option 1: Google Cloud CLI & User Authentication (Recommended)

This is the standard, interactive developer workflow using the Google Cloud CLI (gcloud).

Step 1: Install gcloud (if not installed)

Check if gcloud is installed:

gcloud --version

If not installed, install it following Google Cloud SDK Installation (or on Debian/Ubuntu: sudo apt-get install google-cloud-cli).

Step 2: Log into your Google Cloud account

gcloud auth login

A browser window will open asking you to sign in with your Google account.

Step 3: Set or Create your Project

List existing projects:

gcloud projects list

If you already have a project, set it as active:

gcloud config set project YOUR_PROJECT_ID

Or create a brand new project:

gcloud projects create my-botwebwars-project --name="botWebWars Project"
gcloud config set project my-botwebwars-project

(Ensure billing is enabled for your project in the Google Cloud Console Billing section.)

Step 4: Enable the Vertex AI API

Run:

gcloud services enable aiplatform.googleapis.com

Step 5: Authorize Application Default Credentials (ADC)

This allows Python scripts and SDKs to authenticate automatically:

gcloud auth application-default login

Follow the browser prompt to grant access.

Step 6: Set Environment Variables (Optional but convenient)

Add to your ~/.bashrc or run in your terminal:

export VERTEX_PROJECT_ID=$(gcloud config get-value project)
export VERTEX_LOCATION="us-central1"
export VERTEX_MODEL="gemini-2.5-flash"

---

Option 2: Service Account Key (Headless / Automated Servers)

If running in a Docker container, CI/CD pipeline, or remote VM without a web browser, use a Service Account:

Step 1: Create a Service Account

export PROJECT_ID=$(gcloud config get-value project)

gcloud iam service-accounts create botwebwars-agent \
    --display-name="botWebWars Vertex AI Agent"

Step 2: Grant the Vertex AI User role

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:botwebwars-agent@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

Step 3: Create and Download the Key File

mkdir -p ~/.gcp
gcloud iam service-accounts keys create ~/.gcp/vertex-key.json \
    --iam-account="botwebwars-agent@${PROJECT_ID}.iam.gserviceaccount.com"

Step 4: Point to the Key File

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcp/vertex-key.json"
export VERTEX_PROJECT_ID="$PROJECT_ID"
export VERTEX_LOCATION="us-central1"

---

Option 3: Gemini API Key (Fastest Setup via Google AI Studio)

If you prefer using an API key without configuring GCP IAM roles or OAuth tokens:

1. Go to Google AI Studio.
2. Click Create API Key.
3. Copy your API key.
4. Export the key:

   export GEMINI_API_KEY="YOUR_API_KEY_HERE"
   

The botagent_gear agent will detect GEMINI_API_KEY and interact with Gemini directly.

---

Verification & Troubleshooting

1. Test your credentials

You can quickly verify that Vertex AI accepts your credentials:

python3 -c "
import subprocess, requests, json, os

token = os.getenv('VERTEX_ACCESS_TOKEN') or subprocess.check_output(['gcloud', 'auth', 'print-access-token'], text=True).strip()
project = os.getenv('VERTEX_PROJECT_ID') or subprocess.check_output(['gcloud', 'config', 'get-value', 'project'], text=True).strip()
location = os.getenv('VERTEX_LOCATION', 'us-central1')
model = os.getenv('VERTEX_MODEL', 'gemini-2.5-flash')

url = f'https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent'
headers = {'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'}
payload = {'contents': [{'role': 'user', 'parts': [{'text': 'Hello Gemini'}]}]}

res = requests.post(url, headers=headers, json=payload, timeout=20)
print('Status:', res.status_code)
if res.status_code == 200:
    print('Vertex AI connection successful! Candidate:', res.json()['candidates'][0]['content']['parts'][0]['text'].strip())
else:
    print('Error response:', res.text)
"

2. Common Errors

Error	Cause	Solution
403 PermissionDenied: Vertex AI API has not been used...	API is disabled	Run gcloud services enable aiplatform.googleapis.com
401 Unauthorized / Token expired	Token expired or invalid	Re-run gcloud auth application-default login or refresh gcloud auth login
404 Publisher model ... not found	Region does not have the model	Default to us-central1, us-east4, or check model name (gemini-2.5-flash, gemini-1.5-flash)
No Google Cloud project ID detected	Project is not set	Run gcloud config set project <PROJECT_ID> or export VERTEX_PROJECT_ID

Once setup is complete, proceed to INSTALL.md and README.md to install dependencies and run your agent!