Align `adk run` options with `adk web` (missing --extra_plugins)

[arex18]

ADK Version: 1.21.0

Description

There is a significant discrepancy between the CLI options available for adk run and adk web. Specifically, adk run is missing several critical parameters, most notably --extra_plugins.

This inconsistency creates anti-patterns: This forces manual Runner implementation in CLI mode but not Web mode. Since the Runner isn't always called unless the async loop is managed manually, the CLI should natively support these configuration options to ensure parity across environments.

Parameter	Supported in adk run	Supported in adk web
--session_service_uri	✅	✅
--artifact_service_uri	✅	✅
--memory_service_uri	✅	✅
--extra_plugins	❌ (Missing)	✅
--log_level	❌ (Missing)	✅
--verbose / -v	❌ (Missing)	✅
--trace_to_cloud	❌ (Missing)	✅
--otel_to_cloud	❌ (Missing)	✅
--eval_storage_uri	❌ (Missing)	✅
--save_session	✅	❌
--session_id	✅	❌
--replay	✅	❌
--resume	✅	❌
--host	❌ (N/A)	✅
--port	❌ (N/A)	✅
--allow_origins	❌ (N/A)	✅
--reload / --no-reload	❌ (N/A)	✅
--reload_agents	❌ (N/A)	✅
--a2a	❌ (N/A)	✅
--url_prefix	❌ (N/A)	✅
--logo-text	❌ (N/A)	✅
--logo-image-url	❌ (N/A)	✅
--session_db_url (Deprecated)	❌	✅
--artifact_storage_uri (Deprecated)	❌	✅

Proposed Change

Update the adk run command to accept the same core configuration flags as adk web, specifically --extra_plugins to allow for consistent agent behavior regardless of the entry point.

[wuliang229]

@arex18 Thanks for the great comparison table. We could definitely add --extra_plugins to the adk run command. May I know what your use case is for needing this arg? This argument was mostly added for developing the "conformance test" feature.

[arex18]

Sure :) The main use case is robust Error Handling. We found exception handling within the framework to be challenging, so we’re using a customized version of the ReflectAndRetryToolPlugin to manage tool-calling exceptions.

In adk web, this works perfectly via the --extra_plugins flag. It allows us to keep the Agent definition clean and declarative:

root_agent = Agent(
    model="gemini-2.0-flash",
    name="...",
    instruction=agent_instruction,
    tools=tools,
)

The issue is that going from adk web to adk run should be a natural progression (e.g. for CLI testing, cron jobs or server-side execution), but currently, we can't do that without changing how the app is structured.

To get that same plugin logic in adk run right now, we’re forced to abandon the simple CLI entry point and manually set up a Runner or a FastAPI app through get_fast_api_app:

session_service = InMemorySessionService()
runner = Runner(
    agent=root_agent,
    app_name=app_name,
    session_service=session_service,
    extra_plugins=[MyCustomPlugin()], # This is what's missing from the CLI flag
    ...
)

# OR

app = get_fast_api_app(
    agents_dir=str(AGENTS_DIR),
    web=True,
    trace_to_cloud=False,
    session_service=...,
    ...
)

From a dev perspective, web and run should be 1:1 and we shouldn't have to rewrite the execution flow just to suit the library’s CLI limitations.

[wuliang229]

@arex18 For your particular use case, you can use the App concept, which can contain your agent and a number of plugins. Therefore you don't need the Runner when switching to adk run.

[wuliang229]

As for the discrepancy, the adk run was written as a simple interactive interface and there's no FastAPI server behind it. To test your agent in the CLI, I would recommend using adk api_server, which has more overlap with the functionality of adk web. I'll close the issue for now.

[arex18]

@arex18 For your particular use case, you can use the App concept, which can contain your agent and a number of plugins. Therefore you don't need the Runner when switching to adk run.

Yes, this seems to suit our use case - I had missed it actually, thank you.