@microsoft/agents-hosting-express package

Creates a request handler for processing Agent activities.

This exposes a handler signature without requiring Express types in consumer code. It can be used with Express directly, or with frameworks that provide adapted objects compatible with the requirements of authorizeJWT and CloudAdapter.process.

JWT authorization is applied within the handler before processing the activity. Requests must provide a parsed activity payload at req.body.

Example

import express from 'express';
import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
import { createAgentRequestHandler } from '@microsoft/agents-hosting-express';

const agent = new AgentApplication<TurnState>();
const handler = createAgentRequestHandler(agent);

const app = express();
app.use(express.json());
app.post('/api/messages', handler);
app.get('/health', (req, res) => res.json({ status: 'ok' }));
app.listen(3978);

function createAgentRequestHandler(agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfiguration?: AuthConfiguration): AgentRequestHandler

Parameters

Returns

A request handler function (req, res) => Promise<void>.

Creates a CloudAdapter for the given agent.

If the agent is an AgentApplication with a pre-configured adapter, that adapter is reused. Otherwise, a new CloudAdapter is created.

Example

import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
import { createCloudAdapter } from '@microsoft/agents-hosting-express';

const app = new AgentApplication<TurnState>();
const { adapter, headerPropagation } = createCloudAdapter(app, { clientId: process.env.CLIENT_ID });

// Use the adapter directly with request/response objects compatible with CloudAdapter.process
adapter.process(req, res, (context) => app.run(context), headerPropagation);

function createCloudAdapter(agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfig?: AuthConfiguration): CloudAdapterResult

Parameters

Returns

An object containing the CloudAdapter and optional header propagation configuration.

Starts an Express server for handling Agent requests.

Example

// Basic usage
import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
import { startServer } from '@microsoft/agents-hosting-express';

const app = new AgentApplication<TurnState>();
startServer(app);

Example

// With options
import { AgentApplication, TurnState } from '@microsoft/agents-hosting';
import { startServer } from '@microsoft/agents-hosting-express';

const app = new AgentApplication<TurnState>();
startServer(app, {
  port: 8080,
  routePath: '/bot/messages',
  beforeListen: (server) => {
    server.get('/health', (req, res) => res.json({ status: 'ok' }));
  }
});

function startServer(agent: AgentApplication<TurnState<any, any>> | ActivityHandler, options?: StartServerOptions): express.Express

Parameters

Returns

The Express server instance.

Remarks

This function sets up an Express server with the necessary middleware and routes for handling agent requests. It configures JWT authorization middleware on the messages route and sets up the endpoint. The server will listen on the port specified in options, the PORT environment variable, or 3978 by default.

function startServer(agent: AgentApplication<TurnState<any, any>> | ActivityHandler, authConfiguration?: AuthConfiguration): express.Express

Parameters

Returns