remove unstable\_ prefixes with deprecation warnings

threepointone · threepointone · commit 01b919db6ab6 · 2025-09-03T13:11:22.000+01:00
diff --git a/.changeset/olive-cities-tell.md b/.changeset/olive-cities-tell.md
@@ -0,0 +1,14 @@
+---
+"agents": patch
+---
+
+remove unstable\_ prefixes with deprecation warnings
+
+This deprecates all unstable\_ prefixes with deprecation warnings. Specifically:
+
+- unstable_callable -> callable
+- unstable_getAITools -> getAITools
+- unstable_getSchedulePrompt -> getSchedulePrompt
+- unstable_scheduleSchema -> scheduleSchema
+
+Using the unstable\_ prefixed versions will now emit a deprecation warning. In the next major version, the unstable\_ prefixed versions will be removed.
diff --git a/examples/mcp-elicitation-demo/README.md b/examples/mcp-elicitation-demo/README.md
@@ -15,7 +15,7 @@ import {
   Agent,
   type AgentNamespace,
   routeAgentRequest,
-  unstable_callable as callable,
+  callable,
   type Connection,
   type WSMessage
 } from "agents";
diff --git a/examples/mcp-elicitation-demo/src/server.ts b/examples/mcp-elicitation-demo/src/server.ts
@@ -4,7 +4,7 @@ import {
   Agent,
   type AgentNamespace,
   routeAgentRequest,
-  unstable_callable as callable,
+  callable,
   type Connection,
   type WSMessage
 } from "agents";
diff --git a/examples/playground/src/agents/rpc.ts b/examples/playground/src/agents/rpc.ts
@@ -1,8 +1,4 @@
-import {
-  Agent,
-  type StreamingResponse,
-  unstable_callable as callable
-} from "agents";
+import { Agent, type StreamingResponse, callable } from "agents";
 import type { Env } from "../server";
 
 export class Rpc extends Agent<Env> {
diff --git a/examples/playground/src/agents/scheduler.ts b/examples/playground/src/agents/scheduler.ts
@@ -1,9 +1,6 @@
 import type { Connection, ConnectionContext, Schedule } from "agents";
 import { Agent } from "agents";
-import {
-  unstable_getSchedulePrompt,
-  unstable_scheduleSchema
-} from "agents/schedule";
+import { getSchedulePrompt, scheduleSchema } from "agents/schedule";
 import { generateObject } from "ai";
 import { model } from "../model";
 import type { Env } from "../server";
@@ -42,11 +39,11 @@ export class Scheduler extends Agent<Env> {
         maxRetries: 5,
         mode: "json",
         model,
-        prompt: `${unstable_getSchedulePrompt({
+        prompt: `${getSchedulePrompt({
           date: new Date()
         })} 
 Input to parse: "${event.input}"`,
-        schema: unstable_scheduleSchema, // <- the shape of the object that the scheduler expects
+        schema: scheduleSchema, // <- the shape of the object that the scheduler expects
         schemaDescription: "A task to be scheduled",
         schemaName: "task"
       });
diff --git a/examples/tictactoe/src/server.ts b/examples/tictactoe/src/server.ts
@@ -2,7 +2,7 @@ import { openai } from "@ai-sdk/openai";
 import {
   Agent,
   type AgentNamespace,
-  unstable_callable as callable,
+  callable,
   routeAgentRequest
 } from "agents";
 
diff --git a/openai-sdk/human-in-the-loop/src/server.ts b/openai-sdk/human-in-the-loop/src/server.ts
@@ -1,9 +1,5 @@
 import { Agent, type RunResult, RunState, run, tool } from "@openai/agents";
-import {
-  Agent as CFAgent,
-  unstable_callable as callable,
-  routeAgentRequest
-} from "agents";
+import { Agent as CFAgent, callable, routeAgentRequest } from "agents";
 import { z } from "zod";
 
 type Env = {
diff --git a/openai-sdk/llm-as-a-judge/src/server.ts b/openai-sdk/llm-as-a-judge/src/server.ts
@@ -1,9 +1,5 @@
 import { Agent, type AgentInputItem, run, withTrace } from "@openai/agents";
-import {
-  Agent as CFAgent,
-  unstable_callable as callable,
-  routeAgentRequest
-} from "agents";
+import { Agent as CFAgent, callable, routeAgentRequest } from "agents";
 import { z } from "zod";
 
 type Env = {
diff --git a/packages/agents/README.md b/packages/agents/README.md
@@ -488,7 +488,7 @@ import { generateText } from "ai";
 // Convert MCP tools for AI use
 const result = await generateText({
   model: openai("gpt-4"),
-  tools: client.unstable_getAITools(),
+  tools: client.getAITools(),
   prompt: "What's the weather in Tokyo?"
 });
 ```
diff --git a/packages/agents/evals/scheduling.eval.ts b/packages/agents/evals/scheduling.eval.ts
@@ -5,8 +5,8 @@ import { generateObject } from "ai";
 import { createScorer, evalite } from "evalite";
 import {
   type Schedule,
-  unstable_getSchedulePrompt,
-  unstable_scheduleSchema
+  getSchedulePrompt,
+  scheduleSchema
 } from "../src/schedule";
 
 const model = openai("gpt-4o");
@@ -330,13 +330,13 @@ evalite<string, Schedule>("Evals for scheduling", {
       const result = await generateObject({
         maxRetries: 5,
         model, // <- the shape of the object that the scheduler expects
-        prompt: `${unstable_getSchedulePrompt({ date: new Date() })}
+        prompt: `${getSchedulePrompt({ date: new Date() })}
       
 Input to parse: "${input}"`,
         // mode: "json",
         // schemaName: "task",
         // schemaDescription: "A task to be scheduled",
-        schema: unstable_scheduleSchema
+        schema: scheduleSchema
       });
       return result.object;
     } catch (error) {
diff --git a/packages/agents/src/index.ts b/packages/agents/src/index.ts
@@ -118,7 +118,7 @@ const callableMetadata = new Map<Function, CallableMetadata>();
  * Decorator that marks a method as callable by clients
  * @param metadata Optional metadata about the callable method
  */
-export function unstable_callable(metadata: CallableMetadata = {}) {
+export function callable(metadata: CallableMetadata = {}) {
   return function callableDecorator<This, Args extends unknown[], Return>(
     target: (this: This, ...args: Args) => Return,
     // biome-ignore lint/correctness/noUnusedFunctionParameters: later
@@ -132,6 +132,23 @@ export function unstable_callable(metadata: CallableMetadata = {}) {
   };
 }
 
+let didWarnAboutUnstableCallable = false;
+
+/**
+ * Decorator that marks a method as callable by clients
+ * @deprecated this has been renamed to callable, and unstable_callable will be removed in the next major version
+ * @param metadata Optional metadata about the callable method
+ */
+export const unstable_callable = (metadata: CallableMetadata = {}) => {
+  if (!didWarnAboutUnstableCallable) {
+    didWarnAboutUnstableCallable = true;
+    console.warn(
+      "unstable_callable is deprecated, use callable instead. unstable_callable will be removed in the next major version."
+    );
+  }
+  callable(metadata);
+};
+
 export type QueueItem<T = string> = {
   id: string;
   payload: T;
diff --git a/packages/agents/src/mcp/client.ts b/packages/agents/src/mcp/client.ts
@@ -24,7 +24,7 @@ import {
 export class MCPClientManager {
   public mcpConnections: Record<string, MCPClientConnection> = {};
   private _callbackUrls: string[] = [];
-
+  private _didWarnAboutUnstableGetAITools = false;
   /**
    * @param _name Name of the MCP client
    * @param _version Version of the MCP Client
@@ -185,7 +185,7 @@ export class MCPClientManager {
   /**
    * @returns a set of tools that you can use with the AI SDK
    */
-  unstable_getAITools(): ToolSet {
+  getAITools(): ToolSet {
     return Object.fromEntries(
       getNamespacedData(this.mcpConnections, "tools").map((tool) => {
         return [
@@ -211,6 +211,20 @@ export class MCPClientManager {
     );
   }
 
+  /**
+   * @deprecated this has been renamed to getAITools(), and unstable_getAITools will be removed in the next major version
+   * @returns a set of tools that you can use with the AI SDK
+   */
+  unstable_getAITools(): ToolSet {
+    if (!this._didWarnAboutUnstableGetAITools) {
+      this._didWarnAboutUnstableGetAITools = true;
+      console.warn(
+        "unstable_getAITools is deprecated, use getAITools instead. unstable_getAITools will be removed in the next major version."
+      );
+    }
+    return this.getAITools();
+  }
+
   /**
    * Closes all connections to MCP servers
    */
diff --git a/packages/agents/src/schedule.ts b/packages/agents/src/schedule.ts
@@ -1,8 +1,11 @@
 import { z } from "zod";
 
-export type Schedule = z.infer<typeof unstable_scheduleSchema>;
-
-export function unstable_getSchedulePrompt(event: { date: Date }) {
+/**
+ * Get the schedule prompt for a given event
+ * @param event - The event to get the schedule prompt for
+ * @returns The schedule prompt
+ */
+export function getSchedulePrompt(event: { date: Date }) {
   return `
 [Schedule Parser Component]
 
@@ -52,7 +55,27 @@ Example outputs:
 `;
 }
 
-export const unstable_scheduleSchema = z.object({
+let didWarnAboutUnstableGetSchedulePrompt = false;
+
+/**
+ * @deprecated this has been renamed to getSchedulePrompt, and unstable_getSchedulePrompt will be removed in the next major version
+ * @param event - The event to get the schedule prompt for
+ * @returns The schedule prompt
+ */
+export function unstable_getSchedulePrompt(event: { date: Date }) {
+  if (!didWarnAboutUnstableGetSchedulePrompt) {
+    didWarnAboutUnstableGetSchedulePrompt = true;
+    console.warn(
+      "unstable_getSchedulePrompt is deprecated, use getSchedulePrompt instead. unstable_getSchedulePrompt will be removed in the next major version."
+    );
+  }
+  return getSchedulePrompt(event);
+}
+
+/**
+ * The schema for the schedule prompt
+ */
+export const scheduleSchema = z.object({
   description: z.string().describe("A description of the task"),
   when: z.object({
     cron: z
@@ -78,3 +101,14 @@ export const unstable_scheduleSchema = z.object({
       .describe("The type of scheduling details")
   })
 });
+
+/**
+ * The type for the schedule prompt
+ */
+export type Schedule = z.infer<typeof scheduleSchema>;
+
+/**
+ * @deprecated this has been renamed to scheduleSchema, and unstable_scheduleSchema will be removed in the next major version
+ * @returns The schedule schema
+ */
+export const unstable_scheduleSchema = scheduleSchema;
diff --git a/packages/agents/src/tests-d/example-stub.test-d.ts b/packages/agents/src/tests-d/example-stub.test-d.ts
@@ -1,6 +1,6 @@
 /** biome-ignore-all lint/correctness/useHookAtTopLevel: testing types */
 import type { env } from "cloudflare:workers";
-import { Agent, unstable_callable as callable } from "..";
+import { Agent, callable } from "..";
 import { useAgent } from "../react.tsx";
 
 class MyAgent extends Agent<typeof env, {}> {
diff --git a/packages/agents/src/tests-d/example.test-d.ts b/packages/agents/src/tests-d/example.test-d.ts
@@ -1,6 +1,6 @@
 /** biome-ignore-all lint/correctness/useHookAtTopLevel: testing types */
 import type { env } from "cloudflare:workers";
-import { Agent, unstable_callable as callable } from "..";
+import { Agent, callable } from "..";
 import { useAgent } from "../react.tsx";
 
 class MyAgent extends Agent<typeof env, {}> {
