Interface PrepareClientSessionInput

The shared session id grouping this voice session's runs.

The run's runtime API keys, when the session is prepared from an agent run that carries them (ExecuteAgentParams.apiKeys, set by BaseAgent.StartBridgeRealtimeSession). Vendor selection and the minted session try these first, per driver class; for a class they do not key, this service's RealtimeClientSessionService.getAPIKeyForDriver seam answers (by default the AI_VENDOR_API_KEY__<driver> environment key). That is the same order as GetAIAPIKey — the legacy tier of prompt key resolution. MJ Credentials / AICredentialBindings, which a prompt consults first, are not consulted by realtime. Absent ⇒ the seam alone, which is every client-initiated session today.

Optional app-context snapshot — where the user is, what they see, and the live capability manifest — injected into the companion system prompt at mint (the session-start half of the client-context delivery; the import('@memberjunction/ai-core-plus').AppContextSnapshot shape). The streaming half rides the ClientContextChannel. Absent ⇒ no app-context section.

Optional application id the realtime session runs in. Sources the app cascade layer of the effective config: Application.AgentSettings.Realtime (persona/disclosure/model overrides) + RelevantAgents (union-accumulated into the co-agent's allowed delegation set). Absent ⇒ no app layer (the cascade rests on type/co-agent/target/override only).

'room' for a server-side (bridged) session whose host publishes the agent's avatar into a meeting room: the avatar request resolved for the voiced agent carries it (RealtimeAvatarSettings.Delivery), so a driver may render it there. Absent: a server-side session asks for no video (the driver logs bridged), and its avatar status says bridged also when the prep asked the driver for none, or the driver reported nothing. Ignored on a PhoneCall.

The interactive channels the BROWSER reports it could mount in this session (key, code defaults, native tools, host-declared?). When present the service scopes them — registry kill switch, agent and app configuration (realtime.channels) — narrows/completes ExtraTools to match, and returns the resolved RealtimeClientSessionPrepResult.ClientPolicy for the browser to activate. Absent ⇒ no scoping (a client that predates channel scoping, or a host that mints through its own proxy): ExtraTools is used exactly as declared.

The Realtime Co-Agent entity. Provide this OR PrepareClientSessionInput.CoAgentID.

The Realtime Co-Agent id (resolved from cached metadata). Provide this OR PrepareClientSessionInput.CoAgent.

Optional company-scope id for memory/context retrieval.

Optional provider-specific session config bag (voice, language, turn detection, etc.).

Optional RUNTIME configuration-override layer (the most-specific layer of the effective configuration merge: type DefaultConfiguration ← agent TypeConfiguration ← this). Pre-authorized by the transport layer — the MJServer resolver gates it behind the Realtime: Advanced Session Controls authorization BEFORE threading it here; the service trusts the input. Malformed JSON is tolerated (it simply contributes nothing to the merge).

Optional conversation id the session is attached to — stamped on the co-agent observability run.

Prior conversation history to seed the model's context. Optional.

The run's credential scope (ExecuteAgentParams.CredentialScope). 'RuntimeOnly' makes PrepareClientSessionInput.APIKeys the whole key chain: a vendor they do not key is not selected, and the RealtimeClientSessionService.getAPIKeyForDriver seam (by default the platform's environment key) is never consulted. Absent ⇒ 'Any'.

Multi-agent meeting mode. When true, the agent joins as one of several voices in a shared room: its model's blind auto-response is disabled (the session Config carries disableAutoResponse, which providers translate to e.g. OpenAI turn_detection.create_response=false) and a meeting-aware clause is added to the prompt so it hears everything but speaks only when addressed. The bridge becomes the sole speech trigger (gated by its turn policy). Absent/false = a 1:1 call with the model's normal auto-response. See plans/realtime/multi-agent-meeting-turn-taking.md.

When true, no direct actions are projected for the session, so the model gets none and the session's relays run none. Set for callers that may not run actions directly.

Optional extra tools to expose in addition to invoke-target-agent.

Host-authored instructions appended to the system prompt (e.g. "this is an audio-only phone call …", the caller's number and verification status). Empty/absent adds nothing.

Tools the HOST (not the co-agent runtime) declares AND executes — e.g. a phone call's transfer_call, send_dtmf and end_call. They are added to the session's tool set but, unlike ExtraTools, are NOT described as interactive-surface tools in the prompt. The host executes them through the runtime's local tool handler (BridgeRealtimeRuntime.SetLocalToolHandler).

Optional server-authoritative hard ceiling on the session's wall-clock duration, in seconds. Threaded into RealtimeSessionParams.MaxSessionSeconds so a driver can bound the provider session/token, and surfaced so the transport layer (the MJServer resolver) can stamp the absolute deadline on the session for the janitor to enforce. Set for abuse-sensitive deployments (a public web-widget guest's VoiceMaxSessionMinutes); omitted otherwise.

true when the session is a phone call: a carrier call (Twilio, Vonage, RingCentral), or a call that reaches a LiveKit room through SIP. The caller hears the agent and sees nothing, so the session asks the driver for no avatar, even in a room that could show one, and reports why (phone); the avatar persona's voice is kept, and the default model walk prefers no avatar model. Absent: not a phone call.

Optional EXPLICIT realtime model choice (MJ: AI Models.ID). When set, that exact model is used — it must be Active, of AIModelType Realtime, and have an active vendor whose DriverClass resolves an API key. If the preferred model cannot be satisfied the prepare FAILS with a clear reason (no silent fallback — the user explicitly chose). When omitted, the default highest-PowerRank resolution applies.

Pre-formatted, role-tagged transcript lines (User: … / Assistant: …, newline-separated) from the caller's PRIOR session leg(s) when this session RESUMES one (lastSessionId). The transport layer (the MJServer resolver) loads, ownership-checks, and caps this (~30 turns / ~8k chars, oldest dropped) before threading it here; the service only FRAMES it into the system prompt as a clearly-labeled prior-conversation section so the model remembers the previous leg. Optional — absent for fresh sessions, and any upstream load failure simply omits it (hydration never blocks a start).

Optional callback that allows the host to resolve host tools dynamically based on the model, vendor, and driver actually resolved for the session, before session opening.

The names the meeting-aware prompt tells the agent it answers to (its own display name + aliases). Used ONLY to phrase the "you are addressed when someone says one of these" guidance; the actual addressing GATE is the bridge's RegexAddressedMatcher. Ignored unless DisableAutoResponse.

true for a server-side session (a bridged meeting or a phone call), which can show the agent's avatar only when its host publishes it into a room (AvatarDelivery 'room'). Without that, the default model walk's video preference skips the session: no model would bring it an avatar. Absent: a browser (client-direct) session.

false when the app showing a browser session shows no agent video: none of its channels shows it (the embeddable widgets and the mobile app today; the mint's showsAgentVideo argument). The session then asks the driver for no avatar and reports why (host), the avatar persona's voice is kept, and the default model walk prefers no avatar model. Absent or true: the app may show it, and the browser decides at connect (host or browser then).

The top-level target agent the co-agent voices on behalf of (a runtime parameter).

Optional user-scope id for memory/context retrieval (falls back to the context user).