> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/agents/how-agents-work/message-distribution.md).

# Message Distribution

When an Event-to-Flow agent is configured with more than one parallel instance, the messages waiting in the agent's backlog are distributed across those instances. The way that distribution happens depends on the agent's **Processing Type** and its **Event Lag Threshold**.

## Distribution Behavior

With **Ordered** processing, messages sharing the same key are always routed to the same instance, in arrival order. Different keys are distributed across the available instances.

With **Unordered** processing, any message may be handed to any instance — work is balanced across instances in a round-robin fashion.

In both modes, messages are handed to instances regardless of whether any single instance is still processing its previous message.

See [Definition](/documentation-and-resources/components-and-data/agents/agent-details/definition.md) for how to set the Processing Type.

## How the Backlog Is Shared

Each instance is given a modest buffer of messages at a time, sized proportionally to the **Event Lag Threshold** across the agent's **Maximum Instances**. The practical effect: messages are distributed across instances in a round-robin pattern, and adding more instances actually adds throughput rather than leaving instances idle.

## Tuning Guidance

* **Event Lag Threshold** does double duty: it triggers auto-scaling *and* governs how many messages are allowed to be buffered for a given instance at a time.
* If your agent processes events **quickly**, set a higher Event Lag Threshold so each instance has more work ready to go.
* If your agent processes events **slowly** and you rely on lag-based scaling, set a lower threshold — this gives scaling room to trigger appropriately based on real backlog growth.
* Maximum Instances appears in the formula to keep scaling well-behaved, but it isn't the right knob for tuning distribution. Focus on the threshold.


---

# 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.contextual.io/documentation-and-resources/components-and-data/agents/how-agents-work/message-distribution.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.