Skip to main content

Updating Model Context

A widget can contribute content to the model context so your app can use it on future turns.

ui/update-model-context is sent over the same messageBack channel other Teams surfaces use, so it arrives as a message activity. Tool calls are different: they arrive as htmlwidget/calltool invoke activities (see tool calls). This particular request is fire-and-forget: your app does not send a response.

(If you have used adaptive cards, this is the widget-side equivalent of Action.Submit.)

Preview

HTML Widgets are in preview and the API surface may change. HTML Widgets are planned for public preview on 11/16.

The request​

When a widget calls ui/update-model-context, the Teams client delivers an ordinary message activity, and the McpUiUpdateModelContextRequest arrives on its value field:

{
"type": "message",
"value": {
"method": "ui/update-model-context",
"params": {
"content": [{ "type": "text", "text": "The user selected the blue theme." }],
"structuredContent": { "theme": "blue" }
}
}
}

Inside value, the content field reuses the same content block union as a tool call result, and the structuredContent field carries arbitrary structured data. You never parse this by hand; the helper below reads value off the activity and returns the typed request.

Parsing the request​

The SDK provides a helper that reads the typed request off an incoming message activity. It returns the parsed request when the activity carries a valid ui/update-model-context request, and nothing otherwise, so you can branch on the result inside your message handler.

Call try_get_widget_model_context inside your message handler. It returns the typed request when the activity carries a valid ui/update-model-context request, and None otherwise.

from microsoft_teams.api import MessageActivity
from microsoft_teams.apps import ActivityContext, App
from microsoft_teams.apps.utils.html_widget import try_get_widget_model_context

app = App()


@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]) -> None:
model_context = try_get_widget_model_context(ctx.activity)
if model_context is not None:
# Use model_context.params.content / model_context.params.structured_content
# to update your model context for future turns. No response is sent.
print("model context update:", model_context.params)
return

# ... handle other messages

The helper is tolerant of two wire shapes: the raw request object, and an envelope of the form { "type": "widgetModelContext", "data": <request> }. Both resolve to the same typed request.