Merge branch 'main' into UpdateGkeAgentDeployPreReqsDocumentation

Author: vicentefb

docs/agents/models.md

@@ -28,17 +28,18 @@ The following sections guide you through using these methods based on your needs
 
 ## Using Google Gemini Models
 
-This is the most direct way to use Google's flagship models within ADK.
+This section covers authenticating with Google's Gemini models, either through Google AI Studio for rapid development or Google Cloud Vertex AI for enterprise applications. This is the most direct way to use Google's flagship models within ADK.
+
+**Integration Method:** Once you are authenticated using one of the below methods, you can pass the model's identifier string directly to the
+`model` parameter of `LlmAgent`.
 
-**Integration Method:** Pass the model's identifier string directly to the
-`model` parameter of `LlmAgent` (or its alias, `Agent`).
 
-**Backend Options & Setup:**
+!!!tip 
 
-The `google-genai` library, used internally by ADK for Gemini, can connect
-through either Google AI Studio or Vertex AI.
+    The `google-genai` library, used internally by ADK for Gemini models, can connect
+    through either Google AI Studio or Vertex AI.
 
-!!!note "Model support for voice/video streaming"
+    **Model support for voice/video streaming**
 
     In order to use voice/video streaming in ADK, you will need to use Gemini
     models that support the Live API. You can find the **model ID(s)** that
@@ -49,51 +50,76 @@ through either Google AI Studio or Vertex AI.
 
 ### Google AI Studio
 
-* **Use Case:** Google AI Studio is the easiest way to get started with Gemini.
-  All you need is the [API key](https://aistudio.google.com/app/apikey). Best
-  for rapid prototyping and development.
-* **Setup:** Typically requires an API key:
-     * Set as an environment variable or 
-     * Passed during the model initialization via the `Client` (see example below)
+This is the simplest method and is recommended for getting started quickly.
 
-```shell
-export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
-export GOOGLE_GENAI_USE_VERTEXAI=FALSE
-```
+*   **Authentication Method:** API Key
+*   **Setup:**
+    1.  **Get an API key:** Obtain your key from [Google AI Studio](https://aistudio.google.com/apikey).
+    2.  **Set environment variables:** Create a `.env` file (Python) or `.properties` (Java) in your project's root directory and add the following lines. ADK will automatically load this file.
+
+        ```shell
+        export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
+        export GOOGLE_GENAI_USE_VERTEXAI=FALSE
+        ```
+
+        (or)
+        
+        Pass these variables during the model initialization via the `Client` (see example below).
 
 * **Models:** Find all available models on the
   [Google AI for Developers site](https://ai.google.dev/gemini-api/docs/models).
 
-### Vertex AI
+### Google Cloud Vertex AI
 
-* **Use Case:** Recommended for production applications, leveraging Google Cloud
-  infrastructure. Gemini on Vertex AI supports enterprise-grade features,
-  security, and compliance controls.
-* **Setup:**
-    * Authenticate using Application Default Credentials (ADC):
+For scalable and production-oriented use cases, Vertex AI is the recommended platform. Gemini on Vertex AI supports enterprise-grade features, security, and compliance controls. Based on your development environment and usecase, *choose one of the below methods to authenticate*.
 
-        ```shell
-        gcloud auth application-default login
-        ```
+**Pre-requisites:** A Google Cloud Project with [Vertex AI enabled](https://console.cloud.google.com/apis/enableflow;apiid=aiplatform.googleapis.com).
 
-    * Configure these variables either as environment variables or by providing them directly when initializing the Model.
-            
-         Set your Google Cloud project and location:
-    
-         ```shell
-         export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
-         export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # e.g., us-central1
-         ```     
-    
-         Explicitly tell the library to use Vertex AI:
+### **Method A: User Credentials (for Local Development)**
+
+1.  **Install the gcloud CLI:** Follow the official [installation instructions](https://cloud.google.com/sdk/docs/install).
+2.  **Log in using ADC:** This command opens a browser to authenticate your user account for local development.
+    ```bash
+    gcloud auth application-default login
+    ```
+3.  **Set environment variables:**
+    ```shell
+    export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+    export GOOGLE_CLOUD_LOCATION="YOUR_VERTEX_AI_LOCATION" # e.g., us-central1
+    ```     
 
-         ```shell
-         export GOOGLE_GENAI_USE_VERTEXAI=TRUE
-         ```
+    Explicitly tell the library to use Vertex AI:
 
-* **Models:** Find available model IDs in the
+    ```shell
+    export GOOGLE_GENAI_USE_VERTEXAI=TRUE
+    ```
+
+4. **Models:** Find available model IDs in the
   [Vertex AI documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models).
 
+### **Method B: Vertex AI Express Mode**
+[Vertex AI Express Mode](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) offers a simplified, API-key-based setup for rapid prototyping.
+
+1.  **Sign up for Express Mode** to get your API key.
+2.  **Set environment variables:**
+    ```shell
+    export GOOGLE_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"
+    export GOOGLE_GENAI_USE_VERTEXAI=TRUE
+    ```
+
+### **Method C: Service Account (for Production & Automation)**
+
+For deployed applications, a service account is the standard method.
+
+1.  [**Create a Service Account**](https://cloud.google.com/iam/docs/service-accounts-create#console) and grant it the `Vertex AI User` role.
+2.  **Provide credentials to your application:**
+    *   **On Google Cloud:** If you are running the agent in Cloud Run, GKE, VM or other Google Cloud services, the environment can automatically provide the service account credentials. You don't have to create a key file.
+    *   **Elsewhere:** Create a [service account key file](https://cloud.google.com/iam/docs/keys-create-delete#console) and point to it with an environment variable:
+        ```bash
+        export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
+        ```
+    Instead of the key file, you can also authenticate the service account using Workload Identity. But this is outside the scope of this guide.
+
 **Example:**
 
 === "Python"
@@ -157,6 +183,9 @@ export GOOGLE_GENAI_USE_VERTEXAI=FALSE
     // different availability or quota limitations.
     ```
 
+!!!warning "Secure Your Credentials"
+    Service account credentials or API keys are powerful credentials. Never expose them publicly. Use a secret manager like [Google Secret Manager](https://cloud.google.com/secret-manager) to store and access them securely in production.
+
 ## Using Anthropic models
 
 ![java_only](https://img.shields.io/badge/Supported_in-Java-orange){ title="This feature is currently available for Java. Python support for direct Anthropic API (non-Vertex) is via LiteLLM."}
@@ -753,4 +782,4 @@ Vertex AI.
             }
         }
     }
-    ```
+    ```

docs/deploy/agent-engine.md

@@ -26,7 +26,7 @@ Agent Engine is part of the Vertex AI SDK for Python. For more information, you
 ### Install the Vertex AI SDK
 
 ```shell
-pip install google-cloud-aiplatform[adk,agent_engines]
+pip install "google-cloud-aiplatform[adk,agent_engines]" cloudpickle
 ```
 
 !!!info
@@ -148,15 +148,19 @@ remote_app = agent_engines.create(
 )
 ```
 
-This step may take several minutes to finish. Each deployed agent has a unique identifier. You can run the following command to get the resource_name identifier for your deployed agent:
+This step may take several minutes to finish.
+
+You can check and monitor the deployment of your ADK agent on the [Agent Engine UI](https://console.cloud.google.com/vertex-ai/agents/agent-engines) on Google Cloud.
+
+Each deployed agent has a unique identifier. You can run the following command to get the resource_name identifier for your deployed agent:
 
 ```python
 remote_app.resource_name
 ```
 
 The response should look like the following string:
 
-```
+```shell
 f"projects/{PROJECT_NUMBER}/locations/{LOCATION}/reasoningEngines/{RESOURCE_ID}"
 ```
 
@@ -218,7 +222,7 @@ Expected output for `stream_query` (remote):
 {'parts': [{'text': 'The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit).'}], 'role': 'model'}
 ```
 
-
+## Using the Agent Engine UI
 
 ## Clean up
 
@@ -231,3 +235,5 @@ remote_app.delete(force=True)
 ```
 
 `force=True` will also delete any child resources that were generated from the deployed agent, such as sessions.
+
+You can also delete your deployed agent via the [Agent Engine UI](https://console.cloud.google.com/vertex-ai/agents/agent-engines) on Google Cloud.

docs/get-started/quickstart.md

@@ -133,10 +133,14 @@ application entirely on your machine and is recommended for internal development
 
 Your agent's ability to understand user requests and generate responses is
 powered by a Large Language Model (LLM). Your agent needs to make secure calls
-to this external LLM service, which requires authentication credentials. Without
+to this external LLM service, which **requires authentication credentials**. Without
 valid authentication, the LLM service will deny the agent's requests, and the
 agent will be unable to function.
 
+!!!tip "Model Authentication guide"
+    For a detailed guide on authenticating to different models, see the [Authentication guide](../agents/models.md#google-ai-studio).
+    This is a critical step to ensure your agent can make calls to the LLM service.
+
 === "Gemini - Google AI Studio"
     1. Get an API key from [Google AI Studio](https://aistudio.google.com/apikey).
     2. When using Python, open the **`.env`** file located inside (`multi_tool_agent/`)
@@ -157,17 +161,10 @@ agent will be unable to function.
     3. Replace `PASTE_YOUR_ACTUAL_API_KEY_HERE` with your actual `API KEY`.
 
 === "Gemini - Google Cloud Vertex AI"
-    1. You need an existing
-    [Google Cloud](https://cloud.google.com/?e=48754805&hl=en) account and a
-    project.
-        * Set up a
-          [Google Cloud project](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstarts/quickstart-multimodal#setup-gcp)
-        * Set up the
-          [gcloud CLI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstarts/quickstart-multimodal#setup-local)
-        * Authenticate to Google Cloud, from the terminal by running
-          `gcloud auth login`.
-        * [Enable the Vertex AI API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com).
-    2. When using Python, open the **`.env`** file located inside (`multi_tool_agent/`). Copy-paste
+    1. Set up a [Google Cloud project](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstarts/quickstart-multimodal#setup-gcp) and [enable the Vertex AI API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com).
+    2. Set up the [gcloud CLI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstarts/quickstart-multimodal#setup-local).
+    3. Authenticate to Google Cloud from the terminal by running `gcloud auth login`.
+    4. When using Python, open the **`.env`** file located inside (`multi_tool_agent/`). Copy-paste
     the following code and update the project ID and location.
 
         ```env title="multi_tool_agent/.env"
@@ -222,6 +219,17 @@ agent will be unable to function.
     There are multiple ways to interact with your agent:
 
     === "Dev UI (adk web)"
+
+        !!! success "Authentication Setup for Vertex AI Users"
+            If you selected **"Gemini - Google Cloud Vertex AI"** in the previous step, you must authenticate with Google Cloud before launching the dev UI.
+            
+            Run this command and follow the prompts:
+            ```bash
+            gcloud auth application-default login
+            ```
+            
+            **Note:** Skip this step if you're using "Gemini - Google AI Studio".
+
         Run the following command to launch the **dev UI**.
 
         ```shell

docs/observability/weave.md

@@ -0,0 +1,127 @@
+# Agent Observability with Weave by WandB
+
+[Weave by Weights & Biases (WandB)](https://weave-docs.wandb.ai/) provides a powerful platform for logging and visualizing model calls. By integrating Google ADK with Weave, you can track and analyze your agent's performance and behavior using OpenTelemetry (OTEL) traces.
+
+## Prerequisites
+
+1. Sign up for an account at [WandB](https://wandb.ai).
+
+2. Obtain your API key from [WandB Authorize](https://wandb.ai/authorize).
+
+3. Configure your environment with the required API keys:
+
+   ```bash
+   export WANDB_API_KEY=<your-wandb-api-key>
+   export GOOGLE_API_KEY=<your-google-api-key>
+   ```
+
+## Install Dependencies
+
+Ensure you have the necessary packages installed:
+
+```bash
+pip install google-adk opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
+```
+
+## Sending Traces to Weave
+
+This example demonstrates how to configure OpenTelemetry to send Google ADK traces to Weave.
+
+```python
+# math_agent/agent.py
+
+import base64
+import os
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk import trace as trace_sdk
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry import trace
+
+from google.adk.agents import LlmAgent
+from google.adk.tools import FunctionTool
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Configure Weave endpoint and authentication
+WANDB_BASE_URL = "https://trace.wandb.ai"
+PROJECT_ID = "your-entity/your-project"  # e.g., "teamid/projectid"
+OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"
+
+# Set up authentication
+WANDB_API_KEY = os.getenv("WANDB_API_KEY")
+AUTH = base64.b64encode(f"api:{WANDB_API_KEY}".encode()).decode()
+
+OTEL_EXPORTER_OTLP_HEADERS = {
+    "Authorization": f"Basic {AUTH}",
+    "project_id": PROJECT_ID,
+}
+
+# Create the OTLP span exporter with endpoint and headers
+exporter = OTLPSpanExporter(
+    endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
+    headers=OTEL_EXPORTER_OTLP_HEADERS,
+)
+
+# Create a tracer provider and add the exporter
+tracer_provider = trace_sdk.TracerProvider()
+tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))
+
+# Set the global tracer provider BEFORE importing/using ADK
+trace.set_tracer_provider(tracer_provider)
+
+# Define a simple tool for demonstration
+def calculator(a: float, b: float) -> str:
+    """Add two numbers and return the result.
+
+    Args:
+        a: First number
+        b: Second number
+
+    Returns:
+        The sum of a and b
+    """
+    return str(a + b)
+
+calculator_tool = FunctionTool(func=calculator)
+
+# Create an LLM agent
+root_agent = LlmAgent(
+    name="MathAgent",
+    model="gemini-2.0-flash-exp",
+    instruction=(
+        "You are a helpful assistant that can do math. "
+        "When asked a math problem, use the calculator tool to solve it."
+    ),
+    tools=[calculator_tool],
+)
+```
+
+## View Traces in Weave dashboard
+
+Once the agent runs, all its traces are logged to the corresponding project on [the Weave dashboard](https://wandb.ai/home).
+
+![Traces in Weave](https://wandb.github.io/weave-public-assets/google-adk/traces-overview.png)
+
+You can view a timeline of calls that your ADK agent made during execution -
+
+![Timeline view](https://wandb.github.io/weave-public-assets/google-adk/adk-weave-timeline.gif)
+
+
+## Notes
+
+- **Environment Variables**: Ensure your environment variables are correctly set for both WandB and Google API keys.
+- **Project Configuration**: Replace `<your-entity>/<your-project>` with your actual WandB entity and project name.
+- **Entity Name**: You can find your entity name by visiting your [WandB dashboard](https://wandb.ai/home) and checking the **Teams** field in the left sidebar.
+- **Tracer Provider**: It's critical to set the global tracer provider before using any ADK components to ensure proper tracing.
+
+By following these steps, you can effectively integrate Google ADK with Weave, enabling comprehensive logging and visualization of your AI agents' model calls, tool invocations, and reasoning processes.
+
+## Resources
+
+- **[Send OpenTelemetry Traces to Weave](https://weave-docs.wandb.ai/guides/tracking/otel)** - Comprehensive guide on configuring OTEL with Weave, including authentication and advanced configuration options.
+
+- **[Navigate the Trace View](https://weave-docs.wandb.ai/guides/tracking/trace-tree)** - Learn how to effectively analyze and debug your traces in the Weave UI, including understanding trace hierarchies and span details.
+
+- **[Weave Integrations](https://weave-docs.wandb.ai/guides/integrations/)** - Explore other framework integrations and see how Weave can work with your entire AI stack.