fix(auth): update model authentication info (#516)

* fix(auth): update model authentication info

* add cloudpickle dependency to AE

* update link

* Update models.md

Author: Sita04

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

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"

mkdocs.yml

@@ -128,7 +128,7 @@ nav:
       - Parallel agents: agents/workflow-agents/parallel-agents.md
     - Custom agents: agents/custom-agents.md
     - Multi-agent systems: agents/multi-agents.md
-    - Models: agents/models.md
+    - Models & Authentication: agents/models.md
   - Tools:
     - tools/index.md
     - Function tools: tools/function-tools.md