Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
What is proactive messaging?
Most agent interactions are reactive—a user sends a message, and the agent responds. Proactive messaging inverts this pattern. The agent initiates contact with a user or resumes a conversation without waiting for an incoming message.
This pattern unlocks a fundamental category of agent behaviors that request/response alone can't achieve.
Two core operations
Proactive messaging relies on two core operations:
- Continue an existing conversation
- Create (initiate) a new conversation
Continue
Continue resumes an existing conversation. The agent must know where to send the message, including the user, the channel, and the service. The agent needs a conversation object that it previously captured during a reactive turn. That conversation must persist beyond the turn that created it. The agent needs to store the conversation object somewhere before it can use it later.
Create
Create starts a brand-new conversation with a user who never spoke to the agent. The agent doesn't need a prior conversation. The agent constructs the destination from known information (tenant ID, user ID, channel). If the agent wants to continue that conversation proactively in the future, it needs to keep the conversation returned when it's created.
Storing conversations
Because continuing a conversation requires information that only exists during a live turn, you must preserve that information beyond the turn that captured it. Two approaches exist for preserving this information:
- Use the SDK's built-in conversation store: The SDK can persist the conversation during a reactive turn and return an identifier your code can use later to continue the conversation or send activities.
- Manage storage yourself: Capture the conversation from the current turn and serialize it to any store you control. Pass it back to the SDK to continue or send operations directly when needed.
Either way, persistent storage (Azure Cosmos DB, Blob Storage) is required in production. In-memory storage works for development only.
Two trigger patterns
Internal trigger
The agent queues a background task inside the same process. When the work finishes, the background task uses the captured conversation to resume contact with the user. No external service is involved.
Typical flow:
The user sends a request. The agent captures the conversation and queues a background task.
A background task completes.
The task uses the conversation to send a message or continue the conversation.
External trigger
The agent delegates work to an external service. When that service finishes, it calls back to the agent by some mechanism (HTTP, Service Bus, and so on). The Agents SDK can optionally expose HTTP endpoints that map directly to specific continuation handlers, making it straightforward for external services to trigger the right logic.
Typical flow:
The user sends a request. The agent sends the conversation and task details to an external service.
An external service completes its work.
An external service calls the agent's proactive HTTP endpoint with the result.
The agent runs the appropriate continuation handler and responds to the user.
What the proactive module provides
| Capability | Description |
|---|---|
| Send activity | Sends a single message to an existing conversation without invoking the full routing pipeline. |
| Continue conversation | Runs a handler inside the conversation context, with access to turn state, middleware, and OAuth tokens. |
| Create conversation | Creates a brand-new conversation and optionally continues it immediately. |
| Conversation storage | Persist and retrieve conversations by ID using the SDK's built-in store. |
| HTTP endpoints (optional) | Expose proactive endpoints so external services can trigger send, continue, or create operations over HTTP. |
Summary
Proactive messaging transforms agents from passive responders into active participants, and decouples the receipt of a request from the delivery of a response. This change lets agents integrate better with real-time events, background processes, and external systems, and reach out to the user. This functionality enables experiences that feel natural and timely rather than limited to the conversational turn model.