ReadonlyContext.agent_name raises AttributeError when _invocation_context.agent is None

[lmandrelli]

Environment

• Version: google-adk>=2.1.0 (tested with 2.1.0 and 2.2.0)
• Python: 3.14
• OS: Linux (Docker container)

The Issue

I migrated my project from sequential agents to a workflow using ADK 2.0, specifically with deterministic nodes.

After this migration, I started seeing the following error in my logs:

google_adk.google.adk.plugins.bigquery_agent_analytics_plugin - ERROR - BigQuery analytics plugin error in on_event_callback; skipping.
Traceback (most recent call last):
  File "/app/.venv/lib/python3.14/site-packages/google/adk/plugins/bigquery_agent_analytics_plugin.py", line 121, in wrapper
    return await func(self, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.14/site-packages/google/adk/plugins/bigquery_agent_analytics_plugin.py", line 3069, in on_event_callback
    await self._log_event(
    ...<5 lines>...
    )
  File "/app/.venv/lib/python3.14/site-packages/google/adk/plugins/bigquery_agent_analytics_plugin.py", line 2963, in _log_event
    "agent": callback_context.agent_name,
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.14/site-packages/google/adk/agents/readonly_context.py", line 52, in agent_name
    return self._invocation_context.agent.name
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'name'

Impact

While the BigQueryAgentAnalyticsPlugin wraps its callbacks in @_safe_callback (which catches and logs this as a non-fatal warning), the exception prevents the event from being properly logged to BigQuery. The event is silently dropped instead of being written with a fallback agent name.

This is a data-loss issue for anyone relying on the BigQuery analytics plugin.

Steps to Reproduce

1. Create an ADK workflow using deterministic nodes (ADK 2.0+).
2. Enable the BigQueryAgentAnalyticsPlugin.
3. Run the workflow.
4. Observe the AttributeError in the logs and the missing BigQuery rows.

Bug Description

Under google-adk, ReadonlyContext (and subclasses like CallbackContext) defines the agent_name property as:

@property
def agent_name(self) -> str:
    return self._invocation_context.agent.name

However, _invocation_context.agent is typed as Optional and can legitimately be None (e.g. during certain initialization/teardown phases of the Runner, or when driven by a workflow engine). When agent is None, this raises:

AttributeError: 'NoneType' object has no attribute 'name'

Expected Behavior

ReadonlyContext.agent_name should gracefully handle the case where agent is None, returning a fallback value such as "unknown" or None (typed as Optional[str]), rather than raising an unhandled AttributeError.

---

Temporary Workaround

This is the monkeypatch I applied in my project to work around this issue:

@property
def _safe_agent_name(self) -> str:
    """Safe wrapper for agent_name to prevent AttributeError when agent is None."""
    try:
        agent = self._invocation_context.agent
        return agent.name if agent is not None else "unknown"
    except AttributeError:
        return "unknown"

setattr(ReadonlyContext, "agent_name", _safe_agent_name)

[guillaumeblaquiere]

@haiyuan-eng-google for visibility

[caohy1988]

Confirmed the crash path against current main:

• InvocationContext.agent: Optional[BaseAgent | BaseNode] = None (agents/invocation_context.py:178) — legitimately None for workflow-driven invocations with deterministic nodes.
• ReadonlyContext.agent_name (agents/readonly_context.py:50-52) dereferences .agent.name with no None guard.
• The BQAA plugin reads callback_context.agent_name at row-build time inside _log_event; @_safe_callback swallows the AttributeError, so the row is silently dropped — the data-loss the report describes.

Two notes from working on the BQAA producer side:

1. Plugin-side hardening exists in the ADK 2.0 producer branch (caohy1988/adk-python#6, commit ab56d6e): _log_event now falls back to the source Event.author (the emitting node/agent — a more meaningful value than "unknown" for workflow rows) and then to null, so rows are written regardless of agent being None. That removes the data-loss symptom for the analytics plugin specifically, but does not touch this issue's core surface.

2. The core fix still matters for every other agent_name caller. Two design options for ReadonlyContext.agent_name:

   • return Optional[str] (None when agent is None) — honest typing, but a breaking signature change for callers assuming str;
   • return a sentinel like "" or "unknown" — keeps str, but bakes a magic value into every downstream consumer.

   If the team picks the Optional[str] route, the BQAA plugin needs no further change (it already handles null). If the sentinel route, pick the sentinel once here rather than letting each plugin invent its own.

A minimal reproducible check, for whoever picks this up:

ic = InvocationContext(agent=None, session=..., invocation_id="i", session_service=..., plugin_manager=...)
CallbackContext(ic).agent_name  # AttributeError: 'NoneType' object has no attribute 'name'

[caohy1988]

Correction to my earlier comment: "the plugin is now robust regardless of which way core decides" was only true for row survival, not for preserving the workflow node label.

With #6066 open (sentinel route — agent_name returns "unknown" for the no-agent case), a try/except-AttributeError fallback in the analytics plugin would stop firing once it lands, and workflow Event-originating rows would record "unknown" instead of the more useful Event.author.

The BQAA producer branch now derives the row's agent label from the underlying InvocationContext.agent directly (caohy1988/adk-python#6, commit e859178):

• agent present → agent.name
• no agent + source Event → Event.author (the emitting node)
• callback-only row → null

That is stable under current main (raises), the #6066 sentinel route, and a future Optional[str] route — so whichever direction this issue resolves in core, the analytics rows keep a meaningful label.