Runner.__init__ 'agent' param typed Optional[BaseAgent] but class field and runtime accept BaseNode (e.g. Workflow) roots

[JesusCaseroDiazCano]

Summary

Runner's class-level field is typed to accept node roots:

# runners.py:153
agent: Optional[BaseAgent | 'BaseNode'] = None

but the __init__ parameter was not widened to match:

# runners.py:175
agent: Optional[BaseAgent] = None,

The runtime explicitly supports a BaseNode root (e.g. a Workflow):

# runners.py:1023-1024
if isinstance(self.agent, BaseNode) and not isinstance(self.agent, BaseAgent):
    ...

So passing a Workflow as the root works at runtime, but type checkers (pyright) reject Runner(agent=my_workflow) against the narrower __init__ signature.

Expected

The __init__ agent parameter annotation matches the class field, e.g. Optional[BaseAgent | BaseNode].

Version

google-adk==2.3.0

Note

I only verified the __init__ agent path. There may be similar narrowing on related entry points (node=, run_live), but I have not confirmed those.

[llalitkumarrr]

Hello @JesusCaseroDiazCano ,

We have reviewed this issue and it is our understanding that it should not have any functional impact or cause your code to break. Even if you pass Workflow as the root agent, it should still work. It is worth checking _resolve_app helper function to understand how this argument is processed.

Please let us know if we have understood your issue correctly, if not kindly share additional details.

[JesusCaseroDiazCano]

Thanks for looking into this, @llalitkumarrr . Agreed it has no functional impact, _resolve_app wraps the agent via model_construct and the runner has explicit BaseNode branches, so a Workflow root runs fine at runtime. That matches what we see.

The report is narrower than that though: it is a static typing inconsistency, not a runtime bug. Within runners.py, the class field is typed Optional[BaseAgent | BaseNode] (line 153), but the init parameter (line 175) and _resolve_app (line 245) are typed Optional[BaseAgent]. So Runner(agent=my_workflow) is rejected by type checkers (pyright) even though it is valid and supported. We currently work around it with a # type: ignore[arg-type].

Suggested fix: widen the init and _resolve_app agent parameters to match the class field (Optional[BaseAgent | BaseNode]), so passing a Workflow root type-checks without a suppression. Purely an annotation change, no behaviour impact.

[godququ5-code]

Hi! I verified this on current main: Runner stores Optional[BaseAgent | BaseNode] and the runtime path already supports Workflow/BaseNode, while the Runner.init annotation is still narrower. I would like to make a focused annotation fix and add a static type regression alongside the existing runner node tests. Should the matching InMemoryRunner annotation be updated in the same PR for consistency, or would you prefer this stay limited to Runner? Is anyone already working on this?

[JesusCaseroDiazCano]

Thanks for picking this up. To your questions:

To my knowledge nobody is working on the ADK fix — please go ahead. On our side we only worked around it with a # type: ignore[arg-type]; we are not touching the annotation ourselves.

Please include InMemoryRunner in the same PR. It has the same gap independently: its own __init__ (runners.py ~2158) also types agent: Optional[BaseAgent], so passing a Workflow root there is rejected too. That is a real caller for us, not hypothetical — 3 of our 4 suppressions are on InMemoryRunner(agent=workflow) in tests, the other on Runner. So fixing both keeps it consistent and clears the whole surface we hit.

The static type regression test alongside the node tests sounds right.

[godququ5-code]

Thanks for clarifying the affected surface. @llalitkumarrr, since the issue is currently assigned to you, could you confirm whether I may proceed with a focused fix covering Runner.init, Runner._resolve_app, and InMemoryRunner.init, plus an appropriate static typing regression check? I will keep runtime behavior unchanged and limit the PR to this typing inconsistency.

[llalitkumarrr]

Hello @JesusCaseroDiazCano ,

#6308 should solve this, could you please check it and let us know your inputs?

[adk-bot]

This issue has been automatically marked as stale because it has not had recent activity for 7 days after a maintainer requested clarification. It will be closed if no further activity occurs within 7 days.

[adk-bot]

This has been automatically closed because it has been marked as stale for over 7 days.