Information Ingestion & Exchange

Choose external events, stored user context, or tool retrieval for Classic conversations, with links to the separate Platform data and session contracts.

This page covers the Classic API. Choose a path based on when the conversation needs the information and whether it should remain available to later interactions. These Classic user-model and WebSocket contracts are separate from Platform world-model ingestion and conversation events.

Summary

• External events (WebSocket) supply context to a live interaction.
• Additional context (user model) stores information for later interactions.
• Agent actions (tool calling) retrieve information when the workflow needs it.

Path	Availability	Context use	Direction	When to Use
External events	Interaction selected by event timing and control flags	Turn-scoped context; events are recorded	You push	Supply live application context
Additional context	Next interaction	Persists across sessions	You push	Data should outlive the session
Agent actions	After the configured tool returns	Tool result for the interaction	Agent pulls	Retrieve current external data

External Events During a Conversation

• Purpose: attach real-time facts (UI actions, device telemetry, page changes) to the current or next agent response.
• Transport: WebSocket client.new-text-message with message_type: 'external-event'.
• Timing: events sent before the end of the user's turn are associated with that interaction. Otherwise, they apply to the next turn.
• Select start_interaction according to whether the event should initiate an interaction or wait for the next one. Review interruption and timing rules in the linked protocol guide; sending context does not prove that the model used it in its reply.

External Events & Multi-Stream (WebSocket)

Tip: you can also start a REST conversation with an initial external event using initial_message_type: "external-event".

Create

Additional Context (Push, Next Interaction)

• Purpose: push updates from your systems into the user model when the change doesn't need to affect the current in-session turn.
• Transport: REST update of additional_context on the user.
• Typical use: event or state updates surfaced on your side (for example, CRM status changes, profile edits, a scheduled sync). Not real-time in the middle of a turn.
• Availability:

  • REST flows: available to the next interaction after the update call completes.
  • WebSocket flows: not guaranteed to appear mid-turn; typically visible in the next interaction. Updates are applied per turn, so a write made mid-turn over an open WebSocket is not picked up until the next interaction.
• Use this when the information should outlive the current session or connection and doesn't need to be reflected in the current reply.

User Models

Agent Actions (Tool Calling)

• Purpose: let the agent pull data on demand from your systems (APIs, databases) during a turn.
• Behavior: the agent issues tool or action calls that you expose, and the responses become part of the current decision and reply.
• Use this for dynamic retrieval (checking order status, fetching appointments) instead of pushing context ahead of time.

Events

Choosing the Right Path

Use external events for live application context, additional context for stored user information, and tool calls for a current lookup. Inspect the resulting interaction to verify that the required information was available and used correctly.

For the Platform API, use Data & World Model for retained source observations and projected entity state, Voice Agent for live voice events, and Conversations for text and messaging lifecycle. Choose the documented Platform mechanism for the target runtime instead of applying the Classic fields above.

Consistency and Latency Notes

• External events are turn-scoped and processed in order on the WebSocket connection.
• Additional context writes are persisted and visible on the next interaction. Don't rely on mid-turn visibility over WebSocket.
• Tool response timing depends on the operation and its upstream system. Handle timeout and failure explicitly; do not infer success from a completed agent response.