### Install and Run Generated Fullstack Agent Project

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Navigates into the newly created project directory, installs its dependencies, and starts the development servers.

```bash
cd my-fullstack-agent && make install && make dev
```

--------------------------------

### Install and Run Gemini Fullstack Agent

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Installs project dependencies and starts the development servers for the Gemini Fullstack Agent from the gemini-fullstack directory.

```bash
make install && make dev
```

--------------------------------

### Start Local Development Server

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Command to start the Next.js development server for local testing.

```bash
cd nextjs
npm run dev
```

--------------------------------

### Clone Gemini ADK Repository

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Clones the official ADK samples repository and navigates into the specific fullstack agent directory for setup.

```bash
git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents/gemini-fullstack
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Copies the example environment file and prompts the user to edit it with project-specific details, including the staging bucket.

```bash
cp app/.env.example app/.env
# Edit app/.env with your project details and staging bucket
```

--------------------------------

### Install Vercel CLI

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Installs the Vercel Command Line Interface globally using npm. This tool is recommended for managing Vercel deployments.

```bash
npm i -g vercel
```

--------------------------------

### Google Cloud Authentication and Project Setup

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Sets up authentication for Google Cloud services and configures the active project. These are prerequisites for deploying to Google Cloud.

```bash
gcloud auth application-default login
gcloud config set project your-project-id
```

--------------------------------

### Local Testing with ADK CLI

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Start a local web UI for testing your ADK agent before deployment. This command opens the UI at http://localhost:8000.

```bash
# Test locally first
adk web  # Opens web UI at http://localhost:8000
```

--------------------------------

### Local Testing Commands

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Commands to test the Next.js application locally, including building and starting the development server.

```bash
cd nextjs
npm run build
npm run start
```

--------------------------------

### Next.js Project Setup

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/README.md

Information about the Next.js project setup, including bootstrapping with create-next-app and using next/font for font optimization.

```javascript
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).

This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
```

--------------------------------

### Agent Workflow Phases and Tags

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Describes the two main phases of the agent's workflow and the tags used for planning and refinement. These tags guide the agent's actions and communication.

```apidoc
Agent Workflow:
  Phase 1: Plan & Refine (Human-in-the-Loop)
    - User provides a research topic.
    - Agent generates a high-level research plan.
    - User can approve or chat with the agent to modify the plan.
    - Research Plan Tags:
      - [RESEARCH]: Guides info gathering via search.
      - [DELIVERABLE]: Guides creation of final outputs (e.g., tables, reports).
    - Plan Refinement Tags:
      - [MODIFIED]: Goal was updated.
      - [NEW]: New goal added per user.
      - [IMPLIED]: Deliverable proactively added by AI.

  Phase 2: Execute Autonomous Research
    - Converts approved plan into a structured report outline.
    - Iterative Research & Critique Loop:
      - Search: Gathers information via web searches.
      - Critique: Evaluates findings for gaps or weaknesses.
      - Refine: Generates follow-up questions if weaknesses are found.
    - Compose Final Report: Writes a polished report with inline citations.
```

--------------------------------

### Create Project using uvx with Agent Starter Pack

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

An alternative method using uvx to create and set up a new project from the agent-starter-pack template without pre-installing the package.

```bash
uvx agent-starter-pack create my-fullstack-agent -a adk_gemini_fullstack
```

--------------------------------

### Quick Development Deployment

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Sets the Google Cloud project for development and builds the backend. This is an alternative for quick development iterations.

```bash
# Replace YOUR_DEV_PROJECT_ID with your actual Google Cloud Project ID
gcloud config set project YOUR_DEV_PROJECT_ID
make backend
```

--------------------------------

### Vercel Environment Variable Configuration Example

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Provides an example of how to configure environment variables within the Vercel dashboard or CLI for an Agent Engine backend. This includes project ID, reasoning engine ID, and location.

```bash
# Vercel Environment Variables
GOOGLE_CLOUD_PROJECT=my-ai-project-123456
REASONING_ENGINE_ID=abc123def456
GOOGLE_CLOUD_LOCATION=us-central1
```

--------------------------------

### Python Direct API Integration with Agent Engine

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Integrate directly with the Agent Engine API using the google-cloud-aiplatform library. This example demonstrates initializing the client and querying a deployed reasoning engine.

```python
from google.cloud import aiplatform

# Initialize the client
client = aiplatform.gapic.ReasoningEngineServiceClient()

# Query the deployed agent
response = client.query_reasoning_engine(
    name="projects/your-project-id/locations/us-central1/reasoningEngines/your-agent-id",
    input={"query": "Hello, agent!"}
)
```

--------------------------------

### Local Testing Console Output

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Example console output when running the Next.js application locally, showing the detected endpoint configuration.

```text
🔧 Endpoint Configuration:
  environment: cloud
  deploymentType: agent_engine
  backendUrl: https://us-central1-aiplatform.googleapis.com/v1/...
  agentEngineUrl: https://us-central1-aiplatform.googleapis.com/v1/...
```

--------------------------------

### Start Next.js Development Server

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/README.md

Commands to run the Next.js development server using npm, yarn, or pnpm. Opens the application at http://localhost:3000.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```

--------------------------------

### Test Local Next.js Application

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Commands to start a Next.js application locally and check the browser console for configuration output, verifying the connection and deployment type.

```bash
cd nextjs
npm run dev
```

--------------------------------

### Create Project from Agent Starter Pack Template

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Uses the agent-starter-pack to create a new, production-ready fullstack agent project, specifying the 'adk_gemini_fullstack' agent type.

```bash
# Create and activate a virtual environment
python -m venv .venv && source .venv/bin/activate # On Windows: .venv\Scripts\activate

# Install the starter pack and create your project
pip install --upgrade agent-starter-pack
agent-starter-pack create my-fullstack-agent -a adk_gemini_fullstack
```

--------------------------------

### Agent Code Structure: __init__.py

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Initializes the agent package by importing the agent definition from agent.py.

```python
from . import agent
```

--------------------------------

### Backend Connectivity Test

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Example cURL command to test connectivity to a backend API endpoint, sending a POST request with JSON data.

```bash
curl -X POST "YOUR_BACKEND_URL/api/test" \
  -H "Content-Type: application/json" \
  -d '{"message": "test"}'
```

--------------------------------

### Example Backend CORS Configuration

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Illustrative JavaScript code snippet showing how to configure allowed origins for Cross-Origin Resource Sharing (CORS) in a backend application.

```javascript
// Example backend CORS config
const allowedOrigins = [
  'https://your-app.vercel.app',
  'https://your-app-git-main.vercel.app',
  'https://your-app-preview.vercel.app'
];
```

--------------------------------

### Deploy Agent to Agent Engine

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Deploys the agent application to Agent Engine, a managed infrastructure service. This command handles the deployment process and returns an agent resource ID.

```bash
adk deploy agent_engine app
```

--------------------------------

### ADK CLI Deployment Commands

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Commands for deploying ADK agents using the ADK command-line interface. Supports deployment to Agent Engine and Cloud Run.

```APIDOC
ADK CLI Deployment Commands:

1. Deploy to Agent Engine:
   adk deploy agent_engine <agent_directory>
   - Simple deployment using configurations from .env file.
   - Example: adk deploy agent_engine app

   adk deploy agent_engine \
     --display_name="<Your Agent Name>" \
     --description="<Agent Description>" \
     <agent_directory>
   - Deploys with specified display name and description.
   - Optional parameters:
     --project: Override project from .env or gcloud default.
     --region: Override region from .env.

2. Deploy to Cloud Run (Advanced):
   adk deploy cloud_run \
     --project=<PROJECT_ID> \
     --region=<REGION> \
     --service_name=<SERVICE_NAME> \
     --app_name=<APP_NAME> \
     --with_ui \
     <agent_directory>
   - Deploys to Cloud Run for more control.
   - Required parameters:
     --project: Google Cloud project ID.
     --region: Google Cloud region.
     --service_name: Name for the Cloud Run service.
     --app_name: Name of the ADK application.
   - Optional parameter:
     --with_ui: Enables a web UI for the deployed agent.

3. Test Agent Locally:
   adk web
   - Starts a local web server to test the agent.

4. Google Cloud CLI Setup:
   gcloud auth application-default login
   - Authenticates your application with Google Cloud.

   gcloud config set project <PROJECT_ID>
   - Sets the default Google Cloud project for gcloud commands.

5. Environment Setup:
   cp app/.env.example app/.env
   - Copies the example environment file to be used for configuration.
   - Edit app/.env with project details and staging bucket.
```

--------------------------------

### Deploy to Vercel CLI

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Command to deploy the Next.js frontend to Vercel using the Vercel CLI.

```bash
cd nextjs
vercel --prod
```

--------------------------------

### Environment Variables Reference

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Comprehensive list of environment variables required or recommended for ADK fullstack deployments on Vercel, categorized by service and environment.

```APIDOC
Environment Variables:

Required for All Deployments:
  - GOOGLE_CLOUD_PROJECT: Your Google Cloud project ID. Example: `my-ai-project-123456`

Agent Engine Specific:
  - REASONING_ENGINE_ID: (Required) The Agent Engine reasoning engine ID.
  - GOOGLE_SERVICE_ACCOUNT_KEY_BASE64: (Required) Base64-encoded service account key for authentication.
  - GOOGLE_CLOUD_LOCATION: (Optional, Default: `us-central1`) Google Cloud region.
  - AGENT_ENGINE_ENDPOINT: (Optional, Default: Auto-constructed) Custom Agent Engine endpoint.

Cloud Run Specific:
  - CLOUD_RUN_SERVICE_URL: (Required) The URL of your Cloud Run service.
  - GOOGLE_CLOUD_LOCATION: (Optional, Default: `us-central1`) Google Cloud region.

Development Only:
  - BACKEND_URL: (Optional, Default: `http://127.0.0.1:8000`) Local backend URL.
  - NODE_ENV: (Optional, Default: -) Environment mode, used to enable debug logs.
```

--------------------------------

### Configure Environment Variables for AI Studio

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/README.md

Creates a .env file in the app directory to configure the agent to use a Google AI Studio API key, disabling Vertex AI usage.

```bash
echo "GOOGLE_GENAI_USE_VERTEXAI=FALSE" >> app/.env
echo "GOOGLE_API_KEY=YOUR_AI_STUDIO_API_KEY" >> app/.env
```

--------------------------------

### Vercel Environment Variables (Agent Engine)

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Example Vercel environment variables for a deployment targeting Agent Engine. These variables include the Google Cloud project, the reasoning engine ID, and the Agent Engine endpoint.

```bash
GOOGLE_CLOUD_PROJECT=my-ai-project-123456
REASONING_ENGINE_ID=abc123def456
AGENT_ENGINE_ENDPOINT=https://custom-ai-gateway.example.com/agent
```

--------------------------------

### Vercel Environment Variables (Cloud Run)

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Example Vercel environment variables for a deployment targeting Cloud Run. These variables define the Google Cloud project, the Cloud Run service URL, and the Google Cloud location.

```bash
GOOGLE_CLOUD_PROJECT=my-ai-project-123456
CLOUD_RUN_SERVICE_URL=https://my-agent-service-xyz789-uc.a.run.app
GOOGLE_CLOUD_LOCATION=us-central1
```

--------------------------------

### Vercel CLI Deployment Commands

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Commands to deploy applications using the Vercel CLI, including deploying to preview environments and production.

```APIDOC
Vercel CLI Deployment:

vercel
  - Deploys the project to a preview environment.
  - Useful for testing new features or branches.

vercel --prod --confirm
  - Deploys the project to the production environment.
  - `--prod` flag specifies production deployment.
  - `--confirm` flag bypasses the confirmation prompt.
```

--------------------------------

### Python SDK Deployment to Agent Engine

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Programmatically deploys an ADK agent to Agent Engine using the Vertex AI SDK. Dependencies are automatically read from pyproject.toml.

```python
from vertexai.preview.reasoning_engines import AdkApp
from google.adk.agents import Agent

# Assuming 'your_agent' is defined elsewhere, e.g., from agent.py
# from .agent import root_agent as your_agent

# Placeholder for agent definition if not imported
class MockAgent:
    pass
your_agent = MockAgent()

app = AdkApp(agent=your_agent)

# Deploy to Agent Engine
remote_agent = app.deploy(
    # Dependencies are automatically read from pyproject.toml
    display_name="Your Agent Name", 
    description="Agent description",
    env_vars={
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "GOOGLE_CLOUD_LOCATION": "us-central1",
        "GOOGLE_GENAI_USE_VERTEXAI": "True"
    }
)
```

--------------------------------

### Agent Code Structure: agent.py

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Defines the root agent with its name, model, description, and instructions. This is the core agent logic.

```python
from google.adk.agents import Agent

# Define your agent
root_agent = Agent(
    name="your_agent_name",
    model="gemini-2.5-flash", 
    description="Agent description",
    instruction="Agent instructions",
)
```

--------------------------------

### Deploy Next.js App via Vercel CLI

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Instructions for deploying a Next.js application to Vercel using the command-line interface. Includes logging in, navigating to the project directory, initiating the production deployment, and adding necessary environment variables.

```bash
vercel login
cd nextjs
vercel --prod

# For Agent Engine backend
vercel env add GOOGLE_CLOUD_PROJECT
vercel env add REASONING_ENGINE_ID
vercel env add GOOGLE_CLOUD_LOCATION

# Follow prompts to enter values
```

--------------------------------

### Local Frontend Environment Variables

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Configuration for the `.env.local` file in the Next.js project for local development. It includes project details, service account key, and location.

```bash
# nextjs/.env.local
GOOGLE_CLOUD_PROJECT=my-ai-project-123456
REASONING_ENGINE_ID=abc123def456
GOOGLE_SERVICE_ACCOUNT_KEY_BASE64=your-base64-encoded-key-here
GOOGLE_CLOUD_LOCATION=us-central1
NODE_ENV=development
```

--------------------------------

### Configure Local Environment Variables (.env.local)

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Sets up essential environment variables for local development of a Next.js application, including Google Cloud project details, service account key, and deployment configuration.

```bash
# nextjs/.env.local
GOOGLE_CLOUD_PROJECT=your-project-id
REASONING_ENGINE_ID=your-reasoning-engine-id
GOOGLE_SERVICE_ACCOUNT_KEY_BASE64=your-base64-encoded-key-here
GOOGLE_CLOUD_LOCATION=us-central1
NODE_ENV=development
```

--------------------------------

### Gemini API SSE Example (curl)

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/google-bug-report.md

An example using `curl` to demonstrate the correct Server-Sent Events (SSE) format returned by the Gemini API when using the `alt=sse` parameter. This serves as a comparison to the incorrect behavior observed with Agent Engine, highlighting the expected standard.

```bash
# Gemini API with alt=sse (works correctly)
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:streamGenerateContent?alt=sse&key={API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"parts":[{"text": "Hello"}]}]}'

# Returns proper SSE format:
# data: {"candidates":[{"content": {"parts": [{"text": "Hello"}]}}]}
```

--------------------------------

### Local Development Environment Variables

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Environment variables for connecting a Next.js frontend to a local backend. This includes the backend URL and an optional NODE_ENV for development logging.

```bash
# Local backend URL
BACKEND_URL=http://127.0.0.1:8000

# Optional (for development logging)
NODE_ENV=development
```

--------------------------------

### Deploy ADK Agent

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Command to deploy your ADK agent to Agent Engine. This involves navigating to the agent's directory and executing the 'adk deploy' command.

```bash
cd app
adk deploy agent_engine app
```

--------------------------------

### Agent Engine API Endpoint

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

The structure of the API endpoint for querying an Agent Engine, including project, location, and reasoning engine ID.

```APIDOC
Agent Engine Query Endpoint:

URL:
  https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/reasoningEngines/{id}:query

Description:
  This endpoint is used to send queries to a deployed Agent Engine.

Parameters:
  - {location}: The Google Cloud region where the reasoning engine is deployed (e.g., 'us-central1').
  - {project}: The Google Cloud project ID.
  - {id}: The unique identifier of the reasoning engine.

Example:
  https://us-central1-aiplatform.googleapis.com/v1/projects/my-ai-project-123456/locations/us-central1/reasoningEngines/abc123def456:query
```

--------------------------------

### Agent Engine Query API Endpoint

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

This documentation describes the endpoint for querying a deployed reasoning engine on Agent Engine. It details the request method, URL structure, authentication, headers, and the JSON payload for the input.

```APIDOC
POST https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/AGENT_ID:query

Description:
  Queries a deployed reasoning engine.

Authentication:
  Requires an OAuth 2.0 access token. Obtain via `gcloud auth print-access-token`.

Headers:
  - Authorization: Bearer YOUR_ACCESS_TOKEN
  - Content-Type: application/json

Request Body:
  {
    "input": {
      "query": "string" 
    }
  }
  - input: An object containing the query parameters for the agent.
    - query: The user's input or query string.

Response:
  The response structure depends on the agent's output. Typically includes the agent's reply.

Example:
  See 'Production Testing via Agent Engine REST API' snippet for a full curl example.
```

--------------------------------

### Frontend Endpoint Construction

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

TypeScript code illustrating how the frontend constructs API endpoints based on the detected backend type (Agent Engine, Cloud Run, or Local).

```typescript
// Agent Engine
https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/reasoningEngines/{id}:query

// Cloud Run
{CLOUD_RUN_SERVICE_URL}/api/endpoint

// Local
{BACKEND_URL}/api/endpoint
```

--------------------------------

### Python Backend Integration with ADK Agent

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Connect your Flask or FastAPI backend to a deployed ADK agent using its resource ID. This snippet shows how to initialize the AdkApp and define an API endpoint to query the agent.

```python
from vertexai.preview.reasoning_engines import AdkApp

# Connect to your deployed agent using the resource ID from deployment
agent_resource_id = "projects/your-project-id/locations/us-central1/reasoningEngines/your-agent-id"
app = AdkApp.get_agent(agent_id=agent_resource_id)

# Use in your API endpoints
@app.post("/chat")
async def chat(request):
    response = app.query(
        user_id=request.user_id,
        session_id=request.session_id,
        message=request.message
    )
    return response
```

--------------------------------

### Authenticate and Set Google Cloud Project (Bash)

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Authenticates your local environment with Google Cloud using `gcloud auth application-default login` and sets the default project using `gcloud config set project`. This ensures your CLI commands target the correct Google Cloud project.

```bash
# Authenticate with your Google account
gcloud auth application-default login

# Set your project as default
gcloud config set project YOUR-PROJECT-ID

# Verify your setup
gcloud config list
```

--------------------------------

### Production Testing via Agent Engine REST API

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Test your deployed agent using a curl command against the Agent Engine REST API. This requires authentication and specifies the agent's resource details.

```curl
# Test deployed agent via API
curl -X POST "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/AGENT_ID:query" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "input": {
    "query": "Hello, agent!"
  }
}'
```

--------------------------------

### Encode Service Account Key to Base64

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Demonstrates how to convert a Google Cloud service account JSON key file into a base64 encoded string using PowerShell and Node.js. This is crucial for securely storing the key in environment variables.

```powershell
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((Get-Content path/to/your-service-account-key.json -Raw)))
```

```javascript
const fs = require('fs');
const keyFile = fs.readFileSync('path/to/your-service-account-key.json', 'utf8');
const base64Key = Buffer.from(keyFile).toString('base64');
console.log(base64Key);
```

--------------------------------

### Enable Google Cloud APIs for Agent Engine Deployment (APIDOC)

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/ADK_DEPLOYMENT_GUIDE.md

Enables the necessary Google Cloud APIs required for deploying ADK agents with Vertex AI Agent Engine. These APIs are crucial for AI model operations, storage, container building, and deployment infrastructure.

```APIDOC
API Enablement:
  - Vertex AI API (aiplatform.googleapis.com): For AI models and Agent Engine.
  - Cloud Storage API (storage.googleapis.com): For staging deployment artifacts.
  - Cloud Build API (cloudbuild.googleapis.com): For building agent containers.
  - Cloud Run Admin API (run.googleapis.com): For deployment infrastructure.
  - Artifact Registry API (artifactregistry.googleapis.com): For container storage.

Action: Enable each API individually via the Google Cloud Console or gcloud CLI.
```

--------------------------------

### Cloud Run Backend Environment Variables

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Required and optional environment variables for connecting a Next.js frontend to a backend deployed on Google Cloud Run. These variables specify the Google Cloud project and the Cloud Run service URL.

```bash
# Google Cloud Configuration
GOOGLE_CLOUD_PROJECT=your-project-id
CLOUD_RUN_SERVICE_URL=https://your-service-abcdef-uc.a.run.app

# Optional (has defaults)
GOOGLE_CLOUD_LOCATION=us-central1
```

--------------------------------

### Agent Engine Backend Environment Variables

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Required and optional environment variables for connecting a Next.js frontend to an ADK Agent Engine backend deployed on Google Cloud. These variables configure project ID, reasoning engine, service account, and location.

```bash
# Google Cloud Configuration
GOOGLE_CLOUD_PROJECT=your-project-id
REASONING_ENGINE_ID=your-reasoning-engine-id
GOOGLE_SERVICE_ACCOUNT_KEY_BASE64=your-base64-encoded-service-account-key

# Optional (has defaults)
GOOGLE_CLOUD_LOCATION=us-central1

# Override the auto-constructed Agent Engine endpoint
AGENT_ENGINE_ENDPOINT=https://custom-agent-engine-endpoint
```

--------------------------------

### Convert Service Account Key to Base64

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/NEXTJS_VERCEL_DEPLOYMENT_GUIDE.md

Converts a Google Cloud service account JSON key file into a Base64 encoded string, suitable for use in environment variables. This is a common step for securely providing credentials.

```bash
# On macOS/Linux
cat path/to/your-service-account-key.json | base64
```

--------------------------------

### Configure Cloud Run Deployment Environment

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/README.md

Sets up environment variables for deploying to Cloud Run, including the service URL, Google Cloud project details, and production mode.

```bash
# Cloud Run Service URL
CLOUD_RUN_SERVICE_URL=https://your-service-url.a.run.app

# Google Cloud Configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

# Environment mode
NODE_ENV=production
```

--------------------------------

### Configure Local Development Environment

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/README.md

Sets up environment variables for local Next.js development, specifying the backend URL and development mode.

```bash
# Backend URL for local development
BACKEND_URL=http://127.0.0.1:8000

# Environment mode
NODE_ENV=development
```

--------------------------------

### Configuration System Overview

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/README.md

Details the configuration system within `/src/lib/config.ts`. It handles environment detection, dynamic endpoint configuration, authentication header management, and deployment-specific routing.

```javascript
// /src/lib/config.ts

// Environment detection (local, Agent Engine, Cloud Run)
// Dynamic endpoint configuration
// Authentication header management
// Deployment-specific routing

// Example structure (conceptual):
/*
const config = {
  backendUrl: process.env.BACKEND_URL || 'http://127.0.0.1:8000',
  environment: process.env.NODE_ENV || 'development',
  // ... other configurations
};
*/
```

--------------------------------

### Enable Debugging Output

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/README.md

Enables detailed logging for specific components like endpoints and the agent engine by setting debug flags.

```bash
DEBUG_ENDPOINTS=true
DEBUG_AGENT_ENGINE=true
```

--------------------------------

### Configure Agent Engine Deployment Environment

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/README.md

Configures environment variables for deploying to Agent Engine, including Google Cloud project details, reasoning engine ID, and production mode.

```bash
# Google Cloud Configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

# Agent Engine Configuration
REASONING_ENGINE_ID=your-reasoning-engine-id

# Optional: Direct Agent Engine endpoint URL
# AGENT_ENGINE_ENDPOINT=https://us-central1-aiplatform.googleapis.com/v1/projects/your-project-id/locations/us-central1/reasoningEngines/your-reasoning-engine-id

# Environment mode
NODE_ENV=production
```

--------------------------------

### API Routes for Backend Proxy

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/README.md

Defines the available API routes within the Next.js application that proxy requests to the Python backend. Each route specifies the HTTP method, path, and its corresponding backend proxy target.

```APIDOC
Session Management:
  POST /api/apps/app/users/[userId]/sessions/[sessionId]
    - Creates a new chat session.
    - Proxies to: {BACKEND_URL}/apps/app/users/{userId}/sessions/{sessionId}
    - Parameters:
      - userId: Identifier for the user.
      - sessionId: Identifier for the session.
    - Returns: Structured response indicating session creation status.

Goal Planning:
  POST /api/goal-planning
    - Main goal planning endpoint.
    - Proxies to: {BACKEND_URL}/run (for ADK backend)
    - Handles goal input and returns structured planning response.
    - Parameters:
      - goalInput: The input describing the goal.
    - Returns: Structured planning response.

Chat Streaming:
  POST /api/run_sse
    - Server-Sent Events endpoint for real-time chat.
    - Proxies to: {BACKEND_URL}/run_sse
    - Handles streaming responses from AI agents.
    - Parameters:
      - query: The user's chat query.
    - Returns: Stream of messages from the AI agent.
```

--------------------------------

### Configure Backend URL

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/nextjs/src/app/api/README.md

Sets the environment variable for the backend server URL. This configuration is crucial for the Next.js application to correctly proxy requests to the Python backend.

```bash
BACKEND_URL=http://127.0.0.1:8000
```

--------------------------------

### Test Agent Engine SSE Stream Query (JavaScript)

Source: https://github.com/bhancockio/adk-fullstack-deploy-tutorial/blob/main/google-bug-report.md

Demonstrates how to call the Agent Engine `streamQuery` endpoint with the `alt=sse` parameter using JavaScript and `google-auth-library`. It checks the `Content-Type` header and the format of the first received chunk to highlight the discrepancy between expected SSE and actual JSON fragments.

```javascript
const { GoogleAuth } = require("google-auth-library");

async function testAgentEngineSSE() {
  // Replace with your actual values
  const PROJECT = "your-project-id";
  const LOCATION = "us-central1";
  const REASONING_ENGINE_ID = "your-reasoning-engine-id";
  
  // Authenticate
  const auth = new GoogleAuth({
    scopes: ["https://www.googleapis.com/auth/cloud-platform"],
  });
  const accessToken = await auth.getAccessToken();

  // Test the streamQuery endpoint with alt=sse
  const url = `https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/reasoningEngines/${REASONING_ENGINE_ID}:streamQuery?alt=sse`;
  
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      class_method: "stream_query",
      input: {
        user_id: "test-user",
        session_id: "test-session",
        message: "Say hello"
      }
    })
  });

  console.log("Content-Type:", response.headers.get("content-type"));
  console.log("Expected: text/event-stream");
  console.log("Actual:", response.headers.get("content-type")); // Shows: application/json

  // Read first chunk to show format
  const reader = response.body?.getReader();
  const decoder = new TextDecoder();
  const { value } = await reader.read();
  const firstChunk = decoder.decode(value);
  
  console.log("\nFirst chunk:");
  console.log("Expected SSE format: data: {\"content\": ...}");
  console.log("Actual format:", firstChunk.substring(0, 100) + "..."); // Shows raw JSON
}

testAgentEngineSSE();

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.