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. This is the activity that was received from the user or channel and triggered the creation of this context. |
| adapter | Gets the adapter that created this context. The adapter is responsible for sending and receiving activities to and from the user's channel. |
| 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. The locale affects language-dependent operations like formatting dates or numbers. |
| responded | Gets or sets whether the turn has sent a response to the user. This is used to track whether the agent has responded to the user's activity. Once set to true, it cannot be set back to false. |
| streaming |
|
| turn |
Gets the turn state collection for storing data during the turn. The turn state collection provides a dictionary-like interface for storing arbitrary data that needs to be accessible during the processing of the current 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. This method follows a middleware pattern, allowing multiple handlers to be chained together. Handlers can modify activities or inject new ones. |
| on |
Registers a handler for intercepting activity updates. |
| send |
Sends multiple activities to the sender of the incoming activity. This method applies conversation references to each activity and emits them through the middleware chain before sending them to the adapter. |
| send |
Sends an activity to the sender of the incoming activity. 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. |
| send |
Sends a trace activity for debugging purposes. Trace activities are typically used for debugging and are only visible in channels that support them, like the Bot Framework Emulator. |
| update |
Updates an existing activity in the conversation. This can be used to edit previously sent activities, for example to update the content of an adaptive card or change a message. |
| 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
Gets the incoming activity that started this turn.
This is the activity that was received from the user or channel and triggered the creation of this context.
Activity activityProperty Value
adapter
Gets the adapter that created this context.
The adapter is responsible for sending and receiving activities to and from the user's channel.
BaseAdapter adapterProperty Value
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.
The locale affects language-dependent operations like formatting dates or numbers.
undefined | string localeProperty Value
undefined | string
responded
Gets or sets whether the turn has sent a response to the user.
This is used to track whether the agent has responded to the user's activity. Once set to true, it cannot be set back to false.
boolean respondedProperty Value
boolean
streamingResponse
StreamingResponse streamingResponseProperty Value
StreamingResponse
turnState
Gets the turn state collection for storing data during the turn.
The turn state collection provides a dictionary-like interface for storing arbitrary data that needs to be accessible during the processing of the current 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.
This method follows a middleware pattern, allowing multiple handlers to be chained together. Handlers can modify activities or inject new ones.
function onSendActivities(handler: SendActivitiesHandler): TurnContextParameters
- handler
- SendActivitiesHandler
The handler to register
Returns
The current TurnContext instance for chaining
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.
This method applies conversation references to each activity and emits them through the middleware chain before sending them to the adapter.
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
sendActivity(string | Activity, string, string)
Sends an activity to the sender of the incoming activity.
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.
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
sendTraceActivity(string, any, string, string)
Sends a trace activity for debugging purposes.
Trace activities are typically used for debugging and are only visible in channels that support them, like the Bot Framework Emulator.
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
updateActivity(Activity)
Updates an existing activity in the conversation.
This can be used to edit previously sent activities, for example to update the content of an adaptive card or change a message.
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
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