agent-starter-pack 0.16.0__py3-none-any.whl → 0.17.1__py3-none-any.whl

agent_starter_pack/deployment_targets/agent_engine/deployment/terraform/{% if not cookiecutter.is_adk_live %}service.tf{% else %}unused_service.tf{% endif %}

@@ -0,0 +1,82 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Get project information to access the project number
+data "google_project" "project" {
+  for_each = local.deploy_project_ids
+
+  project_id = local.deploy_project_ids[each.key]
+}
+
+resource "google_vertex_ai_reasoning_engine" "app_staging" {
+  display_name = var.project_name
+  description  = "Agent deployed via Terraform"
+  region       = var.region
+  project      = var.staging_project_id
+
+  spec {
+    service_account = google_service_account.app_sa["staging"].email
+
+    package_spec {
+      # IMPORTANT: This Python version must match the version used in CI/CD pipelines
+      # for pickling compatibility. Mismatched versions will cause deserialization errors.
+      python_version        = "3.12"
+      pickle_object_gcs_uri = "gs://agent-starter-pack/dummy/agent_engine.pkl"
+      dependency_files_gcs_uri = "gs://agent-starter-pack/dummy/dependencies.tar.gz"
+      requirements_gcs_uri  = "gs://agent-starter-pack/dummy/requirements.txt"
+    }
+  }
+
+  # This lifecycle block prevents Terraform from overwriting the spec when it's
+  # updated by Agent Engine deployments outside of Terraform (e.g., via CI/CD pipelines)
+  lifecycle {
+    ignore_changes = [
+      spec,
+    ]
+  }
+
+  # Make dependencies conditional to avoid errors.
+  depends_on = [google_project_service.deploy_project_services]
+}
+
+resource "google_vertex_ai_reasoning_engine" "app_prod" {
+  display_name = var.project_name
+  description  = "Agent deployed via Terraform"
+  region       = var.region
+  project      = var.prod_project_id
+
+  spec {
+    service_account = google_service_account.app_sa["prod"].email
+
+    package_spec {
+      # IMPORTANT: This Python version must match the version used in CI/CD pipelines
+      # for pickling compatibility. Mismatched versions will cause deserialization errors.
+      python_version        = "3.12"
+      pickle_object_gcs_uri = "gs://agent-starter-pack/dummy/agent_engine.pkl"
+      dependency_files_gcs_uri = "gs://agent-starter-pack/dummy/dependencies.tar.gz"
+      requirements_gcs_uri  = "gs://agent-starter-pack/dummy/requirements.txt"
+    }
+  }
+
+  # This lifecycle block prevents Terraform from overwriting the spec when it's
+  # updated by Agent Engine deployments outside of Terraform (e.g., via CI/CD pipelines)
+  lifecycle {
+    ignore_changes = [
+      spec,
+    ]
+  }
+
+  # Make dependencies conditional to avoid errors.
+  depends_on = [google_project_service.deploy_project_services]
+}

{src → agent_starter_pack}/deployment_targets/agent_engine/{{cookiecutter.agent_directory}}/agent_engine_app.py

@@ -239,6 +239,16 @@ class AgentEngineApp:
     default=None,
     help="Service account email to use for the agent engine",
 )
+@click.option(
+    "--staging-bucket-uri",
+    default=None,
+    help="GCS bucket URI for staging files (defaults to gs://{project}-agent-engine)",
+)
+@click.option(
+    "--artifacts-bucket-name",
+    default=None,
+    help="GCS bucket name for artifacts (defaults to gs://{project}-agent-engine)",
+)
 def deploy_agent_engine_app(
     project: str | None,
     location: str,
@@ -247,13 +257,31 @@ def deploy_agent_engine_app(
     extra_packages: tuple[str, ...],
     set_env_vars: str | None,
     service_account: str | None,
+    staging_bucket_uri: str | None,
+    artifacts_bucket_name: str | None,
 ) -> AgentEngine:
     """Deploy the agent engine app to Vertex AI."""
+
+    logging.basicConfig(level=logging.INFO)
+
     # Parse environment variables if provided
     env_vars = parse_env_vars(set_env_vars)
 
     if not project:
         _, project = google.auth.default()
+    if not staging_bucket_uri:
+        staging_bucket_uri = f"gs://{project}-agent-engine"
+    if not artifacts_bucket_name:
+        artifacts_bucket_name = f"gs://{project}-agent-engine"
+
+{%- if "adk" in cookiecutter.tags %}
+    create_bucket_if_not_exists(
+        bucket_name=artifacts_bucket_name, project=project, location=location
+    )
+{%- endif %}
+    create_bucket_if_not_exists(
+        bucket_name=staging_bucket_uri, project=project, location=location
+    )
 
     print("""
     ╔═══════════════════════════════════════════════════════════╗
@@ -263,18 +291,7 @@ def deploy_agent_engine_app(
     ╚═══════════════════════════════════════════════════════════╝
     """)
 
-    logging.basicConfig(level=logging.INFO)
     extra_packages_list = list(extra_packages)
-    staging_bucket_uri = f"gs://{project}-agent-engine"
-{%- if "adk" in cookiecutter.tags %}
-    artifacts_bucket_name = f"{project}-{{cookiecutter.project_name}}-logs"
-    create_bucket_if_not_exists(
-        bucket_name=artifacts_bucket_name, project=project, location=location
-    )
-{%- endif %}
-    create_bucket_if_not_exists(
-        bucket_name=staging_bucket_uri, project=project, location=location
-    )
 
     # Initialize vertexai client
     client = vertexai.Client(
@@ -318,6 +335,7 @@ def deploy_agent_engine_app(
         requirements=requirements,
         staging_bucket=staging_bucket_uri,
         labels=labels,
+        gcs_dir_name=agent_name,
 {%- if cookiecutter.is_adk_live %}
         agent_server_mode=AgentServerMode.EXPERIMENTAL,  # Enable bidi streaming
         resource_limits={"cpu": "4", "memory": "8Gi"},

{src → agent_starter_pack}/deployment_targets/agent_engine/{{cookiecutter.agent_directory}}/utils/deployment.py

@@ -76,14 +76,19 @@ def print_deployment_success(
     console_url = f"https://console.cloud.google.com/vertex-ai/agents/locations/{location}/agent-engines/{agent_engine_id}?project={project}"
 
 {%- if cookiecutter.is_adk %}
-    print(
 {%- if cookiecutter.is_adk_live %}
-        f"\n✅ Deployment successful! Run your agent with: `make playground-remote`"
+    print("\n✅ Deployment successful! Run your agent with: `make playground-remote`")
 {%- else %}
-        f"\n✅ Deployment successful! Test your agent: notebooks/adk_app_testing.ipynb"
-{%- endif %}
-        f"\n📊 View in console: {console_url}\n"
+    print(
+        "\n✅ Deployment successful! Test your agent: notebooks/adk_app_testing.ipynb"
     )
+{%- endif %}
+    service_account = remote_agent.api_resource.spec.service_account
+    print(f"Service Account: {service_account}")
+    print(f"\n📊 View in console: {console_url}\n")
 {%- else %}
-    print(f"\n✅ Deployment successful!\n📊 View in console: {console_url}\n")
+    print("\n✅ Deployment successful!")
+    service_account = remote_agent.api_resource.spec.service_account
+    print(f"Service Account: {service_account}")
+    print(f"\n📊 View in console: {console_url}\n")
 {%- endif %}

{src → agent_starter_pack}/deployment_targets/agent_engine/{{cookiecutter.agent_directory}}/utils/{% if cookiecutter.is_adk_live %}expose_app.py{% else %}unused_expose_app.py{% endif %}

@@ -17,7 +17,7 @@ import json
 import logging
 from collections.abc import Callable
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
 import backoff
 import google.auth
@@ -30,9 +30,6 @@ from google.cloud import logging as google_cloud_logging
 from pydantic import BaseModel
 from websockets.exceptions import ConnectionClosedError
 
-from ..agent import root_agent
-from ..agent_engine_app import AgentEngineApp
-
 app = FastAPI()
 app.add_middleware(
     CORSMiddleware,
@@ -56,28 +53,36 @@ logging_client = google_cloud_logging.Client()
 logger = logging_client.logger(__name__)
 logging.basicConfig(level=logging.INFO)
 
-# Global configuration for agent engine mode
-USE_REMOTE_AGENT = False
-REMOTE_AGENT_ENGINE_ID = None
-PROJECT_ID = None
-LOCATION = "us-central1"
-LOCAL_AGENT_CALLABLE = None
+# Initialize default configuration
+app.state.config = {
+    "use_remote_agent": False,
+    "remote_agent_engine_id": None,
+    "project_id": None,
+    "location": "us-central1",
+    "local_agent_path": "..agent.root_agent",
+    "agent_engine_class_path": "..agent_engine_app.AgentEngineApp",
+}
 
 
 class WebSocketToQueueAdapter:
     """Adapter to convert WebSocket messages to an asyncio Queue for the agent engine."""
 
     def __init__(
-        self, websocket: WebSocket, agent_engine: AgentEngineApp | None = None
+        self,
+        websocket: WebSocket,
+        agent_engine: Any = None,
+        remote_config: dict[str, Any] | None = None,
     ):
         """Initialize the adapter.
 
         Args:
             websocket: The client websocket connection
-            agent_engine: The agent engine instance (None if using remote)
+            agent_engine: The agent engine instance with bidi_stream_query method (None if using remote)
+            remote_config: Remote agent engine configuration (project_id, location, remote_agent_engine_id)
         """
         self.websocket = websocket
         self.agent_engine = agent_engine
+        self.remote_config = remote_config
         self.input_queue: asyncio.Queue[dict] = asyncio.Queue()
         self.first_message = True
 
@@ -170,20 +175,29 @@ class WebSocketToQueueAdapter:
             else:
                 # Remote agent engine mode
                 # Don't send setupComplete until remote connection is established
-                await self.run_remote_agent_engine()
+                assert self.remote_config is not None, (
+                    "remote_config must be set for remote mode"
+                )
+                await self.run_remote_agent_engine(
+                    project_id=self.remote_config["project_id"],
+                    location=self.remote_config["location"],
+                    remote_agent_engine_id=self.remote_config["remote_agent_engine_id"],
+                )
         except Exception as e:
             logging.error(f"Error in agent engine: {e}")
             await self.websocket.send_json({"error": str(e)})
 
-    async def run_remote_agent_engine(self) -> None:
+    async def run_remote_agent_engine(
+        self, project_id: str, location: str, remote_agent_engine_id: str
+    ) -> None:
         """Run the remote agent engine connection."""
         client = vertexai.Client(
-            project=PROJECT_ID,
-            location=LOCATION,
+            project=project_id,
+            location=location,
         )
 
         async with client.aio.live.agent_engines.connect(
-            agent_engine=REMOTE_AGENT_ENGINE_ID,
+            agent_engine=remote_agent_engine_id,
             config={"class_method": "bidi_stream_query"},
         ) as session:
             # Send setupComplete only after remote connection is established
@@ -230,11 +244,30 @@ class WebSocketToQueueAdapter:
             )
 
 
-def get_connect_and_run_callable(websocket: WebSocket) -> Callable:
+def _dynamic_import(path: str) -> Any:
+    """Dynamically import an object from a given path.
+
+    Args:
+        path: Python import path (e.g., '..agent.root_agent')
+
+    Returns:
+        The imported object
+    """
+    import importlib
+
+    module_path, object_name = path.rsplit(".", 1)
+    module = importlib.import_module(module_path, package=__package__)
+    return getattr(module, object_name)
+
+
+def get_connect_and_run_callable(
+    websocket: WebSocket, config: dict[str, Any]
+) -> Callable:
     """Create a callable that handles agent engine connection with retry logic.
 
     Args:
         websocket: The client websocket connection
+        config: Configuration dict with agent engine settings
 
     Returns:
         Callable: An async function that establishes and manages the agent engine connection
@@ -251,18 +284,28 @@ def get_connect_and_run_callable(websocket: WebSocket) -> Callable:
         backoff.expo, ConnectionClosedError, max_tries=10, on_backoff=on_backoff
     )
     async def connect_and_run() -> None:
-        if USE_REMOTE_AGENT:
+        if config["use_remote_agent"]:
             # Remote agent engine mode
-            logging.info(f"Connecting to remote agent engine: {REMOTE_AGENT_ENGINE_ID}")
-            adapter = WebSocketToQueueAdapter(websocket, agent_engine=None)
+            logging.info(
+                f"Connecting to remote agent engine: {config['remote_agent_engine_id']}"
+            )
+            remote_config = {
+                "project_id": config["project_id"],
+                "location": config["location"],
+                "remote_agent_engine_id": config["remote_agent_engine_id"],
+            }
+            adapter = WebSocketToQueueAdapter(
+                websocket, agent_engine=None, remote_config=remote_config
+            )
         else:
             # Local agent engine mode
-            agent_callable = (
-                LOCAL_AGENT_CALLABLE if LOCAL_AGENT_CALLABLE is not None else root_agent
-            )
+            # Dynamically import agent and engine class
+            agent_callable = _dynamic_import(config["local_agent_path"])
             logging.info(
                 f"Starting local agent engine with callable: {agent_callable.__name__ if hasattr(agent_callable, '__name__') else agent_callable}"
             )
+
+            AgentEngineApp = _dynamic_import(config["agent_engine_class_path"])
             agent_engine = AgentEngineApp(agent=agent_callable)
             adapter = WebSocketToQueueAdapter(websocket, agent_engine)
 
@@ -279,7 +322,7 @@ def get_connect_and_run_callable(websocket: WebSocket) -> Callable:
 async def websocket_endpoint(websocket: WebSocket) -> None:
     """Handle new websocket connections."""
     await websocket.accept()
-    connect_and_run = get_connect_and_run_callable(websocket)
+    connect_and_run = get_connect_and_run_callable(websocket, app.state.config)
     await connect_and_run()
 
 
@@ -370,7 +413,14 @@ if __name__ == "__main__":
     parser.add_argument(
         "--local-agent",
         type=str,
-        help="Python path to local agent callable (e.g., 'app.agent.root_agent'). Defaults to root_agent",
+        default="..agent.root_agent",
+        help="Python path to local agent callable (e.g., 'app.agent.root_agent')",
+    )
+    parser.add_argument(
+        "--agent-engine-class",
+        type=str,
+        default="..agent_engine_app.AgentEngineApp",
+        help="Python path to agent engine class",
     )
     parser.add_argument(
         "--port",
@@ -387,8 +437,18 @@ if __name__ == "__main__":
 
     args = parser.parse_args()
 
+    # Initialize configuration
+    config: dict[str, Any] = {
+        "use_remote_agent": False,
+        "remote_agent_engine_id": None,
+        "project_id": None,
+        "location": "us-central1",
+        "local_agent_path": args.local_agent,
+        "agent_engine_class_path": args.agent_engine_class,
+    }
+
     if args.mode == "remote":
-        USE_REMOTE_AGENT = True
+        config["use_remote_agent"] = True
 
         # Try to load from deployment_metadata.json if remote-id not provided
         if not args.remote_id:
@@ -398,8 +458,10 @@ if __name__ == "__main__":
             if deployment_metadata_path.exists():
                 with open(deployment_metadata_path) as f:
                     metadata = json.load(f)
-                    REMOTE_AGENT_ENGINE_ID = metadata.get("remote_agent_engine_id")
-                    if not REMOTE_AGENT_ENGINE_ID:
+                    config["remote_agent_engine_id"] = metadata.get(
+                        "remote_agent_engine_id"
+                    )
+                    if not config["remote_agent_engine_id"]:
                         parser.error(
                             "No remote_agent_engine_id found in deployment_metadata.json"
                         )
@@ -409,7 +471,7 @@ if __name__ == "__main__":
                     "--remote-id is required when deployment_metadata.json is not found"
                 )
         else:
-            REMOTE_AGENT_ENGINE_ID = args.remote_id
+            config["remote_agent_engine_id"] = args.remote_id
 
         # Extract project ID from remote agent engine ID if not provided
         if not args.project_id:
@@ -418,12 +480,12 @@ if __name__ == "__main__":
 
             match = re.match(
                 r"projects/([^/]+)/locations/([^/]+)/reasoningEngines/",
-                REMOTE_AGENT_ENGINE_ID,
+                config["remote_agent_engine_id"],
             )
             if match:
-                PROJECT_ID = match.group(1)
+                config["project_id"] = match.group(1)
                 extracted_location = match.group(2)
-                LOCATION = (
+                config["location"] = (
                     args.location
                     if args.location != "us-central1"
                     else extracted_location
@@ -432,30 +494,27 @@ if __name__ == "__main__":
             else:
                 # Fall back to google.auth.default()
                 try:
-                    _, PROJECT_ID = google.auth.default()
-                    LOCATION = args.location
-                    print(f"Using default project ID from google.auth: {PROJECT_ID}")
+                    _, config["project_id"] = google.auth.default()
+                    config["location"] = args.location
+                    print(
+                        f"Using default project ID from google.auth: {config['project_id']}"
+                    )
                 except Exception as e:
                     parser.error(f"Could not determine project ID: {e}")
         else:
-            PROJECT_ID = args.project_id
-            LOCATION = args.location
+            config["project_id"] = args.project_id
+            config["location"] = args.location
 
         print("Starting server in REMOTE mode:")
-        print(f"  Remote Agent Engine ID: {REMOTE_AGENT_ENGINE_ID}")
-        print(f"  Project ID: {PROJECT_ID}")
-        print(f"  Location: {LOCATION}")
+        print(f"  Remote Agent Engine ID: {config['remote_agent_engine_id']}")
+        print(f"  Project ID: {config['project_id']}")
+        print(f"  Location: {config['location']}")
     else:
         print("Starting server in LOCAL mode")
-        if args.local_agent:
-            # Dynamically import the agent callable
-            import importlib
-
-            module_path, callable_name = args.local_agent.rsplit(".", 1)
-            module = importlib.import_module(module_path)
-            LOCAL_AGENT_CALLABLE = getattr(module, callable_name)
-            print(f"  Using custom agent: {args.local_agent}")
-        else:
-            print("  Using default agent: root_agent")
+        print(f"  Using agent: {config['local_agent_path']}")
+        print(f"  Using agent engine class: {config['agent_engine_class_path']}")
+
+    # Store configuration in app state
+    app.state.config = config
 
     uvicorn.run(app, host=args.host, port=args.port)

{src → agent_starter_pack}/deployment_targets/cloud_run/{{cookiecutter.agent_directory}}/server.py

@@ -19,6 +19,7 @@ from collections.abc import Callable
 from pathlib import Path
 
 import backoff
+import google.auth
 from fastapi import FastAPI, HTTPException, WebSocket
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse
@@ -29,10 +30,13 @@ from google.adk.memory.in_memory_memory_service import InMemoryMemoryService
 from google.adk.runners import Runner
 from google.adk.sessions.in_memory_session_service import InMemorySessionService
 from google.cloud import logging as google_cloud_logging
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider, export
 from vertexai.agent_engines import _utils
 from websockets.exceptions import ConnectionClosedError
 
 from .agent import root_agent
+from .utils.tracing import CloudTraceLoggingSpanExporter
 from .utils.typing import Feedback
 
 app = FastAPI()
@@ -58,6 +62,14 @@ logging_client = google_cloud_logging.Client()
 logger = logging_client.logger(__name__)
 logging.basicConfig(level=logging.INFO)
 
+_, project_id = google.auth.default()
+provider = TracerProvider()
+processor = export.BatchSpanProcessor(
+    CloudTraceLoggingSpanExporter(project_id=project_id)
+)
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
 
 # Initialize ADK services
 session_service = InMemorySessionService()

{src → agent_starter_pack}/resources/docs/adk-cheatsheet.md

@@ -1464,8 +1464,8 @@ if __name__ == "__main__":
 
 For detailed specifications of all classes, methods, and commands, refer to the official reference documentation.
 
-*   [Python API Reference](./api-reference/python/index.html)
-*   [Java API Reference](./api-reference/java/index.html)
-*   [CLI Reference](./api-reference/cli/index.html)
-*   [REST API Reference](./api-reference/rest/index.md)
-*   [Agent Config YAML Reference](./api-reference/agentconfig/index.html)
+*   [Python API Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/python)
+*   [Java API Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/java)
+*   [CLI Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/cli)
+*   [REST API Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/rest)
+*   [Agent Config YAML Reference](https://github.com/google/adk-docs/tree/main/docs/api-reference/agentconfig)