Skip to content

Platform Adapters

Platform adapters are thin wrappers that convert cloud-specific request/response objects to the framework's generic HttpEvent / JsonResponse format. They allow handler factories to remain platform-agnostic while supporting deployment to any cloud provider.

Import

import { gcpHttp, azureHttp } from "@modernpath/agent-framework";

gcpHttp

function gcpHttp(
  handler: (event: HttpEvent) => Promise<JsonResponse>,
): (req: ExpressRequestLike, res: ExpressResponseLike) => Promise<any>

Adapter for Google Cloud Functions (2nd gen) using the Functions Framework / Express request/response pattern.

Request Mapping

Express Property HttpEvent Field
req.params pathParameters
req.query queryStringParameters
req.headers headers (lowercased)
req.body body (stringified if object)
req.method method

Response Mapping

The adapter calls res.status(code), sets each header with res.set(key, value), and sends the body with res.send(body).

ExpressRequestLike / ExpressResponseLike

These are minimal type definitions that avoid a hard dependency on Express. Your application can use the real Express types.

interface ExpressRequestLike {
  params?: Record<string, any>;
  query?: Record<string, any>;
  headers?: Record<string, any>;
  body?: any;
  method?: string;
}

interface ExpressResponseLike {
  status(code: number): this;
  set(header: string, value: string): this;
  send(body: any): any;
}

azureHttp

function azureHttp(
  handler: (event: HttpEvent) => Promise<JsonResponse>,
): (request: AzureHttpRequestLike, context: AzureInvocationContextLike) => Promise<AzureHttpResponseInitLike>

Adapter for Azure Functions v4 (Node.js) using the app.http() programming model.

Request Mapping

Azure Property HttpEvent Field
request.params or context.bindingData pathParameters
request.query (URLSearchParams or Record) queryStringParameters
request.headers (Headers, Map, or Record) headers (lowercased)
request.body, request.text(), or request.json() body (stringified)
request.method method

Response Mapping

Returns an AzureHttpResponseInitLike:

interface AzureHttpResponseInitLike {
  status?: number;
  headers?: Record<string, string>;
  body?: any;
}

Header Handling

The Azure adapter handles multiple header formats:

  • WHATWG Headers (with forEach method)
  • Map-like objects (with entries method)
  • Plain objects (Record-like)

All header keys are lowercased for consistent access.

Code Example

GCP Cloud Functions

import {
  createAgentExecuteHandler,
  gcpHttp,
} from "@modernpath/agent-framework";

const handler = createAgentExecuteHandler({
  resolveAgent: (type) => agentFactory.resolve(type),
  getUserId: (event) => parseInt(event.headers?.["x-user-id"] ?? "0", 10),
});

// Export for Functions Framework
export const agentExecute = gcpHttp(handler);

Azure Functions v4

import {
  createAgentExecuteHandler,
  azureHttp,
} from "@modernpath/agent-framework";
import { app } from "@azure/functions";

const handler = createAgentExecuteHandler({
  resolveAgent: (type) => agentFactory.resolve(type),
  getUserId: (event) => parseInt(event.headers?.["x-user-id"] ?? "0", 10),
});

app.http("agentExecute", {
  methods: ["POST", "OPTIONS"],
  route: "api/agent/{auditingId}/execute",
  handler: azureHttp(handler),
});

Multiple Handlers on One Platform

import {
  createAgentExecuteHandler,
  createTraceHandler,
  createConversationHandler,
  gcpHttp,
} from "@modernpath/agent-framework";

// Each handler is wrapped with the same adapter
export const agentExecute = gcpHttp(
  createAgentExecuteHandler({ resolveAgent, getUserId }),
);

export const traces = gcpHttp(
  createTraceHandler({ traceStore }),
);

export const conversations = gcpHttp(
  createConversationHandler({ resolveAgent, getUserId, conversationStore }),
);