Support both onApproval and HITL

Author: seratch

examples/mcp/hosted-mcp-human-in-the-loop.ts

@@ -0,0 +1,86 @@
+import * as readline from 'readline/promises';
+import { stdin, stdout } from 'node:process';
+import { Agent, run, hostedMcpTool, RunToolApprovalItem } from '@openai/agents';
+
+async function promptApproval(item: RunToolApprovalItem): Promise<boolean> {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const name = item.rawItem.name;
+  const params = JSON.parse(item.rawItem.providerData?.arguments || '{}');
+  const answer = await rl.question(
+    `Approve running tool (mcp: ${name}, params: ${JSON.stringify(params)})? (y/n) `,
+  );
+  rl.close();
+  return answer.toLowerCase().trim() === 'y';
+}
+
+async function main(verbose: boolean, stream: boolean): Promise<void> {
+  // 'always' |
+  // 'never'  |
+  // { never?: { toolNames: string[] }; always?: { toolNames: string[] } }
+  const requireApproval = {
+    never: { toolNames: ['search_codex_code', 'fetch_codex_documentation'] },
+    always: { toolNames: ['fetch_generic_url_content'] },
+  };
+  const agent = new Agent({
+    name: 'MCP Assistant',
+    instructions: 'You must always use the MCP tools to answer questions.',
+    tools: [
+      hostedMcpTool({
+        serverLabel: 'gitmcp',
+        serverUrl: 'https://gitmcp.io/openai/codex',
+        requireApproval,
+        // when you don't pass onApproval, the agent loop will handle the approval process
+      }),
+    ],
+  });
+
+  const input = 'Which language is this repo written in?';
+
+  if (stream) {
+    // Streaming
+    const result = await run(agent, input, { stream: true, maxTurns: 100 });
+    for await (const event of result) {
+      if (verbose) {
+        console.log(JSON.stringify(event, null, 2));
+      } else {
+        if (
+          event.type === 'raw_model_stream_event' &&
+          event.data.type === 'model'
+        ) {
+          console.log(event.data.event.type);
+        }
+      }
+    }
+    console.log(`Done streaming; final result: ${result.finalOutput}`);
+  } else {
+    // Non-streaming
+    let result = await run(agent, input, { maxTurns: 100 });
+    while (result.interruptions && result.interruptions.length) {
+      for (const interruption of result.interruptions) {
+        const approval = await promptApproval(interruption);
+        if (approval) {
+          result.state.approve(interruption);
+        } else {
+          result.state.reject(interruption);
+        }
+      }
+      result = await run(agent, result.state, { maxTurns: 100 });
+    }
+    console.log(result.finalOutput);
+
+    if (verbose) {
+      console.log('----------------------------------------------------------');
+      console.log(JSON.stringify(result.newItems, null, 2));
+      console.log('----------------------------------------------------------');
+    }
+  }
+}
+
+const args = process.argv.slice(2);
+const verbose = args.includes('--verbose');
+const stream = args.includes('--stream');
+
+main(verbose, stream).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

examples/mcp/hosted-mcp-approvals.ts renamed to examples/mcp/hosted-mcp-on-approval.ts

@@ -14,16 +14,28 @@ async function promptApproval(item: RunToolApprovalItem): Promise<boolean> {
 }
 
 async function main(verbose: boolean, stream: boolean): Promise<void> {
+  // 'always' |
+  // 'never'  |
+  // { never?: { toolNames: string[] }; always?: { toolNames: string[] } }
+  const requireApproval = {
+    never: {
+      toolNames: ['fetch_codex_documentation', 'fetch_generic_url_content'],
+    },
+    always: {
+      toolNames: ['search_codex_code'],
+    },
+  };
   const agent = new Agent({
     name: 'MCP Assistant',
     instructions: 'You must always use the MCP tools to answer questions.',
     tools: [
       hostedMcpTool({
         serverLabel: 'gitmcp',
         serverUrl: 'https://gitmcp.io/openai/codex',
-        requireApproval: 'always',
-        onApproval: async (_, data) => {
-          return { approve: await promptApproval(data) };
+        requireApproval,
+        onApproval: async (_context, item) => {
+          const approval = await promptApproval(item);
+          return { approve: approval, reason: undefined };
         },
       }),
     ],

examples/mcp/package.json

@@ -9,7 +9,8 @@
   "scripts": {
     "build-check": "tsc --noEmit",
     "start:stdio": "tsx filesystem-example.ts",
-    "start:hosted-mcp-approvals": "tsx hosted-mcp-approvals.ts",
+    "start:hosted-mcp-on-approval": "tsx hosted-mcp-on-approval.ts",
+    "start:hosted-mcp-human-in-the-loop": "tsx hosted-mcp-human-in-the-loop.ts",
     "start:hosted-mcp-simple": "tsx hosted-mcp-simple.ts"
   }
 }

packages/agents-core/src/items.ts

@@ -142,7 +142,7 @@ export class RunToolApprovalItem extends RunItemBase {
   public readonly type = 'tool_approval_item' as const;
 
   constructor(
-    public rawItem: protocol.FunctionCallItem,
+    public rawItem: protocol.FunctionCallItem | protocol.HostedToolCallItem,
     public agent: Agent<any, any>,
   ) {
     super();

packages/agents-core/src/runContext.ts

@@ -117,7 +117,12 @@ export class RunContext<TContext = UnknownContext> {
       rejected: [],
     };
     if (Array.isArray(approvalEntry.approved)) {
-      approvalEntry.approved.push(approvalItem.rawItem.callId);
+      // function tool has call_id, hosted tool call has id
+      const callId =
+        'callId' in approvalItem.rawItem
+          ? approvalItem.rawItem.callId // function tools
+          : approvalItem.rawItem.id!; // hosted tools
+      approvalEntry.approved.push(callId);
     }
     this.#approvals.set(toolName, approvalEntry);
   }
@@ -146,7 +151,12 @@ export class RunContext<TContext = UnknownContext> {
     };
 
     if (Array.isArray(approvalEntry.rejected)) {
-      approvalEntry.rejected.push(approvalItem.rawItem.callId);
+      // function tool has call_id, hosted tool call has id
+      const callId =
+        'callId' in approvalItem.rawItem
+          ? approvalItem.rawItem.callId // function tools
+          : approvalItem.rawItem.id!; // hosted tools
+      approvalEntry.rejected.push(callId);
     }
     this.#approvals.set(toolName, approvalEntry);
   }