Agent Script Pattern: Agent Router Strategies

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.

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.

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.

  • Limit subagents: Start with essential subagents and add more gradually as needed. Fewer subagents means clearer routing decisions for your agent.
  • Use the 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.
  • Write detailed descriptions: Use detailed and unique descriptions so the agent knows when to choose a subagent, especially if you have similar subagents.
  • Hide subagents based on context: Use available when to control subagent visibility.
  • Conditional logic: Use conditional logic to guarantee that routing occurs before other processing.