diff --git a/fern/docs.yml b/fern/docs.yml index 0575e7b36..c0f0d316d 100644 --- a/fern/docs.yml +++ b/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 diff --git a/fern/squads.mdx b/fern/squads.mdx index de33b9aac..af316eb7c 100644 --- a/fern/squads.mdx +++ b/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" } - ] - }, + } + ] } }, ] diff --git a/fern/squads/examples/clinic-triage-scheduling.mdx b/fern/squads/examples/clinic-triage-scheduling.mdx index 79efa948e..42cff12a6 100644 --- a/fern/squads/examples/clinic-triage-scheduling.mdx +++ b/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 diff --git a/fern/squads/examples/multilingual-support.mdx b/fern/squads/examples/multilingual-support.mdx index e40c84e24..f10a670d9 100644 --- a/fern/squads/examples/multilingual-support.mdx +++ b/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 diff --git a/fern/tools/handoff.mdx b/fern/squads/handoff.mdx similarity index 99% rename from fern/tools/handoff.mdx rename to fern/squads/handoff.mdx index 771e4877e..9b2c3838f 100644 --- a/fern/tools/handoff.mdx +++ b/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. diff --git a/fern/squads/silent-transfers.mdx b/fern/squads/silent-handoffs.mdx similarity index 77% rename from fern/squads/silent-transfers.mdx rename to fern/squads/silent-handoffs.mdx index e589f2980..637db598c 100644 --- a/fern/squads/silent-transfers.mdx +++ b/fern/squads/silent-handoffs.mdx @@ -1,9 +1,9 @@ --- -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: @@ -11,15 +11,15 @@ If you want to allow your call flow to move seamlessly from one assistant to ano - 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** - 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. ```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!