Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
igooch wants to merge 2 commits into google:main from igooch:cli-pass-plugin

Conversation

@igooch
Copy link

@igooch igooch commented Aug 20, 2025

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

unxsist reacted with rocket emoji
Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary of Changes

Hello @igooch, I'm Gemini Code Assist1 ! 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. ↩

@adk-bot adk-bot added bot triaged tools [Component] This issue is related to tools labels Aug 20, 2025
Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

igooch commented Aug 25, 2025

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

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

  2. 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

  3. 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)
  1. 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
  1. 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.

Copy link
Collaborator

@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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@seanzhou1023 seanzhou1023 Awaiting requested review from seanzhou1023

1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

tools [Component] This issue is related to tools

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

feat: Enable Plugin Registration via adk api_server CLI

AltStyle によって変換されたページ (->オリジナル) /