docs: updates for #1040

docs/src/content/docs/guides/results.mdx

@@ -26,6 +26,7 @@ Most applications only need a few result properties:
 | `lastAgent` / `activeAgent` | The agent that should usually handle the next turn.                             |
 | `lastResponseId`            | Continuation with `previousResponseId` on the next OpenAI Responses turn.       |
 | `interruptions`             | Pending tool approvals you must resolve before resuming.                        |
+| `runContext`                | App context, approvals, usage, and nested `toolInput`.                          |
 | `state`                     | A serializable snapshot for resume/retry flows.                                 |
 
 ## Final output
@@ -92,6 +93,10 @@ The `newItems` property contains the new items generated during the run. The ite
 
 The `state` property contains the state of the run. Most of what is attached to the `result` is derived from the `state`, but `state` is also serializable/deserializable and can be used as input for a subsequent call to `run()` if you need to [recover from an error](/openai-agents-js/guides/running-agents#exceptions) or resume a paused [human-in-the-loop](/openai-agents-js/guides/human-in-the-loop) flow.
 
+## Run context
+
+The `runContext` property is the supported way to read the public run context for a result. `result.runContext.context` is the app context you passed into `run()`, and `result.runContext.toolInput` contains structured agent-tool input when that nested run was given one.
+
 ## Interruptions
 
 If you are using `needsApproval` in your agent, your run might pause and expose `interruptions`. This array contains the `RunToolApprovalItem`s that require a decision before the run can continue. Resolve them through `result.state.approve(...)` / `result.state.reject(...)`, then call `run()` again with that same state. Check the [human-in-the-loop guide](/openai-agents-js/guides/human-in-the-loop) for end-to-end patterns.

docs/src/content/docs/guides/tools.mdx

@@ -10,6 +10,7 @@ import localBuiltInToolsExample from '../../../../../examples/docs/tools/localBu
 import nonStrictSchemaTools from '../../../../../examples/docs/tools/nonStrictSchemaTools.ts?raw';
 import agentsAsToolsExample from '../../../../../examples/docs/tools/agentsAsTools.ts?raw';
 import agentsAsToolsStreamingExample from '../../../../../examples/docs/tools/agentsAsToolsStreaming.ts?raw';
+import agentToolRunContextExample from '../../../../../examples/docs/tools/agentToolRunContext.ts?raw';
 import mcpLocalServer from '../../../../../examples/docs/tools/mcpLocalServer.ts?raw';
 import codexToolExample from '../../../../../examples/docs/tools/codexTool.ts?raw';
 import codexRunContextThreadExample from '../../../../../examples/docs/tools/codexRunContextThread.ts?raw';
@@ -189,6 +190,14 @@ When you run an agent as a tool, Agents SDK creates a runner with the default se
 
 You can also set `needsApproval` and `isEnabled` on the agent tool via `asTool()` options to integrate with human‑in‑the‑loop flows and conditional tool availability.
 
+Inside `customOutputExtractor`, use `result.agentToolInvocation` to inspect the current `Agent.asTool()` invocation. In that callback the result always comes from `Agent.asTool()`, so `agentToolInvocation` is always defined and exposes `toolName`, `toolCallId`, and `toolArguments`. Use `result.runContext` for the regular app context and `toolInput`. This metadata is scoped to the current nested invocation and is not serialized into `RunState`.
+
+<Code
+  lang="typescript"
+  code={agentToolRunContextExample}
+  title="Read agent tool invocation metadata"
+/>
+
 Advanced structured-input options for `agent.asTool()`:
 
 - `inputBuilder`: maps structured tool args to the nested agent input payload.

examples/docs/tools/agentToolRunContext.ts

@@ -0,0 +1,25 @@
+import { Agent } from '@openai/agents';
+
+const billingAgent = new Agent({
+  name: 'Billing Agent',
+  instructions: 'Handle billing questions and subscription changes.',
+});
+
+const billingTool = billingAgent.asTool({
+  toolName: 'billing_agent',
+  toolDescription: 'Handles customer billing questions.',
+  customOutputExtractor(result) {
+    console.log('tool', result.agentToolInvocation.toolName);
+    // Direct invoke() calls may not have a model-generated tool call id.
+    console.log('call', result.agentToolInvocation.toolCallId);
+    console.log('args', result.agentToolInvocation.toolArguments);
+
+    return String(result.finalOutput ?? '');
+  },
+});
+
+const orchestrator = new Agent({
+  name: 'Support Orchestrator',
+  instructions: 'Delegate billing questions to the billing agent tool.',
+  tools: [billingTool],
+});