TurnContext class
Represents the context for a single turn in a conversation between a user and an agent.
Remarks
TurnContext is a central concept in the Agents framework - it contains:
- The incoming activity that started the turn
- Access to the adapter that can be used to send responses
- A state collection for storing information during the turn
- Methods for sending, updating, and deleting activities
- Middleware hooks for intercepting activity operations
The TurnContext object is created by the adapter when an activity is received and is passed to the agent's logic to process the turn. It maintains information about the conversation and provides methods to send responses.
This class follows the builder pattern for registering middleware handlers.
Constructors
| Turn |
Initializes a new instance of the TurnContext class. |
| Turn |
Properties
| activity | Gets the incoming activity that started this turn. |
| adapter | Gets the adapter that created this context. |
| buffered |
A list of reply activities that are buffered until the end of the turn. This is primarily used with the 'expectReplies' delivery mode where all activities during a turn are collected and returned as a single response. |
| locale | Gets or sets the locale for the turn. |
| responded | Gets or sets whether the turn has sent a response to the user. |
| streaming |
|
| turn |
Gets the turn state collection for storing data during the turn. |
Methods
| delete |
Deletes an activity from the conversation. |
| get |
Gets the content of an attachment. |
| get |
Gets information about an attachment. |
| on |
Registers a handler for intercepting activity deletions. |
| on |
Registers a handler for intercepting and processing activities being sent. |
| on |
Registers a handler for intercepting activity updates. |
| send |
Sends multiple activities to the sender of the incoming activity. |
| send |
Sends an activity to the sender of the incoming activity. |
| send |
Sends a trace activity for debugging purposes. |
| update |
Updates an existing activity in the conversation. |
| upload |
Uploads an attachment to the conversation. |
Constructor Details
TurnContext(BaseAdapter, Activity)
Initializes a new instance of the TurnContext class.
new TurnContext(adapterOrContext: BaseAdapter, request: Activity)Parameters
- adapterOrContext
- BaseAdapter
The adapter that created this context, or another TurnContext to clone
- request
- Activity
The activity for the turn (required when first parameter is an adapter)
TurnContext(TurnContext)
Property Details
activity
adapter
bufferedReplyActivities
A list of reply activities that are buffered until the end of the turn.
This is primarily used with the 'expectReplies' delivery mode where all activities during a turn are collected and returned as a single response.
bufferedReplyActivities: Activity[]Property Value
Activity[]
locale
Gets or sets the locale for the turn.
undefined | string localeProperty Value
undefined | string
responded
Gets or sets whether the turn has sent a response to the user.
boolean respondedProperty Value
boolean
streamingResponse
turnState
Gets the turn state collection for storing data during the turn.
TurnContextStateCollection turnStateProperty Value
Method Details
deleteActivity(string | ConversationReference)
Deletes an activity from the conversation.
function deleteActivity(idOrReference: string | ConversationReference): Promise<void>Parameters
- idOrReference
-
string | ConversationReference
The ID of the activity to delete or a conversation reference
Returns
Promise<void>
A promise that resolves when the activity has been deleted
getAttachment(string, string)
Gets the content of an attachment.
function getAttachment(attachmentId: string, viewId: string): Promise<ReadableStream>Parameters
- attachmentId
-
string
The ID of the attachment
- viewId
-
string
The view to get
Returns
Promise<ReadableStream>
A promise that resolves to a readable stream of the attachment content
getAttachmentInfo(string)
Gets information about an attachment.
function getAttachmentInfo(attachmentId: string): Promise<AttachmentInfo>Parameters
- attachmentId
-
string
The ID of the attachment
Returns
Promise<AttachmentInfo>
A promise that resolves to the attachment information
onDeleteActivity(DeleteActivityHandler)
Registers a handler for intercepting activity deletions.
function onDeleteActivity(handler: DeleteActivityHandler): TurnContextParameters
- handler
- DeleteActivityHandler
The handler to register
Returns
The current TurnContext instance for chaining
onSendActivities(SendActivitiesHandler)
Registers a handler for intercepting and processing activities being sent.
function onSendActivities(handler: SendActivitiesHandler): TurnContextParameters
- handler
- SendActivitiesHandler
The handler to register
Returns
The current TurnContext instance for chaining
Remarks
This method follows a middleware pattern, allowing multiple handlers to be chained together. Handlers can modify activities or inject new ones.
onUpdateActivity(UpdateActivityHandler)
Registers a handler for intercepting activity updates.
function onUpdateActivity(handler: UpdateActivityHandler): TurnContextParameters
- handler
- UpdateActivityHandler
The handler to register
Returns
The current TurnContext instance for chaining
sendActivities(Activity[])
Sends multiple activities to the sender of the incoming activity.
function sendActivities(activities: Activity[]): Promise<ResourceResponse[]>Parameters
- activities
-
Activity[]
The array of activities to send
Returns
Promise<ResourceResponse[]>
A promise that resolves to an array of resource responses
Remarks
This method applies conversation references to each activity and emits them through the middleware chain before sending them to the adapter.
sendActivity(string | Activity, string, string)
Sends an activity to the sender of the incoming activity.
function sendActivity(activityOrText: string | Activity, speak?: string, inputHint?: string): Promise<undefined | ResourceResponse>Parameters
- activityOrText
-
string | Activity
The activity to send or a string for a simple message
- speak
-
string
Optional text to be spoken by the agent
- inputHint
-
string
Optional input hint to indicate if the agent is expecting input
Returns
Promise<undefined | ResourceResponse>
A promise that resolves to the resource response or undefined
Remarks
This is the primary method used to respond to the user. It automatically addresses the response to the correct conversation and recipient using information from the incoming activity.
sendTraceActivity(string, any, string, string)
Sends a trace activity for debugging purposes.
function sendTraceActivity(name: string, value?: any, valueType?: string, label?: string): Promise<undefined | ResourceResponse>Parameters
- name
-
string
The name/category of the trace
- value
-
any
The value/data to include in the trace
- valueType
-
string
Optional type name for the value
- label
-
string
Optional descriptive label for the trace
Returns
Promise<undefined | ResourceResponse>
A promise that resolves to the resource response or undefined
Remarks
Trace activities are typically used for debugging and are only visible in channels that support them, like the Bot Framework Emulator.
updateActivity(Activity)
Updates an existing activity in the conversation.
function updateActivity(activity: Activity): Promise<void>Parameters
- activity
- Activity
The activity to update with its ID specified
Returns
Promise<void>
A promise that resolves when the activity has been updated
Remarks
This can be used to edit previously sent activities, for example to update the content of an adaptive card or change a message.
uploadAttachment(string, AttachmentData)
Uploads an attachment to the conversation.
function uploadAttachment(conversationId: string, attachmentData: AttachmentData): Promise<ResourceResponse>Parameters
- conversationId
-
string
The ID of the conversation
- attachmentData
- AttachmentData
The attachment data to upload
Returns
Promise<ResourceResponse>
A promise that resolves to the resource response