google-adk 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

google/adk/cli/cli_tools_click.py

@@ -12,10 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import asyncio
 import collections
 from contextlib import asynccontextmanager
 from datetime import datetime
+import functools
 import logging
 import os
 import tempfile
@@ -58,6 +61,19 @@ class HelpfulCommand(click.Command):
   def __init__(self, *args, **kwargs):
     super().__init__(*args, **kwargs)
 
+  @staticmethod
+  def _format_missing_arg_error(click_exception):
+    """Format the missing argument error with uppercase parameter name.
+
+    Args:
+      click_exception: The MissingParameter exception from Click.
+
+    Returns:
+      str: Formatted error message with uppercase parameter name.
+    """
+    name = click_exception.param.name
+    return f"Missing required argument: {name.upper()}"
+
   def parse_args(self, ctx, args):
     """Override the parse_args method to show help text on error.
 
@@ -75,8 +91,10 @@ class HelpfulCommand(click.Command):
     try:
       return super().parse_args(ctx, args)
     except click.MissingParameter as exc:
+      error_message = self._format_missing_arg_error(exc)
+
       click.echo(ctx.get_help())
-      click.secho(f"\nError: {str(exc)}", fg="red", err=True)
+      click.secho(f"\nError: {error_message}", fg="red", err=True)
       ctx.exit(2)
 
 
@@ -84,6 +102,7 @@ logger = logging.getLogger("google_adk." + __name__)
 
 
 @click.group(context_settings={"max_content_width": 240})
+@click.version_option(version.__version__)
 def main():
   """Agent Development Kit CLI tools."""
   pass
@@ -398,57 +417,78 @@ def cli_eval(
       print(eval_result.model_dump_json(indent=2))
 
 
-@main.command("web")
-@click.option(
-    "--session_db_url",
-    help=(
-        """Optional. The database URL to store the session.
+def fast_api_common_options():
+  """Decorator to add common fast api options to click commands."""
 
-  - Use 'agentengine://<agent_engine_resource_id>' to connect to Agent Engine sessions.
+  def decorator(func):
+    @click.option(
+        "--session_db_url",
+        help=(
+            """Optional. The database URL to store the session.
+          - Use 'agentengine://<agent_engine_resource_id>' to connect to Agent Engine sessions.
+          - Use 'sqlite://<path_to_sqlite_file>' to connect to a SQLite DB.
+          - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs."""
+        ),
+    )
+    @click.option(
+        "--artifact_storage_uri",
+        type=str,
+        help=(
+            "Optional. The artifact storage URI to store the artifacts,"
+            " supported URIs: gs://<bucket name> for GCS artifact service."
+        ),
+        default=None,
+    )
+    @click.option(
+        "--host",
+        type=str,
+        help="Optional. The binding host of the server",
+        default="127.0.0.1",
+        show_default=True,
+    )
+    @click.option(
+        "--port",
+        type=int,
+        help="Optional. The port of the server",
+        default=8000,
+    )
+    @click.option(
+        "--allow_origins",
+        help="Optional. Any additional origins to allow for CORS.",
+        multiple=True,
+    )
+    @click.option(
+        "--log_level",
+        type=click.Choice(
+            ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+            case_sensitive=False,
+        ),
+        default="INFO",
+        help="Optional. Set the logging level",
+    )
+    @click.option(
+        "--trace_to_cloud",
+        is_flag=True,
+        show_default=True,
+        default=False,
+        help="Optional. Whether to enable cloud trace for telemetry.",
+    )
+    @click.option(
+        "--reload/--no-reload",
+        default=True,
+        help="Optional. Whether to enable auto reload for server.",
+    )
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+      return func(*args, **kwargs)
 
-  - Use 'sqlite://<path_to_sqlite_file>' to connect to a SQLite DB.
+    return wrapper
 
-  - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs."""
-    ),
-)
-@click.option(
-    "--host",
-    type=str,
-    help="Optional. The binding host of the server",
-    default="127.0.0.1",
-    show_default=True,
-)
-@click.option(
-    "--port",
-    type=int,
-    help="Optional. The port of the server",
-    default=8000,
-)
-@click.option(
-    "--allow_origins",
-    help="Optional. Any additional origins to allow for CORS.",
-    multiple=True,
-)
-@click.option(
-    "--log_level",
-    type=click.Choice(
-        ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], case_sensitive=False
-    ),
-    default="INFO",
-    help="Optional. Set the logging level",
-)
-@click.option(
-    "--trace_to_cloud",
-    is_flag=True,
-    show_default=True,
-    default=False,
-    help="Optional. Whether to enable cloud trace for telemetry.",
-)
-@click.option(
-    "--reload/--no-reload",
-    default=True,
-    help="Optional. Whether to enable auto reload for server.",
-)
+  return decorator
+
+
+@main.command("web")
+@fast_api_common_options()
 @click.argument(
     "agents_dir",
     type=click.Path(
@@ -459,6 +499,7 @@ def cli_eval(
 def cli_web(
     agents_dir: str,
     session_db_url: str = "",
+    artifact_storage_uri: Optional[str] = None,
     log_level: str = "INFO",
     allow_origins: Optional[list[str]] = None,
     host: str = "127.0.0.1",
@@ -502,6 +543,7 @@ def cli_web(
   app = get_fast_api_app(
       agents_dir=agents_dir,
       session_db_url=session_db_url,
+      artifact_storage_uri=artifact_storage_uri,
       allow_origins=allow_origins,
       web=True,
       trace_to_cloud=trace_to_cloud,
@@ -519,56 +561,6 @@ def cli_web(
 
 
 @main.command("api_server")
-@click.option(
-    "--session_db_url",
-    help=(
-        """Optional. The database URL to store the session.
-
-  - Use 'agentengine://<agent_engine_resource_id>' to connect to Agent Engine sessions.
-
-  - Use 'sqlite://<path_to_sqlite_file>' to connect to a SQLite DB.
-
-  - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs."""
-    ),
-)
-@click.option(
-    "--host",
-    type=str,
-    help="Optional. The binding host of the server",
-    default="127.0.0.1",
-    show_default=True,
-)
-@click.option(
-    "--port",
-    type=int,
-    help="Optional. The port of the server",
-    default=8000,
-)
-@click.option(
-    "--allow_origins",
-    help="Optional. Any additional origins to allow for CORS.",
-    multiple=True,
-)
-@click.option(
-    "--log_level",
-    type=click.Choice(
-        ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], case_sensitive=False
-    ),
-    default="INFO",
-    help="Optional. Set the logging level",
-)
-@click.option(
-    "--trace_to_cloud",
-    is_flag=True,
-    show_default=True,
-    default=False,
-    help="Optional. Whether to enable cloud trace for telemetry.",
-)
-@click.option(
-    "--reload/--no-reload",
-    default=True,
-    help="Optional. Whether to enable auto reload for server.",
-)
 # The directory of agents, where each sub-directory is a single agent.
 # By default, it is the current working directory
 @click.argument(
@@ -578,9 +570,11 @@ def cli_web(
     ),
     default=os.getcwd(),
 )
+@fast_api_common_options()
 def cli_api_server(
     agents_dir: str,
     session_db_url: str = "",
+    artifact_storage_uri: Optional[str] = None,
     log_level: str = "INFO",
     allow_origins: Optional[list[str]] = None,
     host: str = "127.0.0.1",
@@ -603,6 +597,7 @@ def cli_api_server(
       get_fast_api_app(
           agents_dir=agents_dir,
           session_db_url=session_db_url,
+          artifact_storage_uri=artifact_storage_uri,
           allow_origins=allow_origins,
           web=False,
           trace_to_cloud=trace_to_cloud,
@@ -706,6 +701,15 @@ def cli_api_server(
   - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs."""
     ),
 )
+@click.option(
+    "--artifact_storage_uri",
+    type=str,
+    help=(
+        "Optional. The artifact storage URI to store the artifacts, supported"
+        " URIs: gs://<bucket name> for GCS artifact service."
+    ),
+    default=None,
+)
 @click.argument(
     "agent",
     type=click.Path(
@@ -734,6 +738,7 @@ def cli_deploy_cloud_run(
     with_ui: bool,
     verbosity: str,
     session_db_url: str,
+    artifact_storage_uri: Optional[str],
     adk_version: str,
 ):
   """Deploys an agent to Cloud Run.
@@ -757,7 +762,131 @@ def cli_deploy_cloud_run(
         with_ui=with_ui,
         verbosity=verbosity,
         session_db_url=session_db_url,
+        artifact_storage_uri=artifact_storage_uri,
         adk_version=adk_version,
     )
   except Exception as e:
     click.secho(f"Deploy failed: {e}", fg="red", err=True)
+
+
+@deploy.command("agent_engine")
+@click.option(
+    "--project",
+    type=str,
+    help="Required. Google Cloud project to deploy the agent.",
+)
+@click.option(
+    "--region",
+    type=str,
+    help="Required. Google Cloud region to deploy the agent.",
+)
+@click.option(
+    "--staging_bucket",
+    type=str,
+    help="Required. GCS bucket for staging the deployment artifacts.",
+)
+@click.option(
+    "--trace_to_cloud",
+    type=bool,
+    is_flag=True,
+    show_default=True,
+    default=False,
+    help="Optional. Whether to enable Cloud Trace for Agent Engine.",
+)
+@click.option(
+    "--adk_app",
+    type=str,
+    default="agent_engine_app",
+    help=(
+        "Optional. Python file for defining the ADK application"
+        " (default: a file named agent_engine_app.py)"
+    ),
+)
+@click.option(
+    "--temp_folder",
+    type=str,
+    default=os.path.join(
+        tempfile.gettempdir(),
+        "agent_engine_deploy_src",
+        datetime.now().strftime("%Y%m%d_%H%M%S"),
+    ),
+    help=(
+        "Optional. Temp folder for the generated Agent Engine source files."
+        " If the folder already exists, its contents will be removed."
+        " (default: a timestamped folder in the system temp directory)."
+    ),
+)
+@click.option(
+    "--env_file",
+    type=str,
+    default="",
+    help=(
+        "Optional. The filepath to the `.env` file for environment variables."
+        " (default: the `.env` file in the `agent` directory, if any.)"
+    ),
+)
+@click.option(
+    "--requirements_file",
+    type=str,
+    default="",
+    help=(
+        "Optional. The filepath to the `requirements.txt` file to use."
+        " (default: the `requirements.txt` file in the `agent` directory, if"
+        " any.)"
+    ),
+)
+@click.argument(
+    "agent",
+    type=click.Path(
+        exists=True, dir_okay=True, file_okay=False, resolve_path=True
+    ),
+)
+def cli_deploy_agent_engine(
+    agent: str,
+    project: str,
+    region: str,
+    staging_bucket: str,
+    trace_to_cloud: bool,
+    adk_app: str,
+    temp_folder: str,
+    env_file: str,
+    requirements_file: str,
+):
+  """Deploys an agent to Agent Engine.
+
+  Args:
+    agent (str): Required. The path to the agent to be deloyed.
+    project (str): Required. Google Cloud project to deploy the agent.
+    region (str): Required. Google Cloud region to deploy the agent.
+    staging_bucket (str): Required. GCS bucket for staging the deployment
+      artifacts.
+    trace_to_cloud (bool): Required. Whether to enable Cloud Trace.
+    adk_app (str): Required. Python file for defining the ADK application.
+    temp_folder (str): Required. The folder for the generated Agent Engine
+      files. If the folder already exists, its contents will be replaced.
+    env_file (str): Required. The filepath to the `.env` file for environment
+      variables. If it is an empty string, the `.env` file in the `agent`
+      directory will be used if it exists.
+    requirements_file (str): Required. The filepath to the `requirements.txt`
+      file to use. If it is an empty string, the `requirements.txt` file in the
+      `agent` directory will be used if exists.
+
+  Example:
+
+    adk deploy agent_engine --project=[project] --region=[region]
+      --staging_bucket=[staging_bucket] path/to/my_agent
+  """
+  try:
+    cli_deploy.to_agent_engine(
+        agent_folder=agent,
+        project=project,
+        region=region,
+        staging_bucket=staging_bucket,
+        trace_to_cloud=trace_to_cloud,
+        adk_app=adk_app,
+        temp_folder=temp_folder,
+        env_file=env_file,
+        requirements_file=requirements_file,
+    )
+  except Exception as e:
+    click.secho(f"Deploy failed: {e}", fg="red", err=True)

google/adk/cli/fast_api.py

@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 from __future__ import annotations
 
 import asyncio
@@ -56,7 +55,9 @@ from ..agents.live_request_queue import LiveRequest
 from ..agents.live_request_queue import LiveRequestQueue
 from ..agents.llm_agent import Agent
 from ..agents.run_config import StreamingMode
+from ..artifacts.gcs_artifact_service import GcsArtifactService
 from ..artifacts.in_memory_artifact_service import InMemoryArtifactService
+from ..errors.not_found_error import NotFoundError
 from ..evaluation.eval_case import EvalCase
 from ..evaluation.eval_case import SessionInput
 from ..evaluation.eval_metrics import EvalMetric
@@ -98,7 +99,7 @@ class ApiServerSpanExporter(export.SpanExporter):
       if (
           span.name == "call_llm"
           or span.name == "send_data"
-          or span.name.startswith("tool_response")
+          or span.name.startswith("execute_tool")
       ):
         attributes = dict(span.attributes)
         attributes["trace_id"] = span.get_span_context().trace_id
@@ -193,6 +194,7 @@ def get_fast_api_app(
     *,
     agents_dir: str,
     session_db_url: str = "",
+    artifact_storage_uri: Optional[str] = None,
     allow_origins: Optional[list[str]] = None,
     web: bool,
     trace_to_cloud: bool = False,
@@ -251,13 +253,12 @@ def get_fast_api_app(
 
   runner_dict = {}
 
-  # Build the Artifact service
-  artifact_service = InMemoryArtifactService()
-  memory_service = InMemoryMemoryService()
-
   eval_sets_manager = LocalEvalSetsManager(agents_dir=agents_dir)
   eval_set_results_manager = LocalEvalSetResultsManager(agents_dir=agents_dir)
 
+  # Build the Memory service
+  memory_service = InMemoryMemoryService()
+
   # Build the Session service
   agent_engine_id = ""
   if session_db_url:
@@ -276,6 +277,18 @@ def get_fast_api_app(
   else:
     session_service = InMemorySessionService()
 
+  # Build the Artifact service
+  if artifact_storage_uri:
+    if artifact_storage_uri.startswith("gs://"):
+      gcs_bucket = artifact_storage_uri.split("://")[1]
+      artifact_service = GcsArtifactService(bucket_name=gcs_bucket)
+    else:
+      raise click.ClickException(
+          "Unsupported artifact storage URI: %s" % artifact_storage_uri
+      )
+  else:
+    artifact_service = InMemoryArtifactService()
+
   # initialize Agent Loader
   agent_loader = AgentLoader(agents_dir)
 
@@ -475,8 +488,66 @@ def get_fast_api_app(
     """Lists all evals in an eval set."""
     eval_set_data = eval_sets_manager.get_eval_set(app_name, eval_set_id)
 
+    if not eval_set_data:
+      raise HTTPException(
+          status_code=400, detail=f"Eval set `{eval_set_id}` not found."
+      )
+
     return sorted([x.eval_id for x in eval_set_data.eval_cases])
 
+  @app.get(
+      "/apps/{app_name}/eval_sets/{eval_set_id}/evals/{eval_case_id}",
+      response_model_exclude_none=True,
+  )
+  def get_eval(app_name: str, eval_set_id: str, eval_case_id: str) -> EvalCase:
+    """Gets an eval case in an eval set."""
+    eval_case_to_find = eval_sets_manager.get_eval_case(
+        app_name, eval_set_id, eval_case_id
+    )
+
+    if eval_case_to_find:
+      return eval_case_to_find
+
+    raise HTTPException(
+        status_code=404,
+        detail=f"Eval set `{eval_set_id}` or Eval `{eval_case_id}` not found.",
+    )
+
+  @app.put(
+      "/apps/{app_name}/eval_sets/{eval_set_id}/evals/{eval_case_id}",
+      response_model_exclude_none=True,
+  )
+  def update_eval(
+      app_name: str,
+      eval_set_id: str,
+      eval_case_id: str,
+      updated_eval_case: EvalCase,
+  ):
+    if updated_eval_case.eval_id and updated_eval_case.eval_id != eval_case_id:
+      raise HTTPException(
+          status_code=400,
+          detail=(
+              "Eval id in EvalCase should match the eval id in the API route."
+          ),
+      )
+
+    # Overwrite the value. We are either overwriting the same value or an empty
+    # field.
+    updated_eval_case.eval_id = eval_case_id
+    try:
+      eval_sets_manager.update_eval_case(
+          app_name, eval_set_id, updated_eval_case
+      )
+    except NotFoundError as nfe:
+      raise HTTPException(status_code=404, detail=str(nfe)) from nfe
+
+  @app.delete("/apps/{app_name}/eval_sets/{eval_set_id}/evals/{eval_case_id}")
+  def delete_eval(app_name: str, eval_set_id: str, eval_case_id: str):
+    try:
+      eval_sets_manager.delete_eval_case(app_name, eval_set_id, eval_case_id)
+    except NotFoundError as nfe:
+      raise HTTPException(status_code=404, detail=str(nfe)) from nfe
+
   @app.post(
       "/apps/{app_name}/eval_sets/{eval_set_id}/run_eval",
       response_model_exclude_none=True,
@@ -491,6 +562,11 @@ def get_fast_api_app(
     # run.
     eval_set = eval_sets_manager.get_eval_set(app_name, eval_set_id)
 
+    if not eval_set:
+      raise HTTPException(
+          status_code=400, detail=f"Eval set `{eval_set_id}` not found."
+      )
+
     if req.eval_ids:
       eval_cases = [e for e in eval_set.eval_cases if e.eval_id in req.eval_ids]
       eval_set_to_evals = {eval_set_id: eval_cases}
@@ -501,34 +577,38 @@ def get_fast_api_app(
     root_agent = agent_loader.load_agent(app_name)
     run_eval_results = []
     eval_case_results = []
-    async for eval_case_result in run_evals(
-        eval_set_to_evals,
-        root_agent,
-        getattr(root_agent, "reset_data", None),
-        req.eval_metrics,
-        session_service=session_service,
-        artifact_service=artifact_service,
-    ):
-      run_eval_results.append(
-          RunEvalResult(
-              app_name=app_name,
-              eval_set_file=eval_case_result.eval_set_file,
-              eval_set_id=eval_set_id,
-              eval_id=eval_case_result.eval_id,
-              final_eval_status=eval_case_result.final_eval_status,
-              eval_metric_results=eval_case_result.eval_metric_results,
-              overall_eval_metric_results=eval_case_result.overall_eval_metric_results,
-              eval_metric_result_per_invocation=eval_case_result.eval_metric_result_per_invocation,
-              user_id=eval_case_result.user_id,
-              session_id=eval_case_result.session_id,
-          )
-      )
-      eval_case_result.session_details = await session_service.get_session(
-          app_name=app_name,
-          user_id=eval_case_result.user_id,
-          session_id=eval_case_result.session_id,
-      )
-      eval_case_results.append(eval_case_result)
+    try:
+      async for eval_case_result in run_evals(
+          eval_set_to_evals,
+          root_agent,
+          getattr(root_agent, "reset_data", None),
+          req.eval_metrics,
+          session_service=session_service,
+          artifact_service=artifact_service,
+      ):
+        run_eval_results.append(
+            RunEvalResult(
+                app_name=app_name,
+                eval_set_file=eval_case_result.eval_set_file,
+                eval_set_id=eval_set_id,
+                eval_id=eval_case_result.eval_id,
+                final_eval_status=eval_case_result.final_eval_status,
+                eval_metric_results=eval_case_result.eval_metric_results,
+                overall_eval_metric_results=eval_case_result.overall_eval_metric_results,
+                eval_metric_result_per_invocation=eval_case_result.eval_metric_result_per_invocation,
+                user_id=eval_case_result.user_id,
+                session_id=eval_case_result.session_id,
+            )
+        )
+        eval_case_result.session_details = await session_service.get_session(
+            app_name=app_name,
+            user_id=eval_case_result.user_id,
+            session_id=eval_case_result.session_id,
+        )
+        eval_case_results.append(eval_case_result)
+    except ModuleNotFoundError as e:
+      logger.exception("%s", e)
+      raise HTTPException(status_code=400, detail=str(e)) from e
 
     eval_set_results_manager.save_eval_set_result(
         app_name, eval_set_id, eval_case_results
@@ -854,6 +934,11 @@ def get_fast_api_app(
     return runner
 
   if web:
+    import mimetypes
+
+    mimetypes.add_type("application/javascript", ".js", True)
+    mimetypes.add_type("text/javascript", ".js", True)
+
     BASE_DIR = Path(__file__).parent.resolve()
     ANGULAR_DIST_PATH = BASE_DIR / "browser"