feat: enhance agents-hosting to support diverse web APIs by matthewmeyer · Pull Request #1135 · microsoft/Agents-for-js

matthewmeyer · 2026-06-04T20:44:01Z

Introduced WebResponse interface to decouple hosting layer from Express types.
Added new interfaces for web response handling and middleware compatibility.
Implemented tests to validate CloudAdapter and authorizeJWT functionality with WebResponse.
Added agents-hosting-fastify to support Fastify hosted agents
Created fastify-empty-agent sample to demonstrate usage with Fastify.
Updated tsconfig and build configurations to include new Fastify agent.

Copilot

Pull request overview

This PR evolves the hosting layer to be web-framework-agnostic by introducing a minimal WebResponse contract and moving shared hosting helpers into @microsoft/agents-hosting, then adds a new @microsoft/agents-hosting-fastify integration plus a Fastify-based sample agent and parity/regression tests.

Changes:

Introduces framework-agnostic WebResponse / middleware types and updates CloudAdapter.process + authorizeJWT to depend on them (not Express types).
Promotes shared helpers (e.g., createCloudAdapter, agent-response handler creation) into @microsoft/agents-hosting and updates Express integration to re-export/align.
Adds new Fastify hosting package + tests, plus a fastify-empty-agent sample and build reference wiring.

Reviewed changes

Copilot reviewed 46 out of 47 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tsconfig.build.json	Adds project references for the new Fastify package and sample agent.
test-agents/fastify-empty-agent/tsconfig.json	TS build config for the new Fastify sample.
test-agents/fastify-empty-agent/src/agent.ts	New Fastify-hosted “empty agent” sample entrypoint.
test-agents/fastify-empty-agent/README.md	Documentation for running the Fastify sample.
test-agents/fastify-empty-agent/package.json	Sample package wiring + deps on local workspaces.
test-agents/fastify-empty-agent/env.TEMPLATE	Sample environment template for auth settings.
test-agents/empty-agent/README.md	Fixes sample title typo (“emtpy-agent” → “empty-agent”).
README.md	Documents the new `@microsoft/agents-hosting-fastify` package in the package table and minor wording fix.
packages/agents-hosting/test/hosting/jwt-middleware.webresponse.test.ts	Regression tests ensuring JWT middleware works with `WebResponse` without Express types.
packages/agents-hosting/test/hosting/adapter/cloudAdapter.webresponse.test.ts	Regression tests ensuring `CloudAdapter.process` works with `WebResponse` and throws structured errors on missing body.
packages/agents-hosting/src/interfaces/webResponse.ts	Introduces the `WebResponse` structural contract plus `NextFunction` and params carrier.
packages/agents-hosting/src/interfaces/index.ts	Re-exports interfaces for public consumption.
packages/agents-hosting/src/index.ts	Exposes new core helpers/interfaces from the package entrypoint.
packages/agents-hosting/src/errorHelper.ts	Adds hosting/web-layer error definitions (e.g., missing request body, JWT decode/audience errors).
packages/agents-hosting/src/createCloudAdapter.ts	Moves `createCloudAdapter` into core for reuse by non-Express integrations.
packages/agents-hosting/src/cloudAdapter.ts	Switches response type dependency from Express `Response` to framework-agnostic `WebResponse`; improves missing-body error.
packages/agents-hosting/src/auth/jwt-middleware.ts	Removes Express type imports; updates error creation and wire error message behavior.
packages/agents-hosting/src/agent-client/index.ts	Exports new response-handler factory.
packages/agents-hosting/src/agent-client/createAgentResponseHandler.ts	Adds framework-agnostic agent-response handler implementation and canonical route constant.
packages/agents-hosting/src/agent-client/agentResponseHandler.ts	Refactors response controller configuration to use the new framework-agnostic handler.
packages/agents-hosting/README.md	Documents new framework-agnostic hosting integration APIs.
packages/agents-hosting-fastify/tsconfig.json	TS build config for the new Fastify integration package.
packages/agents-hosting-fastify/test/startServer.test.ts	Tests Fastify `startServer` behavior (routePath, beforeListen, JWT, rate limit).
packages/agents-hosting-fastify/test/replyAdapter.test.ts	Tests Fastify reply adapter’s `WebResponse` behavior.
packages/agents-hosting-fastify/test/plugin.test.ts	Tests plugin defaults, custom routePath, prefix, decorator preservation.
packages/agents-hosting-fastify/test/parity.test.ts	Express ↔ Fastify parity suite validating key behavior matches.
packages/agents-hosting-fastify/test/createAgentRequestHandler.test.ts	Tests Fastify request handler wrapper behavior vs JWT middleware + adapter.
packages/agents-hosting-fastify/test/configureResponseController.test.ts	Smoke tests Fastify response-controller wrapper registers the canonical route.
packages/agents-hosting-fastify/src/startServer.ts	Implements Fastify `startServer` with per-route JWT auth + optional rate limit/bodyLimit.
packages/agents-hosting-fastify/src/replyAdapter.ts	Implements `FastifyReplyAdapter` to satisfy `WebResponse`.
packages/agents-hosting-fastify/src/plugin.ts	Implements encapsulated Fastify plugin for registering the messages route.
packages/agents-hosting-fastify/src/index.ts	Public exports for the Fastify package and re-exports of core helpers.
packages/agents-hosting-fastify/src/createAgentRequestHandler.ts	Creates a Fastify-native handler that invokes core JWT + `CloudAdapter.process`.
packages/agents-hosting-fastify/src/configureResponseController.ts	Fastify wrapper wiring the agent-response controller via the core handler.
packages/agents-hosting-fastify/README.md	Usage docs and differences vs Express integration.
packages/agents-hosting-fastify/package.json	New package manifest for `@microsoft/agents-hosting-fastify`.
packages/agents-hosting-express/src/startServer.ts	Adjusts legacy overload behavior for empty auth config object and keeps parity with new semantics.
packages/agents-hosting-express/src/createCloudAdapter.ts	Re-exports `createCloudAdapter` from core for backward compatibility.
packages/agents-hosting-express/src/createAgentRequestHandler.ts	Switches to core `WebResponse` and adds compile-time assignability guard.
packages/agents-hosting-express/README.md	Notes `createCloudAdapter` promotion to core.
packages/agents-activity/src/exceptionHelper.ts	Extends `AgentError` to include a `.description` property set by `ExceptionHelper`.
compat/baseline/agents-hosting.api.md	Updates API baseline for new core hosting surface and signature changes.
compat/baseline/agents-hosting-fastify.api.md	Adds API baseline for the new Fastify package.
compat/baseline/agents-hosting-express.api.md	Updates API baseline for expanded Express package exports.
CLAUDE.md	Updates repository guidance to include the new Fastify integration package.
.github/copilot-instructions.md	Adds repo-specific Copilot contribution/architecture guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…rface - Introduced WebResponse interface to decouple hosting layer from Express types. - Added new interfaces for web response handling and middleware compatibility. - Implemented tests to validate CloudAdapter and authorizeJWT functionality with WebResponse. - Added agents-hosting-fastify to support Fastify hosted agents - Created fastify-empty-agent sample to demonstrate usage with Fastify. - Updated tsconfig and build configurations to include new Fastify agent.

Copilot

Pull request overview

Copilot reviewed 47 out of 48 changed files in this pull request and generated 3 comments.

…tests for missing request body handling

Copilot

Pull request overview

Copilot reviewed 49 out of 50 changed files in this pull request and generated 3 comments.

+function extractBearerToken (authorization: string | string[] | undefined): string | undefined {
+  const values = Array.isArray(authorization) ? authorization : [authorization]
+  for (const value of values) {
+    const token = parseBearerValue(value)
+    if (token) {
+      return token
+    }
+  }
+  return undefined
+}


+          // Emit only the human-readable description rather than the
+          // ExceptionHelper-formatted "[code] - description - helplink" string,
+          // so the wire format does not leak internal error codes or help links.
+          const wireMessage: string | undefined = err?.description ?? err?.message
+          res.status(401).send({ 'jwt-auth-error': wireMessage })


+ * still part of the package's public type surface (and the API report). Keeping
+ * it structural avoids committing to a richer, named route-registrar contract.
+ */
+interface WebApp {


Copilot AI review requested due to automatic review settings June 4, 2026 20:44

matthewmeyer requested a review from a team as a code owner June 4, 2026 20:44

Copilot started reviewing on behalf of matthewmeyer June 4, 2026 20:44 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Comment thread packages/agents-hosting/src/auth/jwt-middleware.ts Outdated

Comment thread .github/copilot-instructions.md Outdated

Comment thread test-agents/fastify-empty-agent/src/agent.ts Outdated

Comment thread packages/agents-hosting/src/agent-client/agentResponseHandler.ts Outdated

matthewmeyer force-pushed the users/matthewm/agents-hosting-fastify branch from dee5f21 to eb183cb Compare June 4, 2026 21:13

matthewmeyer force-pushed the users/matthewm/agents-hosting-fastify branch from eb183cb to 5215f68 Compare June 4, 2026 21:17

matthewmeyer and others added 2 commits June 4, 2026 14:20

Merge branch 'main' into users/matthewm/agents-hosting-fastify

55a4ef1

feat: enhance JWT middleware to handle malformed Authorization headers

a1e4c6b

matthewmeyer requested a review from Copilot June 4, 2026 21:46

Copilot started reviewing on behalf of matthewmeyer June 4, 2026 21:46 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Comment thread packages/agents-hosting/src/auth/jwt-middleware.ts Outdated

Comment thread packages/agents-hosting-fastify/src/startServer.ts Outdated

Comment thread packages/agents-hosting/src/agent-client/createAgentResponseHandler.ts

feat: enhance startServer to support non-numeric port values and add …

d09f1d0

…tests for missing request body handling

matthewmeyer requested a review from Copilot June 9, 2026 18:45

Copilot started reviewing on behalf of matthewmeyer June 9, 2026 18:45 View session

Copilot AI reviewed Jun 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: enhance agents-hosting to support diverse web APIs#1135

feat: enhance agents-hosting to support diverse web APIs#1135
matthewmeyer wants to merge 4 commits into
mainfrom
users/matthewm/agents-hosting-fastify

matthewmeyer commented Jun 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

matthewmeyer commented Jun 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants