run_live: change instruction/tools or transfer agents on the open Live connection (send_context_update, in-session transfer) #7692

🔴 Required Information

Is your feature request related to a specific problem?

With Runner.run_live(), every transfer_to_agent closes the Gemini Live connection and opens a new one for the child agent. This is a problem for Live Avatar (video) use cases, where the connection is also the avatar session:

• The connection and avatar session are rebuilt on every transfer. Measured with gemini-3.8-live and a Vertex Live avatar (eu, ADK 2.12): about 4.6 s per transfer. That is a fixed 1.0 s DEFAULT_TRANSFER_AGENT_DELAY, about 0.9 s connect, and about 2.7 s until the new avatar session produces output. The user sees a frozen or blank avatar and hears silence.
• child_ctx.live_session_resumption_handle = None and run_config_for_new_live_session(...) force a fresh session, so the conversation is replayed with send_history(). The server-side state of the first connection is lost.
• Mic frames that queue in LiveRequestQueue during the swap are flushed into the new connection at once. We hit 1011 Client overran StreamHandler internal queue size and had to cap the queue backlog ourselves.

The Live API now allows changing the model preamble on an open session. google-genai >= 2.32 has AsyncSession.send_context_update(system_instruction=..., tools=...). Updates are processed in order with the other inputs. ADK has no way to use it: BaseLlmConnection, GeminiLlmConnection and LiveRequestQueue have no equivalent, and a running run_live agent cannot change its instruction or tools.

Describe the Solution You'd Like

Two layers. The first is small and useful alone.

1. Expose send_context_update through ADK.

   • BaseLlmConnection.send_context_update(system_instruction=None, tools=None) and the GeminiLlmConnection implementation, which forwards to the genai session.
   • A way to call it for an existing agent: either LiveRequestQueue.send_context_update(...), or a field on tool and callback output, e.g. tool_context.actions.live_context_update. The update must be sent before the tool response of the same call, so the model's next turn already uses it.
   • The system instruction and tool declarations that ADK keeps for the active agent (llm_request) are updated too, so later tool dispatch and session_resumption reconnects use the new values.

2. Agent-to-agent transfer without a new connection.

   • An opt-in mode, e.g. RunConfig(live_transfer_mode="in_session") (default "reconnect", today's behaviour).
   • On transfer_to_agent, ADK keeps the connection open. It builds the child's llm_request (instruction, tools, and the callbacks that run in the request processors), sends only the difference as send_context_update, and continues the loop with the child as the active agent. There is no DEFAULT_TRANSFER_AGENT_DELAY, no send_history(), the resumption handle is kept, and LiveRequestQueue keeps its backlog.
   • Limits that can be rejected with a clear error: same model and same Live config for parent and child (voice, avatar, modalities), and transfer_to_agent targets only the agents of the existing tree.

Impact on your work

We build an AI assistant with a Live Avatar and several role agents (routing, consultation, purchase). The per-transfer pause of about 4.6 s is not acceptable for a live session, so we dropped ADK's transfer. We now keep one ADK agent with a fixed instruction and all tools, switch a "virtual agent" in session state with a custom switch_agent tool, and return the role's playbook as the tool result as is specified in LiveAPI Best practices. That works, but it has no restrictive per-agent toolset or static system instructions at the model level that cannot be removed by ContextCompression. We would prefer real sub-agents with their own instruction and tools, as ADK models them. There is no hard deadline; this decides whether we stay on a workaround in production.

Willingness to contribute

Yes. We can send a PR for layer 1 (send_context_update on the connection and queue) first, then discuss layer 2 against the design that the maintainers prefer.

🟡 Recommended Information

Describe Alternatives You've Considered

Proposed API / Implementation

# Layer 1: from a tool (update is sent before this call's tool response)
def become_specialist(tool_context: ToolContext) -> dict:
    tool_context.actions.live_context_update = LiveContextUpdate(
        system_instruction="You are now the specialist. ...",
        tools=[specialist_tool],      # None keeps the current tools, [] clears them
    )
    return {"status": "ok"}

# Or from application code driving the queue
live_request_queue.send_context_update(system_instruction="...", tools=[...])

# Layer 2: opt-in transfer on the same connection
run_config = RunConfig(live_transfer_mode="in_session")
async for event in runner.run_live(..., run_config=run_config):
    ...

Where to change it in ADK 2.12:

• google/adk/models/base_llm_connection.py and gemini_llm_connection.py: new send_context_update, forwarded to session.send_context_update.
• google/adk/agents/live_request_queue.py: new LiveRequestQueue message type and its handling in the send task of live/_live_llm_flow.py.
• live/_live_llm_flow.py (the transfer branch around transfer_to_agent): in in_session mode, skip asyncio.sleep(DEFAULT_TRANSFER_AGENT_DELAY), llm_connection.close() and child_ctx.live_session_resumption_handle = None. Build the child's llm_request, diff its instruction and tools against the current ones, and send send_context_update.

Open questions: tool declarations versus the per-agent tool dispatch table when the active agent changes inside one loop; prefix-cache invalidation (the genai docs say system_instruction and tools updates invalidate it, so updates should be explicit, not automatic).

Additional Context

• Versions: google-adk 2.12.0, google-genai 2.32.0, Python 3.12, model gemini-3.8-live on Agent Platform, Live Avatar enabled, VAD, session resumption and context window compression on.
• send_context_update on an open session had no measurable cost in our probes: the tool call after the update took the same 0.4 s as without it, the speech after the tool response within about 0.1 s (audio), and an instruction of about 9k tokens did not slow the update.