Skip to content

Serverless Deployment

The serverless module provides a three-layer architecture for deploying agents to cloud functions: handler factories that create platform-agnostic request handlers, platform adapters that map cloud-specific request/response formats, and convenience entrypoints that compose both in a single call.

Import

import {
  // Handler factories
  createAgentExecuteHandler,
  createAgentExecuteStreamHandler,
  createConversationHandler,
  createTraceHandler,
  createKnowledgeBaseAdminHandlers,

  // Platform adapters
  gcpHttp,
  azureHttp,

  // Convenience entrypoints
  createGcpAgentExecuteEndpoint,
  createAzureAgentExecuteEndpoint,

  // Types
  HttpEvent,
  AgentResolver,
  CorsOptions,
} from "@modernpath/agent-framework";

Architecture

graph TD
    subgraph "Layer 1: Convenience Entrypoints"
        GE[createGcpAgentExecuteEndpoint]
        AE[createAzureAgentExecuteEndpoint]
    end

    subgraph "Layer 2: Handler Factories"
        H1[createAgentExecuteHandler]
        H2[createAgentExecuteStreamHandler]
        H3[createConversationHandler]
        H4[createTraceHandler]
        H5[createKnowledgeBaseAdminHandlers]
    end

    subgraph "Layer 3: Platform Adapters"
        GA[gcpHttp]
        AA[azureHttp]
    end

    GE --> H1
    GE --> GA
    AE --> H1
    AE --> AA

    subgraph "Cloud Platforms"
        GCF["GCP Cloud Functions"]
        AZF["Azure Functions"]
    end

    GA --> GCF
    AA --> AZF

Components

Handler Factories

Platform-agnostic handler factories that create request handlers for agent execution, streaming, conversations, traces, and knowledge base administration. All handlers accept and return a generic HttpEvent / JsonResponse format.

Platform Adapters

Thin adapters that convert cloud-specific request/response objects (Express for GCP, Azure Functions HttpRequest/HttpResponseInit) to the framework's generic HttpEvent / JsonResponse format.

Convenience Entrypoints

One-liner functions that compose a handler factory with a platform adapter. Use these when you want the simplest possible deployment.

Quick Start

GCP Cloud Functions (2nd Gen)

import { createGcpAgentExecuteEndpoint } from "@modernpath/agent-framework";

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

Azure Functions v4

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

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

export default azureHttp(handler);

Custom HTTP Server

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

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

// Use directly with any HTTP framework
app.post("/api/agent/execute/:auditingId", async (req, res) => {
  const event: HttpEvent = {
    pathParameters: { auditingId: req.params.auditingId },
    headers: req.headers,
    body: JSON.stringify(req.body),
    method: req.method,
  };

  const result = await handler(event);
  res.status(result.statusCode).set(result.headers).json(JSON.parse(result.body));
});