apache/beam · error · ValueError

'agent' must be an Agent instance or a callable.

Error message

'agent' must be an Agent instance or a callable.

What it means

Type guard on the agent argument: ADKAgentModelHandler accepts either a live google.adk Agent instance or a zero-arg callable that constructs one; anything else (a class not derived from Agent, a string, etc.) cannot produce a runnable agent and is rejected.

Solutions

1. Pass an instance of google.adk.Agent directly
2. Or pass a factory lambda: agent=lambda: LlmAgent(name='my_agent', ...)

When it happens

Trigger: Thrown at sdks/python/apache_beam/ml/inference/agent_development_kit.py:144 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/94c1a5afc75c6c5d. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/ml/inference/agent_development_kit.py:144

      self,
      agent: _AgentOrFactory,
      app_name: str = "beam_inference",
      session_service_factory: Optional[Callable[[],
                                                 "BaseSessionService"]] = None,
      *,
      min_batch_size: Optional[int] = None,
      max_batch_size: Optional[int] = None,
      max_batch_duration_secs: Optional[int] = None,
      max_batch_weight: Optional[int] = None,
      element_size_fn: Optional[Callable[[Any], int]] = None,
      **kwargs):
    if not ADK_AVAILABLE:
      raise ImportError(
          "google-adk is required to use ADKAgentModelHandler. "
          "Install it with: pip install google-adk")

    if agent is None:
      raise ValueError("'agent' must be an Agent instance or a callable.")

    self._agent_or_factory = agent
    self._app_name = app_name
    self._session_service_factory = session_service_factory

    super().__init__(
        min_batch_size=min_batch_size,
        max_batch_size=max_batch_size,
        max_batch_duration_secs=max_batch_duration_secs,
        max_batch_weight=max_batch_weight,
        element_size_fn=element_size_fn,
        **kwargs)

  def load_model(self) -> "Runner":
    """Instantiates the ADK Runner on the worker.

    Resolves the agent (calling the factory if a callable was provided), then
    creates a :class:`~google.adk.runners.Runner` backed by the configured

View on GitHub (pinned to 12126d8942)