@microsoft/agents-hosting-extensions-msteams 1.7.0-beta.8.gc2b086aef6

package/src/taskModules/taskModule.ts

@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Activity, ActivityTypes } from '@microsoft/agents-activity'
+import { AgentApplication, RouteHandler, RouteRank, RouteSelector, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import type { TaskModuleRequest, TaskModuleResponse } from '@microsoft/teams.api'
+import { TeamsTurnContext } from '../teamsTurnContext'
+
+const DEFAULT_TASK_DATA_KEY = 'task'
+
+function matchesTaskKeyValue (context: TurnContext, value: string | RegExp, key: string): boolean {
+  const taskData = (context.activity.value as any)?.data
+  if (!taskData || typeof taskData !== 'object') return false
+  const dataValue = taskData[normalizeTaskDataKey(key)]
+  if (typeof dataValue !== 'string') return false
+  return typeof value === 'string' ? dataValue === value : value.test(dataValue)
+}
+
+function isTaskInvoke (context: TurnContext, name: string): boolean {
+  return (
+    context.activity.type === ActivityTypes.Invoke &&
+    context.activity.channelId === 'msteams' &&
+    context.activity.name === name &&
+    context.activity.value != null
+  )
+}
+
+function normalizeTaskDataKey (key: string): string {
+  return key.trim() || DEFAULT_TASK_DATA_KEY
+}
+
+function matchesTaskInvoke (context: TurnContext, name: string, value: string | RegExp | null, key: string): boolean {
+  if (!isTaskInvoke(context, name)) {
+    return false
+  }
+
+  if (value == null || (typeof value === 'string' && value.trim() === '')) {
+    return true
+  }
+
+  return matchesTaskKeyValue(context, value, key)
+}
+
+type FetchHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState, request: TaskModuleRequest) => Promise<TaskModuleResponse>
+type SubmitHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState, request: TaskModuleRequest) => Promise<TaskModuleResponse>
+
+/**
+ * Registers handlers for Microsoft Teams task module invoke activities.
+ *
+ * @typeParam TState - The turn state type used by the agent application.
+ */
+export class TaskModule<TState extends TurnState> {
+  _app: AgentApplication<TState>
+
+  /**
+   * Creates a Teams task module route helper.
+   *
+   * @param app - The agent application that receives the registered routes.
+   */
+  constructor (app: AgentApplication<TState>) {
+    this._app = app
+  }
+
+  /**
+   * Registers a handler for Teams task/fetch invokes.
+   *
+   * @param value - Optional task data value or regular expression used to match the invoke.
+   * @param handler - Handler invoked with the task module request.
+   * @param key - Task data key to inspect when matching `value`. Defaults to `task`.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This task module helper for chaining.
+   */
+  onFetch (value: string | RegExp | null, handler: FetchHandler<TState>, key: string = DEFAULT_TASK_DATA_KEY, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(matchesTaskInvoke(context, 'task/fetch', value, key))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const request = context.activity.value as TaskModuleRequest
+      const response: TaskModuleResponse = await handler(new TeamsTurnContext(context), state, request)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = { status: 200, body: response }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams task/submit invokes.
+   *
+   * @param value - Optional task data value or regular expression used to match the invoke.
+   * @param handler - Handler invoked with the task module request.
+   * @param key - Task data key to inspect when matching `value`. Defaults to `task`.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This task module helper for chaining.
+   */
+  onSubmit (value: string | RegExp | null, handler: SubmitHandler<TState>, key: string = DEFAULT_TASK_DATA_KEY, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(matchesTaskInvoke(context, 'task/submit', value, key))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      const request = context.activity.value as TaskModuleRequest
+      const response: TaskModuleResponse = await handler(new TeamsTurnContext(context), state, request)
+      const invokeResponse = new Activity(ActivityTypes.InvokeResponse)
+      invokeResponse.value = { status: 200, body: response }
+      await context.sendActivity(invokeResponse)
+    }
+    this._app.addRoute(routeSel, routeHandler, true, rank, authHandlers)
+    return this
+  }
+}

package/src/teams/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './teamsTeam'

package/src/teams/teamsTeam.ts

@@ -0,0 +1,189 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { ActivityTypes } from '@microsoft/agents-activity'
+import { AgentApplication, RouteHandler, RouteRank, RouteSelector, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import { parseTeamsChannelData } from '../activity-extensions'
+import type { TeamInfo } from '@microsoft/teams.api'
+import { TeamsTurnContext } from '../teamsTurnContext'
+
+const TEAM_ARCHIVED_EVENT = 'teamArchived'
+const TEAM_UNARCHIVED_EVENT = 'teamUnarchived'
+const TEAM_RENAMED_EVENT = 'teamRenamed'
+const TEAM_RESTORED_EVENT = 'teamRestored'
+const TEAM_DELETED_EVENT = 'teamDeleted'
+const TEAM_HARD_DELETED_EVENT = 'teamHardDeleted'
+
+type TeamUpdateHandler<TState extends TurnState> = (context: TeamsTurnContext, state: TState, data: TeamInfo) => Promise<void>
+
+function isTeamUpdateEvent (context: TurnContext, eventType?: string): boolean {
+  const channelData = parseTeamsChannelData(context.activity.channelData)
+  const actualEventType = typeof channelData?.eventType === 'string' ? channelData.eventType.toLowerCase() : undefined
+  const expectedEventType = eventType?.toLowerCase()
+
+  return (
+    context.activity.type === ActivityTypes.ConversationUpdate &&
+    context.activity.channelId === 'msteams' &&
+    channelData?.team != null &&
+    (
+      expectedEventType != null
+        ? actualEventType === expectedEventType
+        : actualEventType?.startsWith('team') === true
+    )
+  )
+}
+
+function getTeamInfo (context: TurnContext): TeamInfo {
+  return parseTeamsChannelData(context.activity.channelData).team as TeamInfo
+}
+
+/**
+ * Registers handlers for Microsoft Teams team lifecycle events.
+ *
+ * @typeParam TState - The turn state type used by the agent application.
+ */
+export class TeamsTeam<TState extends TurnState = TurnState> {
+  private _app: AgentApplication<TState>
+
+  /**
+   * Creates a Teams team route helper.
+   *
+   * @param app - The agent application that receives the registered routes.
+   */
+  constructor (app: AgentApplication<TState>) {
+    this._app = app
+  }
+
+  /**
+   * Registers a handler for any Teams team update event.
+   *
+   * @param handler - Handler invoked with the Teams turn context, turn state, and team information.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This team helper for chaining.
+   */
+  onTeamEventReceived (handler: TeamUpdateHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isTeamUpdateEvent(context))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      await handler(new TeamsTurnContext(context), state, getTeamInfo(context))
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams team archived events.
+   *
+   * @param handler - Handler invoked with the archived team information.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This team helper for chaining.
+   */
+  onArchived (handler: TeamUpdateHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isTeamUpdateEvent(context, TEAM_ARCHIVED_EVENT))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      await handler(new TeamsTurnContext(context), state, getTeamInfo(context))
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams team unarchived events.
+   *
+   * @param handler - Handler invoked with the unarchived team information.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This team helper for chaining.
+   */
+  onUnarchived (handler: TeamUpdateHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isTeamUpdateEvent(context, TEAM_UNARCHIVED_EVENT))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      await handler(new TeamsTurnContext(context), state, getTeamInfo(context))
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams team renamed events.
+   *
+   * @param handler - Handler invoked with the renamed team information.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This team helper for chaining.
+   */
+  onRenamed (handler: TeamUpdateHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isTeamUpdateEvent(context, TEAM_RENAMED_EVENT))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      await handler(new TeamsTurnContext(context), state, getTeamInfo(context))
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams team restored events.
+   *
+   * @param handler - Handler invoked with the restored team information.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This team helper for chaining.
+   */
+  onRestored (handler: TeamUpdateHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isTeamUpdateEvent(context, TEAM_RESTORED_EVENT))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      await handler(new TeamsTurnContext(context), state, getTeamInfo(context))
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams team deleted events.
+   *
+   * @param handler - Handler invoked with the deleted team information.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This team helper for chaining.
+   */
+  onDeleted (handler: TeamUpdateHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isTeamUpdateEvent(context, TEAM_DELETED_EVENT))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      await handler(new TeamsTurnContext(context), state, getTeamInfo(context))
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+
+  /**
+   * Registers a handler for Teams team hard-deleted events.
+   *
+   * @param handler - Handler invoked with the hard-deleted team information.
+   * @param rank - Optional route rank used for route ordering.
+   * @param authHandlers - Optional authorization handlers required by the route.
+   * @returns This team helper for chaining.
+   */
+  onHardDeleted (handler: TeamUpdateHandler<TState>, rank: number = RouteRank.Unspecified, authHandlers: string[] = []) {
+    const routeSel: RouteSelector = (context: TurnContext) => {
+      return Promise.resolve(isTeamUpdateEvent(context, TEAM_HARD_DELETED_EVENT))
+    }
+    const routeHandler: RouteHandler<TState> = async (context: TurnContext, state: TState) => {
+      await handler(new TeamsTurnContext(context), state, getTeamInfo(context))
+    }
+    this._app.addRoute(routeSel, routeHandler, false, rank, authHandlers)
+    return this
+  }
+}

package/src/teamsActivity.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { Activity } from '@microsoft/agents-activity'
+import type { ChannelData } from '@microsoft/teams.api'
+
+/**
+ * A Teams activity whose channel-specific payload uses the Microsoft Teams API model.
+ *
+ * @remarks
+ * This is a type-only specialization of {@link Activity}. Teams activities keep
+ * their original runtime identity; no activity conversion or cloning occurs.
+ */
+export interface TeamsActivity extends Activity {
+  /**
+   * Channel-specific data for the Teams activity.
+   */
+  channelData?: ChannelData
+}

package/src/teamsActivityExtensions.ts

@@ -0,0 +1,99 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Activity } from '@microsoft/agents-activity'
+import type { ChannelData, OnBehalfOf } from '@microsoft/teams.api'
+import { parseTeamsChannelData } from './activity-extensions'
+
+/**
+ * Gets the Teams selected channel ID from the activity's channel data settings.
+ *
+ * @param activity - Activity containing Teams channel data.
+ * @returns The selected channel ID, if present.
+ */
+export function teamsGetSelectedChannelId (activity: Activity): string | undefined {
+  const channelData = parseTeamsChannelData(activity.channelData)
+  return (channelData as any)?.settings?.selectedChannel?.id
+}
+
+/**
+ * Gets the Teams channel ID from the activity's channel data.
+ *
+ * @param activity - Activity containing Teams channel data.
+ * @returns The Teams channel ID, if present.
+ */
+export function teamsGetChannelId (activity: Activity): string | undefined {
+  const channelData = parseTeamsChannelData(activity.channelData)
+  return (channelData as any)?.channel?.id
+}
+
+/**
+ * Gets the Teams meeting info from the activity's channel data.
+ *
+ * @param activity - Activity containing Teams channel data.
+ * @returns Teams meeting information, if present.
+ */
+export function teamsGetMeetingInfo (activity: Activity): ChannelData['meeting'] | undefined {
+  const channelData = parseTeamsChannelData(activity.channelData)
+  return channelData?.meeting
+}
+
+/**
+ * Gets the Teams team info from the activity's channel data.
+ *
+ * @param activity - Activity containing Teams channel data.
+ * @returns Teams team information, if present.
+ */
+export function teamsGetTeamInfo (activity: Activity): ChannelData['team'] | undefined {
+  const channelData = parseTeamsChannelData(activity.channelData)
+  return channelData?.team
+}
+
+/**
+ * Configures the activity to generate a notification within Teams.
+ * @param activity - The activity to configure.
+ * @param alertInMeeting - If true, renders a popup in meeting chat as well as the chat thread.
+ * @param externalResourceUrl - URL to external resource (must be in manifest's valid domains).
+ */
+export function teamsNotifyUser (activity: Activity, alertInMeeting: boolean = false, externalResourceUrl?: string): void {
+  if (!activity.channelData || typeof activity.channelData !== 'object') {
+    activity.channelData = {}
+  }
+  const channelData = activity.channelData as Record<string, unknown>
+  channelData.notification = {
+    alert: !alertInMeeting,
+    alertInMeeting,
+    ...(externalResourceUrl != null && { externalResourceUrl })
+  }
+}
+
+/**
+ * Gets the Teams OnBehalfOf list from the activity's channel data.
+ *
+ * @param activity - Activity containing Teams channel data.
+ * @returns The Teams on-behalf-of entries, if present.
+ */
+export function teamsGetTeamOnBehalfOf (activity: Activity): OnBehalfOf[] | undefined {
+  const channelData = parseTeamsChannelData(activity.channelData)
+  return (channelData as any)?.onBehalfOf
+}
+
+/**
+ * Adds the Teams feedback loop flag to the activity's channel data.
+ * Returns false if channel data is already set.
+ *
+ * @param activity - The activity to configure.
+ * @param feedbackLoopType - The feedback loop type value. Defaults to "default".
+ * @returns True when feedback loop channel data was added; otherwise false.
+ */
+export function teamsEnableFeedbackLoop (activity: Activity, feedbackLoopType: string = 'default'): boolean {
+  if (activity.channelData != null) {
+    return false
+  }
+  activity.channelData = {
+    feedbackLoop: {
+      type: feedbackLoopType
+    }
+  }
+  return true
+}

package/src/teamsAgentExtension.ts

@@ -0,0 +1,205 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Client as GraphClient } from '@microsoft/microsoft-graph-client'
+import { AgentApplication, AgentExtension, type Connections, TurnContext, TurnState } from '@microsoft/agents-hosting'
+import { Client as TeamsClient } from '@microsoft/teams.api'
+import { parseTeamsChannelData } from './activity-extensions'
+import { TeamsConfig } from './config/config'
+import { FileConsent } from './fileConsents/fileConsent'
+import { Meeting } from './meetings/meeting'
+import { Message } from './messages/message'
+import { MessageExtension } from './messageExtensions/messageExtension'
+import { TaskModule } from './taskModules/taskModule'
+import { TeamsChannel } from './channels/teamsChannel'
+import { TeamsTeam } from './teams/teamsTeam'
+import { setTeamsApiClient } from './teamsApiClientExtensions'
+import { applyTeamsHeaderPropagation } from './teamsHeaderPropagation'
+import { TeamsTurnContext } from './teamsTurnContext'
+import { createAppGraphClient, createUserGraphClient } from './graphClientFactory'
+import { Errors } from './errorHelper'
+
+const DEFAULT_GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0'
+
+/**
+ * Adds Microsoft Teams-specific routing, context helpers, and API clients to an agent application.
+ *
+ * Register an instance with `AgentApplication.registerExtension` to configure handlers for Teams
+ * events, message extensions, task modules, file consent flows, and related Teams capabilities.
+ *
+ * @typeParam TState - The turn state type used by the agent application.
+ */
+export class TeamsAgentExtension<TState extends TurnState = TurnState> extends AgentExtension<TState> {
+  private _app: AgentApplication<TState>
+  private _meetings: Meeting<TState>
+  private _messageExtensions: MessageExtension<TState>
+  private _taskModules: TaskModule<TState>
+  private _channels: TeamsChannel<TState>
+  private _teams: TeamsTeam<TState>
+  private _messages: Message<TState>
+  private _fileConsent: FileConsent<TState>
+  private _config: TeamsConfig<TState>
+
+  /**
+   * Creates a new Teams extension for the provided agent application.
+   *
+   * The extension configures Teams header propagation and prepares a Teams API client for each
+   * incoming Teams turn.
+   *
+   * @param app - The agent application to extend with Teams capabilities.
+   */
+  constructor (app: AgentApplication<TState>) {
+    super('msteams')
+    this._app = app
+    this._meetings = new Meeting(app)
+    this._messageExtensions = new MessageExtension(app)
+    this._taskModules = new TaskModule(app)
+    this._channels = new TeamsChannel(app)
+    this._teams = new TeamsTeam(app)
+    this._messages = new Message(app)
+    this._fileConsent = new FileConsent(app)
+    this._config = new TeamsConfig(app)
+
+    const headerPropagation = this._app.options.headerPropagation
+    this._app.options.headerPropagation = (headers) => {
+      headerPropagation?.(headers)
+      applyTeamsHeaderPropagation(headers)
+    }
+
+    this._app.onTurn('beforeTurn', async (context) => {
+      if (context.activity.channelId === this.channelId) {
+        setTeamsApiClient(context, this.channelId)
+        try {
+          context.activity.channelData = parseTeamsChannelData(context.activity.channelData)
+        } catch {
+          // ignore parse errors for unexpected channelData payloads
+        }
+      }
+      return true
+    })
+  }
+
+  /**
+   * Gets the route registration helper for Teams meeting events.
+   */
+  public get meetings (): Meeting<TState> {
+    return this._meetings
+  }
+
+  /**
+   * Gets the route registration helper for Teams message extension activities.
+   */
+  public get messageExtensions (): MessageExtension<TState> {
+    return this._messageExtensions
+  }
+
+  /**
+   * Gets the route registration helper for Teams task module invoke activities.
+   */
+  public get taskModules (): TaskModule<TState> {
+    return this._taskModules
+  }
+
+  /**
+   * Gets the route registration helper for Teams channel events.
+   */
+  public get channels (): TeamsChannel<TState> {
+    return this._channels
+  }
+
+  /**
+   * Gets the route registration helper for Teams team events.
+   */
+  public get teams (): TeamsTeam<TState> {
+    return this._teams
+  }
+
+  /**
+   * Gets the route registration helper for Teams message lifecycle events.
+   */
+  public get messages (): Message<TState> {
+    return this._messages
+  }
+
+  /**
+   * Gets the route registration helper for Teams file consent card actions.
+   */
+  public get fileConsent (): FileConsent<TState> {
+    return this._fileConsent
+  }
+
+  /**
+   * Gets the route registration helper for Teams app configuration invokes.
+   */
+  public get config (): TeamsConfig<TState> {
+    return this._config
+  }
+
+  /**
+   * Gets the Teams API client associated with the current turn.
+   *
+   * @param context - The turn context for the current Teams activity.
+   * @returns The Teams API client stored on the turn.
+   * @throws If the current turn has not been initialized with a Teams API client.
+   */
+  public getTeamsClient (context: TurnContext): TeamsClient {
+    return new TeamsTurnContext(context).client
+  }
+
+  /**
+   * Creates a Microsoft Graph client that obtains access tokens through the agent authorization system.
+   *
+   * @param context - The turn context used to acquire the user token.
+   * @param handlerName - Optional authorization handler name. Required when multiple handlers are configured.
+   * @param graphBaseUrl - Optional Graph base URL. Defaults to Microsoft Graph v1.0.
+   * @returns A Microsoft Graph client configured with the resolved authentication provider.
+   */
+  public getGraphClient (context: TurnContext, handlerName?: string, graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL): GraphClient {
+    if (!context) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'context' })
+    }
+
+    return createUserGraphClient(this._app.authorization, context, handlerName, graphBaseUrl)
+  }
+
+  /**
+   * Creates a Microsoft Graph client that obtains an app-only token from the connection resolved for the current turn.
+   *
+   * @param context - The turn context used to resolve the token connection.
+   * @param graphBaseUrl - Optional Graph base URL. Defaults to Microsoft Graph v1.0.
+   * @returns A Microsoft Graph client configured with application permissions.
+   */
+  public getAppGraphClient (context: TurnContext, graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL): GraphClient {
+    if (!context) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'context' })
+    }
+
+    const tokenProvider = this.getConnections().getTokenProviderFromActivity(context.identity, context.activity)
+    return createAppGraphClient(tokenProvider, graphBaseUrl)
+  }
+
+  /**
+   * Creates a Microsoft Graph client that obtains an app-only token from a named connection.
+   *
+   * @param connectionName - The configured token connection name.
+   * @param graphBaseUrl - Optional Graph base URL. Defaults to Microsoft Graph v1.0.
+   * @returns A Microsoft Graph client configured with application permissions.
+   */
+  public getAppGraphClientForConnection (connectionName: string, graphBaseUrl: string = DEFAULT_GRAPH_BASE_URL): GraphClient {
+    if (!connectionName) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphParameterRequired, undefined, { parameterName: 'connectionName' })
+    }
+
+    return createAppGraphClient(this.getConnections().getConnection(connectionName), graphBaseUrl)
+  }
+
+  private getConnections (): Connections {
+    const connections = this._app.options.connections ?? this._app.adapter.connectionManager
+    if (!connections) {
+      throw ExceptionHelper.generateException(Error, Errors.TeamsGraphConnectionsNotConfigured)
+    }
+
+    return connections
+  }
+}

package/src/teamsApiClientExtensions.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { ConnectorClient, TurnContext } from '@microsoft/agents-hosting'
+import { Client as TeamsClient } from '@microsoft/teams.api'
+import { Errors } from './errorHelper'
+
+/**
+ * Turn state key used to store the Teams API client for the current turn.
+ */
+export const TeamsClientKey = Symbol('TeamsClient')
+
+/**
+ * Creates and stores a Teams API client for the current Teams turn.
+ *
+ * @param context - Turn context whose turn state should receive the Teams client.
+ * @param channelId - Teams channel ID to match before creating the client. Defaults to `msteams`.
+ * @throws If the connector client or service URL required to create the Teams client is missing.
+ */
+export function setTeamsApiClient (context: TurnContext, channelId: string = 'msteams'): void {
+  if (context.activity.channelId !== channelId || context.turnState.has(TeamsClientKey)) {
+    return
+  }
+
+  const connectorClient = context.turnState.get<ConnectorClient>(context.adapter.ConnectorClientKey)
+  const serviceUrl = context.activity.serviceUrl ?? connectorClient?.httpClient.baseURL
+
+  if (!connectorClient) {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsApiClientSetupFailed, undefined, { missing: 'ConnectorClient in turnState' })
+  }
+
+  if (!serviceUrl) {
+    throw ExceptionHelper.generateException(Error, Errors.TeamsApiClientSetupFailed, undefined, { missing: 'activity.serviceUrl and ConnectorClient baseURL' })
+  }
+
+  context.turnState.set(
+    TeamsClientKey,
+    new TeamsClient(serviceUrl, {
+      headers: getClientHeaders(connectorClient)
+    })
+  )
+}
+
+function getClientHeaders (connectorClient: ConnectorClient): Record<string, string> {
+  return { ...connectorClient.httpClient.defaultHeaders }
+}