Navigation
- 00.OVERVIEW
- Action Planner
- Actions
- AI System
- Application class
- Augmentations
- Data Sources
- Function Calls
- Moderator
- Planner
- Powered by AI
- Prompts
- Streaming
- Turns
- User Authentication
In a conversation, people often speak one-at-a-time, taking turns speaking. With a bot, it generally reacts to user input. Within the Teams AI Library, a turn consists of the user's incoming activity to the bot and any activity the bot sends back to the user as an immediate response. You can think of a turn as the processing associated with the bot receiving a given activity.
In each turn the turn context and the turn state are configured to manage conversational data.
The turn context object provides information about the activity such as the sender and receiver, the channel, and other data needed to process the activity.
The turn context is one of the most important abstractions in the SDK. Not only does it carry the inbound activity to all the middleware components and the application logic but it also provides the mechanism whereby the components and the bot logic can send outbound activities.
The turn context object is accessible from the activity handler or an action. Here's how to use it send a message back to the user in an activity handler:
app.OnActivity(ActivityTypes.Message, async (ITurnContext turnContext, TurnState turnState, CancellationToken cancellationToken) =>
{
// Extract user's message
string message = turnContext.Activity.Text;
await turnContext.sendActivity(`You said: ${message}`);
})
app.activity(ActivityTypes.Message, async (context: TurnContext, state: ApplicationTurnState) => {
// Extract user's message
let message = context.activity.text;
await context.sendActivity(`You said: ${message}`);
});
@app.activity("message")
async def on_message(context: TurnContext, state: TurnState):
# Extract user's message
message = context.activity.text
await context.send_activity(f"You said: {message}")
return True
The turn state object stores cookie-like data for the current turn. Just like the turn context, it is carried through the entire application logic, including the activity handlers and the AI System. Unlike the turn context, the turn state is not fixed and is meant to be configured to each application-specific use case. It is common for apps to have conversation state, user state, and temp (temporary) state, but as a developer you can add or remove state objects to fit your needs.
It is used to store information like the user's message, the conversation history, and any custom data configured by the application code.
This is how a bot can keep track of the number of messages send by the user using the turn state:
app.OnActivity(ActivityTypes.Message, async (ITurnContext turnContext, AppState turnState, CancellationToken cancellationToken) =>
{
int count = turnState.Conversation.MessageCount;
// Increment count state.
turnState.Conversation.MessageCount = ++count;
// Send a message back to the user....
});
app.activity(ActivityTypes.Message, async (context: TurnContext, state: ApplicationTurnState) => {
let count = state.conversation.value.count ?? 0;
// Increment count state
state.conversation.value.count += 1;
// Send a message back to the user....
});
@app.activity("message")
async def on_message(context: TurnContext, state: AppTurnState):
count = state.conversation.count
# Increment count state
state.conversation.count += 1
# Send a message back to the user....
return True
What happens when the user sends a message to the bot?
When a message is sent by the user it is routed to the bots HTTP POST
endpoint /api/messages
, which
starts the routing process.