Concurrent Message Handling

The uAgents v0.23.6 release introduces an important new capability for local agents: optional concurrent message handling. This means that agents can optionally process multiple incoming messages at the same time. This guide explains what that means and how to enable it.

Overview

Local Agents could only process one incoming message at a time. This meant that:

• Message handlers were executed sequentially.
• If an agent performed a long-running task (e.g., image generation, video generation, or heavy computation), then, all other incoming messages were blocked until that task completed.

This behavior was intentional and necessary because certain shared global objects, such as storage and wallet, are not thread-safe. Additionally, ensuring data consistency required that handlers could not run in parallel.

While this design was safe, it limited throughput and responsiveness for Agents handling multiple requests.

Now, with this latest release, you can explicitly enable concurrent message handling for any Agent you create using the uAgents Framework. This feature simply allows you to:

• Process multiple incoming messages at the same time;
• Execute long-running tasks without blocking other requests.

This feature is opt-in and disabled by default. Running handlers concurrently introduces risks when working with shared state, so existing agents continue to process messages sequentially to preserve data consistency. Developers must explicitly enable concurrency once they are ready to handle these risks.

When concurrent message handling feature is enabled, shared objects such as ctx.storage and ctx.wallet are accessed by multiple handlers at the same time. These objects are not thread-safe, which can lead to race conditions, inconsistent data, or incorrect wallet operations. To reduce risk, avoid concurrent writes to shared storage, do not perform overlapping wallet transactions, and design handlers so that shared state access is minimal, predictable, or serialized when consistency is required.

Why Using Concurrent Message Handling?

This feature is very useful whenever:

• Your Agent performs long-running or blocking operations:
  • Image generation;
  • Video generation;
  • External API calls.
• Your Agent needs to handle multiple independent user requests efficiently.
• Your Agent logic is mostly stateless, or shared state is carefully controlled.

How to Enable Concurrency

To enable concurrency just pass the following flag when creating your Agent:

agent = Agent(
    ...,
    handle_messages_concurrently=True,
)

Once enabled:

• Message handlers may run in parallel
• The agent can continue processing new requests even while long-running tasks are in progress.