@microsoft/agents-hosting package

Handles incoming activities from channels and dispatches them to the appropriate handlers.

A class to handle Adaptive Card actions such as executing actions, submitting actions, and performing searches.

Main application class for handling agent conversations and routing.

Example

const app = new AgentApplication<MyState>({
  storage: new MemoryStorage(),
  adapter: myAdapter
});

app.onMessage('hello', async (context, state) => {
  await context.sendActivity('Hello there!');
});

await app.run(turnContext);

Builder class for creating and configuring AgentApplication instances.

Client for communicating with other agents through HTTP requests. Manages configuration, authentication, and activity exchange with target agents.

Represents an extension that adds channel-specific routing functionality to an agent application. This class allows you to register routes that are only active for a specific channel.

Manages the state of an Agent across turns in a conversation.

Provides typed access to an Agent state property with automatic state loading and persistence management.

Example

Basic Usage

// Create a property accessor
const userProfile = userState.createProperty<UserProfile>("userProfile");

// Get with default value
const profile = await userProfile.get(context, {
  name: "",
  preferences: { theme: "light", language: "en" }
});

// Modify the profile
profile.preferences.theme = "dark";

// Save the changes
await userProfile.set(context, profile);
await userState.saveChanges(context); // Persist to storage

Example

Working with Primitive Types

const counterProperty = userState.createProperty<number>("counter");

// Increment counter
const currentCount = await counterProperty.get(context, 0);
await counterProperty.set(context, currentCount + 1);
await userState.saveChanges(context);

Example

Conditional Logic

const settingsProperty = userState.createProperty<Settings>("settings");

// Check if property exists
const settings = await settingsProperty.get(context);
if (settings === undefined) {
  // Property doesn't exist, initialize with defaults
  await settingsProperty.set(context, getDefaultSettings());
}

Example

Custom Storage Keys

// Store state with a custom key for multi-tenant scenarios
const customKey = { key: `tenant_${tenantId}` };
const tenantData = await dataProperty.get(context, defaultData, customKey);
await dataProperty.set(context, updatedData, customKey);

Important Notes

• Thread Safety: This class is not thread-safe. Ensure proper synchronization in concurrent scenarios.
• Memory Usage: State objects are kept in memory until the context is disposed.
• Persistence: Always call state.saveChanges(context) to persist changes to storage.
• Deep Cloning: Default values are deep cloned using JSON serialization, which may not work with complex objects containing functions or circular references.

See createProperty for creating property accessors See StatePropertyAccessor for the interface definition

A utility class for downloading input files from activity attachments.

Class responsible for managing authorization and OAuth flows. Handles multiple OAuth providers and manages the complete authentication lifecycle.

Example

const auth = new Authorization(storage, {
  'microsoft': {
    name: 'Microsoft',
    title: 'Sign in with Microsoft',
    text: 'Please sign in'
  }
});

auth.onSignInSuccess(async (context, state) => {
  await context.sendActivity('Welcome! You are now signed in.');
});

Abstract base class for all adapters in the Agents framework.

Factory class for creating various types of cards.

Represents an identity with a collection of claims.

Adapter for handling agent interactions with various channels through cloud-based services.

ConnectorClient is a client for interacting with the Microsoft Connector API.

A transcript logger that logs activities to the console.

Manages the state of a conversation.

A file-based storage implementation that persists data to the local filesystem.

Example

const storage = new FileStorage('./data');

// Write some data
await storage.write({
  'user123': { name: 'John', lastSeen: new Date().toISOString() },
  'conversation456': { turn: 5, context: 'discussing weather' }
});

// Read specific keys
const data = await storage.read(['user123']);
console.log(data.user123); // { name: 'John', lastSeen: '...' }

// Delete data
await storage.delete(['conversation456']);

A class that implements the HeaderPropagationCollection interface. It filters the incoming request headers based on the definition provided and loads them into the outgoing headers collection.

Represents an exception that occurs during an invoke operation.

A simple in-memory storage provider that implements the Storage interface.

A factory class for creating various types of message activities.

Represents a set of middleware.

Token credential implementation that uses MSAL (Microsoft Authentication Library) to acquire access tokens. Implements the Azure Core Auth TokenCredential interface for authentication scenarios.

Provides tokens using MSAL.

Manages the OAuth flow

A helper class for streaming responses to the client.

Represents a task module action.

Middleware for logging agent conversations to a transcript logger.

Represents the context for a single turn in a conversation between a user and an agent.

A collection for managing state within a turn context.

Base class defining a collection of turn state scopes.

Example

class MyTurnState extends TurnState {
  protected async onComputeStorageKeys(context) {
    const keys = await super.onComputeStorageKeys(context);
    keys['myScope'] = `myScopeKey`;
    return keys;
  }

  public get myScope() {
    const scope = this.getScope('myScope');
    if (!scope) {
      throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
    }
    return scope.value;
  }

  public set myScope(value) {
    const scope = this.getScope('myScope');
    if (!scope) {
      throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
    }
    scope.replace(value);
  }
}

Represents an entry in the turn state that can be tracked for changes and stored.

Manages the state of a user.

Client for managing user tokens.

Represents a collection of Azure Active Directory (AAD) resource URLs. This interface defines the structure of a collection of resource URLs.

Represents an Adaptive Card, which is a card framework that enables developers to exchange UI content in a common and consistent way.

See Adaptive Cards Documentation

Represents the authentication information for an adaptive card.

Represents the response of an adaptive card invoke request.

Represents the value of an adaptive card invoke request.

Represents a single search result item returned from an Adaptive Card search operation.

Example

const searchResult: AdaptiveCardSearchResult = {
  title: "John Doe",
  value: "john.doe@company.com"
};

Configuration options for Adaptive Cards.

Represents the search parameters for adaptive cards.

Configuration options for creating and initializing an Agent Application. This interface defines all the configurable aspects of an agent's behavior, including adapter settings, storage, authorization, and various feature flags.

Configuration settings required to connect to an agent endpoint.

Represents an Animation Card.

Interface for memory operations that provides a way to store and retrieve values by path. Allows components to persist state data during a conversation.

Represents a route configuration for handling bot activities within an application.

Example

const echoRoute: AppRoute<MyTurnState> = {
  selector: (activity) => activity.type === 'message',
  handler: async (context, state) => {
    await context.sendActivity(`You said: ${context.activity.text}`);
  }
};

Represents the data of an attachment.

Represents information about an attachment.

Represents a view of an attachment.

Represents an Audio Card.

Represents the authentication configuration.

Interface defining an authorization handler for OAuth flows.

Represents an authentication provider.

Options for configuring user authorization. Contains settings to configure OAuth connections.

Represents agent state that has been cached in the turn context.

Represents a Card Image.

Citations returned by the model.

Represents a claim with a type and value.

Data structure to store conversation state for agent interactions

Represents the members of a conversation.

Represents the response from a conversation resource operation.

Represents the result of a conversation query.

Represents a custom key for storing state in a specific location.

Default interface for conversation state. Extend this interface to define custom conversation state properties.

Default interface for temporary state that persists only during the current turn. Contains properties used for handling user input, file attachments, and OAuth flows.

Default interface for user state. Extend this interface to define custom user state properties.

Represents a Fact.

Represents the state of the OAuth flow.

Defines the interface for managing header propagation.

Represents a Hero Card.

Represents a file input with its content, type, and optional URL.

Interface for downloading input files in a specific turn context and state.

Represents the response of an invoke request.

Represents a media URL.

Interface for middleware.

Represents an O365 connector card.

Represents a base action in an O365 connector card.

Represents a fact in an O365 connector card.

Represents an image in an O365 connector card.

Represents a section in an O365 connector card.

Represents an OAuth card. This interface defines the structure of an OAuth card, including its buttons, connection name, text, and associated resources.

Paged result of items.

Represents a query with pagination and parameters.

Represents a receipt card.

Represents an item in a receipt card.

Represents a Node.js HTTP Request, including the minimal set of use properties. Compatible with Restify, Express, and Node.js core http.

Represents a response containing a resource ID.

Represents the options for a search invoke request.

Represents the response of a search invoke request.

Represents the value of a search invoke request.

Represents a resource for signing in. This interface defines the structure of a sign-in resource, including the sign-in link, token exchange resource, and token post resource.

Represents the state of a sign-in process.

Interface for accessing a property in state storage with type safety.

Defines the interface for storage operations in the Agents platform.

Represents an item to be stored in a storage provider.

Represents a collection of store items indexed by key.

Represents a thumbnail card.

Represents a thumbnail URL.

Represents a token exchange invoke request.

Represents a request for exchanging tokens. This interface defines the structure of a token exchange request, including the URI, token, and ID.

Represents a resource for exchanging tokens. This interface defines the structure of a token exchange resource, including its ID, URI, and provider ID.

Represents a response containing either a token or a sign-in resource. This interface defines the structure of a response that includes a token response and a sign-in resource.

Represents a resource for posting tokens. This interface defines the structure of a token post resource, including its SAS URL.

Represents the response containing OAuth token information. This interface encapsulates all data related to an OAuth token response.

Represents the status of a token. This interface defines the structure of a token status, including channel ID, connection name, and other metadata.

Information about a transcript.

Interface for logging activities to a transcript.

Interface for storing and managing transcripts.

Represents a video card.

Defines the type of activity image to display in an O365 connector card section.

• 'avatar': Displays the image as a profile avatar (typically circular or small)
• 'article': Displays the image as an article thumbnail (typically rectangular or larger)

Type definition for agent handler function

Event handler function type for application events.

Represents the types of conversation update events that can occur.

• membersAdded: Triggered when new members are added to the conversation.
• membersRemoved: Triggered when members are removed from the conversation.

Defines a handler for deleting an activity. Used for middleware that needs to intercept or handle activity deletions.

Type for middleware handler.

Defines the possible types of actions in an O365 connector card.

• ViewAction: Represents an action to view content.
• OpenUri: Represents an action to open a URI.
• HttpPOST: Represents an action to make an HTTP POST request.
• ActionCard: Represents an action that opens a card with additional actions or inputs.

A handler function for routing operations in a specific turn context and state.

A specialized selector for routing operations.

A function that determines whether a specific condition is met in the given turn context.

Defines a handler for processing and sending activities. Used for middleware that needs to intercept or modify activities being sent.

A factory function to generate storage keys based on the conversation context.

Represents the types of events that can occur during a turn in the application.

• beforeTurn: Triggered before the turn starts.
• afterTurn: Triggered after the turn ends.

Defines a handler for updating an activity. Used for middleware that needs to intercept or modify activity updates.

Defines the types of responses that can be returned after executing an Adaptive Card action.

Defines the priority ranking for route evaluation in the agent hosting framework.

Example

// High priority route that should be evaluated first
this.onMessage('urgent', handler, undefined, RouteRank.First);

// Normal priority route with default ranking
this.onMessage('data', handler, undefined, RouteRank.Unspecified);

// Fallback route that should be evaluated last
this.onActivity('message', fallbackHandler, undefined, RouteRank.Last);

// Multiple routes with same pattern - first ranked executes first
this.onMessage('dupText', handler1, undefined, RouteRank.Last);
this.onMessage('dupText', handler2, undefined, RouteRank.First); // This executes first

HTTP status codes enumeration for agent hosting responses.

This enum provides a comprehensive set of HTTP status codes commonly used in agent hosting scenarios, including success, redirection, client error, and server error status codes.

Middleware to authorize JWT tokens.

To enable Agent to Agent communication, configures the agent response controller endpoint for handling incoming activities from external services.

Example

const app = express();
const adapter = new CloudAdapter();
const agent = new MyActivityHandler();
const conversationState = new ConversationState(memoryStorage);

configureResponseController(app, adapter, agent, conversationState);

Generates a string containing information about the SDK version and runtime environment. This is used for telemetry and User-Agent headers in HTTP requests.

Loads the authentication configuration from environment variables.

Example

tenantId=your-tenant-id
clientId=your-client-id
clientSecret=your-client-secret

certPemFile=your-cert-pem-file
certKeyFile=your-cert-key-file

FICClientId=your-FIC-client-id

connectionName=your-connection-name
authority=your-authority-endpoint

Loads the agent authentication configuration from previous version environment variables.

Example

MicrosoftAppId=your-client-id
MicrosoftAppPassword=your-client-secret
MicrosoftAppTenantId=your-tenant-id