Deploy Agents

Declare one agent host in cloud.config.ts. The Nuxt module binds useCloudConfigAgents(event) to your selected cloud's native runtime. Local development uses an in-process adapter; production requires durable execution.

This guide covers the automatic Nuxt deployment path. Standalone Cloudflare Workers export their Agent class from their own Worker entry. Automatic Vercel agent builds currently require Nuxt; other frameworks must integrate the Workflow compiler and agent platform themselves.

1. Declare the Host

Add the host to your existing backend config:

deploy: {
  target: 'vercel', // 'cloudflare' | 'vercel' | 'azure'
  agent: { entry: 'server/cloudconfig/agents.ts' },
  secrets: ['OPENAI_API_KEY', 'OPENAI_AGENT_MODEL'],
},

Supply the API key and your chosen model ID in the ignored .env file or CI environment. Keep provider keys on the server. The legacy deploy.agents declaration also works, but use one host for all saved agents and sessions.

This minimal host uses a fixed definition with no external tools:

import { createAgentDefinition } from '@cloudconfig/core/agents'
import { defineAgentHost } from '@cloudconfig/core/agents/runs'

export default defineAgentHost({
  async resolve(_request, env) {
    const key = env?.OPENAI_API_KEY
    const model = env?.OPENAI_AGENT_MODEL
    if (typeof key !== 'string' || typeof model !== 'string') {
      throw new Error('Configure OPENAI_API_KEY and OPENAI_AGENT_MODEL.')
    }
    return {
      agent: {
        ...createAgentDefinition('Assistant'),
        provider: 'openai',
        model,
        status: 'active',
      },
      keys: { openai: key, anthropic: '', google: '' },
      tools: [],
      callTool: async () => null,
    }
  },
})

For saved agents, implement resolve using your application services: load the definition for request.scope, verify ownership, and return the currently granted tools. It runs again on each continuation. Use explicit portable server imports in the host: Azure executes it in a Function app outside Nuxt, where Nuxt auto-imports, request events, and aliases are unavailable.

2. Install the Native Runtime

For Cloudflare:

pnpm add agents@0.27.0
pnpm add -D wrangler
pnpm exec wrangler login

CloudConfig generates the Agent export in Nuxt's Worker entry, reconciles the Durable Object binding, and adds its SQLite migration. Defaults are CloudconfigAgent, CLOUDCONFIG_AGENTS, and migration tag cloudconfig-agents-v1. Override them under deploy.agent.cloudflare when adopting existing resources. Keep the class identity and migration tag stable. Runs, checkpoints, tool receipts, and schedules live in the Agent's SQLite storage, independently of D1 application tables. Alarms continue work after the HTTP request ends and recover queued or running work after eviction.

For Vercel:

pnpm add workflow@^5.2.2
pnpm add -D vercel
pnpm exec vercel login

The Nuxt module configures the official workflow/nuxt integration and writes compiler input under .cloudconfig/agent-workflows.ts and agent-steps.ts. The build emits Vercel Workflow functions and queue triggers. Workflow steps execute one new model or tool call per activity; durable sleeps suspend approvals and schedules without holding a Function open.

The configured application database also stores private agent records, receipts, and concurrency leases in _cloudconfig_agent_records. With Vercel's Turso default, provide TURSO_DATABASE_URL and TURSO_AUTH_TOKEN. Workflow history contains scope/run IDs and activity results; provider keys stay in step environment variables. Schedules start a continuation run after each occurrence to bound their execution history.

For Azure:

pnpm add @azure/functions@^4.16.5 durable-functions@^3.6.0 @azure/storage-blob@^12
az login

CloudConfig builds and packages a separate Node.js 22 Durable Functions app, provisions a Storage account with private Blob storage, and reuses the web app's App Service plan. The Storage account holds orchestration state and agent receipts. Native orchestration activities perform model/tool calls, external events resume approvals, and durable timers drive schedules. Recurring schedules use continueAsNew to bound history.

Deployment uploads the Function code and server settings before publishing the web app. It supplies CLOUDCONFIG_AZURE_AGENT_ENDPOINT and CLOUDCONFIG_AZURE_AGENT_KEY to the web app automatically. The Function endpoint requires a Function key; the browser never receives it. Optional deploy.azure.agents.appName and storageAccount select existing resource names. Preserve these names to retain execution state between deployments.

3. Deploy and Call the Agent

Generate application migrations, check the plan, and deploy:

pnpm exec cloudconfig db generate
pnpm exec cloudconfig deploy --dry-run
pnpm exec cloudconfig deploy

Inside an authenticated server route, derive scope from the session and verify the caller owns the requested agent and workspace. Then call the platform:

const runs = await useCloudConfigAgents(event).runs(scope)
await runs.start({ runId, scope, payload, instructions })
const result = await runs.status(runId)

Reuse the same runId when retrying an accepted request. Poll status for queued, running, waiting, succeeded, or failed. After an owner answers an approval, call runs.resume(runId); the host's approval method must return the approved action's actual result or its pending approval ID. Vercel also rechecks waiting runs every 60 seconds in case a wake-up races a sleep.

Schedule Saved Work

Implement the host's scheduled(payload, dueAt, env) method, then use platform.schedule(key, { cron, timeZone, payload }). Cron has five fields; timeZone is an IANA name such as Europe/Amsterdam. A stable key replaces the previous schedule; platform.schedule(key, null) cancels future occurrences. Reload the saved automation, recheck ownership and enabled status, and use dueAt to deduplicate downstream work.

Recovery and Host Changes

Completed model and tool receipts replay without repeating those calls. A tool interrupted after dispatch but before its result was recorded is ambiguous: the run fails for review rather than issuing the external action again. Tools receive a stable idempotencyKey; Vercel and Azure activities also supply a deadline signal. Forward these to external services. An ambiguous scheduled action requires review before re-enabling its schedule.

Agent definitions stay portable, but changing application hosts does not migrate in-flight native executions. Drain existing runs, retain the previous runtime for approvals, and recreate schedules on the destination. Pin the application database provider separately when switching hosts. Cloudflare deploy.workflows entries are Cloudflare Workflow classes and remain specific to that platform.

For portable scheduled and event-driven application jobs, declare deploy.automations alongside the agent host. Both ports are available inside native callbacks through getAgentPlatform(env) and getAutomationPlatform(env). Pass the supplied activity environment, particularly inside Azure Functions. See Deploy Automations for checkpointed tasks and automatic Connect maintenance. Azure hosts both workloads in the same Function app and private Storage account.