fixes, more handoff (#804)

* fixes, more handoff

* actually save files

* move handoff location

* add function name

* handoff tool top level

* properly link handoff docs from tools -> squads

Author: arthurchi93

fern/docs.yml

@@ -191,8 +191,8 @@ navigation:
               - page: Custom tools troubleshooting
                 path: tools/custom-tools-troubleshooting.mdx
                 icon: fa-light fa-wrench
-              - page: Handoff tool
-                path: tools/handoff.mdx
+              - link: Handoff tool
+                href: /squads/handoff
                 icon: fa-light fa-hand-holding-hand
               - section: External tools
                 icon: fa-light fa-cubes
@@ -308,6 +308,9 @@ navigation:
           - page: Overview
             path: squads.mdx
             icon: fa-light fa-eye
+          - page: Handoff tool
+            path: squads/handoff.mdx
+            icon: fa-light fa-hand-holding-hand
           - section: Examples
             icon: fa-light fa-code
             contents:
@@ -321,8 +324,8 @@ navigation:
                 path: squads/examples/property-management.mdx
               - page: Multilingual support
                 path: squads/examples/multilingual-support.mdx
-              - page: Silent transfers
-                path: squads/silent-transfers.mdx
+              - page: Silent handoffs
+                path: squads/silent-handoffs.mdx
                 icon: fa-light fa-arrow-right-arrow-left
 
       - section: Best practices

fern/squads.mdx

@@ -51,7 +51,10 @@ We recommend using [Handoff Tools](/tools/handoff) to specify which destinations
                                         "assistantId": "assistant-123",
                                         "description": "Call this tool when the customer wants to talk about pricing"
                                     }
-                                ]
+                                ],
+                                "function": {
+                                    "name": "handoff_to_assistant_123"
+                                }
                             }
                         ]
                     },
@@ -94,7 +97,7 @@ To override the configuration of a saved assistant without modifying the underly
 }
 ```
 
-You may also define inline tools via assistant overrides through the `model` object (using `tools:append`), so that the assistant will only handoff if it is a part of this squad.
+You may also define inline tools via `assistantOverrides` through the `tools:append` array, so that the assistant will only handoff if it is a part of this squad.
 ```json
 {
     "squad": {
@@ -111,22 +114,21 @@ You may also define inline tools via assistant overrides through the `model` obj
             {
                 "assistantId": "saved-assistant-id",
                 "assistantOverrides": {
-                    "model": {
-                        "provider": "openai",
-                        "model": "gpt-4o",
-                        "tools:append": [
-                            {
-                                "type": "handoff",
-                                "destinations": [
-                                    {
-                                        "type": "assistant",
-                                        "assistantId": "assistant-123",
-                                        "description": "Call this tool when the customer wants to talk about pricing"
-                                    }
-                                ]
+                    "tools:append": [
+                        {
+                            "type": "handoff",
+                            "destinations": [
+                                {
+                                    "type": "assistant",
+                                    "assistantId": "assistant-123",
+                                    "description": "Call this tool when the customer wants to talk about pricing"
+                                }
+                            ],
+                            "function": {
+                                "name": "handoff_to_assistant_123"
                             }
-                        ]
-                    },
+                        }
+                    ]
                 }
             },
         ]

fern/squads/examples/clinic-triage-scheduling.mdx

@@ -35,8 +35,6 @@ Compose multiple assistants into a Squad for safe, specialized healthcare flows:
 - From Triage → Scheduler for routine care
 - Warm-transfer with a short summary for human escalation
 
-See: [Silent transfers](/squads/silent-transfers).
-
 ## 3. Implement
 
 <Tabs>

fern/squads/examples/multilingual-support.mdx

@@ -12,7 +12,7 @@ Provide structured multilingual support using a Squad: present a short language
 **Squad Capabilities:**
 * Explicit language choice for clarity
 * Language‑specific prompts and voices
-* Seamless transfers while preserving context
+* Seamless handoffs while preserving context
 
 ## 1. Define members
 

fern/tools/handoff.mdx renamed to fern/squads/handoff.mdx

@@ -1,7 +1,7 @@
 ---
 title: Handoff Tool
 subtitle: 'Transfer the call to another assistant.'
-slug: tools/handoff
+slug: squads/handoff
 ---
 
 The handoff tool enables seamless call transfers between assistants in a multi-agent system. This guide covers all configuration patterns and use cases.

fern/squads/silent-transfers.mdx renamed to fern/squads/silent-handoffs.mdx

@@ -1,25 +1,25 @@
 ---
-title: Silent Transfers
-slug: squads/silent-transfers
+title: Silent Handoffs
+slug: squads/silent-handoffs
 ---
-- **The Problem**: In traditional AI call flows, when transferring from one agent to another, announcing the transfer verbally can confuse or annoy callers and disrupt the conversation's flow.
-- **The Solution**: Silent transfers keep the call experience _uninterrupted_, so the user doesn’t know multiple assistants are involved. The conversation flows more naturally, boosting customer satisfaction.
+- **The Problem**: In traditional AI call flows, when handing off from one agent to another, announcing the handoff verbally can confuse or annoy callers and disrupt the conversation's flow.
+- **The Solution**: Silent handoffs keep the call experience _uninterrupted_, so the user doesn’t know multiple assistants are involved. The conversation flows more naturally, boosting customer satisfaction.
 
 If you want to allow your call flow to move seamlessly from one assistant to another _without_ the caller hearing `Please hold while we transfer you` here’s what to do:
 
 1. **Update the Destination Assistant’s First Message**
    - Set the assistant's `firstMessage` to an _empty string_.
    - Set the assistant's `firstMessageMode` to `assistant-speaks-first-with-model-generated-message`.
 
-2. **Update the Squad's assistant destinations messages**
-   - For every `members[*].assistantDestinations[*]`, set the `message` property to an _empty string_.
+2. **Update the Squad's handoff messages**
+   - For every `members[*].model.tools/toolIds`, unset the `messages` property.
 
 3. **Trigger the Transfer from the Source Assistant**
 
-   - In that assistant’s prompt, include a line instructing it to transfer to the desired assistant:
+   - In that assistant’s prompt, include a line instructing it to hand off to the desired assistant:
 
    ```json
-   trigger the transferCall tool with 'assistantName' Assistant.
+   trigger the 'handoff' tool with 'assistantName' Assistant.
    ```
 
    - Replace `'assistantName'` with the exact name of the next assistant.
@@ -32,49 +32,65 @@ If you want to allow your call flow to move seamlessly from one assistant to ano
 
 - **HPMA (Main Assistant)** is talking to the customer. They confirm the order details and then quietly passes the conversation to **HPPA (Payment Assistant)**.
 - **HPPA** collects payment details without the customer ever hearing, `We’re now transferring you to the Payment Assistant.` It feels like one continuous conversation.
-- Once payment is done, **HPPA** transfers the call again—this time to **HPMA-SA (Main Sub Assistant)**—which takes over final shipping arrangements.
+- Once payment is done, **HPPA** hands off the call again—this time to **HPMA-SA (Main Sub Assistant)**—which takes over final shipping arrangements.
 
 Everything happens smoothly behind the scenes!
 
 ## **Squad and Assistant Configurations**
 
-Below are the key JSON examples you’ll need. These show how to structure your assistants and squads so they work together for silent transfers.
+Below are the key JSON examples you’ll need. These show how to structure your assistants and squads so they work together for silent handoffs.
 
 ### **HP Payment Squad With SubAgent**
 
 <Warning>
-  Make sure the `members[*].assistantDestinations[*].message` properties are set to an _empty string_.
+  Make sure the `members[*].model.tools.messages` properties are set to null or empty array.
 </Warning>
 
 ```json
 {
   "members": [
     {
-      "assistantId": "2d8e0d13-1b3c-4358-aa72-cf6204d6244e",
-      "assistantDestinations": [
-        {
-          "message": " ",
-          "description": "Transfer call to the payment agent",
-          "type": "assistant",
-          "assistantName": "HPPA"
-        }
-      ]
+      "name": "HPMA (Main Assistant)",
+      "model": {
+        "provider": "openai",
+        "model": "gpt-4o",
+        "tools": [
+          {
+            "type": "handoff",
+            "destinations": [
+              {
+                "type": "assistant",
+                "assistantName": "HPPA"
+              }
+            ],
+            "messages": [],
+          }
+        ]
+      },
+      ...
     },
     {
-      "assistantId": "ad1c5347-bc32-4b31-8bb7-6ff5fcb131f4",
-      "assistantDestinations": [
-        {
-          "message": " ",
-          "description": "Transfer call to the main sub agent",
-          "type": "assistant",
-          "assistantName": "HPMA-SA"
-        }
-      ]
+      "name": "HPPA",
+      "model": {
+        "tools": [
+          {
+            "type": "handoff",
+            "destinations": [
+              {
+                "type": "assistant",
+                "assistantName": "HPMA-SA"
+              }
+            ],
+            "messages": null,
+          }
+        ]
+      },
+      ...
     },
     {
-      "assistantId": "f1c258bc-4c8b-4c51-9b44-883ab5e40b2f",
-      "assistantDestinations": []
-    }
+      "name": "HPMA-SA",
+      ...
+    },
   ],
   "name": "HP Payment Squad With SubAgent"
 }
@@ -160,7 +176,7 @@ Answer only questions related to the context.
 3.Ask how many widgets the customer would like to purchase.
    - Wait for the customer's response.
 4.Confirm the order details with the customer.
-   - trigger the transferCall tool with Payment `HPPA` Assistant.
+   - trigger the handoff tool with Payment `HPPA` Assistant.
 ```
 
 ### **HPPA (Payment Assistant Prompt)**
@@ -200,7 +216,7 @@ any greetings or small talk.
 3. Ask for the CVV number.
    - Wait for the customer's response.
 4. Confirm that the payment has been processed successfully.
-   - trigger the transferCall tool with Payment `HPMA-SA` Assistant.
+   - trigger the handoff tool with Payment `HPMA-SA` Assistant.
 ```
 
 ### **HPMA-SA (Main Sub Assistant Prompt)**
@@ -245,6 +261,6 @@ or small talk.
 
 ## **Conclusion**
 
-By following these steps and examples, you can configure your call system to conduct **silent transfers** ensuring that callers experience a single, uninterrupted conversation. Each assistant does its job smoothly, whether it’s capturing payment, finalizing a shipping address, or collecting basic info.
+By following these steps and examples, you can configure your call system to conduct **silent handoffs** ensuring that callers experience a single, uninterrupted conversation. Each assistant does its job smoothly, whether it’s capturing payment, finalizing a shipping address, or collecting basic info.
 
-Enjoy setting up your silent transfers!
+Enjoy setting up your silent handoffs!