Skip to content

Deployment

The ModernPath Agents Framework is designed for serverless and containerized deployment. The framework's handler factories produce platform-agnostic request/response objects, and thin platform adapters translate them into the shapes expected by each cloud provider.

This means your agent logic, tool registrations, and knowledge base configuration remain identical regardless of where you deploy.

Supported Platforms

Platform Adapter Best For Streaming (SSE)
GCP Cloud Functions gcpHttp() Event-driven workloads, pay-per-invocation Yes
Azure Functions azureHttp() Azure-native environments, enterprise integration Limited
Cloud Run None (full HTTP server) Long-running requests, custom middleware, static UI hosting Yes

Architecture

All deployment targets share the same two-layer pattern:

graph LR
    subgraph "Your Cloud Platform"
        Adapter["Platform Adapter<br/><code>gcpHttp</code> | <code>azureHttp</code> | raw HTTP"]
    end

    subgraph "Framework"
        Handler["Handler Factory<br/><code>createAgentExecuteHandler</code><br/><code>createAgentExecuteStreamHandler</code>"]
        Agent["Your Agent<br/><code>extends BaseAgent</code>"]
    end

    Adapter --> Handler --> Agent

  1. Handler factory -- createAgentExecuteHandler or createAgentExecuteStreamHandler -- accepts a platform-neutral HttpEvent and returns a JsonResponse (or an SSE stream). You configure it with an AgentResolver function and a getUserId callback.

  2. Platform adapter -- gcpHttp() for Cloud Functions, azureHttp() for Azure Functions -- wraps the handler so it matches the platform's native function signature. For Cloud Run, you wire the handler directly into your HTTP server.

Choosing a Platform

Decision guide

  • Cloud Functions if you want zero infrastructure management, automatic scaling to zero, and pay-per-invocation billing.
  • Azure Functions if your organization is Azure-native and you need integration with Azure Active Directory or other Azure services.
  • Cloud Run if you need long-running requests (> 60 seconds), custom middleware, static file serving, or want to bundle a React UI into the same service.

Comparison

Capability Cloud Functions Azure Functions Cloud Run
Cold start ~1--3 s ~1--3 s ~2--5 s (min instances = 0)
Max request duration 540 s (2nd gen) 230 s 3600 s
Bundling esbuild to single file esbuild or tsc esbuild + Docker
Static file serving No (use a CDN) No Yes
Custom middleware No Limited Full control
WebSocket / SSE SSE via createAgentExecuteStreamHandler Not natively supported Full SSE support
Min instances Yes (2nd gen) Yes (Premium plan) Yes

Bundling

All serverless targets benefit from esbuild bundling. The framework and its dependencies are bundled into a single output file, reducing cold-start time and deployment size.

Typical esbuild command
esbuild src/index.ts \
  --bundle \
  --platform=node \
  --target=node20 \
  --format=esm \
  --outfile=dist/index.mjs \
  --external:@google-cloud/firestore

External packages

If you use FirestoreTraceStore or FirestoreConversationStore, mark @google-cloud/firestore as external. It relies on native bindings that cannot be bundled. Include it in your deployment's package.json instead.

Environment Variables

All deployment targets require the same core set of environment variables. See the Environment Variables reference for the complete list.

At minimum, you need:

GOOGLE_AI_STUDIO_KEY=your-gemini-api-key
GEMINI_MODEL=gemini-3-flash-preview

Next Steps