diff --git a/docs/deploy/agent-engine.md b/docs/deploy/agent-engine.md index 1e44337f1..af2ae8345 100644 --- a/docs/deploy/agent-engine.md +++ b/docs/deploy/agent-engine.md @@ -13,6 +13,11 @@ instruction set for when you want to deploy an ADK project quickly, and a standard, step-by-step set of instructions for when you want to carefully manage deploying an agent to Agent Engine. +!!! example "Preview: Vertex AI in express mode" + If you don't have a Google Cloud project, you can try Agent Engine without cost using + [Vertex AI in Express mode](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview). + For details on using this feature, see the [Standard deployment](#standard-deployment) section. + ## Accelerated deployment This section describes how to perform a deployment using the @@ -40,7 +45,6 @@ see the and [Development guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/development-guide.html). - ### Prerequisites {#prerequisites-ad} You need the following resources configured to use this deployment path: @@ -229,30 +233,52 @@ deployment settings, or are modifying an existing deployment with Agent Engine. ### Prerequisites -These instructions assume you have already defined an ADK project. If you do not +These instructions assume you have already defined an ADK project and GCP project. If you do not have an ADK project, see the instructions for creating a test project in -[Define your agent](#define-your-agent). - -Before starting deployment procedure, ensure you have the following: - -1. **Google Cloud Project**: A Google Cloud project with the [Vertex AI API enabled](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com). - -2. **Authenticated gcloud CLI**: You need to be authenticated with Google Cloud. Run the following command in your terminal: - ```shell - gcloud auth application-default login - ``` - -3. **Google Cloud Storage (GCS) Bucket**: Agent Engine requires a GCS bucket to stage your agent's code and dependencies for deployment. If you don't have a bucket, create one by following the instructions [here](https://cloud.google.com/storage/docs/creating-buckets). - -4. **Python Environment**: A Python version between 3.9 and 3.13. - -5. **Install Vertex AI SDK** - - Agent Engine is part of the Vertex AI SDK for Python. For more information, you can review the [Agent Engine quickstart documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/quickstart). - - ```shell - pip install google-cloud-aiplatform[adk,agent_engines]>=1.111 - ``` +[Define your agent](#define-your-agent). + +!!! example "Preview: Vertex AI in express mode" + If you do not have an exising GCP project, you can try Agent Engine without cost using + [Vertex AI in Express mode](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview). + +=== "Google Cloud Project" + + Before starting deployment procedure, ensure you have the following: + + 1. **Google Cloud Project**: A Google Cloud project with the [Vertex AI API enabled](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com). + + 2. **Authenticated gcloud CLI**: You need to be authenticated with Google Cloud. Run the following command in your terminal: + ```shell + gcloud auth application-default login + ``` + + 3. **Google Cloud Storage (GCS) Bucket**: Agent Engine requires a GCS bucket to stage your agent's code and dependencies for deployment. If you don't have a bucket, create one by following the instructions [here](https://cloud.google.com/storage/docs/creating-buckets). + + 4. **Python Environment**: A Python version between 3.9 and 3.13. + + 5. **Install Vertex AI SDK** + + Agent Engine is part of the Vertex AI SDK for Python. For more information, you can review the [Agent Engine quickstart documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/quickstart). + + ```shell + pip install google-cloud-aiplatform[adk,agent_engines]>=1.111 + ``` + +=== "Vertex AI express mode" + + Before starting deployment procedure, ensure you have the following: + + 1. **API Key from Express Mode project**: Sign up for an Express Mode project with your gmail account following the [Express mode sign up](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview#eligibility). Get an API key from that project to use with Agent Engine! + + 2. **Python Environment**: A Python version between 3.9 and 3.13. + + 3. **Install Vertex AI SDK** + + Agent Engine is part of the Vertex AI SDK for Python. For more information, you can review the [Agent Engine quickstart documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/quickstart). + + ```shell + pip install google-cloud-aiplatform[adk,agent_engines]>=1.111 + ``` ### Define your agent {#define-your-agent} @@ -272,22 +298,40 @@ Next, initialize the Vertex AI SDK. This tells the SDK which Google Cloud projec !!! tip "For IDE Users" You can place this initialization code in a separate `deploy.py` script along with the deployment logic for the following steps: 3 through 6. -```python title="deploy.py" -import vertexai -from agent import root_agent # modify this if your agent is not in agent.py - -# TODO: Fill in these values for your project -PROJECT_ID = "your-gcp-project-id" -LOCATION = "us-central1" # For other options, see https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview#supported-regions -STAGING_BUCKET = "gs://your-gcs-bucket-name" - -# Initialize the Vertex AI SDK -vertexai.init( - project=PROJECT_ID, - location=LOCATION, - staging_bucket=STAGING_BUCKET, -) -``` +=== "Google Cloud Project" + + ```python title="deploy.py" + import vertexai + from agent import root_agent # modify this if your agent is not in agent.py + + # TODO: Fill in these values for your project + PROJECT_ID = "your-gcp-project-id" + LOCATION = "us-central1" # For other options, see https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview#supported-regions + STAGING_BUCKET = "gs://your-gcs-bucket-name" + + # Initialize the Vertex AI SDK + vertexai.init( + project=PROJECT_ID, + location=LOCATION, + staging_bucket=STAGING_BUCKET, + ) + ``` + +=== "Vertex AI express mode" + + ```python title="deploy.py" + import vertexai + from agent import root_agent # modify this if your agent is not in agent.py + + # TODO: Fill in these values for your api key + API_KEY = "your-express-mode-api-key" + + # Initialize the Vertex AI SDK + vertexai.init( + api_key=API_KEY, + ) + ``` + ### Prepare the agent for deployment @@ -418,6 +462,43 @@ This process packages your code, builds it into a container, and deploys it to t # Note: The PROJECT_NUMBER is different than the PROJECT_ID. ``` +=== "Vertex AI express mode" + + Vertex AI express mode supports both ADK CLI deployment and Python deployment. + + The following example deploy command uses the `multi_tool_agent` sample + code as the project to be deployed with express mode: + + ```shell + adk deploy agent_engine \ + --display_name="My Agent Name" \ + --api_key=your-api-key-here + /multi_tool_agent + ``` + + !!! tip + Make sure your main ADK agent definition (`root_agent`) is + discoverable when deploying your ADK project. + + This code block initiates the deployment from a Python script or notebook. + + ```python title="deploy.py" + from vertexai import agent_engines + + remote_app = agent_engines.create( + agent_engine=app, + requirements=[ + "google-cloud-aiplatform[adk,agent_engines]" + ] + ) + + print(f"Deployment finished!") + print(f"Resource Name: {remote_app.resource_name}") + # Resource Name: "projects/{PROJECT_NUMBER}/locations/{LOCATION}/reasoningEngines/{RESOURCE_ID}" + # Note: The PROJECT_NUMBER is different than the PROJECT_ID. + ``` + + #### Monitoring and verification * You can monitor the deployment status in the [Agent Engine UI](https://console.cloud.google.com/vertex-ai/agents/agent-engines) in the Google Cloud Console. @@ -447,6 +528,9 @@ You need the address and resource identification for your project (`PROJECT_ID`, `LOCATION`, `RESOURCE_ID`) to be able to test your deployment. You can use Cloud Console or the `gcloud` command line tool to find this information. +!!! note "Vertex AI express mode API key" + If you are using Vertex AI express mode, you can skip this step and use your API key. + To find your project information with Google Cloud Console: 1. In the Google Cloud Console, navigate to the Agent Engine page: @@ -494,11 +578,21 @@ To send a REST call get a response from deployed agent: - In a terminal window of your development environment, build a request and execute it: - ```shell - curl -X GET \ - -H "Authorization: Bearer $(gcloud auth print-access-token)" \ - "https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines" - ``` + === "Google Cloud Project" + + ```shell + curl -X GET \ + -H "Authorization: Bearer $(gcloud auth print-access-token)" \ + "https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines" + ``` + + === "Vertex AI express mode" + + ```shell + curl -X GET \ + -H "x-goog-api-key:YOUR-EXPRESS-MODE-API-KEY" \ + "https://aiplatform.googleapis.com/v1/reasoningEngines" + ``` If your deployment was successful, this request responds with a list of valid requests and expected data formats. @@ -519,13 +613,25 @@ To test interaction with the deployed agent via REST: 1. In a terminal window of your development environment, create a session by building a request using this template: - ```shell - curl \ - -H "Authorization: Bearer $(gcloud auth print-access-token)" \ - -H "Content-Type: application/json" \ - https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines/$(RESOURCE_ID):query \ - -d '{"class_method": "async_create_session", "input": {"user_id": "u_123"},}' - ``` + === "Google Cloud Project" + + ```shell + curl \ + -H "Authorization: Bearer $(gcloud auth print-access-token)" \ + -H "Content-Type: application/json" \ + https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines/$(RESOURCE_ID):query \ + -d '{"class_method": "async_create_session", "input": {"user_id": "u_123"},}' + ``` + + === "Vertex AI express mode" + + ```shell + curl \ + -H "x-goog-api-key:YOUR-EXPRESS-MODE-API-KEY" \ + -H "Content-Type: application/json" \ + https://aiplatform.googleapis.com/v1/reasoningEngines/$(RESOURCE_ID):query \ + -d '{"class_method": "async_create_session", "input": {"user_id": "u_123"},}' + ``` 1. In the response to the previous command, extract the created **Session ID** from the **id** field: @@ -547,19 +653,37 @@ To test interaction with the deployed agent via REST: your agent by building a request using this template and the Session ID created in the previous step: - ```shell - curl \ - -H "Authorization: Bearer $(gcloud auth print-access-token)" \ - -H "Content-Type: application/json" \ - https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines/$(RESOURCE_ID):streamQuery?alt=sse -d '{ - "class_method": "async_stream_query", - "input": { - "user_id": "u_123", - "session_id": "4857885913439920384", - "message": "Hey whats the weather in new york today?", - } - }' - ``` + === "Google Cloud Project" + + ```shell + curl \ + -H "Authorization: Bearer $(gcloud auth print-access-token)" \ + -H "Content-Type: application/json" \ + https://$(LOCATION)-aiplatform.googleapis.com/v1/projects/$(PROJECT_ID)/locations/$(LOCATION)/reasoningEngines/$(RESOURCE_ID):streamQuery?alt=sse -d '{ + "class_method": "async_stream_query", + "input": { + "user_id": "u_123", + "session_id": "4857885913439920384", + "message": "Hey whats the weather in new york today?", + } + }' + ``` + + === "Vertex AI express mode" + + ```shell + curl \ + -H "x-goog-api-key:YOUR-EXPRESS-MODE-API-KEY" \ + -H "Content-Type: application/json" \ + https://aiplatform.googleapis.com/v1/reasoningEngines/$(RESOURCE_ID):streamQuery?alt=sse -d '{ + "class_method": "async_stream_query", + "input": { + "user_id": "u_123", + "session_id": "4857885913439920384", + "message": "Hey whats the weather in new york today?", + } + }' + ``` This request should generate a response from your deployed agent code in JSON format. For more information about interacting with a deployed ADK agent in diff --git a/docs/sessions/express-mode.md b/docs/sessions/express-mode.md index ccbac7f1c..b9f9e2252 100644 --- a/docs/sessions/express-mode.md +++ b/docs/sessions/express-mode.md @@ -17,41 +17,42 @@ Once you sign up, get an [API key](https://cloud.google.com/vertex-ai/generative `Session` objects are children of an `AgentEngine`. When using Vertex AI Express Mode, we can create an empty `AgentEngine` parent to manage all of our `Session` and `Memory` objects. First, ensure that your environment variables are set correctly. For example, in Python: -```env title="weather_agent/.env" +```env title="agent/.env" GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_EXPRESS_MODE_API_KEY_HERE ``` -Next, we can create our Agent Engine instance. You can use the Gen AI SDK. +Next, we can create our Agent Engine instance. You can use the Vertex AI SDK. -=== "Gen AI SDK" +=== "Vertex AI SDK" - 1. Import Gen AI SDK. + 1. Import Vertex AI SDK. ```py - from google import genai + import vertexai + from vertexai import agent_engines ``` - 2. Set Vertex AI to be True, then use a `POST` request to create the Agent Engine + 2. Initialize the Vertex AI Client with your API key and create an agent engine instance. ```py # Create Agent Engine with Gen AI SDK - client = genai.Client(vertexai=True)._api_client - - response = client.request( - http_method='POST', - path=f'reasoningEngines', - request_dict={"displayName": "YOUR_AGENT_ENGINE_DISPLAY_NAME", "description": "YOUR_AGENT_ENGINE_DESCRIPTION"}, + client = vertexai.Client( + api_key="YOUR_API_KEY", ) - response + + agent_engine = client.agent_engines.create( + config={ + "display_name": "Demo Agent Engine", + "description": "Agent Engine for Session and Memory", + }) ``` 3. Replace `YOUR_AGENT_ENGINE_DISPLAY_NAME` and `YOUR_AGENT_ENGINE_DESCRIPTION` with your use case. - 4. Get the Agent Engine name and ID from the response + 4. Get the Agent Engine name and ID from the response to use with Memories and Sessions. ```py - APP_NAME = "/".join(response['name'].split("/")[:6]) - APP_ID = APP_NAME.split('/')[-1] + APP_ID = agent_engine.api_resource.name.split('/')[-1] ``` ## Managing Sessions with a `VertexAiSessionService` @@ -72,15 +73,15 @@ APP_ID = "your-reasoning-engine-id" # Project and location are not required when initializing with Vertex Express Mode session_service = VertexAiSessionService(agent_engine_id=APP_ID) # Use REASONING_ENGINE_APP_ID when calling service methods, e.g.: -# session = await session_service.create_session(app_name=REASONING_ENGINE_APP_ID, user_id= ...) +# session = await session_service.create_session(app_name=APP_ID, user_id= ...) ``` !!! info Session Service Quotas For Free Express Mode Projects, `VertexAiSessionService` has the following quota: - - 100 Session Entities - - 10,000 Event Entities + - 10 Create, delete, or update Vertex AI Agent Engine sessions per minute + - 30 Append event to Vertex AI Agent Engine sessions per minute ## Managing Memories with a `VertexAiMemoryBankService` @@ -92,7 +93,7 @@ instead initialize the memory object without any project or location. # Plus environment variable setup: # GOOGLE_GENAI_USE_VERTEXAI=TRUE # GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_EXPRESS_MODE_API_KEY_HERE -from google.adk.sessions import VertexAiMemoryBankService +from google.adk.memory import VertexAiMemoryBankService # The app_name used with this service should be the Reasoning Engine ID or name APP_ID = "your-reasoning-engine-id" @@ -107,7 +108,8 @@ memory_service = VertexAiMemoryBankService(agent_engine_id=APP_ID) For Free Express Mode Projects, `VertexAiMemoryBankService` has the following quota: - - 200 Memory Entities + - 10 Create, delete, or update Vertex AI Agent Engine memory resources per minute + - 10 Get, list, or retrieve from Vertex AI Agent Engine Memory Bank per minute ## Code Sample: Weather Agent with Session and Memory using Vertex AI Express Mode diff --git a/examples/python/notebooks/express-mode-weather-agent.ipynb b/examples/python/notebooks/express-mode-weather-agent.ipynb index 2f554977d..801eab98c 100644 --- a/examples/python/notebooks/express-mode-weather-agent.ipynb +++ b/examples/python/notebooks/express-mode-weather-agent.ipynb @@ -98,8 +98,8 @@ "outputs": [], "source": [ "# Gemini API Key (Get from Vertex Express Mode)\n", - "easygcp_api_key = \"INSERT_API_KEY\" #@param {type:\"string\"}\n", - "os.environ[\"GOOGLE_API_KEY\"] = easygcp_api_key\n", + "express_mode_api_key = \"YOUR-EXPRESS-MODE-API-KEY\" #@param {type:\"string\"}\n", + "os.environ[\"GOOGLE_API_KEY\"] = express_mode_api_key\n", "# Set vertex to true\n", "os.environ[\"GOOGLE_GENAI_USE_VERTEXAI\"] = \"True\"\n", "\n", @@ -127,10 +127,8 @@ "source": [ "# --- Define Model Constants for easier use ---\n", "\n", - "# Use an allowlisted model for EasyGCP, we will use gemini 2.0\n", - "MODEL_GEMINI_2_0_FLASH = \"gemini-2.0-flash-001\"\n", - "\n", - "print(\"\\nEnvironment configured.\")" + "# Use an allowlisted model for EasyGCP, we will use gemini 2.5\n", + "MODEL = \"gemini-2.5-flash-lite\"" ] }, { @@ -244,7 +242,7 @@ "\n", "weather_agent = Agent(\n", " name=\"weather_agent_v1\",\n", - " model=MODEL_GEMINI_2_0_FLASH,\n", + " model=MODEL,\n", " description=\"Provides weather information for specific cities.\",\n", " instruction=\"You are a helpful weather assistant. \"\n", " \"When the user asks for the weather in a specific city, \"\n", @@ -255,7 +253,7 @@ " tools=[get_weather, adk.tools.preload_memory_tool.PreloadMemoryTool()], # Pass the function directly\n", ")\n", "\n", - "print(f\"Agent '{weather_agent.name}' created using model '{MODEL_GEMINI_2_0_FLASH}'.\")" + "print(f\"Agent '{weather_agent.name}' created using model '{MODEL}'.\")" ] }, { @@ -280,18 +278,10 @@ "cell_type": "code", "source": [ "# @title Create the Agent Engine\n", - "from google import genai\n", - "import json\n", - "\n", - "# Create Agent Engine with GenAI SDK\n", - "client = genai.Client(vertexai = True)._api_client\n", - "string_response = client.request(\n", - " http_method='POST',\n", - " path=f'reasoningEngines',\n", - " request_dict={\"displayName\": \"Express-Mode-Agent-Engine\", \"description\": \"Test Agent Engine demo\"},\n", - " ).body\n", - "response = json.loads(string_response)\n", - "response" + "import vertexai\n", + "\n", + "client = vertexai.Client(api_key=express_mode_api_key)\n", + "agent_engine = client.agent_engines.create(config={\"display_name\": \"Test Agent Engine\", \"description\": \"My first Agent Engine\"})" ], "metadata": { "id": "goqjFK2SMNa4" @@ -302,7 +292,7 @@ { "cell_type": "code", "source": [ - "APP_NAME=\"/\".join(response['name'].split(\"/\")[:6])\n", + "APP_NAME=agent_engine.api_resource.name\n", "APP_NAME" ], "metadata": { @@ -344,9 +334,10 @@ "source": [ "# @title Create Our Initial Session\n", "\n", - "# Create Vertex AI Session through ADK\n", + "# Create Vertex AI Session through ADK to use locally\n", "session_service = VertexAiSessionService(agent_engine_id=APP_ID)\n", - "memory_service = VertexAiMemoryBankService(agent_engine_id=APP_ID)\n", + "\n", + "# Create Vertex AI Memory through ADK to use locally\n", "\n", "USER_ID = \"INSERT_USER_ID\" #@param {type:\"string\"}\n", "session = await session_service.create_session(app_name=APP_ID, user_id=USER_ID)\n", @@ -582,4 +573,4 @@ }, "nbformat": 4, "nbformat_minor": 0 -} \ No newline at end of file +}