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

{% content-ref url="../../classic-api/core-api/conversations/conversations-realtime-external-events" %}
[conversations-realtime-external-events](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-realtime-external-events)
{% endcontent-ref %}

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

{% content-ref url="../../classic-api/core-api/conversations/conversations-create" %}
[conversations-create](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-create)
{% endcontent-ref %}

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

{% content-ref url="../../classic-api/core-api/users/user-models" %}
[user-models](https://docs.amigo.ai/developer-guide/classic-api/core-api/users/user-models)
{% endcontent-ref %}

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

{% content-ref url="../../classic-api/core-api/conversations/conversations-events" %}
[conversations-events](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-events)
{% endcontent-ref %}

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