From 8932f87cc330e521b7a11a7196fe004c06bdf26a Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 28 Nov 2025 18:57:35 +0000
Subject: [PATCH 1/2] Add documentation for file attachments in chat agents
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the new file attachment capabilities added in PR #688:
- Added filesToParts() helper function documentation
- Added sendMessage() method to useAgentChat return type
- Added comprehensive example showing how to send messages with file attachments

This enables users to build chat interfaces with image and file upload support.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../docs/agents/api-reference/agents-api.mdx  | 127 ++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/src/content/docs/agents/api-reference/agents-api.mdx b/src/content/docs/agents/api-reference/agents-api.mdx
index b58194fcb79491..68d459eb1263bf 100644
--- a/src/content/docs/agents/api-reference/agents-api.mdx
+++ b/src/content/docs/agents/api-reference/agents-api.mdx
@@ -933,6 +933,37 @@ const { messages } = useAgentChat({
 
 ### Chat Agent React API
 
+#### filesToParts
+
+Helper function to convert File objects to FileUIPart format for use with `sendMessage`.
+
+```ts
+import { filesToParts } from "agents/ai-react";
+import type { FileUIPart } from "ai";
+
+// Convert File[] to FileUIPart[] for use with sendMessage
+async function filesToParts(files: File[]): Promise<FileUIPart[]>;
+```
+
+This utility is useful when you have an array of Files from component state. If you have a FileList directly from an input element, use the AI SDK's `convertFileListToFileUIParts` instead.
+
+<TypeScriptExample>
+
+```tsx
+import { filesToParts } from "agents/ai-react";
+
+// Convert files from state to parts for sending
+const fileArray = [file1, file2];
+const fileParts = await filesToParts(fileArray);
+
+await sendMessage({
+	text: "Please analyze these files",
+	files: fileParts,
+});
+```
+
+</TypeScriptExample>
+
 #### useAgentChat
 
 React hook for building AI chat interfaces using an Agent.
@@ -1005,6 +1036,11 @@ function useAgentChat(options: UseAgentChatOptions): {
 	}) => void;
 	// Current error if any
 	error: Error | undefined;
+	// Send a message with optional file attachments
+	sendMessage: (options: {
+		text: string;
+		files?: FileUIPart[];
+	}) => Promise<void>;
 };
 ```
 
@@ -1074,6 +1110,97 @@ function ChatInterface() {
 
 </TypeScriptExample>
 
+#### Sending messages with file attachments
+
+You can send files (images, documents) along with text messages using the `sendMessage` method and `filesToParts` helper:
+
+<TypeScriptExample>
+
+```tsx
+import { useAgentChat, filesToParts } from "agents/ai-react";
+import { useAgent } from "agents/react";
+import { useState, useRef } from "react";
+
+function ChatWithFiles() {
+	const [files, setFiles] = useState<File[]>([]);
+	const [input, setInput] = useState("");
+	const fileInputRef = useRef<HTMLInputElement>(null);
+
+	const agent = useAgent({
+		agent: "chat-agent",
+		name: "user-123",
+	});
+
+	const { messages, sendMessage, status } = useAgentChat({
+		agent,
+	});
+
+	const handleSubmit = async (e: React.FormEvent) => {
+		e.preventDefault();
+		if (!input.trim() && files.length === 0) return;
+
+		const message = input;
+		const fileArray = files;
+
+		// Clear input and files
+		setInput("");
+		setFiles([]);
+
+		// Send message with files
+		await sendMessage({
+			text: message || "Please analyze these files",
+			files: fileArray.length > 0 ? await filesToParts(fileArray) : undefined,
+		});
+	};
+
+	const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+		if (e.target.files) {
+			setFiles(Array.from(e.target.files));
+		}
+	};
+
+	return (
+		<div>
+			<div>
+				{messages.map((message, i) => (
+					<div key={i}>
+						<strong>{message.role}:</strong>
+						{message.parts
+							.filter((part) => part.type === "text")
+							.map((part, j) => (
+								<span key={j}>{(part as any).text}</span>
+							))}
+					</div>
+				))}
+			</div>
+
+			<form onSubmit={handleSubmit}>
+				<input
+					type="file"
+					ref={fileInputRef}
+					onChange={handleFileChange}
+					multiple
+					accept="image/*"
+				/>
+
+				<input
+					type="text"
+					value={input}
+					onChange={(e) => setInput(e.target.value)}
+					placeholder="Type a message..."
+				/>
+
+				<button type="submit" disabled={status === "streaming"}>
+					Send
+				</button>
+			</form>
+		</div>
+	);
+}
+```
+
+</TypeScriptExample>
+
 ### Next steps
 
 - [Build a chat Agent](/agents/getting-started/build-a-chat-agent/) using the Agents SDK and deploy it to Workers.

From 02c730af818ae09a4580c37feeeb9949bb7d6e0d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 28 Nov 2025 19:03:36 +0000
Subject: [PATCH 2/2] Add documentation for file attachments in AI chat
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the new file attachment feature added in cloudflare/agents#688.
This includes:
- The filesToParts() function for converting File objects to AI SDK format
- Example of using file attachments in React clients with useAgentChat
- Server-side handling with AIChatAgent and vision-capable models
- Storage optimization details (files are stripped to avoid SQLite limits)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../agents/api-reference/using-ai-models.mdx  | 92 +++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/src/content/docs/agents/api-reference/using-ai-models.mdx b/src/content/docs/agents/api-reference/using-ai-models.mdx
index 4bb1bfffcde6dc..cb8a3cffd1fb78 100644
--- a/src/content/docs/agents/api-reference/using-ai-models.mdx
+++ b/src/content/docs/agents/api-reference/using-ai-models.mdx
@@ -225,6 +225,98 @@ export class MyAgent extends Agent<Env> {
 
 </TypeScriptExample>
 
+#### File attachments in AI chat
+
+When building AI chat applications with `AIChatAgent`, you can send file attachments (such as images or documents) along with text messages. This is useful for vision-capable models or when you need to provide context from documents.
+
+The `filesToParts()` function converts JavaScript `File` objects into the format expected by the AI SDK. You can use this in your React client with the `useAgentChat` hook.
+
+<TypeScriptExample filename="src/client.tsx">
+
+```ts
+import { useAgentChat, filesToParts } from "agents/ai-react";
+import { useAgent } from "agents/react";
+import { useState } from "react";
+
+function ChatComponent() {
+	const [files, setFiles] = useState<File[]>([]);
+	const [input, setInput] = useState("");
+
+	const agent = useAgent({
+		agent: "MyAgent",
+		name: "chat-session",
+	});
+
+	const { messages, sendMessage } = useAgentChat({ agent });
+
+	const handleSubmit = async (e: React.FormEvent) => {
+		e.preventDefault();
+
+		await sendMessage({
+			text: input || "Please describe this image",
+			files: files.length > 0 ? await filesToParts(files) : undefined,
+		});
+
+		setInput("");
+		setFiles([]);
+	};
+
+	return (
+		<form onSubmit={handleSubmit}>
+			<input
+				type="file"
+				multiple
+				onChange={(e) => setFiles(Array.from(e.target.files || []))}
+			/>
+			<textarea
+				value={input}
+				onChange={(e) => setInput(e.target.value)}
+				placeholder="Message..."
+			/>
+			<button type="submit">Send</button>
+		</form>
+	);
+}
+```
+
+</TypeScriptExample>
+
+On the server side, `AIChatAgent` automatically handles file attachments. The files are included in the `this.messages` array and can be passed directly to vision-capable models.
+
+<TypeScriptExample filename="src/server.ts">
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+import { openai } from "@ai-sdk/openai";
+import {
+	streamText,
+	convertToModelMessages,
+	createUIMessageStream,
+	createUIMessageStreamResponse,
+} from "ai";
+
+export class MyAgent extends AIChatAgent<Env> {
+	async onChatMessage() {
+		const stream = createUIMessageStream({
+			execute: async ({ writer }) => {
+				const result = streamText({
+					model: openai("gpt-4o"), // Use a vision-capable model
+					messages: convertToModelMessages(this.messages),
+				});
+
+				writer.merge(result.toUIMessageStream());
+			},
+		});
+
+		return createUIMessageStreamResponse({ stream });
+	}
+}
+```
+
+</TypeScriptExample>
+
+File attachments are automatically stripped from storage to avoid SQLite size limits. When a user message contains files, the files are sent to the model but only metadata (filename and type) is persisted in the Agent state. This prevents large image data URLs from exceeding storage limits while maintaining conversation context.
+
 ### OpenAI compatible endpoints
 
 Agents can call models across any service, including those that support the OpenAI API. For example, you can use the OpenAI SDK to use one of [Google's Gemini models](https://ai.google.dev/gemini-api/docs/openai#node.js) directly from your Agent.