Add DurableAgent and WorkflowChatTransport doc pages (#44)

Co-authored-by: Adrian <[email protected]>

Author: TooTallNate

.changeset/mean-mangos-hope.md

@@ -0,0 +1,2 @@
+---
+---

docs/components/experimental-package-callout.tsx

@@ -0,0 +1,16 @@
+import * as CalloutComponents from '@/components/ui/callout';
+
+interface ExperimentalPackageCalloutProps {
+  packageName: string;
+}
+
+export function ExperimentalPackageCallout({
+  packageName,
+}: ExperimentalPackageCalloutProps) {
+  return (
+    <CalloutComponents.Callout type="warn">
+      The <code>{packageName}</code> package is currently in active development
+      and should be considered experimental.
+    </CalloutComponents.Callout>
+  );
+}

docs/content/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -0,0 +1,248 @@
+---
+title: DurableAgent
+---
+
+import { ExperimentalPackageCallout } from "@/components/experimental-package-callout"
+import { generateDefinition } from "@/lib/tsdoc"
+
+# `DurableAgent`
+
+<ExperimentalPackageCallout packageName="@workflow/ai" />
+
+The `DurableAgent` class enables you to create AI-powered agents that can maintain state across workflow steps, call tools, and gracefully handle interruptions and resumptions.
+
+Tool calls can be implemented as workflow steps for automatic retries, or as regular workflow-level logic utilizing core library features such as [`sleep()`](/docs/api-reference/workflow/sleep) and [Hooks](/docs/foundations/hooks).
+
+```typescript lineNumbers
+import { DurableAgent } from '@workflow/ai/agent';
+import { z } from 'zod';
+
+async function getWeather({ city }: { city: string }) {
+  "use step";
+
+  return `Weather in ${city} is sunny`;
+}
+
+async function myAgent() {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-haiku-4.5',
+    system: 'You are a helpful weather assistant.',
+    tools: {
+      getWeather: {
+        description: 'Get weather for a city',
+        inputSchema: z.object({ city: z.string() }),
+        execute: getWeather,
+      },
+    },
+  });
+
+  await agent.stream({
+    messages: [{ role: 'user', content: 'How is the weather in San Francisco?' }],
+  });
+}
+```
+
+## API Signature
+
+### Class
+
+<TSDoc
+definition={generateDefinition({
+  code: `
+import { DurableAgent } from "@workflow/ai/agent";
+export default DurableAgent;`
+})}
+/>
+
+### DurableAgentOptions
+
+<TSDoc
+definition={generateDefinition({
+  code: `
+import type { DurableAgentOptions } from "@workflow/ai/agent";
+export default DurableAgentOptions;`
+})}
+/>
+
+### DurableAgentStreamOptions
+
+<TSDoc
+definition={generateDefinition({
+  code: `
+import type { DurableAgentStreamOptions } from "@workflow/ai/agent";
+export default DurableAgentStreamOptions;`
+})}
+/>
+
+## Key Features
+
+- **Durable Execution**: Agents can be interrupted and resumed without losing state
+- **Flexible Tool Implementation**: Tools can be implemented as workflow steps for automatic retries, or as regular workflow-level logic
+- **Stream Processing**: Handles streaming responses and tool calls in a structured way
+- **Workflow Native**: Fully integrated with Workflow DevKit for production-grade reliability
+
+## Good to Know
+
+- Tools can be implemented as workflow steps (using `"use step"` for automatic retries), or as regular workflow-level logic
+- Tools can use core library features like `sleep()` and Hooks within their `execute` functions
+- The agent processes tool calls iteratively until completion
+- When no custom `writable` stream is provided, the agent uses the workflow's default writable stream
+
+## Examples
+
+### Basic Agent with Tools
+
+```typescript
+import { DurableAgent } from '@workflow/ai/agent';
+import { z } from 'zod';
+
+async function getWeather({ location }: { location: string }) {
+  "use step";
+  // Fetch weather data
+  const response = await fetch(`https://api.weather.com?location=${location}`);
+  return response.json();
+}
+
+async function weatherAgentWorkflow(userQuery: string) {
+  'use workflow';
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-haiku-4.5',
+    tools: {
+      getWeather: {
+        description: 'Get current weather for a location',
+        inputSchema: z.object({ location: z.string() }),
+        execute: getWeather,
+      },
+    },
+    system: 'You are a helpful weather assistant. Always provide accurate weather information.',
+  });
+
+  await agent.stream({
+    messages: [
+      {
+        role: 'user',
+        content: userQuery,
+      },
+    ],
+  });
+}
+```
+
+### Multiple Tools
+
+```typescript
+import { DurableAgent } from '@workflow/ai/agent';
+import { z } from 'zod';
+
+async function getWeather({ location }: { location: string }) {
+  "use step";
+  return `Weather in ${location}: Sunny, 72°F`;
+}
+
+async function searchEvents({ location, category }: { location: string; category: string }) {
+  "use step";
+  return `Found 5 ${category} events in ${location}`;
+}
+
+async function multiToolAgentWorkflow(userQuery: string) {
+  'use workflow';
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-haiku-4.5',
+    tools: {
+      getWeather: {
+        description: 'Get weather for a location',
+        inputSchema: z.object({ location: z.string() }),
+        execute: getWeather,
+      },
+      searchEvents: {
+        description: 'Search for upcoming events in a location',
+        inputSchema: z.object({ location: z.string(), category: z.string() }),
+        execute: searchEvents,
+      },
+    },
+  });
+
+  await agent.stream({
+    messages: [
+      {
+        role: 'user',
+        content: userQuery,
+      },
+    ],
+  });
+}
+```
+
+### Tools with Workflow Library Features
+
+```typescript
+import { DurableAgent } from '@workflow/ai/agent';
+import { sleep, defineHook } from 'workflow';
+import { z } from 'zod';
+
+// Define a reusable hook type
+const approvalHook = defineHook<{ approved: boolean; reason: string }>();
+
+async function scheduleTask({ delaySeconds }: { delaySeconds: number }) {
+  "use step";
+  // Use core library features like sleep() in tools
+  await sleep(`${delaySeconds}s`);
+  return `Slept for ${delaySeconds} seconds`;
+}
+
+async function requestApproval({ message }: { message: string }) {
+  // Note: No "use step" for this tool call
+
+  // Utilize a Hook for Human-in-the-loop approval
+  const hook = approvalHook.create({
+    metadata: { message }
+  });
+
+  console.log(`Approval needed - token: ${hook.token}`);
+
+  // Wait for the approval payload
+  const approval = await hook;
+
+  if (approval.approved) {
+    return `Request approved: ${approval.reason}`;
+  } else {
+    throw new Error(`Request denied: ${approval.reason}`);
+  }
+}
+
+async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
+  'use workflow';
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-haiku-4.5',
+    tools: {
+      scheduleTask: {
+        description: 'Pause the workflow for the specified number of seconds',
+        inputSchema: z.object({
+          delaySeconds: z.number(),
+        }),
+        execute: scheduleTask,
+      },
+      requestApproval: {
+        description: 'Request approval for an action',
+        inputSchema: z.object({ message: z.string() }),
+        execute: requestApproval,
+      },
+    },
+  });
+
+  await agent.stream({
+    messages: [{ role: 'user', content: userRequest }],
+  });
+}
+```
+
+## See Also
+
+- [WorkflowChatTransport](/docs/api-reference/workflow-ai/workflow-chat-transport) - Transport layer for AI SDK streams
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow fundamentals
+- [AI SDK Documentation](https://ai-sdk.dev/docs) - AI SDK documentation reference

docs/content/docs/api-reference/workflow-ai/index.mdx

@@ -1,20 +1,24 @@
 ---
 title: "@workflow/ai"
+icon: FlaskConical
 ---
 
+import { ExperimentalPackageCallout } from "@/components/experimental-package-callout"
+
 # `@workflow/ai`
 
-<Callout type="warn">
-  The `@workflow/ai` package is currently in active development.
-</Callout>
+<ExperimentalPackageCallout packageName="@workflow/ai" />
 
 Helpers for integrating AI SDK for building AI-powered workflows.
 
 ---
 
-## Functions
+## Classes
 
 <Cards>
+    <Card title="DurableAgent" href="/docs/api-reference/workflow-ai/durable-agent">
+      A class for building durable AI agents that maintain state across workflow steps and handle tool execution with automatic retries.
+    </Card>
     <Card title="WorkflowChatTransport" href="/docs/api-reference/workflow-ai/workflow-chat-transport">
       A drop-in transport for the AI SDK for automatic reconnection in interrupted streams.
     </Card>