Agents OpenAI (TypeScript): offer source tools under their own names (#1650)

Author: longquanzheng

agents/typescript/openai-agents/README.md

@@ -226,6 +226,11 @@ Pass `toolSources: [refunds]` to `createOpenAIAgentsSessionFlow`.
 - Every `RunModel` lists each source and wraps the agent graph again, so every
   agent of the graph offers the listed tools after its own tools, as
   non-strict function tools with the source's description and JSON Schema.
+- The model sees each source tool by its name in the source, such as
+  `fake-ledger_get_balance`, so `fake-ledger_get_balance` and
+  `fake_ledger_get_balance` are two tools. A character other than a letter,
+  digit, `_`, or `-` reaches the model as `_`, because the OpenAI API accepts
+  no other. `toolPolicies`, records, and events always use the source's name.
 - A call of a source tool never runs inside the model call. The source
   builds the call, so its effect, its approval, and whether it is an ordered
   write come from the source; a tool's `needsApproval`, input guardrails, and `createContext` do not apply. A
@@ -251,8 +256,8 @@ Pass `toolSources: [refunds]` to `createOpenAIAgentsSessionFlow`.
   instead, also inside the turn. A resumed call replays only a record of the
   same tool name, once.
 - Definition fails with `TypeError` when a name a source declares repeats a
-  tool or handoff of the graph or another source's tool. A listing that
-  repeats one fails its `RunModel` attempt.
+  tool or handoff of the graph or another source's tool, also after that `_`
+  replacement. A listing that repeats one fails its `RunModel` attempt.
 
 ## Tracing
 

agents/typescript/openai-agents/src/openai-agents-agent-graph.ts

@@ -165,14 +165,14 @@ export function listAgentGraphToolNames(startingAgent: AnyAgent): ReadonlySet<st
 }
 
 /**
- * Returns the name the model sees for a function tool created with `name`. The SDK replaces every character
- * other than a letter or digit with `_`, so `fake-ledger_get_balance` becomes `fake_ledger_get_balance`.
+ * Returns the name the model sees for a tool source's tool. A function name may hold letters, digits, `_`, and
+ * `-`, so `fake-ledger_get_balance` stays as it is, and every other character becomes `_`.
  *
- * @param name - The name passed to `tool()`.
- * @returns The SDK's function tool name.
+ * @param name - The tool's name in its source.
+ * @returns The function tool name.
  */
 export function readFunctionToolName(name: string): string {
-  return createSourceFunctionTool({ name, description: "", inputSchema: {} }).name;
+  return name.replace(/[^A-Za-z0-9_-]/g, "_");
 }
 
 /**
@@ -286,7 +286,7 @@ export function describeReplayOnlyToolRefusal(sourceToolName: string): string {
 
 
 function createSourceFunctionTool(definition: SourceToolDefinition): AnyFunctionTool {
-  return tool({
+  const functionTool = tool({
     name: definition.name,
     description: definition.description,
     // A source's schema need not meet strict mode, such as a connector input with optional fields.
@@ -297,6 +297,8 @@ function createSourceFunctionTool(definition: SourceToolDefinition): AnyFunction
       throw new Error(`tool ${definition.name} of a tool source ran inside the model call`);
     },
   });
+  // tool() also turns `-` into `_`, which would hide the source's name from the model.
+  return cloneFunctionTool(functionTool, { name: readFunctionToolName(definition.name) });
 }
 
 /** `toolName` is the name the call's record holds: the qualified function tool name, or the source's name. */

agents/typescript/openai-agents/src/openai-agents-runner.ts

@@ -416,7 +416,7 @@ export class OpenAIAgentsRunner<TContext> implements AgentFrameworkRunner {
     };
   }
 
-  /** The SDK renames a function tool for the model, so two source names may meet one graph name. */
+  /** The model sees `_` for a source name's other characters, so two source names may meet one graph name. */
   private mapSourceToolNamesToFunctionToolNames(sourceToolNames: readonly string[]): ReadonlyMap<string, string> {
     const functionToolNames = new Map<string, string>();
     const sourceToolNamesByFunctionToolName = new Map<string, string>();

agents/typescript/openai-agents/test/fixtures/connector-openai-agent.ts

@@ -10,7 +10,7 @@
 // The scripted model reads `calls <json>` from the last user text, a JSON list of [toolName, arguments] pairs, and
 // calls them in one response with IDs call-0, call-1, and so on. Once results arrive it answers one
 // `<toolName>: <output>` line per result. A `hold:<gate>` word before `calls` makes that answer wait at a FileGate,
-// so a test can read the turn's records before the turn ends.
+// so a test can read the turn's records before the turn ends. The text `tools` answers the request's tool names.
 
 import {
   Agent,
@@ -68,8 +68,8 @@ export function retriedNoteManifest(): ConnectorPackageManifest {
 }
 
 /**
- * The ledger tools: a Query under a chosen and its default name, a payout without and with approval, a fenced note,
- * and that note retried.
+ * The ledger tools: a Query under a chosen name, its default name, and that name with `_` for `-`, a payout without
+ * and with approval, a fenced note, and that note retried.
  */
 export function createLedgerToolSource(stateDirectory: string, sourceName?: string): ConnectorToolSource {
   const provider = new FakeLedgerProvider(stateDirectory);
@@ -83,11 +83,16 @@ export function createLedgerToolSource(stateDirectory: string, sourceName?: stri
         inputValidator: GetBalanceInputSchema,
         name: "get_balance",
       }),
-      // The default name, fake-ledger_get_balance, which the OpenAI Agents SDK renames for the model.
+      // The default name, fake-ledger_get_balance, which the OpenAI Agents SDK's tool() would turn into the next one.
       connectorTool(new GetBalanceOperation(provider), fakeLedgerConnection, {
         manifest,
         inputValidator: GetBalanceInputSchema,
       }),
+      connectorTool(new GetBalanceOperation(provider), fakeLedgerConnection, {
+        manifest,
+        inputValidator: GetBalanceInputSchema,
+        name: "fake_ledger_get_balance",
+      }),
       connectorTool(payouts, fakeLedgerConnection, {
         manifest,
         inputValidator: CreatePayoutInputSchema,
@@ -127,7 +132,7 @@ export function createConnectorStartingAgent(stateDirectory: string): Agent {
 /** Creates the connector agent Flow; tests and the Worker child build it identically. */
 export function createConnectorOpenAIAgentFlow(stateDirectory: string): AgentSessionFlow {
   return createOpenAIAgentsSessionFlow(createConnectorStartingAgent(stateDirectory), connectorOpenAIAgentFlowType, {
-    toolPolicies: { echo_text: { effect: "read" } },
+    toolPolicies: { echo_text: { effect: "read" }, "fake-ledger_get_balance": { effect: "read", requiresApproval: true } },
     toolSources: [createLedgerToolSource(stateDirectory)],
   });
 }
@@ -181,6 +186,9 @@ class ConnectorScriptedModel implements Model {
       }
       return [answerItem(results.join("\n"))];
     }
+    if (command === "tools") {
+      return [answerItem(request.tools.map((requestTool) => requestTool.name).join("\n"))];
+    }
     if (!command.startsWith("calls ")) {
       return [answerItem(`said: ${command}`)];
     }

agents/typescript/openai-agents/test/integ/connector-tools.integration.test.ts

@@ -27,7 +27,7 @@ import {
   type AgentToolCall,
   type AgentToolCallRecord,
 } from "@superdurable/dex-agents";
-import { connectorTool } from "@superdurable/dex-agents/connectors";
+import { ConnectorToolSource, connectorTool } from "@superdurable/dex-agents/connectors";
 import {
   AgentSessionTestClient,
   AgentTestEnvironment,
@@ -49,6 +49,8 @@ import {
   CloseAccountInputSchema,
   CloseAccountOperation,
   FakeLedgerProvider,
+  GetBalanceInputSchema,
+  GetBalanceOperation,
   fakeLedgerConnection,
   fakeLedgerStateDirectoryVariable,
 } from "../fixtures/fake-ledger.js";
@@ -100,11 +102,24 @@ describe("connector tools refused when the OpenAI Agents session is defined", ()
     );
   });
 
-  test("a source tool that the SDK renames to a function tool name is refused", () => {
+  function createBalanceToolSource(toolNames: readonly string[]): ConnectorToolSource {
+    const provider = new FakeLedgerProvider(stateDirectory);
+    return new ConnectorToolSource(
+      toolNames.map((name) =>
+        connectorTool(new GetBalanceOperation(provider), fakeLedgerConnection, {
+          manifest: readFakeLedgerManifest(),
+          inputValidator: GetBalanceInputSchema,
+          name,
+        }),
+      ),
+    );
+  }
+
+  test("a source tool that the model sees under a function tool name is refused", () => {
     const startingAgent = createConnectorStartingAgent(stateDirectory).clone({
       tools: [
         tool({
-          name: "fake_ledger_get_balance",
+          name: "ledger_balance",
           description: "A local balance tool.",
           parameters: z.object({ accountId: z.string() }),
           execute: async () => "local",
@@ -114,13 +129,26 @@ describe("connector tools refused when the OpenAI Agents session is defined", ()
     assert.throws(
       () =>
         createOpenAIAgentsSessionFlow(startingAgent, "RenamedConnectorAgent", {
-          toolSources: [createLedgerToolSource(stateDirectory)],
+          toolSources: [createBalanceToolSource(["ledger.balance"])],
         }),
       {
         name: "TypeError",
         message:
-          "tool fake-ledger_get_balance of a tool source becomes function tool fake_ledger_get_balance, the name of " +
-          "a tool or handoff of the agent graph",
+          "tool ledger.balance of a tool source becomes function tool ledger_balance, the name of a tool or handoff " +
+          "of the agent graph",
+      },
+    );
+  });
+
+  test("two source tools that the model would see under one name are refused", () => {
+    assert.throws(
+      () =>
+        createOpenAIAgentsSessionFlow(createConnectorStartingAgent(stateDirectory), "CollidingSourceToolsAgent", {
+          toolSources: [createBalanceToolSource(["ledger.balance", "ledger_balance"])],
+        }),
+      {
+        name: "TypeError",
+        message: "tools ledger.balance and ledger_balance of tool sources both become function tool ledger_balance",
       },
     );
   });
@@ -245,14 +273,51 @@ describe("connector tools in an OpenAI Agents session on a Dex engine", () => {
     ]);
   });
 
-  test("a tool under its default connector name runs through its source", async () => {
+  test("the model sees each source tool by its source name, with its -", async () => {
+    await startHarness();
+    const sessionId = `connector-${randomUUID()}`;
+    await sessions.startSession(sessionId, "tools");
+    assert.deepEqual((await answerLines(sessionId, 1)).sort(), [
+      "approved_payout",
+      "create_payout",
+      "echo_text",
+      "fake-ledger_get_balance",
+      "fake_ledger_get_balance",
+      "get_balance",
+      "post_note",
+      "post_note_retried",
+    ]);
+  });
+
+  test("two tools that differ only by - and _ each run through their own name and policy", async () => {
     const harness = await startHarness();
     const sessionId = `connector-${randomUUID()}`;
-    await sessions.startSession(sessionId, calls([["fake_ledger_get_balance", { accountId: "a-2" }]], "default-name"));
-    const [record] = await heldRecords(harness, sessionId, "default-name", 1);
-    assert.equal(record?.toolName, "fake-ledger_get_balance");
-    assert.equal(record?.status, "succeeded");
-    assert.deepEqual(await answerLines(sessionId, 1), ['fake_ledger_get_balance: {"accountId":"a-2","amount":100}']);
+    await sessions.startSession(
+      sessionId,
+      calls(
+        [
+          ["fake-ledger_get_balance", { accountId: "a-2" }],
+          ["fake_ledger_get_balance", { accountId: "a-3" }],
+        ],
+        "default-name",
+      ),
+    );
+    // Only the default name's toolPolicies entry requires approval.
+    const interrupt = await sessions.waitForPendingInterrupt(sessionId);
+    assert.equal(interrupt.toolName, "fake-ledger_get_balance");
+    assert.equal(await sessions.resolveInterrupt(sessionId, interrupt.interruptId, true), true);
+    const records = await heldRecords(harness, sessionId, "default-name", 2);
+    assert.deepEqual(
+      records.map((record) => [record.toolName, record.status]),
+      [
+        ["fake-ledger_get_balance", "succeeded"],
+        ["fake_ledger_get_balance", "succeeded"],
+      ],
+    );
+    assert.deepEqual(await answerLines(sessionId, 1), [
+      'fake-ledger_get_balance: {"accountId":"a-2","amount":100}',
+      'fake_ledger_get_balance: {"accountId":"a-3","amount":100}',
+    ]);
   });
 
   test("an approved Mutation runs once after its approval", async () => {

changelog.d/agents-packages/agents-ts-openai-tool-names-0dac5b.md

@@ -0,0 +1,11 @@
+---
+section: Fixed
+---
+- TypeScript OpenAI Agents adapter and the TypeScript **dex-agents-openai-sdk**:
+  the model sees each tool source's tool, such as a Connector tool, by its
+  source name, as the Python adapter does. The OpenAI Agents SDK's `tool()`
+  used to turn every `-` into `_`, so the model saw
+  `hacker_news_daily_list_story_ids` for `hacker-news-daily_list_story_ids`,
+  and two tools that differ only by `-` and `_` could not both be offered.
+  Only a character the OpenAI API refuses, one other than a letter, digit,
+  `_`, or `-`, still reaches the model as `_`.

changelog.d/agents-packages/agents-ts-openai-tool-names-ac7754.md

@@ -0,0 +1,8 @@
+---
+section: Breaking
+---
+- TypeScript OpenAI Agents adapter and the TypeScript **dex-agents-openai-sdk**:
+  a turn that waits on a call of a source tool whose name has `-`, such as one
+  waiting for approval, while its Worker upgrades fails when it resumes. Its
+  saved run state names the tool with `_`, the name the model saw before this
+  release, and the SDK no longer finds that tool. New turns are not affected.