Pass Workflow retention through Agent.runWorkflow() so that callers can control instance retention

.changeset/workflow-retention-passthrough.md

@@ -0,0 +1,5 @@
+---
+"agents": minor
+---
+
+Pass Workflow instance retention options through `Agent.runWorkflow()`.

docs/agents/workflows.md

@@ -246,7 +246,11 @@ const instanceId = await this.runWorkflow(
   {
     id: "custom-id", // optional - auto-generated if not provided
     metadata: { userId: "user-456", priority: "high" }, // optional - for querying
-    agentBinding: "MyAgent" // optional - auto-detected from class name if not provided
+    agentBinding: "MyAgent", // optional - auto-detected from class name if not provided
+    retention: {
+      successRetention: "1 day",
+      errorRetention: "7 days"
+    }
   }
 );
 ```
@@ -258,6 +262,10 @@ const instanceId = await this.runWorkflow(
 - `options.id` - Custom workflow ID (auto-generated if not provided)
 - `options.metadata` - Optional metadata stored for querying (not passed to workflow)
 - `options.agentBinding` - Agent binding name (auto-detected from class name if not provided). When called from a sub-agent, this is the root Agent binding name.
+- `options.retention` - Workflow instance retention passed unchanged to
+  [`Workflow.create()`](https://developers.cloudflare.com/workflows/build/workers-api/#workflowinstancecreateoptions).
+  Use `successRetention` for successful instances and `errorRetention` for
+  errored or terminated instances.
 
 **Returns:** Workflow instance ID
 

packages/agents/src/index.ts

@@ -11216,7 +11216,10 @@ export class Agent<
     // Create the workflow instance
     const instance = await workflow.create({
       id: workflowId,
-      params: augmentedParams
+      params: augmentedParams,
+      ...(options?.retention === undefined
+        ? {}
+        : { retention: options.retention })
     });
 
     // Track the workflow in our database

packages/agents/src/tests-d/workflow-retention.test-d.ts

@@ -0,0 +1,24 @@
+import { expectTypeOf } from "vitest";
+import type { RunWorkflowOptions } from "../workflows";
+
+expectTypeOf<RunWorkflowOptions["retention"]>().toEqualTypeOf<
+  WorkflowInstanceCreateOptions["retention"]
+>();
+
+const validRetention = {
+  retention: {
+    successRetention: "1 day",
+    errorRetention: 60_000
+  }
+} satisfies RunWorkflowOptions;
+
+void validRetention;
+
+const invalidRetention = {
+  retention: {
+    // @ts-expect-error Workflow retention uses WorkflowSleepDuration units.
+    successRetention: "1 fortnight"
+  }
+} satisfies RunWorkflowOptions;
+
+void invalidRetention;

packages/agents/src/tests/agents/workflow.ts

@@ -1,5 +1,9 @@
 import { Agent } from "../../index.ts";
-import type { WorkflowStatus, WorkflowInfo } from "../../workflows.ts";
+import type {
+  RunWorkflowOptions,
+  WorkflowStatus,
+  WorkflowInfo
+} from "../../workflows.ts";
 
 type WorkflowSubAgentState = {
   status: string;
@@ -701,6 +705,17 @@ export class TestWorkflowAgent extends Agent {
     });
   }
 
+  async runSimpleWorkflowWithRetentionTest(
+    workflowId: string,
+    retention: NonNullable<RunWorkflowOptions["retention"]>
+  ): Promise<string> {
+    return this.runWorkflow(
+      "SIMPLE_WORKFLOW",
+      { value: "retention-test" },
+      { id: workflowId, retention }
+    );
+  }
+
   // Start a simple workflow using the Agent's generated default ID
   async runSimpleWorkflowTestWithDefaultId(params: {
     value: string;

packages/agents/src/tests/workflow.test.ts

@@ -25,6 +25,25 @@ async function getTestAgent(name: string) {
 
 describe("workflow operations", () => {
   describe("workflow tracking", () => {
+    it("starts and tracks a workflow with custom retention", async () => {
+      const agentStub = await getTestAgent("workflow-retention-test");
+      const workflowId = "workflow-with-retention";
+
+      const instanceId = await agentStub.runSimpleWorkflowWithRetentionTest(
+        workflowId,
+        {
+          successRetention: "1 day",
+          errorRetention: "2 weeks"
+        }
+      );
+
+      expect(instanceId).toBe(workflowId);
+      expect(await agentStub.getWorkflowById(workflowId)).toMatchObject({
+        workflowId,
+        workflowName: "SIMPLE_WORKFLOW"
+      });
+    });
+
     it("should insert and retrieve a workflow tracking record", async () => {
       const agentStub = await getTestAgent("workflow-tracking-test-1");
 

packages/agents/src/workflow-types.ts

@@ -230,6 +230,8 @@ export type RunWorkflowOptions = {
   metadata?: Record<string, unknown>;
   /** Agent binding name (auto-detected from class name if not provided) */
   agentBinding?: string;
+  /** Retention policy for the underlying Workflow instance */
+  retention?: WorkflowInstanceCreateOptions["retention"];
 };
 
 /**