Durable Agents

Terminal

npm i workflow

next.config.ts

import { withWorkflow } from 'workflow/next';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // ...your existing config
};

export default withWorkflow(nextConfig);

proxy.ts (excerpt)

// proxy.ts: if you have one, keep it away from Workflow's internal routes
export const config = {
  matcher: [
    {
      source: "/((?!_next/static|_next/image|favicon.ico|.well-known/workflow/).*)",
    },
  ],
};

workflows/hooks.ts

import { defineHook } from 'workflow';
import { z } from 'zod';

export const approvalHook = defineHook({
  schema: z.object({
    approved: z.boolean(),
    note: z.string().optional(),
  }),
});

workflows/newsletter.ts

import { FatalError, sleep } from 'workflow';
import { generateText } from 'ai';
import { approvalHook } from './hooks';

export async function newsletterWorkflow(issueId: string) {
  'use workflow';

  const sources = await gatherSources(issueId);
  const draft = await writeDraft(sources);

  // Pause until a human clicks Approve / Reject. Could be minutes or days.
  const hook = approvalHook.create({ token: `newsletter:${issueId}` });
  const { approved, note } = await hook;
  if (!approved) return { status: 'rejected', note };

  await sleep('1d'); // send tomorrow morning; no function is running meanwhile
  await sendNewsletter(issueId, draft);
  return { status: 'sent' };
}

async function gatherSources(issueId: string) {
  'use step';
  const res = await fetch(`https://example.com/api/issues/${issueId}/links`);
  if (res.status === 404) throw new FatalError('Issue does not exist'); // don't retry
  if (!res.ok) throw new Error(`Upstream ${res.status}`); // retried automatically
  return (await res.json()) as string[];
}

async function writeDraft(sources: string[]) {
  'use step';
  const { text } = await generateText({
    model: 'anthropic/claude-sonnet-5',
    prompt: `Write a short newsletter from these links:\n${sources.join('\n')}`,
  });
  return text;
}

async function sendNewsletter(issueId: string, draft: string) {
  'use step';
  console.log('sending', issueId, draft.length); // call your email provider here
}

app/api/newsletter/route.ts

import { start } from 'workflow/api';
import { newsletterWorkflow } from '@/workflows/newsletter';

export async function POST(req: Request) {
  const { issueId } = await req.json();
  const run = await start(newsletterWorkflow, [issueId]); // returns immediately
  return Response.json({ runId: run.runId });
}

app/api/approve/route.ts

import { approvalHook } from '@/workflows/hooks';

export async function POST(req: Request) {
  // Check the caller is an admin before this line (auth omitted for brevity).
  const { issueId, approved, note } = await req.json();
  const hook = await approvalHook.resume(`newsletter:${issueId}`, { approved, note });
  if (!hook) return Response.json({ error: 'No run is waiting' }, { status: 404 });
  return Response.json({ ok: true, runId: hook.runId });
}

Terminal

# Watch runs, steps, retries, and sleeps locally
npx workflow web
# or in the terminal
npx workflow inspect runs

Terminal

npm i @vercel/queue

app/api/import/route.ts (producer)

import { send } from '@vercel/queue';

export async function POST(req: Request) {
  const { docIds }: { docIds: string[] } = await req.json();
  // One message per document: 500 docs = 500 small, independently retried jobs.
  await Promise.all(
    docIds.map((docId) => send('embed-doc', { docId }, { idempotencyKey: `embed:${docId}` })),
  );
  return Response.json({ queued: docIds.length });
}

app/api/queues/embed-doc/route.ts (consumer)

import { handleCallback } from '@vercel/queue';

export const POST = handleCallback<{ docId: string }>(async (message, metadata) => {
  console.log(`attempt ${metadata.deliveryCount} for ${message.docId}`);
  await embedDocument(message.docId); // throw = message is retried later
});

vercel.json

{
  "functions": {
    "app/api/queues/embed-doc/route.ts": {
      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "embed-doc" }]
    }
  }
}

Terminal

npm i @vercel/sandbox
vercel link
vercel env pull   # OIDC token the SDK uses to authenticate

lib/run-untrusted.ts

import { Sandbox } from '@vercel/sandbox';

export async function runUntrustedJs(code: string) {
  const sandbox = await Sandbox.create({
    timeout: 60_000,           // the whole VM dies after 60s no matter what
    networkPolicy: 'deny-all', // generated code can't phone home
  });

  try {
    await sandbox.writeFiles([{ path: 'main.js', content: code }]);
    const result = await sandbox.runCommand('node', ['main.js'], { timeoutMs: 10_000 });
    return { exitCode: result.exitCode, output: await result.output('both') };
  } finally {
    await sandbox.stop();
  }
}