Information Ingestion & Exchange

Amigo supports three primary paths for getting information into an ongoing experience or into a user model. Choose the path based on immediacy needs and data lifecycle.

Summary

• External events (WebSocket): Fastest, turn-scoped context during live conversations.

• Additional context (User model): Next-fastest, persists across sessions; available next interaction.

• Agent actions (tool calling): Agent proactively fetches data from your systems.

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 when you need immediate incorporation into 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 changes don’t need to affect the current in‑session turn.

• Transport: REST update of additional_context on the user.

• Typical use: Event/state updates surfaced on your side (e.g., CRM status changes, profile edits, 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/turn.

• Use when the information should outlive the current session/connection and does not need to be reflected in the current reply.

User Models

Agent Actions (Tool Calling)

• Purpose: Let agents pull data on demand from your systems (APIs, databases) during a turn.

• Behavior: The agent issues tool/action calls you expose; responses become part of the current decision and reply.

• Use for dynamic retrieval (e.g., check order status, fetch 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 & 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 in WebSocket.

• Tool responses arrive within the same turn, but are bounded by your upstream latency.