From 4aac4acff04379678d172b209ef7e884ac85247f Mon Sep 17 00:00:00 2001
From: Kazuhiro Sera <seratch@openai.com>
Date: Tue, 9 Sep 2025 18:46:49 +0900
Subject: [PATCH] docs: Update Agents docs to align with
 https://github.com/openai/openai-agents-python/pull/1650

---
 docs/src/content/docs/guides/agents.mdx | 24 +++++++++++++++++-----
 examples/docs/agents/agentsAsTools.ts   | 27 +++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 5 deletions(-)
 create mode 100644 examples/docs/agents/agentsAsTools.ts

diff --git a/docs/src/content/docs/guides/agents.mdx b/docs/src/content/docs/guides/agents.mdx
index 2cc73916..9ba2b8a9 100644
--- a/docs/src/content/docs/guides/agents.mdx
+++ b/docs/src/content/docs/guides/agents.mdx
@@ -8,6 +8,7 @@ import simpleAgent from '../../../../../examples/docs/agents/simpleAgent.ts?raw'
 import agentWithTools from '../../../../../examples/docs/agents/agentWithTools.ts?raw';
 import agentWithContext from '../../../../../examples/docs/agents/agentWithContext.ts?raw';
 import agentWithAodOutputType from '../../../../../examples/docs/agents/agentWithAodOutputType.ts?raw';
+import agentsAsTools from '../../../../../examples/docs/agents/agentsAsTools.ts?raw';
 import agentWithHandoffs from '../../../../../examples/docs/agents/agentWithHandoffs.ts?raw';
 import agentWithDynamicInstructions from '../../../../../examples/docs/agents/agentWithDynamicInstructions.ts?raw';
 import agentWithLifecycleHooks from '../../../../../examples/docs/agents/agentWithLifecycleHooks.ts?raw';
@@ -76,14 +77,27 @@ plain text.
 
 ---
 
-## Handoffs
+## Multi-agent system design patterns
 
-An Agent can **delegate** to other Agents via the `handoffs` property. A common pattern is to
-use a _triage agent_ that routes the conversation to a more specialised sub‑agent.
+There are many ways to compose agents together. Two patterns we regularly see in
+production apps are:
 
-<Code lang="typescript" code={agentWithHandoffs} title="Agent with handoffs" />
+1. **Manager (agents as tools)** – a central agent owns the conversation and invokes specialized agents that are exposed as tools.
+2. **Handoffs** – the initial agent delegates the entire conversation to a specialist once it has identified the user's request.
+
+These approaches are complementary. Managers give you a single place to enforce guardrails or rate limits, while handoffs let each agent focus on a single task without retaining control of the conversation.
+
+### Manager (agents as tools)
+
+In this pattern the manager never hands over control—the LLM uses the tools and the manager summarizes the final answer. Read more in the [tools guide](/openai-agents-js/guides/tools#agents-as-tools).
 
-You can read more about this pattern in the [handoffs guide](/openai-agents-js/guides/handoffs).
+<Code lang="typescript" code={agentsAsTools} title="Agents as tools" />
+
+### Handoffs
+
+With handoffs the triage agent routes requests, but once a handoff occurs the specialist agent owns the conversation until it produces a final output. This keeps prompts short and lets you reason about each agent independently. Learn more in the [handoffs guide](/openai-agents-js/guides/handoffs).
+
+<Code lang="typescript" code={agentWithHandoffs} title="Agent with handoffs" />
 
 ---
 
diff --git a/examples/docs/agents/agentsAsTools.ts b/examples/docs/agents/agentsAsTools.ts
new file mode 100644
index 00000000..06d50b7c
--- /dev/null
+++ b/examples/docs/agents/agentsAsTools.ts
@@ -0,0 +1,27 @@
+import { Agent } from '@openai/agents';
+
+const bookingAgent = new Agent({
+  name: 'Booking expert',
+  instructions: 'Answer booking questions and modify reservations.',
+});
+
+const refundAgent = new Agent({
+  name: 'Refund expert',
+  instructions: 'Help customers process refunds and credits.',
+});
+
+const customerFacingAgent = new Agent({
+  name: 'Customer-facing agent',
+  instructions:
+    'Talk to the user directly. When they need booking or refund help, call the matching tool.',
+  tools: [
+    bookingAgent.asTool({
+      toolName: 'booking_expert',
+      toolDescription: 'Handles booking questions and requests.',
+    }),
+    refundAgent.asTool({
+      toolName: 'refund_expert',
+      toolDescription: 'Handles refund questions and requests.',
+    }),
+  ],
+});