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

# Information Ingestion & Exchange

Choose external events, stored user context, or tool retrieval for Classic conversations, with links to the separate Platform data and session contracts.

This page covers the **Classic API**. Choose a path based on when the conversation needs the information and whether it should remain available to later interactions. These Classic user-model and WebSocket contracts are separate from Platform world-model ingestion and conversation events.

## Summary

* **External events (WebSocket)** supply context to a live interaction.
* **Additional context (user model)** stores information for later interactions.
* **Agent actions (tool calling)** retrieve information when the workflow needs it.

| Path               | Availability                                           | Context use                              | Direction   | When to Use                     |
| ------------------ | ------------------------------------------------------ | ---------------------------------------- | ----------- | ------------------------------- |
| External events    | Interaction selected by event timing and control flags | Turn-scoped context; events are recorded | You push    | Supply live application context |
| Additional context | Next interaction                                       | Persists across sessions                 | You push    | Data should outlive the session |
| Agent actions      | After the configured tool returns                      | Tool result for the interaction          | Agent pulls | Retrieve current external data  |

## External Events During a Conversation <a href="#external-events-live-fastest" id="external-events-live-fastest"></a>

* **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.
* Select `start_interaction` according to whether the event should initiate an interaction or wait for the next one. Review interruption and timing rules in the linked protocol guide; sending context does not prove that the model used it in its 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

Use external events for live application context, additional context for stored user information, and tool calls for a current lookup. Inspect the resulting interaction to verify that the required information was available and used correctly.

For the **Platform API**, use [Data & World Model](/developer-guide/platform-api/data-world-model.md) for retained source observations and projected entity state, [Voice Agent](/developer-guide/platform-api/conversations/voice-agent.md) for live voice events, and [Conversations](/developer-guide/platform-api/conversations.md) for text and messaging lifecycle. Choose the documented Platform mechanism for the target runtime instead of applying the Classic fields above.

## 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 response timing depends on the operation and its upstream system. Handle timeout and failure explicitly; do not infer success from a completed agent response.


---

# 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.concurrence.com/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.