Gemini 3.1 Live — document update_instructions limitation + provide alternative pattern for dynamic prompts

[webbliam124]

Problem

Since livekit-plugins-google 1.5.3, calling session.update_instructions() on a session using gemini-3.1-flash-live-preview emits:

update_instructions is not compatible with 'gemini-3.1-flash-live-preview' and will be ignored.

Per PR #5332, this is an intentional guard around a server-side Gemini 3.1 restriction (send_client_content rejected with WS 1007 after the first model turn).

What's missing

Production use cases need to update an agent's behavior mid-call (escalation prompts, language switching, context-aware tool enable/disable). On Gemini 2.5 we used update_instructions for this. On 3.1 there is no documented alternative.

Request

1. Document the limitation in the plugin README + RealtimeModel docstring.
2. Provide a recommended pattern for dynamic prompts on 3.1:
   • End session + restart with updated instructions?
   • Inject context via tool result?
   • session.generate_reply(instructions=...) for per-turn instructions?
3. Emit the warning once per session, not once per call — current verbosity pollutes production logs.

Reproduction

Any session on gemini-3.1-flash-live-preview calling await session.update_instructions("new") emits the warning; behavior is silently a no-op.

Environment

• livekit-agents[google] 1.5.2-1.5.4
• gemini-3.1-flash-live-preview
• LiveKit Cloud (eu-central)

[nightcityblade]

Hi, I'd like to work on this. I'll submit a PR shortly.

[ndandanov]

This limitation also affects my use case and renders gemini-3.1-flash-live-preview unfit for the project.
Please note that, according to the docs and if I understand correctly, session.generate_reply(instructions=...) doesn't work for the same reason as session.update_instructions().

Would love to know a workaround until some official way of updating the context is settled.