@microsoft/agents-hosting 1.9.0-beta.3.gb2d23c1c44 → 1.9.1

package/src/app/agentApplication.ts

@@ -20,6 +20,7 @@ import { TranscriptLoggerMiddleware } from '../transcript'
 import { CloudAdapter } from '../cloudAdapter'
 import { Authorization, UserAuthorization, AuthorizationManager } from './auth'
 import { Proactive } from './proactive'
+import { AgentApplicationRateLimiter } from './rateLimit'
 import { JwtPayload } from 'jsonwebtoken'
 import { trace, debug, redactString } from '@microsoft/agents-telemetry'
 import { AgentApplicationTraceDefinitions } from '../observability'
@@ -104,6 +105,7 @@ export class AgentApplication<TState extends TurnState> {
   private readonly _proactive?: Proactive<TState>
   protected readonly _extensions: AgentExtension<TState>[] = []
   private readonly _adaptiveCards: AdaptiveCardsActions<TState>
+  private readonly _rateLimiter?: AgentApplicationRateLimiter
 
   /**
    * Creates a new instance of AgentApplication.
@@ -141,6 +143,7 @@ export class AgentApplication<TState extends TurnState> {
       longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false,
       removeRecipientMention: options?.removeRecipientMention !== undefined ? options.removeRecipientMention : true,
       transcriptLogger: options?.transcriptLogger || undefined,
+      rateLimit: options?.rateLimit || undefined,
     }
 
     this._adaptiveCards = new AdaptiveCardsActions<TState>(this)
@@ -148,11 +151,20 @@ export class AgentApplication<TState extends TurnState> {
     if (this._options.adapter) {
       this._adapter = this._options.adapter
     } else {
-      this._adapter = new CloudAdapter()
+      this._adapter = new CloudAdapter(
+        undefined,
+        undefined,
+        undefined,
+        { configurationContext: this._options.configurationContext }
+      )
     }
 
     this._adapter.setAgentName(this._options.agentName)
 
+    if (this._options.rateLimit && this._options.rateLimit.length > 0) {
+      this._rateLimiter = new AgentApplicationRateLimiter(this._options.rateLimit, this._options.storage)
+    }
+
     // Create Proactive whenever proactive options are explicitly configured or a storage
     // backend is available — no explicit `proactive` option is required.
     if (this._options.proactive !== undefined || this._options.storage !== undefined) {
@@ -201,6 +213,7 @@ export class AgentApplication<TState extends TurnState> {
       fileDownloaders: this._options.fileDownloaders ? 'configured' : undefined,
       turnStateFactory: options?.turnStateFactory ? 'custom' : 'default',
       adaptiveCardsOptions: this._options.adaptiveCardsOptions,
+      rateLimitRules: this._options.rateLimit?.length,
     })
   }
 
@@ -208,7 +221,7 @@ export class AgentApplication<TState extends TurnState> {
    * Gets the authorization instance for the application.
    *
    * @returns The authorization instance.
-   * @throws Error if no authentication options were configured.
+   * @throws Error if no authorization handlers were resolved.
    */
   public get authorization (): Authorization {
     if (this._authorizationManager.handlers.length === 0) {
@@ -495,7 +508,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    * @param handler - The handler function to be called after successful sign-in.
    * @returns The current instance of the application.
-   * @throws Error if authentication options were not configured.
+   * @throws Error if no authorization handlers were resolved.
    *
    * @remarks
    * This method allows you to perform actions after a user has successfully authenticated.
@@ -510,11 +523,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    */
   public onSignInSuccess (handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this {
-    if (this.options.authorization) {
-      this.authorization.onSignInSuccess(handler)
-    } else {
-      throw ExceptionHelper.generateException(Error, Errors.AuthorizationOptionNotAvailable)
-    }
+    this.authorization.onSignInSuccess(handler)
     return this
   }
 
@@ -523,7 +532,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    * @param handler - The handler function to be called after a failed sign-in attempt.
    * @returns The current instance of the application.
-   * @throws Error if authentication options were not configured.
+   * @throws Error if no authorization handlers were resolved.
    *
    * @remarks
    * This method allows you to handle cases where a user fails to authenticate,
@@ -538,11 +547,7 @@ export class AgentApplication<TState extends TurnState> {
    *
    */
   public onSignInFailure (handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this {
-    if (this.options.authorization) {
-      this.authorization.onSignInFailure(handler)
-    } else {
-      throw ExceptionHelper.generateException(Error, Errors.AuthorizationOptionNotAvailable)
-    }
+    this.authorization.onSignInFailure(handler)
     return this
   }
 
@@ -675,6 +680,14 @@ export class AgentApplication<TState extends TurnState> {
    * ```
    */
   public async runInternal (turnContext: TurnContext): Promise<boolean> {
+    if (this._rateLimiter) {
+      const rateLimitDecision = await this._rateLimiter.shouldAllowTurn(turnContext)
+      if (!rateLimitDecision.allowed) {
+        await this._rateLimiter.handleThrottledTurn(turnContext, rateLimitDecision.rule!, rateLimitDecision.result!)
+        return false
+      }
+    }
+
     const { authorized, context } = await this.handleAuthorization(turnContext)
 
     if (!authorized) {

package/src/app/agentApplicationBuilder.ts

@@ -3,11 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { Storage } from '../storage'
+import { StorageProvider } from '../storage'
 import { AgentApplication } from './agentApplication'
 import { AgentApplicationOptions } from './agentApplicationOptions'
 import { AuthorizationOptions } from './auth/types'
 import { ProactiveOptions } from './proactive'
+import { RateLimitRule } from './rateLimit'
 import { TurnState } from './turnState'
 import { TypingOptions } from './agentApplicationOptions'
 
@@ -31,7 +32,7 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
    * @param storage The storage implementation to use
    * @returns This builder instance for chaining
    */
-  public withStorage (storage: Storage): this {
+  public withStorage (storage: StorageProvider): this {
     this._options.storage = storage
     return this
   }
@@ -86,6 +87,16 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
     return this
   }
 
+  /**
+   * Configures rate limit rules for incoming turns.
+   * @param rules The rate limit rules to apply
+   * @returns This builder instance for chaining
+   */
+  public withRateLimit (rules: RateLimitRule[]): this {
+    this._options.rateLimit = rules
+    return this
+  }
+
   /**
    * Builds and returns a new AgentApplication instance configured with the provided options.
    * @returns A new AgentApplication instance

package/src/app/agentApplicationOptions.ts

@@ -4,7 +4,7 @@
  */
 
 import { CloudAdapter } from '../cloudAdapter'
-import { Storage } from '../storage'
+import { StorageProvider } from '../storage'
 import { TranscriptLogger } from '../transcript'
 import { AdaptiveCardsOptions } from './adaptiveCards'
 import { InputFileDownloader } from './inputFileDownloader'
@@ -13,6 +13,8 @@ import { HeaderPropagationDefinition } from '../headerPropagation'
 import { AuthorizationOptions } from './auth/types'
 import { Connections } from '../auth/connections'
 import { ProactiveOptions } from './proactive'
+import { RateLimitRule } from './rateLimit'
+import { ConfigurationContext } from '../configuration/configuration'
 
 /**
  * Typing timer settings for a specific channel or the global default.
@@ -52,6 +54,12 @@ export interface TypingOptions extends TypingTimingOptions {
  * custom state management specific to your agent's needs.
  */
 export interface AgentApplicationOptions<TState extends TurnState> {
+  /**
+   * Optional host-scoped external configuration used by the application's
+   * default adapter and authorization handlers.
+   */
+  configurationContext?: ConfigurationContext;
+
   /**
    * The adapter used for handling bot interactions with various messaging platforms.
    * This adapter manages the communication layer between your agent and the Bot Framework.
@@ -72,12 +80,12 @@ export interface AgentApplicationOptions<TState extends TurnState> {
 
   /**
    * The storage mechanism for persisting conversation and user state across turns.
-   * This can be any implementation of the Storage interface, such as memory storage
-   * for development or blob storage for production scenarios.
+   * This can be a legacy Storage implementation, a StorageV2 implementation,
+   * or a built-in storage provider.
    *
    * @default undefined (no persistence)
    */
-  storage?: Storage;
+  storage?: StorageProvider;
 
   /**
    * Whether to start a typing indicator timer when the bot begins processing a message.
@@ -201,4 +209,10 @@ export interface AgentApplicationOptions<TState extends TurnState> {
    * When provided, `app.proactive` will be available.
    */
   proactive?: ProactiveOptions
+
+  /**
+   * Optional. Rate limit rules for incoming turns.
+   * When omitted or empty, no rate limiting is applied.
+   */
+  rateLimit?: RateLimitRule[]
 }

package/src/app/auth/authorization.ts

@@ -3,21 +3,25 @@
  * Licensed under the MIT License.
  */
 
-import { debug } from '@microsoft/agents-telemetry'
+import { TokenCredential } from '@azure/core-auth'
 import { ExceptionHelper } from '@microsoft/agents-activity'
+import { debug } from '@microsoft/agents-telemetry'
+import { DelegatedTokenCredential } from '../../auth/delegatedTokenCredential'
+import { Errors } from '../../errorHelper'
 import { TokenResponse } from '../../oauth'
 import { TurnContext } from '../../turnContext'
 import { TurnState } from '../turnState'
 import { AuthorizationManager } from './authorizationManager'
 import { AuthorizationHandlerTokenOptions } from './types'
-import { Errors } from '../../errorHelper'
 
 const logger = debug('agents:authorization')
 
 export interface Authorization {
   getToken(context: TurnContext, authHandlerId: string): Promise<TokenResponse>
+  getTokenAsTokenCredential?(context: TurnContext, authHandlerId: string): TokenCredential
   exchangeToken(context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse>
   exchangeToken(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>
+  exchangeTokenAsTokenCredential?(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): TokenCredential
   signOut(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<void>
   onSignInSuccess(handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>): void
   onSignInFailure(handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>): void
@@ -75,6 +79,31 @@ export class UserAuthorization implements Authorization {
     return { token }
   }
 
+  /**
+   * Creates a token credential backed by the current turn's user token.
+   *
+   * @param context - The context object for the current turn.
+   * @param authHandlerId - ID of the auth handler to use.
+   * @returns A {@link TokenCredential} that resolves to the current turn's user token.
+   * @throws {Error} If the auth handler is not configured.
+   *
+   * @remarks
+   * The returned credential is scoped to this `context` and should only be used during the
+   * current turn. Do not cache it or pass it to a client that outlives the turn; create a new
+   * credential in each turn instead.
+   *
+   * @example
+   * ```typescript
+   * const credential = auth.getTokenAsTokenCredential(context, 'microsoft');
+   * const client = new SomeAzureClient(endpoint, credential);
+   * ```
+   *
+   * @public
+   */
+  public getTokenAsTokenCredential (context: TurnContext, authHandlerId: string): TokenCredential {
+    return new DelegatedTokenCredential(async () => await this.getToken(context, authHandlerId))
+  }
+
   /**
    * @deprecated
    * Exchanges a token for a new token with different scopes.
@@ -153,6 +182,42 @@ export class UserAuthorization implements Authorization {
     throw ExceptionHelper.generateException(Error, Errors.InvalidExchangeTokenParameters)
   }
 
+  /**
+   * Creates a token credential that exchanges the user token for requested scopes during the current turn.
+   *
+   * @param context - The context object for the current turn.
+   * @param authHandlerId - ID of the auth handler to use.
+   * @param options - Optional token options. If `connection` and `scopes` are NOT provided, the auth handler's
+   * configured `obo` options are used. Provide `options` only to override them for a specific credential.
+   * @returns A {@link TokenCredential} that exchanges the current turn's user token for the requested scopes.
+   * @throws {Error} If the auth handler is not configured.
+   *
+   * @remarks
+   * The returned credential is scoped to this `context` and should only be used during the current turn.
+   * Do not cache it or pass it to a client that outlives the turn; create a new credential in each turn instead.
+   * Scopes requested from the credential (via `TokenCredential.getToken`) are combined with `options.scopes`,
+   * and duplicate scopes are removed.
+   *
+   * @example
+   * ```typescript
+   * const credential = auth.exchangeTokenAsTokenCredential(
+   *   context,
+   *   'microsoft',
+   *   { connection: 'oboConnection', scopes: ['https://graph.microsoft.com/.default'] }
+   * );
+   * const client = new SomeAzureClient(endpoint, credential);
+   * ```
+   *
+   * @public
+   */
+  public exchangeTokenAsTokenCredential (context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): TokenCredential {
+    return new DelegatedTokenCredential(async (scopes) => {
+      const scopeSet = new Set([...scopes, ...(options?.scopes ?? [])])
+      const mergedScopes = Array.from(scopeSet)
+      return await this.exchangeToken(context, authHandlerId, { connection: options?.connection, scopes: mergedScopes })
+    })
+  }
+
   /**
    * Signs out the current user.
    *