@microsoft/agents-hosting 1.6.0-beta.9.gce9d8facd2 → 1.6.1

package/src/connector-client/connectorClient.ts

@@ -1,5 +1,8 @@
-/** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
-import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
 import { AuthConfiguration } from '../auth/authConfiguration'
 import { AuthProvider } from '../auth/authProvider'
 import { debug } from '@microsoft/agents-telemetry'
@@ -11,72 +14,47 @@ import { ResourceResponse } from './resourceResponse'
 import { AttachmentInfo } from './attachmentInfo'
 import { AttachmentData } from './attachmentData'
 import { normalizeOutgoingActivity } from '../activityWireCompat'
-import { getProductInfo } from '../getProductInfo'
+import { applyUserAgentHeader, getProductInfo } from '../getProductInfo'
 import { HeaderPropagation, HeaderPropagationCollection } from '../headerPropagation'
 import { trace } from '@microsoft/agents-telemetry'
 import { ConnectorClientTraceDefinitions } from '../observability'
+import { parseIntEnv } from '../utils/env'
+import { HttpClient, HttpRequestConfig, HttpResponse, HttpError } from '../httpClient'
 
 const logger = debug('agents:connector-client')
 
+function formatHttpErrorMessage (error: HttpError): string {
+  const responseData = error.response?.data
+  if (responseData === undefined) {
+    return error.message
+  }
+
+  try {
+    const serializedResponseData = JSON.stringify(responseData)
+    return serializedResponseData === undefined ? error.message : `${error.message}: ${serializedResponseData}`
+  } catch {
+    return error.message
+  }
+}
+
 export { getProductInfo }
 
 /**
  * ConnectorClient is a client for interacting with the Microsoft Connector API.
  */
 export class ConnectorClient {
-  protected readonly _axiosInstance: AxiosInstance
+  protected readonly _httpClient: HttpClient
 
   /**
    * Private constructor for the ConnectorClient.
-   * @param axInstance - The AxiosInstance to use for HTTP requests.
+   * @param httpClient - The HttpClient instance to use for HTTP requests.
    */
-  protected constructor (axInstance: AxiosInstance) {
-    this._axiosInstance = axInstance
-    this._axiosInstance.interceptors.request.use((config) => {
-      const { method, url, data, headers, params } = config
-      // Clone headers and remove Authorization before logging
-      const { Authorization, authorization, ...headersToLog } = headers || {}
-      logger.debug('Request: ', {
-        host: this._axiosInstance.getUri(),
-        url,
-        data,
-        method,
-        params,
-        headers: headersToLog
-      })
-      return config
-    })
-    this._axiosInstance.interceptors.response.use(
-      (config) => {
-        const { status, statusText, config: requestConfig } = config
-        logger.debug('Response: ', {
-          status,
-          statusText,
-          host: this._axiosInstance.getUri(),
-          url: requestConfig?.url,
-          data: config.config.data,
-          method: requestConfig?.method,
-        })
-        return config
-      },
-      (error) => {
-        const { code, message, stack, response } = error
-        const errorDetails = {
-          code,
-          host: this._axiosInstance.getUri(),
-          url: error.config.url,
-          method: error.config.method,
-          data: error.config.data,
-          message: message + JSON.stringify(response?.data),
-          stack,
-        }
-        return Promise.reject(errorDetails)
-      }
-    )
+  protected constructor (httpClient: HttpClient) {
+    this._httpClient = httpClient
   }
 
-  public get axiosInstance (): AxiosInstance {
-    return this._axiosInstance
+  public get httpClient (): HttpClient {
+    return this._httpClient
   }
 
   /**
@@ -112,28 +90,23 @@ export class ConnectorClient {
     headers?: HeaderPropagationCollection
   ): ConnectorClient {
     const headerPropagation = headers ?? new HeaderPropagation({})
-    const userAgent = headerPropagation.outgoing['user-agent']
-    const productInfo = getProductInfo()
-    if (!userAgent) {
-      headerPropagation.add({ 'User-Agent': productInfo })
-    } else if (!userAgent.includes(productInfo)) {
-      headerPropagation.concat({ 'User-Agent': productInfo })
-    }
+    applyUserAgentHeader(headerPropagation)
     headerPropagation.override({
       Accept: 'application/json',
-      'Content-Type': 'application/json', // Required by transformRequest
-    })
-
-    const axiosInstance = axios.create({
-      baseURL,
-      headers: headerPropagation.outgoing,
+      'Content-Type': 'application/json',
     })
 
+    const clientHeaders: Record<string, string> = { ...headerPropagation.outgoing }
     if (token && token.length > 1) {
-      axiosInstance.defaults.headers.common.Authorization = `Bearer ${token}`
+      clientHeaders.Authorization = `Bearer ${token}`
     }
 
-    return new ConnectorClient(axiosInstance)
+    const httpClient = new HttpClient({
+      baseURL,
+      headers: clientHeaders,
+    })
+
+    return new ConnectorClient(httpClient)
   }
 
   /**
@@ -143,12 +116,12 @@ export class ConnectorClient {
    */
   public async getConversations (continuationToken?: string): Promise<ConversationsResult> {
     return trace(ConnectorClientTraceDefinitions.getConversations, async ({ record }) => {
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: '/v3/conversations',
         params: continuationToken ? { continuationToken } : undefined
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ConversationsResult>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -159,14 +132,14 @@ export class ConnectorClient {
       if (!userId || !conversationId) {
         throw ExceptionHelper.generateException(Error, Errors.UserIdAndConversationIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: `v3/conversations/${conversationId}/members/${userId}`,
         headers: {
           'Content-Type': 'application/json'
         }
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ChannelAccount>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -183,7 +156,7 @@ export class ConnectorClient {
         ...body,
         activity: normalizeOutgoingActivity(body.activity)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: '/v3/conversations',
         headers: {
@@ -191,7 +164,7 @@ export class ConnectorClient {
         },
         data: payload
       }
-      const response: AxiosResponse = await this._axiosInstance(config)
+      const response = await this.executeRequest<ConversationResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -219,7 +192,7 @@ export class ConnectorClient {
 
       const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
 
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: `v3/conversations/${trimmedConversationId}/activities/${encodeURIComponent(activityId)}`,
         headers: {
@@ -228,7 +201,7 @@ export class ConnectorClient {
         data: normalizeOutgoingActivity(body),
         ...(body.channelId === Channels.Msteams && body.isTargetedActivity() ? { params: { isTargetedActivity: 'true' } } : {})
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       logger.info('Reply to conversation/activity: ', response.data.id!, activityId)
       return response.data
@@ -236,20 +209,19 @@ export class ConnectorClient {
   }
 
   /**
-   * Trim the conversationId to a fixed length when creating the URL. This is applied only in specific API calls for agentic calls.
+   * Trim and sanitize the conversationId when creating the URL for agentic calls in agents channels.
    * @param conversationId The ID of the conversation to potentially truncate.
    * @param activity The activity object used to determine if truncation is necessary.
-   * @returns The original or truncated conversationId, depending on the channel and activity role.
+   * @returns The original conversationId for non-agents channels/non-agentic roles, otherwise a trimmed and sanitized value.
    */
   private conditionallyTruncateConversationId (conversationId: string, activity: Activity): string {
     if (
-      (activity.channelIdChannel === Channels.Msteams || activity.channelIdChannel === Channels.Agents) &&
+      activity.channelIdChannel === Channels.Agents &&
       (activity.from?.role === RoleTypes.AgenticIdentity || activity.from?.role === RoleTypes.AgenticUser)) {
-      let maxLength = 150
-      if (process.env.MAX_APX_CONVERSATION_ID_LENGTH && !isNaN(parseInt(process.env.MAX_APX_CONVERSATION_ID_LENGTH, 10))) {
-        maxLength = parseInt(process.env.MAX_APX_CONVERSATION_ID_LENGTH, 10)
-      }
-      return conversationId.length > maxLength ? conversationId.substring(0, maxLength) : conversationId
+      const maxLength = parseIntEnv(process.env.MAX_APX_CONVERSATION_ID_LENGTH, 150)
+      const trimmedConversationId = conversationId.length > maxLength ? conversationId.substring(0, maxLength) : conversationId
+
+      return trimmedConversationId.replace(/[/\\#?]/g, '_')
     } else {
       return conversationId
     }
@@ -275,7 +247,7 @@ export class ConnectorClient {
 
       const trimmedConversationId: string = this.conditionallyTruncateConversationId(conversationId, body)
 
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: `v3/conversations/${trimmedConversationId}/activities`,
         headers: {
@@ -285,7 +257,7 @@ export class ConnectorClient {
         ...(body.channelId === Channels.Msteams && body.isTargetedActivity() ? { params: { isTargetedActivity: 'true' } } : {})
 
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -308,7 +280,7 @@ export class ConnectorClient {
         throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
       }
       record({ conversationId, activityId })
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'put',
         url: `v3/conversations/${conversationId}/activities/${activityId}`,
         headers: {
@@ -317,7 +289,7 @@ export class ConnectorClient {
         data: normalizeOutgoingActivity(body),
         ...(body.channelId === Channels.Msteams && body.isTargetedActivity() ? { params: { isTargetedActivity: 'true' } } : {})
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -341,7 +313,7 @@ export class ConnectorClient {
       if (!conversationId || !activityId) {
         throw ExceptionHelper.generateException(Error, Errors.ConversationIdAndActivityIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'delete',
         url: `v3/conversations/${conversationId}/activities/${activityId}`,
         headers: {
@@ -349,7 +321,7 @@ export class ConnectorClient {
         },
         ...(isTargetedActivity ? { params: { isTargetedActivity: 'true' } } : {})
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<void>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -370,7 +342,7 @@ export class ConnectorClient {
       if (conversationId === undefined) {
         throw ExceptionHelper.generateException(Error, Errors.ConversationIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'post',
         url: `v3/conversations/${conversationId}/attachments`,
         headers: {
@@ -378,7 +350,7 @@ export class ConnectorClient {
         },
         data: body
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<ResourceResponse>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -397,14 +369,14 @@ export class ConnectorClient {
       if (attachmentId === undefined) {
         throw ExceptionHelper.generateException(Error, Errors.AttachmentIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: `v3/attachments/${attachmentId}`,
         headers: {
           'Content-Type': 'application/json'
         }
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<AttachmentInfo>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
@@ -428,16 +400,66 @@ export class ConnectorClient {
       if (viewId === undefined) {
         throw ExceptionHelper.generateException(Error, Errors.ViewIdRequired)
       }
-      const config: AxiosRequestConfig = {
+      const config: HttpRequestConfig = {
         method: 'get',
         url: `v3/attachments/${attachmentId}/views/${viewId}`,
         headers: {
           'Content-Type': 'application/json'
-        }
+        },
+        responseType: 'stream'
       }
-      const response = await this._axiosInstance(config)
+      const response = await this.executeRequest<NodeJS.ReadableStream>(config)
       record({ httpStatusCode: response.status?.toString() })
       return response.data
     })
   }
+
+  private async executeRequest<T = unknown> (config: HttpRequestConfig): Promise<HttpResponse<T>> {
+    const { method, url, data, headers, params } = config
+    const { Authorization, authorization, ...headersToLog } = { ...this._httpClient.defaultHeaders, ...headers } as Record<string, string>
+    logger.debug('Request: ', {
+      host: this._httpClient.baseURL,
+      url,
+      data,
+      method,
+      params,
+      headers: headersToLog
+    })
+
+    try {
+      const response = await this._httpClient.request<T>(config)
+      logger.debug('Response: ', {
+        status: response.status,
+        statusText: response.statusText,
+        host: this._httpClient.baseURL,
+        url: response.config?.url,
+        data: response.config?.data,
+        method: response.config?.method,
+      })
+      return response
+    } catch (error) {
+      if (error instanceof HttpError) {
+        const message = formatHttpErrorMessage(error)
+        logger.debug('Response error: ', {
+          host: this._httpClient.baseURL,
+          url: error.config.url,
+          method: error.config.method,
+          data: error.config.data,
+          message,
+          stack: error.stack,
+        })
+
+        Object.assign(error, {
+          host: this._httpClient.baseURL,
+          url: error.config.url,
+          method: error.config.method,
+          data: error.config.data,
+          message,
+        })
+
+        throw error
+      }
+      throw error
+    }
+  }
 }

package/src/errorHelper.ts

@@ -256,6 +256,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'request.body parameter required'
   },
 
+  /**
+   * Error thrown when HttpClient is given a relative URL without a configured base URL.
+   */
+  HttpClientRelativeUrlRequiresBaseUrl: {
+    code: -120291,
+    description: 'HttpClient requires baseURL when using a relative URL: {url}'
+  },
+
   // ============================================================================
   // Connection and Authentication Errors (-120300 to -120590)
   // ============================================================================
@@ -516,8 +524,64 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: "The current token for the '{connectionName}' AzureBot connection is not exchangeable for an on-behalf-of flow. Ensure the base token audience is for the bot/resource app, such as an App ID URI like 'api://...' or otherwise includes the app's client id."
   },
 
+  /**
+   * Error thrown when an unsupported authentication type is specified in authConfig.
+   */
+  UnsupportedAuthType: {
+    code: -120593,
+    description: 'Unsupported authentication type: {authType}'
+  },
+
+  /**
+     * Error thrown when WorkloadIdentity authentication requires `federatedTokenFile` or the deprecated `WIDAssertionFile` to be configured.
+     */
+  WorkloadIdentityTokenFileRequired: {
+    code: -120594,
+    description: 'WorkloadIdentity authentication requires `federatedTokenFile` or the deprecated `WIDAssertionFile` to be configured'
+  },
+
+  /**
+   * Error thrown when ClientSecret authentication is specified but `clientSecret` is not configured.
+   */
+  ClientSecretRequired: {
+    code: -120595,
+    description: 'ClientSecret authentication requires `clientSecret` to be configured'
+  },
+
+  /**
+   * Error thrown when Certificate authentication is specified but `certPemFile` or `certKeyFile` is not configured.
+   */
+  CertificateFilesRequired: {
+    code: -120596,
+    description: 'Certificate authentication requires both `certPemFile` and `certKeyFile` to be configured'
+  },
+
+  /**
+   * Error thrown when FederatedCredentials authentication is specified but `federatedClientId` or the deprecated `FICClientId` is not configured.
+   */
+  FICClientIdRequired: {
+    code: -120597,
+    description: 'FederatedCredentials authentication requires `federatedClientId` or the deprecated `FICClientId` to be configured'
+  },
+
+  /**
+   * Error thrown when UserManagedIdentity authentication is specified but `clientId` is not configured.
+   */
+  ClientIdRequiredForUserManagedIdentity: {
+    code: -120598,
+    description: 'UserManagedIdentity authentication requires `clientId` to be configured'
+  },
+
+  /**
+   * Error thrown when there's a timeout during a token request.
+   */
+  TokenRequestTimeout: {
+    code: -120599,
+    description: 'Token request timed out after {timeoutMs} ms'
+  },
+
   // ============================================================================
-  // Agent and Client Errors (-120600 to -120630)
+  // Agent and Client Errors (-120600 to -120650)
   // ============================================================================
 
   /**
@@ -537,18 +601,34 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   /**
-     * Error thrown when failed to post activity to agent.
-     */
-  FailedToPostActivityToAgent: {
+   * Error thrown when agent ID is required.
+   */
+  AgentIdRequired: {
     code: -120620,
+    description: 'Agent ID is required to apply outbound agent headers'
+  },
+
+  /**
+   * Error thrown when agent name contains invalid characters.
+   */
+  AgentNameInvalid: {
+    code: -120630,
+    description: 'Agent name contains invalid characters: {agentName}'
+  },
+
+  /**
+   * Error thrown when failed to post activity to agent.
+   */
+  FailedToPostActivityToAgent: {
+    code: -120640,
     description: 'Failed to post activity to agent: {statusText}'
   },
 
   /**
-     * Error thrown when logic parameter must be defined.
-     */
+   * Error thrown when logic parameter must be defined.
+   */
   LogicParameterRequired: {
-    code: -120630,
+    code: -120650,
     description: 'logic must be defined'
   },
 
@@ -784,6 +864,15 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'This proactive operation requires app storage to load and save TurnState. Set options.storage on AgentApplication.'
   },
 
+  /**
+   * Error thrown when CreateConversationOptionsBuilder.build() is called for a Teams channel
+   * conversation (withTeamsChannelId) without an activity set via withActivity().
+   */
+  CreateConversationBuilderChannelActivityRequired: {
+    code: -120753,
+    description: 'CreateConversationOptionsBuilder: Teams channel conversations require an initial activity. Call withActivity() before build().'
+  },
+
   // ============================================================================
   // General Errors (-120990)
   // ============================================================================

package/src/getProductInfo.ts

@@ -1,5 +1,15 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
 import { version } from '../package.json'
 import os from 'os'
+import { Activity, ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from './errorHelper'
+import { HeaderPropagationCollection } from './headerPropagation'
+
+const AGENT_NAME_PATTERN = /^[A-Za-z0-9 _-]+$/
+const AGENT_REGISTRAR = 'A365'
+const DEFAULT_AGENT_NAME = 'Agents-SDK-JS'
 
 /**
  * Generates a string containing information about the SDK version and runtime environment.
@@ -7,4 +17,72 @@ import os from 'os'
  *
  * @returns A formatted string containing the SDK version, Node.js version, and OS details
  */
-export const getProductInfo = () : string => `agents-sdk-js/${version} nodejs/${process.version} ${os.platform()}-${os.arch()}/${os.release()}`
+export const getProductInfo = () : string => `${DEFAULT_AGENT_NAME.toLowerCase()}/${version} nodejs/${process.version} ${os.platform()}-${os.arch()}/${os.release()}`
+
+/**
+ * Applies the SDK product information to the User-Agent header of outgoing requests.
+ * @param headers The HeaderPropagationCollection to which the User-Agent header will be added or updated
+ */
+export function applyUserAgentHeader (headers: HeaderPropagationCollection): void {
+  const userAgentKey = headers.key?.('User-Agent') ?? 'User-Agent'
+  const userAgent = headers.outgoing[userAgentKey] ?? headers.incoming[userAgentKey]
+  const productInfo = getProductInfo()
+  if (!userAgent) {
+    headers.add({ [userAgentKey]: productInfo })
+  } else if (!userAgent.includes(productInfo)) {
+    headers.concat({ [userAgentKey]: productInfo })
+  } else {
+    headers.propagate([userAgentKey])
+  }
+}
+
+/**
+ * Applies standardized agent-related headers for agentic requests.
+ *
+ * @param headers The HeaderPropagationCollection to which the agent headers will be applied.
+ * @param activity The incoming Activity containing agentic request information.
+ * @param agentName An optional human-friendly name for the agent, which will be validated and included in the headers.
+ *
+ * @remarks
+ * The function sets the following headers:
+ * - `AgentRegistrar`: A fixed value indicating the registrar of the agent (e.g., "A365").
+ * - `AgentName`: A human-friendly name for the agent, validated against a pattern to ensure it only contains allowed characters.
+ * - `AgentID`: A unique identifier for the agent instance, resolved from the activity's agentic instance ID or agentic user.
+ * - `Agent-Referrer`: The channel ID from the incoming activity, indicating the source of the request.
+ * The function ensures that the agent headers are consistently applied to outgoing requests for proper identification and tracing.
+ */
+export function applyAgenticHeaders (
+  headers: HeaderPropagationCollection,
+  activity: Activity,
+  agentName?: string
+): void {
+  headers.override({
+    AgentRegistrar: AGENT_REGISTRAR,
+    AgentName: normalizeAgentName(agentName),
+    AgentID: resolveAgentId(activity),
+    'Agent-Referrer': activity.channelId ?? '',
+  })
+}
+
+function resolveAgentId (activity: Activity): string {
+  const agentId = activity.getAgenticInstanceId() ?? activity.getAgenticUser()
+
+  if (!agentId) {
+    throw ExceptionHelper.generateException(Error, Errors.AgentIdRequired)
+  }
+
+  return agentId
+}
+
+function normalizeAgentName (agentName?: string): string {
+  const normalizedAgentName = agentName?.trim()
+  if (!normalizedAgentName) {
+    return DEFAULT_AGENT_NAME
+  }
+
+  if (!AGENT_NAME_PATTERN.test(normalizedAgentName)) {
+    throw ExceptionHelper.generateException(Error, Errors.AgentNameInvalid, undefined, { agentName: normalizedAgentName })
+  }
+
+  return normalizedAgentName
+}