Per-call dynamic context injection into agent instructions (like caller phone number)

[arsenieciprian]

Problem

When building SIP telephony agents, we need to inject per-call context (e.g. the caller's phone number) into the agent's instructions so the LLM knows it without asking the user.

Currently we work around this by extracting the phone from the room name with regex (_+40712345678_RandomId) and passing it to the agent at __init__ time — before session.start().

What we tried

Option A — wait_for_participant() before session.start()
Fails with "room is not connected" — the room isn't connected until session.start() is called.

Option B — update_instructions() in on_enter() after session starts
Works technically but causes the LLM to go silent with Google Realtime (Gemini Live) — the audio stream resets. Works fine with pipeline mode.

Option C — room name regex
What we use now. Fragile by design — depends on a naming convention.

What ElevenLabs does

ElevenLabs injects {{system__caller_id}} as a platform-level variable directly into the system prompt per call. The LLM sees it as plain text in instructions. No timing issues, no stream resets.

Question

Is there an official/recommended way to inject per-call dynamic context (participant attributes, caller phone, custom metadata) into agent instructions before the first LLM turn, without calling update_instructions() mid-session?

For example:

• Access to participant.attributes before session.start()?
• A hook between session.start() and on_enter() where the room is already connected?
• Support for template variables in instructions like {{sip.phoneNumber}}?

Environment: livekit-agents 1.5.1, Google Realtime (Gemini Live 2.5 Flash), inbound SIP calls.

[longcw]

Option A — wait_for_participant() before session.start()

wait_for_participant will wait for room connection in next release, addressing it in #5271

before that, you can call ctx.connect() to wait for the room connected

await ctx.connect()
await wait_for_participant()