Information Ingestion & Exchange

Three paths for getting external information into ongoing conversations or user models.

Amigo supports three primary paths for getting information into an ongoing experience or into a user model. Which one you reach for depends on how urgently the data needs to show up and how long it should stick around.

Summary

• External events (WebSocket): fastest path. Turn-scoped context during a live conversation.

• Additional context (user model): next fastest. Persists across sessions and shows up in the next interaction.

• Agent actions (tool calling): the agent proactively fetches data from your systems during a turn.

External Events (Live, Fastest)

• 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.

• Use this when the information needs to land in the current agent 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. This is the next-fastest route after external events, because transaction guarantees are per connection and per turn.

• 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

• Need it in the current reply? Use external events (WebSocket).

• Need it to persist for future sessions? Update additional context.

• Need the agent to query systems autonomously? Provide agent actions (tools).

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 responses arrive within the same turn, but are bounded by your upstream latency.