# Information Ingestion & Exchange

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.

{% content-ref url="/pages/lF0Oh8O7Odic2iZpEmAL" %}
[External Events & Multi-Stream (WebSocket)](/developer-guide/classic-api/core-api/conversations/conversations-realtime-external-events.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/dQSRSiEACAn2dGIOEJ0m" %}
[Create](/developer-guide/classic-api/core-api/conversations/conversations-create.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/vX6z4zD2a8fjLjPeW9FZ" %}
[User Models](/developer-guide/classic-api/core-api/users/user-models.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/kCrJX14EAGxaN1HezBV6" %}
[Events](/developer-guide/classic-api/core-api/conversations/conversations-events.md)
{% 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 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/developer-guide/operations/devops/information-ingestion-and-exchange.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.