Table of Contents

Interface ITurnContext

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

Provides context for a turn of an Agent.

public interface ITurnContext

Remarks

Context provides information needed to process an incoming Microsoft.Agents.Core.Models.IActivity. The context object is created by a IChannelAdapter and persists for the length of the turn.

Properties

Activity

Gets the Activity for this Turn. This is the incoming Microsoft.Agents.Core.Models.IActivity.

IActivity Activity { get; }

Property Value

IActivity

The activity for this turn of the Agent.

Adapter

Gets the Adapter that created this context object.

IChannelAdapter Adapter { get; }

Property Value

IChannelAdapter

The Adapter that created this context object.

Identity 

ClaimsIdentity Identity { get; }

Property Value

ClaimsIdentity

Responded

Gets a value indicating whether at least one response was sent for the current turn.

bool Responded { get; }

Property Value

bool

true if at least one response was sent for the current turn; otherwise, false.

See Also

Services 

TurnContextStateCollection Services { get; }

Property Value

TurnContextStateCollection

StackState 

TurnContextStateCollection StackState { get; }

Property Value

TurnContextStateCollection

StreamingResponse

Provides access to the IStreamingResponse to allow streaming of chunked messages (for example, via streaming AI responses).

IStreamingResponse StreamingResponse { get; }

Property Value

IStreamingResponse

Methods

DeleteActivityAsync(ConversationReference, CancellationToken)

Deletes an existing activity.

Task DeleteActivityAsync(ConversationReference conversationReference, CancellationToken cancellationToken = default)

Parameters

conversationReference ConversationReference

The conversation containing 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

The conversation reference's Microsoft.Agents.Core.Models.ConversationReference.ActivityId indicates the activity in the conversation to delete.

Not all channels support this operation. For channels that don't, this call may throw an exception.

See Also

DeleteActivityAsync(string, CancellationToken)

Deletes an existing activity.

Task DeleteActivityAsync(string activityId, CancellationToken cancellationToken = default)

Parameters

activityId string

The ID of 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

Not all channels support this operation. For channels that don't, this call may throw an exception.

See Also

OnDeleteActivity(DeleteActivityHandler)

Adds a response handler for delete activity operations.

ITurnContext OnDeleteActivity(DeleteActivityHandler handler)

Parameters

handler DeleteActivityHandler

The handler to add to the context object.

Returns

ITurnContext

The updated context object.

Remarks

When the context's DeleteActivityAsync(string, CancellationToken) is called, the adapter calls the registered handlers in the order in which they were added to the context object.

Exceptions

ArgumentNullException

handler is null.

See Also

OnSendActivities(SendActivitiesHandler)

Adds a response handler for send activity operations.

ITurnContext OnSendActivities(SendActivitiesHandler handler)

Parameters

handler SendActivitiesHandler

The handler to add to the context object.

Returns

ITurnContext

The updated context object.

Remarks

When the context's SendActivityAsync(IActivity, CancellationToken) or SendActivitiesAsync(IActivity[], CancellationToken) method is called, the adapter calls the registered handlers in the order in which they were added to the context object.

See Also

OnUpdateActivity(UpdateActivityHandler)

Adds a response handler for update activity operations.

ITurnContext OnUpdateActivity(UpdateActivityHandler handler)

Parameters

handler UpdateActivityHandler

The handler to add to the context object.

Returns

ITurnContext

The updated context object.

Remarks

When the context's UpdateActivityAsync(IActivity, CancellationToken) is called, the adapter calls the registered handlers in the order in which they were added to the context object.

See Also

SendActivitiesAsync(IActivity[], CancellationToken)

Sends a set of activities to the sender of the incoming activity.

Task<ResourceResponse[]> SendActivitiesAsync(IActivity[] activities, CancellationToken cancellationToken = default)

Parameters

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

SendActivityAsync(IActivity, CancellationToken)

Sends an activity to the sender of the incoming activity.

Task<ResourceResponse> SendActivityAsync(IActivity activity, CancellationToken cancellationToken = default)

Parameters

activity IActivity

The activity 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 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.

See Also

SendActivityAsync(string, string, string, CancellationToken)

Sends a message activity to the sender of the incoming activity.

Task<ResourceResponse> SendActivityAsync(string text, string speak = null, string inputHint = "acceptingInput", CancellationToken cancellationToken = default)

Parameters

text string

The text of the message to send.

speak string

Optional, text to be spoken by your Agent on a speech-enabled channel.

inputHint string

Optional, indicates whether your Agent is accepting, expecting, or ignoring user input after the message is delivered to the client. Microsoft.Agents.Core.Models.InputHints defines the possible values. Default is Microsoft.Agents.Core.Models.InputHints.AcceptingInput.

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 that contains the ID that the receiving channel assigned to the activity.

See the channel's documentation for limits imposed upon the contents of text.

To control various characteristics of your Agent's speech such as voice, rate, volume, pronunciation, and pitch, specify speak in Speech Synthesis Markup Language (SSML) format.

See Also

TraceActivityAsync(string, object, string, string, CancellationToken)

Sends a trace activity to the IChannelAdapter for logging purposes.

Task<ResourceResponse> TraceActivityAsync(string name, object value = null, string valueType = null, string label = null, CancellationToken cancellationToken = default)

Parameters

name string

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.Name property.

value object

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.Value property.

valueType string

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.ValueType property.

label string

The value to assign to the activity's Microsoft.Agents.Core.Models.Activity.Label property.

cancellationToken CancellationToken

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

Returns

Task<ResourceResponse>

If the adapter is being hosted in the Emulator, the task result contains a Microsoft.Agents.Core.Models.ResourceResponse object with the original trace activity's ID; otherwise, it contains a Microsoft.Agents.Core.Models.ResourceResponse object containing the ID that the receiving channel assigned to the activity.

UpdateActivityAsync(IActivity, CancellationToken)

Replaces an existing activity.

Task<ResourceResponse> UpdateActivityAsync(IActivity activity, CancellationToken cancellationToken = default)

Parameters

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.

Not all channels support this operation. For channels that don't, this call may throw an exception.

See Also

See Also

IAgent