The agent router is the start_agent block that serves as the entry point for your agent.
The agent router (also described as the start_agent subagent in Agent Script) controls your agent’s entry point and routing logic. Keep it focused on essential subagents and use clear descriptions, filtering, and conditional transitions to guide users to the right place.
Every user utterance begins at the start_agent subagent. It welcomes users, classifies intent, routes to appropriate subagents, and controls which subagents are available based on user state. A well-structured agent router ensures that your users get to the right subagent as effectively as possible.
Pattern Example: A customer service agent’s agent router forces unverified users through identity verification, then routes verified users to Order Management, Returns, or Escalation based on their intent.
The start_agent subagent has the same structure as any other subagent. However, it’s usually geared towards effective and efficient subagent routing.
1start_agent agent_router:
2 description: "Welcome the user and determine the appropriate subagent based on user input"
3
4 reasoning:
5 instructions: ->
6 | Select the best tool to call based on conversation history and user's intent.
7
8 actions:
9 go_to_orders: @utils.transition to @subagent.Order_Management
10 description: "Handles order lookup, refunds, and order updates."
11
12 go_to_faq: @utils.transition to @subagent.General_FAQ
13 description: "Handles FAQ lookup and provides answers to common questions."
14
15 go_to_escalation: @utils.transition to @subagent.Escalation
16 description: "Escalate to a human representative."Remove references to a subagent if you want the subagent to be accessible only via transitions from other subagents.
Good descriptions help your agent select the best subagent. Be specific about what each subagent handles.
1actions:
2 go_to_order: @utils.transition to @subagent.Order_Management
3 description: "Handles order lookup, refunds, order updates, and summarizes status, order date, current location, delivery address, items, and driver name."
4
5 go_to_returns: @utils.transition to @subagent.Returns
6 description: "Processes return requests for orders within the 60-day return window."
7
8 go_to_billing: @utils.transition to @subagent.Billing
9 description: "Handles billing inquiries, payment issues, and invoice questions."You can gate and control flow using available when filters. See the Filtering Pattern for examples.
For critical routing decisions, use conditional transitions in instructions instead of relying on the LLM to choose the right flow. See the Required Subagent Workflow Pattern for examples.
For more on how to effectively transition to another subagent, see the Transitions Pattern.
By default, the agent router is defined as the starting subagent in your agent’s Agent Script. In other words, this is the subagent that uses the start_agent prefix instead of the subagent prefix.
However, you can define another subagent as the starting subagent instead (in Agent Script, the new subagent becomes the start_agent subagent). You can choose to use the agent router to move to subagent classification later in the conversation, or you can remove the agent router from your agent altogether if you want to control subagent routing differently.
go_to_ prefix: Name transition actions with a go_to_ prefix (for example, go_to_orders) so the agent understands they navigate to other subagents.available when to control subagent visibility.
j