<divclass="mr-1">/</div><spanaria-current="page"class="font-medium text-foreground overflow-hidden text-ellipsis whitespace-nowrap">Agent Routing and Hand Off</span>
</nav>
<divid="content"role="main">
<sectionid="agent-routing-and-hand-off">
<spanid="agent-routing"></span><h1>Agent Routing and Hand Off<a@click.prevent="window.navigator.clipboard.writeText($el.href); $el.setAttribute('data-tooltip', 'Copied!'); setTimeout(() => $el.setAttribute('data-tooltip', 'Copy link to this element'), 2000)"aria-label="Copy link to this element"class="headerlink"data-tooltip="Copy link to this element"href="#agent-routing-and-hand-off"><svgheight="1em"viewbox="0 0 24 24"width="1em"xmlns="http://www.w3.org/2000/svg"><pathd="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"></path></svg></a></h1>
<p>Agent Routing and Hand Off is a key feature in Arch that enables intelligent routing of user prompts to specialized AI agents or human agents based on the nature and complexity of the user’s request.</p>
<p>This capability significantly enhances the efficiency and personalization of interactions, ensuring each prompt receives the most appropriate and effective handling. The following section describes
the workflow, configuration, and implementation of Agent routing and hand off in Arch.</p>
<olclass="arabic simple">
<li><p><strong>Agent Selection</strong>
When a user submits a prompt, Arch analyzes the input to determine the intent and complexity. Based on the analysis, Arch selects the most suitable agent configured within your application to handle the specific category of the user’s request—such as sales inquiries, technical issues, or complex scenarios requiring human attention.</p></li>
<li><p><strong>Prompt Routing</strong>
After selecting the appropriate agent, Arch routes the user’s prompt to the designated agent’s endpoint and waits for the agent to respond back with the processed output or further instructions.</p></li>
<li><p><strong>Hand Off</strong>
Based on follow-up queries from the user, Arch repeats the process of analysis, agent selection, and routing to ensure a seamless hand off between AI agents as needed.</p></li>
<divclass="code-block-caption"><spanclass="caption-text">Agent Routing and Hand Off Configuration Example</span><a@click.prevent="window.navigator.clipboard.writeText($el.href); $el.setAttribute('data-tooltip', 'Copied!'); setTimeout(() => $el.setAttribute('data-tooltip', 'Copy link to this element'), 2000)"aria-label="Copy link to this element"class="headerlink"data-tooltip="Copy link to this element"href="#id1"><svgheight="1em"viewbox="0 0 24 24"width="1em"xmlns="http://www.w3.org/2000/svg"><pathd="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"></path></svg></a></div>
</span><spanid="line-3"><spanclass="w"></span><spanclass="nt">description</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">Handles queries related to sales and purchases</span>
</span><spanid="line-9"><spanclass="w"></span><spanclass="nt">description</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">escalates to human agent</span>
<divclass="code-block-caption"><spanclass="caption-text">Agent Routing and Hand Off Implementation Example via FastAPI</span><a@click.prevent="window.navigator.clipboard.writeText($el.href); $el.setAttribute('data-tooltip', 'Copied!'); setTimeout(() => $el.setAttribute('data-tooltip', 'Copy link to this element'), 2000)"aria-label="Copy link to this element"class="headerlink"data-tooltip="Copy link to this element"href="#id2"><svgheight="1em"viewbox="0 0 24 24"width="1em"xmlns="http://www.w3.org/2000/svg"><pathd="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"></path></svg></a></div>
</span><spanid="line-3"><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">system_prompt</span><spanclass="o">=</span><spanclass="sa">f</span><spanclass="s2">"You are a </span><spanclass="si">{</span><spanclass="n">role</span><spanclass="si">}</span><spanclass="s2">.</span><spanclass="se">\n</span><spanclass="si">{</span><spanclass="n">instructions</span><spanclass="si">}</span><spanclass="s2">"</span>
</span><spanid="line-9"><spanclass="k">return</span><spanclass="n">call_openai</span><spanclass="p">(</span><spanclass="n">messages</span><spanclass="p">,</span><spanclass="n">req</span><spanclass="o">.</span><spanclass="n">stream</span><spanclass="p">)</span><spanclass="c1">#call_openai is a placeholder for the actual API call</span>
</span><spanid="line-27"><spanclass="n">role</span><spanclass="o">=</span><spanclass="s2">"issues and repairs agent"</span><spanclass="p">,</span>
</span><spanid="line-28"><spanclass="n">instructions</span><spanclass="o">=</span><spanclass="s2">"Propose a solution, offer refund if necessary."</span><spanclass="p">,</span>
</span><spanid="line-31"><spanclass="n">role</span><spanclass="o">=</span><spanclass="s2">"human escalation agent"</span><spanclass="p">,</span><spanclass="n">instructions</span><spanclass="o">=</span><spanclass="s2">"Escalate issues to a human."</span>
</span><spanid="line-34"><spanclass="n">role</span><spanclass="o">=</span><spanclass="s2">"general assistant"</span><spanclass="p">,</span><spanclass="n">instructions</span><spanclass="o">=</span><spanclass="s2">"Assist the user in general queries."</span>
</span><spanid="line-35"><spanclass="p">),</span>
</span><spanid="line-36"><spanclass="p">}</span>
</span><spanid="line-37">
</span><spanid="line-38"><spanclass="c1">#handle the request from arch gateway</span>
</span><spanid="line-44"><spanclass="n">logger</span><spanclass="o">.</span><spanclass="n">info</span><spanclass="p">(</span><spanclass="sa">f</span><spanclass="s2">"Routing to agent: </span><spanclass="si">{</span><spanclass="n">agent_name</span><spanclass="si">}</span><spanclass="s2">"</span><spanclass="p">)</span>
<h2>Example Use Cases<a@click.prevent="window.navigator.clipboard.writeText($el.href); $el.setAttribute('data-tooltip', 'Copied!'); setTimeout(() => $el.setAttribute('data-tooltip', 'Copy link to this element'), 2000)"aria-label="Copy link to this element"class="headerlink"data-tooltip="Copy link to this element"href="#example-use-cases"x-intersect.margin.0%.0%.-70%.0%="activeSection ='#example-use-cases'"><svgheight="1em"viewbox="0 0 24 24"width="1em"xmlns="http://www.w3.org/2000/svg"><pathd="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"></path></svg></a></h2>
<p>Agent Routing and Hand Off is particularly beneficial in scenarios such as:</p>
<ulclass="simple">
<li><p><strong>Customer Support</strong>: Routing common customer queries to automated support agents, while escalating complex or sensitive issues to human support staff.</p></li>
<li><p><strong>Sales and Marketing</strong>: Automatically directing potential leads and sales inquiries to specialized sales agents for timely and targeted follow-ups.</p></li>
<li><p><strong>Technical Assistance</strong>: Managing user-reported issues, repairs, or refunds by assigning them to the correct technical or support agent efficiently.</p></li>
</ul>
</section>
<sectionid="best-practices-and-tips">
<h2>Best Practices and Tips<a@click.prevent="window.navigator.clipboard.writeText($el.href); $el.setAttribute('data-tooltip', 'Copied!'); setTimeout(() => $el.setAttribute('data-tooltip', 'Copy link to this element'), 2000)"aria-label="Copy link to this element"class="headerlink"data-tooltip="Copy link to this element"href="#best-practices-and-tips"x-intersect.margin.0%.0%.-70%.0%="activeSection ='#best-practices-and-tips'"><svgheight="1em"viewbox="0 0 24 24"width="1em"xmlns="http://www.w3.org/2000/svg"><pathd="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"></path></svg></a></h2>
<p>When implementing Agent Routing and Hand Off in your applications, consider these best practices:</p>
<li><p>Clearly define agent responsibilities: Ensure each agent or human endpoint has a clear, specific description of the prompts they handle, reducing mis-routing.</p></li>
<li><p>Monitor and optimize routes: Regularly review how prompts are routed to adjust and optimize agent definitions and configurations.</p></li>
<p>To observe traffic to and from agents, please read more about <aclass="reference internal"href="observability/observability.html#observability"><spanclass="std std-ref">observability</span></a> in Arch.</p>
<p>By carefully configuring and managing your Agent routing and hand off, you can significantly improve your application’s responsiveness, performance, and overall user satisfaction.</p>
