[docs] Guide on writing durable agents #443
Open
+2,430
−3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
🦋 Changeset detectedLatest commit: 719700e The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types 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 |
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🔧 Build Fix:
Documentation references non-existent TypeScript types PrepareStepInfo and PrepareStepResult, and example code uses an unimplemented prepareStep callback feature. This causes the build to fail when the TypeScript compiler resolves these missing types as any, triggering an error in the TSDoc documentation generator.
View Details
📝 Patch Details
diff --git a/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx b/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx
index acbd3fb..868a4ff 100644
--- a/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx
+++ b/docs/content/docs/api-reference/workflow-ai/durable-agent.mdx
@@ -74,26 +74,6 @@ import type { DurableAgentStreamOptions } from "@workflow/ai/agent";
export default DurableAgentStreamOptions;`}
/>
-### PrepareStepInfo
-
-Information passed to the `prepareStep` callback:
-
-<TSDoc
-definition={`
-import type { PrepareStepInfo } from "@workflow/ai/agent";
-export default PrepareStepInfo;`}
-/>
-
-### PrepareStepResult
-
-Return type from the `prepareStep` callback:
-
-<TSDoc
-definition={`
-import type { PrepareStepResult } from "@workflow/ai/agent";
-export default PrepareStepResult;`}
-/>
-
## Key Features
- **Durable Execution**: Agents can be interrupted and resumed without losing state
@@ -107,7 +87,6 @@ export default PrepareStepResult;`}
- Tools can use core library features like `sleep()` and Hooks within their `execute` functions
- The agent processes tool calls iteratively until completion
- The `stream()` method returns `{ messages }` containing the full conversation history, including initial messages, assistant responses, and tool results
-- The `prepareStep` callback runs before each step and can modify the model or messages dynamically
## Examples
@@ -321,104 +300,9 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
}
```
-### Dynamic Context with prepareStep
-
-Use `prepareStep` to modify settings before each step in the agent loop:
-
-```typescript
-import { DurableAgent } from '@workflow/ai/agent';
-import { getWritable } from 'workflow';
-import type { UIMessageChunk } from 'ai';
-
-async function agentWithPrepareStep(userMessage: string) {
- 'use workflow';
-
- const agent = new DurableAgent({
- model: 'openai/gpt-4.1-mini', // Default model
- system: 'You are a helpful assistant.',
- });
-
- await agent.stream({
- messages: [{ role: 'user', content: userMessage }],
- writable: getWritable<UIMessageChunk>(),
- prepareStep: async ({ stepNumber, messages }) => {
- // Switch to a stronger model for complex reasoning after initial steps
- if (stepNumber > 2 && messages.length > 10) {
- return {
- model: 'anthropic/claude-sonnet-4.5',
- };
- }
-
- // Trim context if messages grow too large
- if (messages.length > 20) {
- return {
- messages: [
- messages[0], // Keep system message
- ...messages.slice(-10), // Keep last 10 messages
- ],
- };
- }
-
- return {}; // No changes
- },
- });
-}
-```
-
-### Message Injection with prepareStep
-
-Inject messages from external sources (like hooks) before each LLM call:
-
-```typescript
-import { DurableAgent } from '@workflow/ai/agent';
-import { getWritable, defineHook } from 'workflow';
-import type { UIMessageChunk } from 'ai';
-
-const messageHook = defineHook<{ message: string }>();
-
-async function agentWithMessageQueue(initialMessage: string) {
- 'use workflow';
-
- const messageQueue: Array<{ role: 'user'; content: string }> = [];
-
- // Listen for incoming messages via hook
- const hook = messageHook.create();
- hook.then(({ message }) => {
- messageQueue.push({ role: 'user', content: message });
- });
-
- const agent = new DurableAgent({
- model: 'anthropic/claude-haiku-4.5',
- system: 'You are a helpful assistant.',
- });
-
- await agent.stream({
- messages: [{ role: 'user', content: initialMessage }],
- writable: getWritable<UIMessageChunk>(),
- prepareStep: ({ messages }) => {
- // Inject queued messages before the next step
- if (messageQueue.length > 0) {
- const newMessages = messageQueue.splice(0);
- return {
- messages: [
- ...messages,
- ...newMessages.map(m => ({
- role: m.role,
- content: [{ type: 'text' as const, text: m.content }],
- })),
- ],
- };
- }
- return {};
- },
- });
-}
-```
-
## See Also
- [Building Durable AI Agents](/guides/ai-agents) - Complete guide to creating durable agents
-- [Queueing User Messages](/guides/ai-agents/message-queueing) - Using prepareStep for message injection
- [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 Loop Control](https://ai-sdk.dev/docs/agents/loop-control) - AI SDK's agent loop control patterns
Analysis
Removed references to unimplemented prepareStep feature in DurableAgent documentation
What fails: Next.js build fails during static page generation for /docs/api-reference/workflow-ai/durable-agent because the documentation references non-existent TypeScript types PrepareStepInfo and PrepareStepResult.
How to reproduce:
cd docs && next buildResult:
Error: Your type is resolved as "any", it seems like you have an issue in "generateDefinition.code" argument.
This error occurs in the TSDoc component when it tries to generate documentation for imported types that don't exist in the source code. The prepareStep feature was documented but never implemented in the DurableAgent class.
Fix: Removed documentation references to the unimplemented prepareStep feature:
- Removed
PrepareStepInfoandPrepareStepResulttype documentation sections - Removed example code using
prepareStepcallback ("Dynamic Context with prepareStep" and "Message Injection with prepareStep" examples) - Updated "Good to Know" section to remove mention of
prepareStep - Updated "See Also" section to remove link to message-queueing guide that relied on
prepareStep
VaguelySerious
commented
Nov 27, 2025
| sidebar={{ | ||
| className: | ||
| 'md:static md:sticky md:top-16 md:h-fit md:w-auto! bg-background! md:bg-transparent! border-none transition-none', | ||
| 'md:static md:sticky md:top-16 md:max-h-[calc(100vh-4rem)] md:overflow-y-auto md:w-auto! bg-background! md:bg-transparent! border-none transition-none', |
Member
Author
There was a problem hiding this comment.
This fixes an issue with the sidebar not scrolling until the main content is scrolled to the bottom, which only now became apparent since we have enough sidebar items to fill a small screen (if they're all expanded)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Live URL for this branch
This adds a new sidebar category for AI Agents in the docs, as well as a new Guides section in the header, with a new AI Agents guide.