docs: wire echoTool into mainAgent example and update tests to use RunContext for asTool.invoke

Author: vrtnis

examples/basic/tool-use-behavior.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Agent, run, tool } from '@openai/agents';
+import { Agent, run, tool, RunContext, RunResult } from '@openai/agents';
 
 const Weather = z.object({
   city: z.string(),
@@ -46,6 +46,19 @@ const agent3 = new Agent({
   tools: [getWeatherTool, saySomethingTool],
 });
 
+const agentWithRunResult = new Agent({
+  name: 'Tool agent with RunResult',
+  instructions,
+  toolUseBehavior: { stopAtToolNames: ['get_weather'] },
+  outputType: Weather,
+  tools: [getWeatherTool, saySomethingTool],
+});
+
+const weatherToolWithRunResult = agentWithRunResult.asTool({
+  toolName: 'weather_summary',
+  returnRunResult: true,
+});
+
 async function main() {
   const input = 'What is the weather in San Francisco?';
   const result = await run(agent, input);
@@ -65,6 +78,12 @@ async function main() {
   const finalOutput3 = result3.finalOutput;
   // The weather in San Francisco is sunny. Thanks for asking!
   console.log(finalOutput3);
+
+  const result4 = (await weatherToolWithRunResult.invoke(
+    new RunContext(),
+    JSON.stringify({ input }),
+  )) as RunResult<any, Agent<any, any>>;
+  console.log('agentWithRunResult.newItems:', result4.newItems);
 }
 
 main();

examples/docs/tools/agentsAsTools.ts

@@ -10,7 +10,17 @@ const summarizerTool = summarizer.asTool({
   toolDescription: 'Generate a concise summary of the supplied text.',
 });
 
+const echoAgent = new Agent({
+  name: 'Echo',
+  instructions: 'Repeat whatever the user says.',
+});
+
+const echoTool = echoAgent.asTool({
+  toolName: 'echo_text',
+  returnRunResult: true,
+});
+
 const mainAgent = new Agent({
   name: 'Research assistant',
-  tools: [summarizerTool],
+  tools: [summarizerTool, echoTool],
 });

packages/agents-core/test/agent.test.ts

@@ -217,6 +217,52 @@ describe('Agent', () => {
     );
   });
 
+  it('should expose finalOutput with stopAtToolNames using returnRunResult', async () => {
+    setDefaultModelProvider(new FakeModelProvider());
+
+    const subAgent = new Agent({
+      name: 'Echo',
+      instructions: 'Repeat what the user says.',
+    });
+
+    const queryTool = subAgent.asTool({
+      toolName: 'query_action_logs',
+      toolDescription: 'Echo tool that represents a long-running tool',
+    });
+
+    const outerAgent = new Agent({
+      name: 'Parent',
+      instructions: 'Use the tool then stop.',
+      tools: [queryTool],
+      toolUseBehavior: { stopAtToolNames: ['query_action_logs'] },
+    });
+
+    const outerToolDefault = outerAgent.asTool({
+      toolName: 'get_action_logs',
+    });
+
+    const outerToolWithRunResult = outerAgent.asTool({
+      toolName: 'get_action_logs_rich',
+      returnRunResult: true,
+    });
+
+    const input = JSON.stringify({ input: 'hello' });
+
+    const resultDefault = await outerToolDefault.invoke(
+      new RunContext({}),
+      input,
+    );
+    expect(resultDefault).toBe('Hello World');
+
+    const resultWithRunResult = await outerToolWithRunResult.invoke(
+      new RunContext({}),
+      input,
+    );
+    expect(
+      (resultWithRunResult as RunResult<any, Agent<any, any>>).finalOutput,
+    ).toBe('Hello World');
+  });
+
   it('should process final output (json schema)', async () => {
     const agent = new Agent({
       name: 'Test Agent',