feat(agent): add Routing node to agent graph

This commit introduces the Routing node to the Agent graph:
- Adds AgentGraphNode::Route and adapts AgentGraph to start from Route, calling agent.route() before CreateTodos.
- Adds the route method to Agent trait and implements it in ButBot to select a workflow path by running pick_route(), which inspects the conversation and chooses Simple or Planning routes.
- ButBotRoute and RouteResponse types introduced to enable flexible agent workflow control.
- butbot.rs now contains logic to determine route based on conversation, plus initiates the correct node.
- lib.rs exposes structured_output_blocking in but-action for routing logic.

This refactor enables dynamic agent flow control between direct/simple actions and planning-based workflows.

Author: estib-vega

crates/but-action/src/lib.rs

@@ -34,7 +34,8 @@ pub use action::Source;
 pub use action::list_actions;
 use but_graph::VirtualBranchesTomlMetadata;
 pub use openai::{
-    ChatMessage, ToolCallContent, ToolResponseContent, tool_calling_loop, tool_calling_loop_stream,
+    ChatMessage, ToolCallContent, ToolResponseContent, structured_output_blocking,
+    tool_calling_loop, tool_calling_loop_stream,
 };
 use strum::EnumString;
 use uuid::Uuid;

crates/but-bot/src/agent.rs

@@ -1,4 +1,5 @@
 pub enum AgentGraphNode {
+    Route,
     CreateTodos,
     ExecuteTodo,
     Done(String),
@@ -17,13 +18,16 @@ impl Default for AgentGraph {
 impl AgentGraph {
     pub fn new() -> Self {
         Self {
-            current_node: AgentGraphNode::CreateTodos,
+            current_node: AgentGraphNode::Route,
         }
     }
 
     pub fn start(&mut self, agent: &mut dyn Agent) -> anyhow::Result<String> {
         loop {
             match self.current_node {
+                AgentGraphNode::Route => {
+                    self.current_node = agent.route()?;
+                }
                 AgentGraphNode::CreateTodos => {
                     self.current_node = agent.create_todos()?;
                 }
@@ -39,6 +43,7 @@ impl AgentGraph {
 }
 
 pub trait Agent {
+    fn route(&mut self) -> anyhow::Result<AgentGraphNode>;
     fn create_todos(&mut self) -> anyhow::Result<AgentGraphNode>;
     fn execute_todo(&mut self) -> anyhow::Result<AgentGraphNode>;
 }

crates/but-bot/src/butbot.rs

@@ -8,6 +8,40 @@ use crate::{
     state::{AgentState, Todo},
 };
 
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub enum ButBotRoute {
+    #[schemars(description = "
+<description>
+Simple routing, no complex planning needed.
+</description>
+
+<when_to_use>
+Use this route when the user request is straightforward and can be handled with simple actions.
+This is the fastest route, and is suitable whenever the objectives are clear and there are not multiple steps involved.
+</when_to_use>
+    ")]
+    Simple,
+    #[schemars(description = "
+<description>
+Complex routing, requires planning and multiple steps.
+</description>
+
+<when_to_use>
+Use this route when the user request is complex, or there is some investigation that needs to be done and requires multiple steps to complete.
+This route is slower, but allows for more complex actions to be performed.
+</when_to_use>
+")]
+    Planning,
+}
+
+#[derive(Debug, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ButButRouteResponse {
+    #[schemars(description = "The route that was taken by the agent.")]
+    pub route: ButBotRoute,
+}
+
 const MODEL: &str = "gpt-4.1";
 
 const SYS_PROMPT: &str = "
@@ -87,6 +121,41 @@ impl<'a> ButBot<'a> {
         }
     }
 
+    pub fn pick_route(&mut self) -> anyhow::Result<ButBotRoute> {
+        let routing_sys_prompt = "
+Your are an expert in determining the best workflow path to take based on the user request.
+Please, take a look at the provided conversation and return which is the route that should be taken.
+";
+
+        let conversation = self
+            .chat_messages
+            .iter()
+            .map(|msg| msg.to_string())
+            .collect::<Vec<_>>()
+            .join("\n\n");
+
+        let messages = vec![but_action::ChatMessage::User(format!(
+            "
+Take a look at the conversation, specifically, the last user request below, and choose the best route to take.
+<CONVERSATION>
+{}
+</CONVERSATION>
+            ",
+             conversation
+        ))];
+
+        let response = but_action::structured_output_blocking::<ButButRouteResponse>(
+            self.openai,
+            routing_sys_prompt,
+            messages,
+        )?;
+
+        match response {
+            Some(route) => Ok(route.route),
+            None => Err(anyhow::anyhow!("Failed to determine the route to take.")),
+        }
+    }
+
     /// Update the agent's state and the provided todos.
     ///
     /// Based on the provided chat messages and the project status, this function will
@@ -372,6 +441,15 @@ If you need to perform actions, do so, and be concise in the description of the
 }
 
 impl Agent for ButBot<'_> {
+    fn route(&mut self) -> anyhow::Result<AgentGraphNode> {
+        match self.pick_route()? {
+            ButBotRoute::Planning => Ok(AgentGraphNode::CreateTodos),
+            ButBotRoute::Simple => {
+                let response = self.workspace_loop()?;
+                Ok(AgentGraphNode::Done(response))
+            }
+        }
+    }
     fn create_todos(&mut self) -> anyhow::Result<AgentGraphNode> {
         self.update_state()?;
 
@@ -385,7 +463,6 @@ impl Agent for ButBot<'_> {
 
     fn execute_todo(&mut self) -> anyhow::Result<AgentGraphNode> {
         if let Some(todo) = self.state.next_todo() {
-            println!("Executing todo: {}", todo.clone().as_prompt());
             let (text_response, messages) = self.execute_todo(&todo)?;
             self.chat_messages = messages;
             self.text_response_buffer.push(text_response);