# @microsoft/agents-hosting

> Microsoft 365 Agents SDK for JavaScript

Latest version **1.8.1** (published 2026-08-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @microsoft/agents-hosting
pnpm add @microsoft/agents-hosting
yarn add @microsoft/agents-hosting
bun add @microsoft/agents-hosting
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.8.1 |
| Published | 2026-08-27 |
| First published | 2025-03-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 7 |
| Unpacked size | 2.3 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 88 |
| Author | Microsoft |
| Maintainers | microsoft1es, microsoft-oss-releases |
| Keywords | Agents |

## Links

- npm: https://www.npmjs.com/package/@microsoft/agents-hosting
- Repository: https://github.com/microsoft/Agents-for-js
- Issues: https://github.com/microsoft/Agents-for-js/issues
- npm.io page: https://npm.io/package/@microsoft/agents-hosting

## Dependencies (7)

- [zod](https://npm.io/package/zod.md) 3.25.75
- [jwks-rsa](https://npm.io/package/jwks-rsa.md) 4.0.1
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) 9.0.3
- [@azure/core-auth](https://npm.io/package/@azure/core-auth.md) 1.10.1
- [@azure/msal-node](https://npm.io/package/@azure/msal-node.md) 5.1.5
- [@microsoft/agents-activity](https://npm.io/package/@microsoft/agents-activity.md) 1.8.1
- [@microsoft/agents-telemetry](https://npm.io/package/@microsoft/agents-telemetry.md) 1.8.1

## Recent versions

- 1.8.1 (latest) — 2026-08-27
- 1.9.0-beta.8.gf58e66b2ee (next) — 2026-09-15
- 1.2.0-alpha.19.g9aeee229e8 (rc) — 2026-01-09
- 1.1.4-g8d884129e7 (preview) — 2025-12-15
- 1.1.0-alpha.8.g2362542eea (wid) — 2025-09-05
- 0.2.9-g361635b71c (if(eq(variables['publicrelease'],) — 2025-04-23
- 0.2.8-g3bf5832077 ($[if(eq(variables['publicrelease'],) — 2025-04-23
- 1.9.0-beta.3.gb2d23c1c44 — 2026-09-03
- 1.9.0-beta.1.gaa38b73718 — 2026-08-28
- 1.8.0-beta.40.g837137bc36 — 2026-08-27
- 1.8.0-beta.36.gb033f0abc1 — 2026-08-26
- 1.8.0-beta.34.g5d543f96c0 — 2026-08-25
- 1.7.0-beta.11.gb5d3e8c751 — 2026-08-12
- 1.7.0-beta.10.g0c6864b626 — 2026-08-08
- 1.7.0-beta.8.gc2b086aef6 — 2026-08-04
- … 120 more at https://npm.io/package/@microsoft/agents-hosting/versions

## README

# @microsoft/agents-hosting

## Overview

The `@microsoft/agents-hosting` package provides the necessary tools and components to create and host Microsoft Agents. This package includes a compatible API to migrate a bot using `botbuilder` from the BotFramework SDK.

## Installation

To install the package:

```sh
npm install @microsoft/agents-hosting
```

## Hosting integration APIs

To make hosting an agent independent of any single web framework, this package
exposes framework-agnostic primitives that the
[`@microsoft/agents-hosting-express`](../agents-hosting-express) and
[`@microsoft/agents-hosting-fastify`](../agents-hosting-fastify) packages build on:

- `createCloudAdapter(agent, authConfig)` — returns `{ adapter, headerPropagation }` for processing incoming activities. Use this from any web framework.
- `CloudAdapterResult` — return type of `createCloudAdapter`.
- `createAgentResponseHandler(adapter, agent, conversationState)` — framework-agnostic handler `(req, res, params) => Promise<void>` for the authenticated SDK-specific Activity callback route.
- `AgentResponseHandler`, `AgentResponseHandlerParams`, `AGENT_RESPONSE_ROUTE_PATH` — supporting types and the canonical route path.
- `WebResponse`, `NextFunction`, `WebRequestParamsCarrier` — minimal structural interfaces (no Express/Fastify imports) used by the cross-framework helpers above.

Most consumers should keep using `startServer`/`createAgentRequestHandler` from the
Express or Fastify packages; reach for these APIs when adapting another framework.

This Activity callback flow is used for SDK-specific Activity-protocol
delegation.

The Activity callback handler authenticates requests once through the supplied
`CloudAdapter`. That boundary validates the token for any configured host connection;
the handler then verifies that the caller application matches the delegated agent
recorded for that conversation. Existing route-level `authorizeJWT` middleware is
redundant but remains compatible. On configured or production hosts, missing,
invalid, expired, or wrong-audience tokens return `401`. An authenticated caller
that does not match the delegated agent, or missing, malformed, or pre-upgrade
delegated state, returns `403`.
Anonymous callbacks are supported only for unconfigured development hosts
outside production and emit a registration warning because peer ownership cannot
be verified. Pre-upgrade conversations must be restarted.

## Example Usage based on the AgentApplication object

```ts
import { AgentApplication, MemoryStorage, TurnContext, TurnState } from '@microsoft/agents-hosting'

const echo = new AgentApplication<TurnState>({ storage: new MemoryStorage() })
echo.onConversationUpdate('membersAdded', async (context: TurnContext) => {
  await context.sendActivity('Welcome to the Echo sample, send a message to see the echo feature in action.')
})
echo.onActivity('message', async (context: TurnContext, state: TurnState) => {
  let counter: number = state.getValue('conversation.counter') || 0
  await context.sendActivity(`[${counter++}]You said: ${context.activity.text}`)
  state.setValue('conversation.counter', counter)
})
```

## Example Usage based on bot framework Activity Handler

Create an Echo bot using the ActivityHandler

```ts
// myHandler.ts
import { ActivityHandler, MessageFactory } from '@microsoft/agents-hosting'

export class MyHandler extends ActivityHandler {
  constructor () {
    super()
    this.onMessage(async (context, next) => {
      const replyText = `Agent: ${context.activity.text}`
      await context.sendActivity(MessageFactory.text(replyText))
      await next()
    })
  }
}
```

Host the bot with express

```ts
// index.ts
import express, { Response } from 'express'
import { Request, CloudAdapter, authorizeJWT, AuthConfiguration, loadAuthConfigFromEnv } from '@microsoft/agents-hosting'
import { EchoBot } from './myHandler'

const authConfig: AuthConfiguration = loadAuthConfigFromEnv()

const adapter = new CloudAdapter(authConfig)
const myHandler = new MyHandler()

const app = express()

app.use(express.json())
app.use(authorizeJWT(authConfig))

app.post('/api/messages', async (req: Request, res: Response) => {
  await adapter.process(req, res, async (context) => await myHandler.run(context))
})

```

## Outbound request host validation

`OutboundHostValidator` provides an opt-in allowlist for server-side requests made
to activity service URLs and attachment URLs. Enforcement is disabled by default.
It can be configured with environment variables:

```dotenv
OutboundHostValidator__Enabled=true
OutboundHostValidator__IncludeDefaultMicrosoftHosts=true
OutboundHostValidator__Hosts=contoso.com,fabrikam.com
```

Indexed host variables such as `OutboundHostValidator__Hosts__0=contoso.com` are
also supported. A host entry matches both the exact host and its subdomains, and
is normalized (scheme/port/path stripped; a leading `*.` is accepted and ignored).

When enforcement is enabled, `CloudAdapter` rejects inbound activities whose
`serviceUrl` host is not allowlisted, and it also rejects `serviceurl` claim
mismatches (equivalent to `CloudAdapterOptions.validateServiceUrl=true`).

For explicit configuration, reuse the same immutable policy in the adapter and
attachment downloaders:

```ts
import {
  AgentApplication,
  AttachmentDownloader,
  CloudAdapter,
  OutboundHostValidator
} from '@microsoft/agents-hosting'

const outboundHostValidator = new OutboundHostValidator({
  enabled: true,
  hosts: ['contoso.com']
})

const adapter = new CloudAdapter(undefined, undefined, undefined, undefined, outboundHostValidator)

const agent = new AgentApplication({
  adapter,
  fileDownloaders: [new AttachmentDownloader('inputFiles', outboundHostValidator)]
})
```

The validator checks the URL supplied to the downloader. Redirects retain native
`fetch` behavior.

---
_Source: https://npm.io/package/@microsoft/agents-hosting · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._