From aebe45df3450a747971ed3c9297377fd98597f86 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Thu, 4 Dec 2025 09:35:22 +0000
Subject: [PATCH] Document getCurrentAgent() context propagation in async
 functions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updates documentation to clarify that getCurrentAgent() properly works
inside nested async functions like AI SDK tool execution. This reflects
the bug fix in cloudflare/agents#712 that ensures connection context
is properly propagated to tool execute functions called from onChatMessage.

Adds a practical example showing how to use getCurrentAgent() inside
tool execution to access the triggering connection.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../docs/agents/concepts/agent-class.mdx      | 41 ++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/agents/concepts/agent-class.mdx b/src/content/docs/agents/concepts/agent-class.mdx
index 86f130d5f4..6e39ab2028 100644
--- a/src/content/docs/agents/concepts/agent-class.mdx
+++ b/src/content/docs/agents/concepts/agent-class.mdx
@@ -389,7 +389,7 @@ export default {
 
 ### Context Management
 
-`agents` wraps all your methods with an `AsyncLocalStorage` to maintain context throughout the request lifecycle. This allows you to access the current agent, connection, request, or email (depending of what event is being handled) from anywhere in your code:
+`agents` wraps all your methods with an `AsyncLocalStorage` to maintain context throughout the request lifecycle. This allows you to access the current agent, connection, request, or email (depending of what event is being handled) from anywhere in your code, including nested async functions:
 
 ```ts
 import { getCurrentAgent } from "agents";
@@ -407,6 +407,45 @@ function someUtilityFunction() {
 }
 ```
 
+The context is properly propagated through async operations, making it available in tool execution functions and other nested async calls:
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+import { getCurrentAgent } from "agents";
+import { tool } from "ai";
+
+class MyAgent extends AIChatAgent {
+  async onChatMessage() {
+    const tools = {
+      checkStatus: tool({
+        description: "Check the status of something",
+        parameters: z.object({}),
+        execute: async () => {
+          // getCurrentAgent() works inside tool execution
+          const { agent, connection } = getCurrentAgent();
+
+          if (connection) {
+            // You can access the connection that triggered this chat
+            console.log("Tool called by connection:", connection.id);
+          }
+
+          return "Status: OK";
+        }
+      })
+    };
+
+    // Use tools in your chat response
+    const result = await streamText({
+      model: this.env.AI.openai("gpt-4o"),
+      messages: this.messages,
+      tools
+    });
+
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
 ### `this.onError`
 
 `Agent` extends `Server`'s `onError` so it can be used to handle errors that are not necessarily WebSocket errors. It is called with a `Connection` or `unknown` error.