IChannelAdapter.ProcessProactiveAsync Method

public System.Threading.Tasks.Task ProcessProactiveAsync(System.Security.Claims.ClaimsIdentity claimsIdentity, Microsoft.Agents.Core.Models.IActivity continuationActivity, Microsoft.Agents.Builder.IAgent agent, System.Threading.CancellationToken cancellationToken, string audience = default);

abstract member ProcessProactiveAsync : System.Security.Claims.ClaimsIdentity * Microsoft.Agents.Core.Models.IActivity * Microsoft.Agents.Builder.IAgent * System.Threading.CancellationToken * string -> System.Threading.Tasks.Task

Public Function ProcessProactiveAsync (claimsIdentity As ClaimsIdentity, continuationActivity As IActivity, agent As IAgent, cancellationToken As CancellationToken, Optional audience As String = Nothing) As Task

Parameters

Returns

public System.Threading.Tasks.Task ProcessProactiveAsync(System.Security.Claims.ClaimsIdentity claimsIdentity, Microsoft.Agents.Core.Models.IActivity continuationActivity, string audience, Microsoft.Agents.Builder.AgentCallbackHandler callback, System.Threading.CancellationToken cancellationToken);

abstract member ProcessProactiveAsync : System.Security.Claims.ClaimsIdentity * Microsoft.Agents.Core.Models.IActivity * string * Microsoft.Agents.Builder.AgentCallbackHandler * System.Threading.CancellationToken -> System.Threading.Tasks.Task

Public Function ProcessProactiveAsync (claimsIdentity As ClaimsIdentity, continuationActivity As IActivity, audience As String, callback As AgentCallbackHandler, cancellationToken As CancellationToken) As Task

Parameters

Returns

Remarks

A Turn, and the TurnContext, are in the context of an Activity. Normally this is from Activities arriving via an endpoint (api/messages) which are handled in ProcessActivityAsync(ClaimsIdentity, IActivity, AgentCallbackHandler, CancellationToken). Proactive is an Agent initiated Turn, typically for a different conversation.

The continuationActivity argument is used to "seed" the TurnContext created by the pipeline. It is not the Activity sent to the conversation. This is normally acquired by GetContinuationActivity(). This Activity becomes Activity within AgentCallbackHandler. The GetContinuationActivity methods creates a ContinueConversation Event Activity with Activity.Conversation, Activity.From, and Activity.Recipient from the ConversationReference.

As for ProcessActivity, the pipeline will call AgentCallbackHandler with the expected TurnContext. Actions are performed in this callback as would for any other turn, relative to continuationActivity.Conversation. For example, SendActivityAsync(IActivity, CancellationToken). State is supported by loading the desired state manually.

For example, from an AgentApplication RouteHandler, sending messages to another conversation would be the following. The variable proactiveReference (below) is a previously saved ConversationReference which is typically acquired by using ITurnContext.Activity.GetConversationReference() from a previous turn for a conversation.

Task OnSendProactiveAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
    await context.Adapter.ProcessProactiveAsync(
        turnContext.Identity,
        proactiveReference.GetContinuationActivity(),
        null,
        async(proactiveContext, proactiveCt) =>
        {
           // Middleware will have been executed

           // TurnState must be manually loaded and saved.
           var turnState = Options.TurnStateFactory();
           await turnState.LoadStateAsync(proactiveContext, cancellationToken: proactiveCt);

           // State is relative to the proactive conversation and user.
           turnState.Conversation.SetValue("lastConvoMessage", context.Activity.Text);

           // Perform actions as you would for any other turn.
           await proactiveContext.SendActivityAsync($"Proactive Conversation: {context.Activity.Text}", cancellationToken: proactiveCt);

           await turnState.SaveStateAsync(proactiveContext, cancellationToken: proactiveCt);
        },
        cancellationToken);
}