feat: Add ApigeeLlm as a model that let's ADK Agent developers to connect with an Apigee proxy

PiperOrigin-RevId: 824712152

Author: google-genai-bot

contributing/samples/hello_world_apigeellm/.env-sample

@@ -0,0 +1,8 @@
+# This is a sample .env file.
+# Copy this file to .env and replace the placeholder values with your actual credentials.
+
+# Your Google API key for accessing Gemini models.
+GOOGLE_API_KEY="your-google-api-key"
+
+# The URL of your Apigee proxy.
+APIGEE_PROXY_URL="https://your-apigee-proxy.net/basepath"

contributing/samples/hello_world_apigeellm/README.md

@@ -0,0 +1,84 @@
+# Hello World with Apigee LLM
+
+This sample demonstrates how to use the Agent Development Kit (ADK) with an LLM fronted by an Apigee proxy. It showcases the flexibility of the `ApigeeLlm` class in configuring the target LLM provider (Gemini or Vertex AI) and API version through the model string.
+
+## Setup
+
+Before running the sample, you need to configure your environment with the necessary credentials.
+
+1.  **Create a `.env` file:**
+    Copy the sample environment file to a new file named `.env` in the same directory.
+    ```bash
+    cp .env-sample .env
+    ```
+
+2.  **Set Environment Variables:**
+    Open the `.env` file and provide values for the following variables:
+
+    -   `GOOGLE_API_KEY`: Your API key for the Google AI services (Gemini).
+    -   `APIGEE_PROXY_URL`: The full URL of your Apigee proxy endpoint.
+
+    Example `.env` file:
+    ```
+    GOOGLE_API_KEY="your-google-api-key"
+    APIGEE_PROXY_URL="https://your-apigee-proxy.net/basepath"
+    ```
+
+    The `main.py` script will automatically load these variables when it runs.
+
+## Run the Sample
+
+Once your `.env` file is configured, you can run the sample with the following command:
+
+```bash
+python main.py
+```
+
+## Configuring the Apigee LLM
+
+The `ApigeeLlm` class is configured using a special model string format in `agent.py`. This string determines which backend provider (Vertex AI or Gemini) and which API version to use.
+
+### Model String Format
+
+The supported format is:
+
+`apigee/[<provider>/][<version>/]<model_id>`
+
+-   **`provider`** (optional): Can be `vertex_ai` or `gemini`.
+    -   If specified, it forces the use of that provider.
+    -   If omitted, the provider is determined by the `GOOGLE_GENAI_USE_VERTEXAI` environment variable. If this variable is set to `true` or `1`, Vertex AI is used; otherwise, `gemini` is used by default.
+
+-   **`version`** (optional): The API version to use (e.g., `v1`, `v1beta`).
+    -   If omitted, the default version for the selected provider is used.
+
+-   **`model_id`** (required): The identifier for the model you want to use (e.g., `gemini-2.5-flash`).
+
+### Configuration Examples
+
+Here are some examples of how to configure the model string in `agent.py` to achieve different behaviors:
+
+1.  **Implicit Provider (determined by environment variable):**
+
+    -   `model="apigee/gemini-2.5-flash"`
+        -   Uses the default API version.
+        -   Provider is Vertex AI if `GOOGLE_GENAI_USE_VERTEXAI` is true, otherwise Gemini.
+
+    -   `model="apigee/v1/gemini-2.5-flash"`
+        -   Uses API version `v1`.
+        -   Provider is determined by the environment variable.
+
+2.  **Explicit Provider (ignores environment variable):**
+
+    -   `model="apigee/vertex_ai/gemini-2.5-flash"`
+        -   Uses Vertex AI with the default API version.
+
+    -   `model="apigee/gemini/gemini-2.5-flash"`
+        -   Uses Gemini with the default API version.
+
+    -   `model="apigee/gemini/v1/gemini-2.5-flash"`
+        -   Uses Gemini with API version `v1`.
+
+    -   `model="apigee/vertex_ai/v1beta/gemini-2.5-flash"`
+        -   Uses Vertex AI with API version `v1beta`.
+
+By modifying the `model` string in `agent.py`, you can test various configurations without changing the core logic of the agent.

contributing/samples/hello_world_apigeellm/agent.py

@@ -0,0 +1,108 @@
+# 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.
+
+import random
+
+from google.adk import Agent
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+
+
+def roll_die(sides: int, tool_context: ToolContext) -> int:
+  """Roll a die and return the rolled result.
+
+  Args:
+    sides: The integer number of sides the die has.
+
+  Returns:
+    An integer of the result of rolling the die.
+  """
+  result = random.randint(1, sides)
+  if "rolls" not in tool_context.state:
+    tool_context.state["rolls"] = []
+
+  tool_context.state["rolls"] = tool_context.state["rolls"] + [result]
+  return result
+
+
+async def check_prime(nums: list[int]) -> str:
+  """Check if a given list of numbers are prime.
+
+  Args:
+    nums: The list of numbers to check.
+
+  Returns:
+    A str indicating which number is prime.
+  """
+  primes = set()
+  for number in nums:
+    number = int(number)
+    if number <= 1:
+      continue
+    is_prime = True
+    for i in range(2, int(number**0.5) + 1):
+      if number % i == 0:
+        is_prime = False
+        break
+    if is_prime:
+      primes.add(number)
+  return (
+      "No prime numbers found."
+      if not primes
+      else f"{', '.join(str(num) for num in primes)} are prime numbers."
+  )
+
+
+root_agent = Agent(
+    model="apigee/gemini-2.5-flash",
+    name="hello_world_agent",
+    description=(
+        "hello world agent that can roll a dice of 8 sides and check prime"
+        " numbers."
+    ),
+    instruction="""
+      You roll dice and answer questions about the outcome of the dice rolls.
+      You can roll dice of different sizes.
+      You can use multiple tools in parallel by calling functions in parallel(in one request and in one round).
+      It is ok to discuss previous dice roles, and comment on the dice rolls.
+      When you are asked to roll a die, you must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.
+      You should never roll a die on your own.
+      When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. You should never pass in a string.
+      You should not check prime numbers before calling the tool.
+      When you are asked to roll a die and check prime numbers, you should always make the following two function calls:
+      1. You should first call the roll_die tool to get a roll. Wait for the function response before calling the check_prime tool.
+      2. After you get the function response from roll_die tool, you should call the check_prime tool with the roll_die result.
+        2.1 If user asks you to check primes based on previous rolls, make sure you include the previous rolls in the list.
+      3. When you respond, you must include the roll_die result from step 1.
+      You should always perform the previous 3 steps when asking for a roll and checking prime numbers.
+      You should not rely on the previous history on prime results.
+    """,
+    tools=[
+        roll_die,
+        check_prime,
+    ],
+    # planner=BuiltInPlanner(
+    #     thinking_config=types.ThinkingConfig(
+    #         include_thoughts=True,
+    #     ),
+    # ),
+    generate_content_config=types.GenerateContentConfig(
+        safety_settings=[
+            types.SafetySetting(  # avoid false alarm about rolling dice.
+                category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+                threshold=types.HarmBlockThreshold.OFF,
+            ),
+        ]
+    ),
+)

contributing/samples/hello_world_apigeellm/main.py

@@ -0,0 +1,112 @@
+# 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.
+
+import asyncio
+import os
+import time
+
+import agent
+from dotenv import load_dotenv
+from google.adk.agents.run_config import RunConfig
+from google.adk.cli.utils import logs
+from google.adk.runners import InMemoryRunner
+from google.adk.sessions.session import Session
+from google.genai import types
+
+load_dotenv(override=True)
+logs.log_to_tmp_folder()
+
+
+async def main():
+  app_name = "my_app"
+  user_id_1 = "user1"
+  runner = InMemoryRunner(
+      agent=agent.root_agent,
+      app_name=app_name,
+  )
+  session_11 = await runner.session_service.create_session(
+      app_name=app_name, user_id=user_id_1
+  )
+
+  async def run_prompt(session: Session, new_message: str):
+    content = types.Content(
+        role="user", parts=[types.Part.from_text(text=new_message)]
+    )
+    print("** User says:", content.model_dump(exclude_none=True))
+    async for event in runner.run_async(
+        user_id=user_id_1,
+        session_id=session.id,
+        new_message=content,
+    ):
+      if event.content.parts and event.content.parts[0].text:
+        print(f"** {event.author}: {event.content.parts[0].text}")
+
+  async def run_prompt_bytes(session: Session, new_message: str):
+    content = types.Content(
+        role="user",
+        parts=[
+            types.Part.from_bytes(
+                data=str.encode(new_message), mime_type="text/plain"
+            )
+        ],
+    )
+    print("** User says:", content.model_dump(exclude_none=True))
+    async for event in runner.run_async(
+        user_id=user_id_1,
+        session_id=session.id,
+        new_message=content,
+        run_config=RunConfig(save_input_blobs_as_artifacts=True),
+    ):
+      if event.content.parts and event.content.parts[0].text:
+        print(f"** {event.author}: {event.content.parts[0].text}")
+
+  async def check_rolls_in_state(rolls_size: int):
+    session = await runner.session_service.get_session(
+        app_name=app_name, user_id=user_id_1, session_id=session_11.id
+    )
+    assert len(session.state["rolls"]) == rolls_size
+    for roll in session.state["rolls"]:
+      assert roll > 0 and roll <= 100
+
+  start_time = time.time()
+  print("Start time:", start_time)
+  print("------------------------------------")
+  await run_prompt(session_11, "Hi")
+  await run_prompt(session_11, "Roll a die with 100 sides")
+  await check_rolls_in_state(1)
+  await run_prompt(session_11, "Roll a die again with 100 sides.")
+  await check_rolls_in_state(2)
+  await run_prompt(session_11, "What numbers did I got?")
+  await run_prompt_bytes(session_11, "Hi bytes")
+  print(
+      await runner.artifact_service.list_artifact_keys(
+          app_name=app_name, user_id=user_id_1, session_id=session_11.id
+      )
+  )
+  end_time = time.time()
+  print("------------------------------------")
+  print("End time:", end_time)
+  print("Total time:", end_time - start_time)
+
+
+if __name__ == "__main__":
+  # The API key can be set in a .env file.
+  # For example, create a .env file with the following content:
+  # GOOGLE_API_KEY="your-api-key"
+  # APIGEE_PROXY_URL="your-proxy-url"
+  if not os.getenv("GOOGLE_API_KEY"):
+    raise ValueError("GOOGLE_API_KEY environment variable is not set.")
+  if not os.getenv("APIGEE_PROXY_URL"):
+    raise ValueError("APIGEE_PROXY_URL environment variable is not set.")
+  asyncio.run(main())

src/google/adk/models/__init__.py

@@ -14,6 +14,7 @@
 
 """Defines the interface to support a model."""
 
+from .apigee_llm import ApigeeLlm
 from .base_llm import BaseLlm
 from .gemma_llm import Gemma
 from .google_llm import Gemini
@@ -31,3 +32,4 @@
 
 LLMRegistry.register(Gemini)
 LLMRegistry.register(Gemma)
+LLMRegistry.register(ApigeeLlm)