Creates a plugin flag to register a plugin with the adk api_server

[igooch]

feat: Enable Plugin Registration via adk api_server CLI

This PR adds support for registering plugins directly via the adk api_server command using a new --plugin option.

Main Logic Changes:

• CLI Option: Added --plugin to cli_api_server in src/google/adk/cli/cli_tools_click.py to accept multiple plugin import paths.
• Plugin Loading: In src/google/adk/cli/fast_api.py, the get_fast_api_app function now dynamically loads and instantiates classes passed to the plugins argument.
• Runner Integration: Instantiated plugins are now passed to the AdkWebServer constructor, which in turn passes them to the Runner instance it creates in src/google/adk/cli/adk_web_server.py.
• Unit Tests: Added test_agent_run_with_plugin to tests/unittests/cli/test_fast_api.py to verify plugin loading and execution, using patching to mock plugin imports and services.
• This allows developers to use plugins without a custom server entry point, directly with the adk api_server command.

How to Use:

adk api_server . \
  --plugin my_package.my_module.MyFirstPlugin \
  --plugin another_package.other_module.MySecondPlugin

Fixes #2636

[gemini-code-assist]

Summary of Changes

Hello @igooch, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new --plugin command-line option to the adk api_server command, enabling developers to register and utilize custom plugins directly without requiring a custom server entry point. This enhancement streamlines the process of integrating custom functionalities into the ADK API server.

Highlights

• CLI Enhancement: A new --plugin option is added to the adk api_server command, allowing users to specify multiple fully qualified paths to BasePlugin classes for registration.
• Dynamic Plugin Loading: The get_fast_api_app function now includes logic to dynamically import and instantiate BasePlugin classes provided via the new --plugin option.
• Runner Integration: Instantiated plugins are now passed to the AdkWebServer constructor, which then forwards them to the Runner instance, ensuring plugins are active within the server's operational flow.
• Comprehensive Unit Testing: New unit tests, specifically test_agent_run_with_plugin, have been added to validate the end-to-end functionality of plugin loading and execution within the API server.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature for registering plugins via the adk api_server CLI. The implementation is well-structured, and the addition of unit tests is commendable. My main feedback concerns a potential TypeError during plugin instantiation, which could affect usability for developers. I've provided a suggestion to make the instantiation more robust. I also have a minor suggestion to improve the test mocks for better maintainability.

[igooch]

E2E Testing

1. Create a Clean Virtual Environment and Install ADK-Python Development Version
   1.0 cd ~/adk-python
   1.1 python3 -m venv /tmp/adk-test-venv
   1.2 source /tmp/adk-test-venv/bin/activate
   1.3 uv build
   1.4 pip install dist/google_adk-1.12.0-py3-none-any.whl

2. Create Test Plugins
   2.0 For this test we are using the quickstart weather agent.
   2.1 Create contributing/samples/quickstart/my_plugins.py with two sample plugins:

import logging
import time
from typing import Dict, Optional
from google.adk.agents.invocation_context import InvocationContext
from google.adk.events.event import Event
from google.adk.plugins.base_plugin import BasePlugin
from google.genai import types


class MetadataInjectionPlugin(BasePlugin):
  """A dummy plugin that injects metadata into events."""

  def __init__(self, name="metadata_injection_plugin"):
      super().__init__(name=name)

  async def on_event_callback(
      self, *, invocation_context: InvocationContext, event: Event
  ) -> Event:
      """Adds a custom metadata field to every event."""
      if not event.custom_metadata:
          event.custom_metadata = {}
      event.custom_metadata["injected_by_plugin"] = True
      return event

class RunTimingPlugin(BasePlugin):
  """A plugin to measure and log the duration of an agent run."""

  def __init__(self, name="run_timing_plugin"):
      super().__init__(name=name)
      self._start_times: Dict[str, float] = {}
      logging.info("RTP: RunTimingPlugin Initialized")

  async def before_run_callback(
      self, *, invocation_context: InvocationContext
  ) -> Optional[types.Content]:
      """Called at the beginning of a runner.run() or runner.run_async()."""
      session_id = invocation_context.session.id
      if session_id:
          self._start_times[session_id] = time.monotonic()
          logging.info(f"RTP: Run started for session {session_id}")
      else:
          logging.warning("RTP: before_run_callback called without session_id")
      return None  # This hook can optionally return Content to prepend to the conversation

  async def after_run_callback(
      self, *, invocation_context: InvocationContext
  ) -> Optional[None]:
      """Called at the end of a runner.run() or runner.run_async()."""
      session_id = invocation_context.session.id
      if session_id and session_id in self._start_times:
          end_time = time.monotonic()
          duration = end_time - self._start_times.pop(session_id)
          logging.info(f"RTP: Run finished for session {session_id}. Duration: {duration:.4f} seconds.")
      elif session_id:
          logging.warning(f"RTP: after_run_callback called for session {session_id} but no start time found.")
      else:
          logging.warning("RTP: after_run_callback called without session_id")
      return None

3. Add Google API Key
   3.1 Create contributing/samples/quickstart/.env file with GOOGLE_API_KEY="{$MY_API_KEY}"

4. Add adk-python to PYTHONPATH
   4.0 Necessary so that Python can recognize the quickstart directory as a Python module.
   4.1 cd ~/adk-python
   4.2 PYTHONPATH=$PWD

5. Run adk api_server with the Test Plugins

~/adk-python$ adk api_server ./contributing/samples/quickstart   --plugin "contributing.samples.quickstart.my_plugins.MetadataInjectionPlugin"   --plugin "contributing.samples.quickstart.my_plugins.RunTimingPlugin"

/tmp/adk-test-venv/lib/python3.13/site-packages/google/adk/cli/fast_api.py:192: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
 credential_service = InMemoryCredentialService()
/tmp/adk-test-venv/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
 super().__init__()
2025-08-25 11:28:23,639 - INFO - my_plugins.py:31 - RTP: RunTimingPlugin Initialized
INFO:     Started server process [2629300]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

6. Create a Session via Curl

~$     curl -X POST http://localhost:8000/apps/agent/users/test_user_1/sessions/session_1 \
    -H "Content-Type: application/json" \
    -d '{}'

{"id":"session_1","appName":"agent","userId":"test_user_1","state":{},"events":[],"lastUpdateTime":1756103305.194144}

Server Output on Session Creation:

2025-08-25 11:28:26,817 - INFO - adk_web_server.py:450 - New session created: session_1
INFO:     127.0.0.1:41920 - "POST /apps/agent/users/test_user_1/sessions/session_1 HTTP/1.1" 200 OK

7. Send Request to the Agent via Curl

~$     curl -X POST http://localhost:8000/run \$     curl -X POST http://localhost:8000/run \
    -H "Content-Type: application/json" \
    -d '{
      "app_name": "agent",
      "user_id": "test_user_1",
      "session_id": "session_1",
      "new_message": {
        "role": "user",
        "parts": [{
          "text": "What is the weather in New York?"
        }]
      }
    }'


[
  {
    "content": {
      "parts": [
        {
          "functionCall": {
            "id": "adk-68fcc67a-6edf-4106-ad60-84337bd74331",
            "args": {
              "city": "New York"
            },
            "name": "get_weather"
          }
        }
      ],
      "role": "model"
    },
    "finishReason": "STOP",
    "customMetadata": {
      "injected_by_plugin": true
    },
    "usageMetadata": {
      "candidatesTokenCount": 6,
      "candidatesTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 6
        }
      ],
      "promptTokenCount": 169,
      "promptTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 169
        }
      ],
      "totalTokenCount": 175
    },
    "invocationId": "e-5d57da62-8beb-40b6-8130-0f59f10bcbf9",
    "author": "weather_time_agent",
    "actions": {
      "stateDelta": {},
      "artifactDelta": {},
      "requestedAuthConfigs": {}
    },
    "longRunningToolIds": [],
    "id": "88fb6719-7492-4a76-b6c2-4643463e90c1",
    "timestamp": 1756146510.979906
  },
  {
    "content": {
      "parts": [
        {
          "functionResponse": {
            "id": "adk-68fcc67a-6edf-4106-ad60-84337bd74331",
            "name": "get_weather",
            "response": {
              "status": "success",
              "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit)."
            }
          }
        }
      ],
      "role": "user"
    },
    "customMetadata": {
      "injected_by_plugin": true
    },
    "invocationId": "e-5d57da62-8beb-40b6-8130-0f59f10bcbf9",
    "author": "weather_time_agent",
    "actions": {
      "stateDelta": {},
      "artifactDelta": {},
      "requestedAuthConfigs": {}
    },
    "id": "3051b467-d3f7-4045-8d29-71d931f22adf",
    "timestamp": 1756146511.735478
  },
  {
    "content": {
      "parts": [
        {
          "text": "OK. The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).\n"
        }
      ],
      "role": "model"
    },
    "finishReason": "STOP",
    "customMetadata": {
      "injected_by_plugin": true
    },
    "usageMetadata": {
      "candidatesTokenCount": 25,
      "candidatesTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 25
        }
      ],
      "promptTokenCount": 203,
      "promptTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 203
        }
      ],
      "totalTokenCount": 228
    },
    "invocationId": "e-5d57da62-8beb-40b6-8130-0f59f10bcbf9",
    "author": "weather_time_agent",
    "actions": {
      "stateDelta": {},
      "artifactDelta": {},
      "requestedAuthConfigs": {}
    },
    "id": "8e88e16e-3ae9-4b7e-acc4-374c236e7340",
    "timestamp": 1756146511.737461
  }
]

Confirmed that the returned json includes the data from our first plugin with "customMetadata": { "injected_by_plugin": true },

Server Output on Agent Request:

2025-08-25 11:28:30,977 - INFO - envs.py:47 - Loaded .env file for agent at /usr/local/google/home/igooch/adk-python/contributing/samples/quickstart/.env
2025-08-25 11:28:30,977 - INFO - envs.py:47 - Loaded .env file for agent at /usr/local/google/home/igooch/adk-python/contributing/samples/quickstart/.env
2025-08-25 11:28:30,978 - INFO - plugin_manager.py:96 - Plugin 'MetadataInjectionPlugin' registered.
2025-08-25 11:28:30,978 - INFO - plugin_manager.py:96 - Plugin 'RunTimingPlugin' registered.
2025-08-25 11:28:30,978 - INFO - my_plugins.py:40 - RTP: Run started for session session_1
2025-08-25 11:28:31,019 - INFO - google_llm.py:112 - Sending out request, model: gemini-2.0-flash, backend: GoogleLLMVariant.GEMINI_API, stream: False
2025-08-25 11:28:31,019 - INFO - models.py:8204 - AFC is enabled with max remote calls: 10.
2025-08-25 11:28:31,732 - INFO - _client.py:1740 - HTTP Request: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent "HTTP/1.1 200 OK"
2025-08-25 11:28:31,734 - INFO - google_llm.py:205 - Response received from the model.
2025-08-25 11:28:31,734 - WARNING - types.py:5440 - Warning: there are non-text parts in the response: ['function_call'], returning concatenated text result from text parts. Check the full candidates.content.parts accessor to get the full model response.
2025-08-25 11:28:31,754 - INFO - google_llm.py:112 - Sending out request, model: gemini-2.0-flash, backend: GoogleLLMVariant.GEMINI_API, stream: False
2025-08-25 11:28:31,754 - INFO - models.py:8204 - AFC is enabled with max remote calls: 10.
2025-08-25 11:28:32,435 - INFO - _client.py:1740 - HTTP Request: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent "HTTP/1.1 200 OK"
2025-08-25 11:28:32,437 - INFO - google_llm.py:205 - Response received from the model.
2025-08-25 11:28:32,438 - INFO - my_plugins.py:53 - RTP: Run finished for session session_1. Duration: 1.4598 seconds.
2025-08-25 11:28:32,439 - INFO - adk_web_server.py:914 - Generated 3 events in agent run
INFO:     127.0.0.1:56680 - "POST /run HTTP/1.1" 200 OK

Confirmed that this contains our log lines from our second plugin like RTP: Run finished for session session_1. Duration: 1.4598 seconds.

[boyangsvl]

@igooch Thank you for the contribution! We are adding support of plugins to adk web, adk api_server and adk deploy as well. We are introducing an App concept that will be used to configure the plugins. I will close this PR because our change will be released next week. Sorry about that!