> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/operations/devops/information-ingestion-and-exchange.md).

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

| Path               | Latency                                    | Persistence              | Direction   | When to Use                         |
| ------------------ | ------------------------------------------ | ------------------------ | ----------- | ----------------------------------- |
| External events    | Current or next turn                       | Turn-scoped              | You push    | Data must land in the current reply |
| Additional context | Next interaction                           | Persists across sessions | You push    | Data should outlive the session     |
| Agent actions      | Within the turn (bounded by your upstream) | Not stored by default    | Agent pulls | Agent decides when to fetch         |

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

{% 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.