Table of Contents

Interface IChannelAdapter

Namespace
Microsoft.Agents.Builder
Assembly
Microsoft.Agents.Builder.dll

Represents an Adapter that can connect an Agent to a service endpoint.

public interface IChannelAdapter

Remarks

The Adapter encapsulates processing a received Activity, creates an ITurnContext and calls OnTurnAsync(ITurnContext, CancellationToken). When your Agent receives an activity, response are sent to the caller via SendActivityAsync(IActivity, CancellationToken).

Properties

MiddlewareSet

Gets the collection of middleware in the Adapter's pipeline.

IMiddlewareSet MiddlewareSet { get; }

Property Value

IMiddlewareSet

The middleware collection for the pipeline.

OnTurnError

Gets or sets an error handler that can catch exceptions in the middleware or application.

Func<ITurnContext, Exception, Task> OnTurnError { get; set; }

Property Value

Func<ITurnContext, Exception, Task>

An error handler that can catch exceptions in the middleware or application.

Methods

ContinueConversationAsync(ClaimsIdentity, ConversationReference, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, ConversationReference reference, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

reference ConversationReference

A reference to the conversation to continue.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(ClaimsIdentity, ConversationReference, string, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, ConversationReference reference, string audience, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

reference ConversationReference

A reference to the conversation to continue.

audience string

A value signifying the recipient of the proactive message.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(ClaimsIdentity, IActivity, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

continuationActivity IActivity

An Microsoft.Agents.Core.Models.Activity with the appropriate Microsoft.Agents.Core.Models.ConversationReference with which to continue the conversation.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

A task that represents the work queued to execute.

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(ClaimsIdentity, IActivity, string, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

Task ContinueConversationAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, string audience, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

continuationActivity IActivity

An Microsoft.Agents.Core.Models.Activity with the appropriate Microsoft.Agents.Core.Models.ConversationReference with which to continue the conversation.

audience string

A value signifying the recipient of the proactive message.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most _channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(string, ConversationReference, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

Task ContinueConversationAsync(string agentId, ConversationReference reference, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

agentId string

The application ID of the Agent.

reference ConversationReference

A reference to the conversation to continue.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most _channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

ContinueConversationAsync(string, IActivity, AgentCallbackHandler, CancellationToken)

Sends a proactive message to a conversation.

Task ContinueConversationAsync(string agentId, IActivity continuationActivity, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

agentId string

The application ID of the Agent.

continuationActivity IActivity

An Microsoft.Agents.Core.Models.Activity with the appropriate Microsoft.Agents.Core.Models.ConversationReference with which to continue the conversation.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Remarks

Call this method to proactively send a message to a conversation. Most channels require a user to initiate a conversation with an Agent before the Agent can send activities to the user.

CreateConversationAsync(string, string, string, string, ConversationParameters, AgentCallbackHandler, CancellationToken)

Creates a conversation on the specified channel.

Task CreateConversationAsync(string agentAppId, string channelId, string serviceUrl, string audience, ConversationParameters conversationParameters, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

agentAppId string

TThe application ID of the Agent.

channelId string

The ID for the channel.

serviceUrl string

The channel's service URL endpoint.

audience string

The audience for the connector.

conversationParameters ConversationParameters

The conversation information to use to create the conversation.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Remarks

To start a conversation, your Agent must know its account information and the user's account information on that channel. Most channels only support initiating a direct message (non-group) conversation.

The adapter attempts to create a new conversation on the channel, and then sends a conversationUpdate Activity through its middleware pipeline to the callback method.

If the conversation is established with the specified users, the ID of the activity's Microsoft.Agents.Core.Models.Activity.Conversation will contain the ID of the new conversation.

DeleteActivityAsync(ITurnContext, ConversationReference, CancellationToken)

When overridden in a derived class, deletes an existing activity in the conversation.

Task DeleteActivityAsync(ITurnContext turnContext, ConversationReference reference, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The context object for the turn.

reference ConversationReference

Conversation reference for the activity to delete.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Remarks

The Microsoft.Agents.Core.Models.ConversationReference.ActivityId of the conversation reference identifies the activity to delete.

See Also

ProcessActivityAsync(ClaimsIdentity, IActivity, AgentCallbackHandler, CancellationToken)

Creates a turn context and runs the middleware pipeline for an incoming TRUSTED activity.

Task<InvokeResponse> ProcessActivityAsync(ClaimsIdentity claimsIdentity, IActivity activity, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the request.

activity IActivity

The incoming activity.

callback AgentCallbackHandler

The code to run at the end of the adapter's middleware pipeline.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task<InvokeResponse>

If an Invoke Activity was received, an Microsoft.Agents.Core.Models.InvokeResponse, otherwise null.

ProcessProactiveAsync(ClaimsIdentity, IActivity, IAgent, CancellationToken, string) 

Task ProcessProactiveAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, IAgent agent, CancellationToken cancellationToken, string audience = null)

Parameters

claimsIdentity ClaimsIdentity
continuationActivity IActivity
agent IAgent
cancellationToken CancellationToken
audience string

Returns

Task

ProcessProactiveAsync(ClaimsIdentity, IActivity, string, AgentCallbackHandler, CancellationToken)

The implementation for continue conversation.

Task ProcessProactiveAsync(ClaimsIdentity claimsIdentity, IActivity continuationActivity, string audience, AgentCallbackHandler callback, CancellationToken cancellationToken)

Parameters

claimsIdentity ClaimsIdentity

A ClaimsIdentity for the conversation.

continuationActivity IActivity

The continuation Microsoft.Agents.Core.Models.Activity used to create the ITurnContext.

audience string

The audience for the call.

callback AgentCallbackHandler

The method to call for the resulting Agent turn.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

SendActivitiesAsync(ITurnContext, IActivity[], CancellationToken)

When overridden in a derived class, sends activities to the conversation.

Task<ResourceResponse[]> SendActivitiesAsync(ITurnContext turnContext, IActivity[] activities, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The context object for the turn.

activities IActivity[]

The activities to send.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task<ResourceResponse[]>

If the activities are successfully sent, the task result contains an array of Microsoft.Agents.Core.Models.ResourceResponse objects containing the IDs that the receiving channel assigned to the activities.

See Also

UpdateActivityAsync(ITurnContext, IActivity, CancellationToken)

When overridden in a derived class, replaces an existing activity in the conversation.

Task<ResourceResponse> UpdateActivityAsync(ITurnContext turnContext, IActivity activity, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The context object for the turn.

activity IActivity

New replacement activity.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task<ResourceResponse>

If the activity is successfully sent, the task result contains a Microsoft.Agents.Core.Models.ResourceResponse object containing the ID that the receiving channel assigned to the activity.

Before calling this, set the ID of the replacement activity to the ID of the activity to replace.

See Also

Use(IMiddleware)

Adds middleware to the adapter's pipeline.

IChannelAdapter Use(IMiddleware middleware)

Parameters

middleware IMiddleware

The middleware to add.

Returns

IChannelAdapter

The updated IChannelAdapter object.

Remarks

Middleware is added to the adapter at initialization time. For each turn, the adapter calls middleware in the order in which you added it.

See Also

ITurnContext
IActivity
IAgent