WIP: Ensure this.mcp.jsonSchema is initialized on ai chat agent start

.changeset/nice-schools-laugh.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Ensure this.mcp.jsonSchema is initialized on ai chat agent start

packages/agents/src/ai-chat-agent.ts

@@ -138,7 +138,8 @@ type StreamMetadata = {
  */
 export class AIChatAgent<
   Env extends Cloudflare.Env = Cloudflare.Env,
-  State = unknown
+  State = unknown,
+  Props extends Record<string, unknown> = Record<string, unknown>
 > extends Agent<Env, State> {
   /**
    * Map of message `id`s to `AbortController`s
@@ -239,6 +240,28 @@ export class AIChatAgent<
 
     this._chatMessageAbortControllers = new Map();
 
+    // a fair assumption for the AIChatAgent is that "ai"
+    // is available, but we still need to ensure .jsonSchema's
+    // been initialised on this.mcp. Let's do it as soon
+    // as we start the agent.
+    const _onStart = this.onStart.bind(this);
+    this.onStart = async (props?: Props) => {
+      return agentContext.run(
+        {
+          agent: this,
+          connection: undefined,
+          request: undefined,
+          email: undefined
+        },
+        async () => {
+          await this._tryCatchChat(async () => {
+            await this.mcp.ensureJsonSchema();
+            return _onStart(props);
+          });
+        }
+      );
+    };
+
     // Check for any active streams from a previous session
     this._restoreActiveStream();
     const _onConnect = this.onConnect.bind(this);

packages/agents/src/mcp/client.ts

@@ -913,7 +913,9 @@ export class MCPClientManager {
    */
   getAITools(): ToolSet {
     if (!this.jsonSchema) {
-      throw new Error("jsonSchema not initialized.");
+      throw new Error(
+        "jsonSchema not initialized, please call `await this.mcp.ensureJsonSchema()` before calling getAITools(). This will be fixed in the next major version."
+      );
     }
 
     // Warn if tools are being read from non-ready connections

packages/agents/src/tests/mcp/client-manager.test.ts

@@ -1781,7 +1781,7 @@ describe("MCPClientManager OAuth Integration", () => {
       });
 
       expect(() => newManager.getAITools()).toThrow(
-        "jsonSchema not initialized."
+        "jsonSchema not initialized, please call `await this.mcp.ensureJsonSchema()` before calling getAITools(). This will be fixed in the next major version."
       );
     });
   });