Add Think workflow prompt integration

[threepointone]

Summary

This adds a first-class Think integration for Cloudflare Workflows via @cloudflare/think/workflows.

The main new API is ThinkWorkflow plus step.prompt(), which lets a Workflow run a single durable Think reasoning turn and resume with typed structured output:

const draft = await step.prompt("draft-report", {
  prompt: `Draft an operational report about: ${event.payload.topic}`,
  output: reportDraftSchema,
  timeout: "3 days"
});

The call reads like a blocking Workflow step, but it is implemented as an event-driven submit-and-resume flow so it does not hold a long-lived Durable Object RPC open.

What Changed

• Added @cloudflare/think/workflows with ThinkWorkflow, ThinkWorkflowStep, ThinkPromptOptions, and typed prompt errors.
• Added AgentWorkflow.extendStep() so framework-specific workflow integrations can add helpers to the wrapped Workflow step without duplicating the base Agent workflow machinery.
• Added step.prompt(name, options) for Think workflows:
  • accepts prompt: string and a Zod object output schema
  • converts the schema to JSON Schema for the submitted Think turn
  • re-validates the returned output with the original Zod schema when the Workflow resumes
  • infers submission idempotency from workflow name, workflow id, step name, and optional string key
  • supports Workflow wait timeouts and cancels the Think submission by default on timeout
• Updated Think programmatic submissions to capture AI SDK structured output when invoked by a Workflow prompt.
• Kept workflow prompt configuration on an internal inference-loop field so client/app body data cannot accidentally trigger workflow structured-output mode.
• Namespaced workflow prompt control data under a private metadata envelope so public workflow/workflowPrompt metadata remains ordinary caller metadata.
• Added a private durable workflow notification outbox in Think:
  • terminal workflow submissions enqueue a notification row
  • notification delivery calls sendWorkflowEvent() once per drain pass and relies on its built-in transient retry plus outbox alarm retry
  • Durable Object alarms continue draining pending notifications after failures
  • delivered rows are retained but have their payload cleared
  • terminal aborted, skipped, and error submissions can be recovered into missing notifications on startup
• Added a server-side examples/think-workflows example showing:
  • starting a Workflow from an Agent with runWorkflow()
  • using step.prompt() for a report draft
  • waiting for approval with step.waitForEvent()
  • saving deterministic side effects through the originating Agent
• Added Think docs covering:
  • when to use Workflows versus scheduled tasks, submissions, or fibers
  • how to start a Workflow from inside a Think Agent
  • why Agent workflows should use runWorkflow() rather than direct env.WORKFLOW.create()
  • idempotency, timeout, structured output, and notification delivery behavior
• Added a changeset for @cloudflare/think and agents.

API Shape

New import:

import { ThinkWorkflow } from "@cloudflare/think/workflows";
import type { ThinkWorkflowStep } from "@cloudflare/think/workflows";

Workflow definition:

export class ReportWorkflow extends ThinkWorkflow<ReportAgent, ReportParams> {
  async run(event: AgentWorkflowEvent<ReportParams>, step: ThinkWorkflowStep) {
    const draft = await step.prompt("draft-report", {
      prompt: `Draft an operational report about: ${event.payload.topic}`,
      output: reportDraftSchema,
      timeout: "3 days"
    });

    await step.do("store-draft", async () => {
      await this.agent.saveReport({ draft, status: "drafted" });
    });
  }
}

Agent entry point:

async startReport(topic: string) {
  const reportId = crypto.randomUUID();
  const workflowId = await this.runWorkflow(
    "REPORT_WORKFLOW",
    { reportId, topic },
    { metadata: { reportId, topic } }
  );
  return { reportId, workflowId };
}

Design Notes

The important design choice is that step.prompt() does not synchronously wait on the Agent RPC. It submits a durable Think submission inside step.do(), then waits for a Workflow event. Think sends that event from a private notification outbox when the submission reaches a terminal state.

This gives the API a simple blocking shape while preserving the durable execution model:

1. Workflow submits or reuses an idempotent Think submission.
2. Think processes the turn through its existing durable submission queue.
3. Terminal submission state enqueues a Workflow notification.
4. Think retries notification delivery until sendWorkflowEvent() succeeds.
5. Workflow resumes from step.waitForEvent().
6. step.prompt() validates structured output or throws a typed error.

Tests

• npm run test -w @cloudflare/think -- submissions.test.ts
• npx vitest --run -c packages/agents/src/tests/vitest.config.ts packages/agents/src/tests/workflow-prototype.test.ts
• npx nx run @cloudflare/think:build
• npx nx run agents:build
• npm run check
• After the rename: npx nx run @cloudflare/think:build
• After the rename: npm run typecheck -- examples/think-workflows/tsconfig.json packages/think/tsconfig.json packages/think/src/tests/tsconfig.json
• After the structured output fix: npm run test -w @cloudflare/think -- submissions.test.ts
• After the structured output fix: npx nx run @cloudflare/think:build
• After the structured output fix: npm run typecheck -- packages/think/tsconfig.json packages/think/src/tests/tsconfig.json examples/think-workflows/tsconfig.json
• After internalizing workflow prompt config: npm run test -w @cloudflare/think -- submissions.test.ts
• After internalizing workflow prompt config: npx nx run @cloudflare/think:build
• After internalizing workflow prompt config: npm run typecheck -- packages/think/tsconfig.json packages/think/src/tests/tsconfig.json examples/think-workflows/tsconfig.json
• After the timeout cancellation fix: npx nx run @cloudflare/think:build
• After the timeout cancellation fix: npm run typecheck -- packages/think/tsconfig.json examples/think-workflows/tsconfig.json
• After simplifying notification delivery retries: npm run test -w @cloudflare/think -- submissions.test.ts
• After simplifying notification delivery retries: npx nx run @cloudflare/think:build
• After simplifying notification delivery retries: npm run typecheck -- packages/think/tsconfig.json packages/think/src/tests/tsconfig.json examples/think-workflows/tsconfig.json
• After reserving workflow prompt metadata: npm run test -w @cloudflare/think -- submissions.test.ts
• After reserving workflow prompt metadata: npx nx run @cloudflare/think:build
• After reserving workflow prompt metadata: npm run typecheck -- packages/think/tsconfig.json packages/think/src/tests/tsconfig.json examples/think-workflows/tsconfig.json

The original full npm run check passed before the rename, with only the repo's existing sherif warnings. After the rename, @cloudflare/think builds and the new examples/think-workflows project typechecks; a full npm run check rerun reached typecheck and failed in unrelated examples/mcp-rpc-transport because TypeScript could not resolve workers-ai-provider from that example.

Remaining Follow-Up

There is not yet a true end-to-end Workflows runtime test that drives step.prompt() through an actual waitForEvent() resume. The focused tests cover the risky durable pieces added here: the base step-extension hook, workflow notification recovery, successful delivery, payload clearing, retry state after failed delivery, structured output capture in terminal workflow notifications, and isolation from workflow-shaped client body/metadata data.

[changeset-bot]

🦋 Changeset detected

Latest commit: 200fde5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@cloudflare/think	Minor
agents	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

Devin Review found 2 potential issues.

View 6 additional findings in Devin Review.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1598

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1598

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1598

hono-agents

npm i https://pkg.pr.new/hono-agents@1598

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1598

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1598

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1598

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1598

commit: 200fde5