From 40aa36c5db95f2f962dc852d1a089d9397a1e8f0 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 9 Dec 2025 23:51:48 +0000
Subject: [PATCH] Document cacheTtl option and async query caching in useAgent
 hook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This update adds documentation for the cacheTtl option in the useAgent hook,
which was previously undocumented. The documentation clarifies:

- Default cache behavior (5 minute TTL)
- How to customize cache duration with cacheTtl
- How to disable caching by setting cacheTtl to 0
- Cache invalidation with queryDeps

This corresponds to a bug fix in cloudflare/agents PR #726 that corrected
the behavior when cacheTtl is set to 0 (previously incorrectly cached for
5 minutes instead of disabling cache).

Related: https://github.com/cloudflare/agents/pull/726

🤖 Generated with Claude Code

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

diff --git a/src/content/docs/agents/api-reference/agents-api.mdx b/src/content/docs/agents/api-reference/agents-api.mdx
index b58194fcb79..44f3d35553f 100644
--- a/src/content/docs/agents/api-reference/agents-api.mdx
+++ b/src/content/docs/agents/api-reference/agents-api.mdx
@@ -780,12 +780,19 @@ import { useAgent } from "agents/react";
 // Options for the useAgent hook
 type UseAgentOptions<State = unknown> = Omit<
 	Parameters<typeof usePartySocket>[0],
-	"party" | "room"
+	"party" | "room" | "query"
 > & {
 	// Name of the agent to connect to
 	agent: string;
 	// Name of the specific Agent instance (optional)
 	name?: string;
+	// Query parameters - can be static object or async function
+	query?: Record<string, string | null> | (() => Promise<Record<string, string | null>>);
+	// Dependencies for async query caching
+	queryDeps?: unknown[];
+	// Cache TTL in milliseconds for async query results (default: 300000ms / 5 minutes)
+	// Set to 0 to disable caching
+	cacheTtl?: number;
 	// Called when the Agent's state is updated
 	onStateUpdate?: (state: State, source: "server" | "client") => void;
 };
@@ -800,6 +807,44 @@ function useAgent<State = unknown>(
 };
 ```
 
+**Async Query Caching**
+
+When using the `query` option as an async function (for example, to fetch authentication tokens), the `useAgent` hook automatically caches query results to avoid unnecessary repeated calls.
+
+- **Default behavior**: Query results are cached for 5 minutes (300,000 milliseconds)
+- **Custom TTL**: Set `cacheTtl` to a custom value in milliseconds to control cache duration
+- **Disable caching**: Set `cacheTtl: 0` to disable caching entirely (query will be executed fresh every time)
+- **Cache invalidation**: Use `queryDeps` array to specify dependencies that trigger cache invalidation when they change
+
+<TypeScriptExample>
+
+```ts
+import { useAgent } from "agents/react";
+
+// Example: Cache authentication token for 10 minutes
+const agent = useAgent({
+	agent: "my-agent",
+	query: async () => {
+		const token = await fetchAuthToken();
+		return { token };
+	},
+	cacheTtl: 10 * 60 * 1000, // 10 minutes
+	queryDeps: [userId], // Invalidate cache when userId changes
+});
+
+// Example: Disable caching for always-fresh data
+const agent = useAgent({
+	agent: "my-agent",
+	query: async () => {
+		const nonce = await generateNonce();
+		return { nonce };
+	},
+	cacheTtl: 0, // No caching
+});
+```
+
+</TypeScriptExample>
+
 ### Chat Agent
 
 The Agents SDK exposes an `AIChatAgent` class that extends the `Agent` class and exposes an `onChatMessage` method that simplifies building interactive chat agents.