[ai] Make DurableAgent#stream() return a messages array (#362)

* Make `DurableAgent#stream()` return a `messages` array

* Docs updates

* Docs updates

* fix

---------

Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>

Author: TooTallNate

.changeset/eleven-roses-enter.md

@@ -0,0 +1,5 @@
+---
+"@workflow/ai": patch
+---
+
+Make `DurableAgent#stream()` return a `messages` array

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

@@ -86,6 +86,7 @@ export default DurableAgentStreamOptions;`}
 - 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
+- The `stream()` method returns `{ messages }` containing the full conversation history, including initial messages, assistant responses, and tool results
 
 ## Examples
 
@@ -180,6 +181,58 @@ async function multiToolAgentWorkflow(userQuery: string) {
 }
 ```
 
+### Multi-turn Conversation
+
+```typescript
+import { DurableAgent } from '@workflow/ai/agent';
+import { z } from 'zod';
+
+async function searchProducts({ query }: { query: string }) {
+  "use step";
+  // Search product database
+  return `Found 3 products matching "${query}"`;
+}
+
+async function multiTurnAgentWorkflow() {
+  'use workflow';
+
+  const agent = new DurableAgent({
+    model: 'anthropic/claude-haiku-4.5',
+    tools: {
+      searchProducts: {
+        description: 'Search for products',
+        inputSchema: z.object({ query: z.string() }),
+        execute: searchProducts,
+      },
+    },
+  });
+
+  const writable = getWritable<UIMessageChunk>();
+
+  // First user message
+  //   - Result is streamed to the provided `writable` stream
+  //   - Message history is returned in `messages` for LLM context
+  let { messages } = await agent.stream({
+    messages: [
+      { role: 'user', content: 'Find me some laptops' }
+    ],
+    writable,
+  });
+
+  // Continue the conversation with the accumulated message history
+  const result = await agent.stream({
+    messages: [
+      ...messages,
+      { role: 'user', content: 'Which one has the best battery life?' }
+    ],
+    writable,
+  });
+
+  // result.messages now contains the complete conversation history
+  return result.messages;
+}
+```
+
 ### Tools with Workflow Library Features
 
 ```typescript

packages/ai/src/agent/durable-agent.ts

@@ -168,6 +168,12 @@ export class DurableAgent {
     if (sendFinish || !preventClose) {
       await closeStream(options.writable, preventClose, sendFinish);
     }
+
+    // The iterator returns the final conversation prompt (LanguageModelV2Prompt)
+    // which is compatible with ModelMessage[]
+    const messages = result.value as ModelMessage[];
+
+    return { messages };
   }
 }
 
@@ -215,7 +221,7 @@ async function executeTool(
   try {
     const toolResult = await tool.execute(input.value, {
       toolCallId: toolCall.toolCallId,
-      // TODO: pass the proper messages to the tool
+      // TODO: pass the proper messages to the tool (we'd need to pass them through the iterator)
       messages: [],
     });
 

packages/ai/src/agent/stream-text-iterator.ts

@@ -25,7 +25,7 @@ export async function* streamTextIterator({
   sendStart?: boolean;
 }): AsyncGenerator<
   LanguageModelV2ToolCall[],
-  void,
+  LanguageModelV2Prompt,
   LanguageModelV2ToolResultPart[]
 > {
   const conversationPrompt = [...prompt]; // Create a mutable copy
@@ -78,11 +78,25 @@ export async function* streamTextIterator({
         }
       }
     } else if (finish?.finishReason === 'stop') {
+      // Add assistant message with text content to the conversation
+      const textContent = step.content.filter(
+        (item) => item.type === 'text'
+      ) as Array<{ type: 'text'; text: string }>;
+
+      if (textContent.length > 0) {
+        conversationPrompt.push({
+          role: 'assistant',
+          content: textContent,
+        });
+      }
+
       done = true;
     } else {
       throw new Error(`Unexpected finish reason: ${finish?.finishReason}`);
     }
   }
+
+  return conversationPrompt;
 }
 
 async function writeToolOutputToUI(