universal-mcp-agents 0.1.15__tar.gz → 0.1.16__tar.gz

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: universal-mcp-agents
-Version: 0.1.15
+Version: 0.1.16
 Summary: Add your description here
 Project-URL: Homepage, https://github.com/universal-mcp/applications
 Project-URL: Repository, https://github.com/universal-mcp/applications

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "universal-mcp-agents"
-version = "0.1.15"
+version = "0.1.16"
 description = "Add your description here"
 readme = "README.md"
 authors = [

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/src/universal_mcp/agents/codeact0/llm_tool.py

@@ -27,6 +27,7 @@ def smart_print(data: Any) -> None:
     Args:
         data: Either a dictionary with string keys, or a list of such dictionaries
     """
+    print(light_copy(data)) # noqa
 
 
 def creative_writer(

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/src/universal_mcp/agents/codeact0/playbook_agent.py

@@ -25,7 +25,7 @@ from universal_mcp.agents.codeact0.state import CodeActState
 from universal_mcp.agents.codeact0.tools import create_meta_tools, enter_playbook_mode, exit_playbook_mode, get_valid_tools
 from universal_mcp.agents.codeact0.utils import inject_context, smart_truncate
 from universal_mcp.agents.llm import load_chat_model
-from universal_mcp.agents.utils import filter_retry_on, get_message_text
+from universal_mcp.agents.utils import filter_retry_on, get_message_text, convert_tool_ids_to_dict
 
 PLAYBOOK_PLANNING_PROMPT = """Now, you are tasked with creating a reusable playbook from the user's previous workflow.
 
@@ -69,6 +69,7 @@ class CodeActPlaybookAgent(BaseAgent):
         memory: BaseCheckpointSaver | None = None,
         tools: ToolConfig | None = None,
         registry: ToolRegistry | None = None,
+        playbook_registry: object | None = None,
         sandbox_timeout: int = 20,
         **kwargs,
     ):
@@ -82,33 +83,33 @@ class CodeActPlaybookAgent(BaseAgent):
         self.model_instance = load_chat_model(model, thinking=True)
         self.tools_config = tools or []
         self.registry = registry
+        self.playbook_registry = playbook_registry
         self.eval_fn = eval_unsafe
         self.sandbox_timeout = sandbox_timeout
         self.processed_tools: list[StructuredTool | Callable] = []
 
     async def _build_graph(self):
-        self.exported_tools = []
-        if self.tools_config:
-            # Convert dict format to list format if needed
-            if isinstance(self.tools_config, dict):
-                self.tools_config = [
-                    f"{provider}__{tool}" 
-                    for provider, tools in self.tools_config.items() 
-                    for tool in tools
-                ]
-            if not self.registry:
-                raise ValueError("Tools are configured but no registry is provided")
-            # Langchain tools are fine
-            self.exported_tools = await self.registry.export_tools(self.tools_config, ToolFormat.LANGCHAIN)
         meta_tools = create_meta_tools(self.registry)
-        await self.registry.export_tools(["exa__search_with_filters"], ToolFormat.LANGCHAIN)
         additional_tools = [smart_print, data_extractor, ai_classify, call_llm, meta_tools["web_search"]]
         self.additional_tools = [t if isinstance(t, StructuredTool) else create_tool(t) for t in additional_tools]
-        self.final_instructions, self.tools_context = create_default_prompt(
-            self.exported_tools, self.additional_tools, self.instructions
-        )
-
-        def call_model(state: CodeActState) -> Command[Literal["sandbox", "execute_tools"]]:
+        async def call_model(state: CodeActState) -> Command[Literal["sandbox", "execute_tools"]]:
+            self.exported_tools = []
+            if self.tools_config:
+                # Convert dict format to list format if needed
+                if isinstance(self.tools_config, dict):
+                    self.tools_config = [
+                        f"{provider}__{tool}" 
+                        for provider, tools in self.tools_config.items() 
+                        for tool in tools
+                    ]
+                if not self.registry:
+                    raise ValueError("Tools are configured but no registry is provided")
+                # Langchain tools are fine
+            self.tools_config.extend(state.get('selected_tool_ids',[]))
+            self.exported_tools = await self.registry.export_tools(self.tools_config, ToolFormat.LANGCHAIN)
+            self.final_instructions, self.tools_context = create_default_prompt(
+                self.exported_tools, self.additional_tools, self.instructions
+            )
             messages = [{"role": "system", "content": self.final_instructions}] + state["messages"]
 
             # Run the model and potentially loop for reflection
@@ -262,16 +263,16 @@ class CodeActPlaybookAgent(BaseAgent):
                 # Extract plan from response text between triple backticks
                 plan_match = re.search(r'```(.*?)```', response_text, re.DOTALL)
                 if plan_match:
-                    self.plan = plan_match.group(1).strip()
+                    plan = plan_match.group(1).strip()
                 else:
-                    self.plan = response_text.strip()
-                return Command(update={"messages": [response], "playbook_mode": "confirming"})
+                    plan = response_text.strip()
+                return Command(update={"messages": [response], "playbook_mode": "confirming", "plan": plan})
                 
 
             elif playbook_mode == "confirming":
                 confirmation_instructions = self.instructions + PLAYBOOK_CONFIRMING_PROMPT
                 messages = [{"role": "system", "content": confirmation_instructions}] + state["messages"]
-                response = self.model_instance.invoke(messages)
+                response = self.model_instance.invoke(messages, stream=False)
                 response = get_message_text(response)
                 if "true" in response.lower():
                     return Command(goto="playbook", update={"playbook_mode": "generating"})
@@ -296,24 +297,34 @@ class CodeActPlaybookAgent(BaseAgent):
                 else:
                     function_name = "generated_playbook"
 
+                # Save or update an Agent using the helper registry
+                saved_note = ""
                 try:
-                    current_path = Path(__file__).resolve()
-                    repo_root = None
-                    for ancestor in current_path.parents:
-                        if ancestor.name == "src":
-                            repo_root = ancestor.parent
-                            break
-                    if repo_root is None:
-                        repo_root = current_path.parents[-1]
-
-                    playbooks_dir = repo_root / "playbooks"
-                    playbooks_dir.mkdir(parents=True, exist_ok=True)
-
-                    file_path = playbooks_dir / f"{function_name}.py"
-                    file_path.write_text(func_code, encoding="utf-8")
-                    saved_note = f"Playbook function saved to: {file_path} ```{func_code}```"
+                    if not self.playbook_registry:
+                        raise ValueError("Playbook registry is not configured")
+
+                    # Build instructions payload embedding the plan and function code
+                    instructions_payload = {
+                        "playbookPlan": state["plan"],
+                        "playbookScript": {
+                            "name": function_name,
+                            "code": func_code,
+                        },
+                    }
+
+                    # Convert tool ids list to dict
+                    tool_dict = convert_tool_ids_to_dict(state["selected_tool_ids"])
+
+                    res = self.playbook_registry.create_agent(
+                        name=function_name,
+                        description=f"Generated playbook: {function_name}",
+                        instructions=instructions_payload,
+                        tools=tool_dict,
+                        visibility="private",
+                    )
+                    saved_note = f"Successfully created your playbook! Check it out here: [View Playbook](https://wingmen.info/agents/{res.id})"
                 except Exception as e:
-                    saved_note = f"Failed to save playbook function {function_name}: {e}"
+                    saved_note = f"Failed to save generated playbook as Agent '{function_name}': {e}"
 
                 # Mock tool call for exit_playbook_mode (for testing/demonstration)
                 mock_exit_tool_call = {
@@ -322,7 +333,7 @@ class CodeActPlaybookAgent(BaseAgent):
                     "id": "mock_exit_playbook_123"
                 }
                 mock_assistant_message = AIMessage(
-                    content="",  # Can be empty or a brief message
+                    content=saved_note, 
                     tool_calls=[mock_exit_tool_call]
                 )
 

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/src/universal_mcp/agents/codeact0/state.py

@@ -34,3 +34,5 @@ class CodeActState(AgentState):
     """State for the playbook agent."""
     selected_tool_ids: Annotated[list[str], _enqueue]
     """Queue for tools exported from registry"""
+    plan: str | None
+    """Plan for the playbook agent."""

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/src/universal_mcp/agents/codeact0/tools.py

@@ -4,6 +4,7 @@ from typing import Any
 
 from langchain_core.tools import tool
 from universal_mcp.tools.registry import ToolRegistry
+from universal_mcp.types import ToolFormat
 
 MAX_LENGHT=100
 
@@ -30,8 +31,8 @@ def create_meta_tools(tool_registry: ToolRegistry) -> dict[str, Any]:
             connections = await tool_registry.list_connected_apps()
             connected_apps = {connection["app_id"] for connection in connections}
 
-            # Use defaultdict to avoid key existence checks
-            app_tools = defaultdict(list)
+            app_tools = defaultdict(set)
+            MAX_LENGTH = 20
 
             # Process all queries concurrently
             search_tasks = []
@@ -40,20 +41,24 @@ def create_meta_tools(tool_registry: ToolRegistry) -> dict[str, Any]:
 
             query_results = await asyncio.gather(*search_tasks)
 
-            # Aggregate results with limit per app
+            # Aggregate results with limit per app and automatic deduplication
             for tools_list in query_results:
                 for tool in tools_list:
                     app = tool["id"].split("__")[0]
-                    if len(app_tools[app]) < MAX_LENGHT:
+                    tool_id = tool["id"]
+                    
+                    # Check if within limit and add to set (automatically deduplicates)
+                    if len(app_tools[app]) < MAX_LENGTH:
                         cleaned_desc = tool["description"].split("Context:")[0].strip()
-                        app_tools[app].append(f"{tool['id']}: {cleaned_desc}")
+                        app_tools[app].add(f"{tool_id}: {cleaned_desc}")
 
             # Build result string efficiently
             result_parts = []
             for app, tools in app_tools.items():
                 app_status = "connected" if app in connected_apps else "NOT connected"
                 result_parts.append(f"Tools from {app} (status: {app_status} by user):")
-                for tool in tools:
+                # Convert set to sorted list for consistent output
+                for tool in sorted(tools):
                     result_parts.append(f" - {tool}")
                 result_parts.append("")  # Empty line between apps
 
@@ -116,6 +121,7 @@ def create_meta_tools(tool_registry: ToolRegistry) -> dict[str, Any]:
         Example:
             results = await web_search(query="python programming")
         """
+        await tool_registry.export_tools(["exa__search_with_filters"], ToolFormat.LANGCHAIN)
         response = await tool_registry.call_tool(
             "exa__search_with_filters", {"query": query, "contents": {"summary": True}}
         )

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/src/universal_mcp/agents/codeact0/utils.py

@@ -6,7 +6,7 @@ from typing import Any
 
 from langchain_core.messages import BaseMessage
 
-MAX_CHARS = 300
+MAX_CHARS = 700
 
 
 def light_copy(data):

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/src/universal_mcp/agents/utils.py

@@ -214,3 +214,21 @@ def filter_retry_on(exc: Exception) -> bool:
 
     # Default: do not retry unknown exceptions
     return False
+
+
+def convert_tool_ids_to_dict(tool_ids: list[str]) -> dict[str, list[str]]:
+    """Convert list of tool ids like 'provider__tool' into a provider->tools dict.
+
+    Any ids without the expected delimiter are ignored.
+    """
+    provider_to_tools: dict[str, list[str]] = {}
+    for tool_id in tool_ids or []:
+        if "__" not in tool_id:
+            continue
+        provider, tool = tool_id.split("__", 1)
+        if not provider or not tool:
+            continue
+        if provider not in provider_to_tools:
+            provider_to_tools[provider] = []
+        provider_to_tools[provider].append(tool)
+    return provider_to_tools

{universal_mcp_agents-0.1.15 → universal_mcp_agents-0.1.16}/uv.lock

@@ -4925,7 +4925,7 @@ wheels = [
 
 [[package]]
 name = "universal-mcp-agents"
-version = "0.1.14"
+version = "0.1.15"
 source = { editable = "." }
 dependencies = [
     { name = "langchain-anthropic" },

universal_mcp_agents-0.1.15/test.py

@@ -1,25 +0,0 @@
-import asyncio
-import time
-
-from loguru import logger
-
-from universal_mcp.agents import get_agent
-
-
-async def main():
-    agent_cls = get_agent("simple")
-    start_time = time.time()
-    agent = agent_cls(
-        name="Simple Agent",
-        instructions="You are a simple agent that can answer questions.",
-        model="anthropic/claude-sonnet-4-20250514",
-    )
-    logger.info(f"Time building agent taken: {time.time() - start_time} seconds")
-    await agent.ainit()
-    logger.info(f"Time initializing agent taken: {time.time() - start_time} seconds")
-    result = await agent.invoke(user_input="What is the capital of France?")
-    logger.info(f"Time invoking agent taken: {time.time() - start_time} seconds")
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

universal_mcp_agents-0.1.15/todo.md

@@ -1,157 +0,0 @@
-# Design Decisions and Learnings
-
-This section documents the key architectural decisions and learnings guiding the evolution of the `UnifiedAgent`. It will be updated continuously as the project progresses.
-
-## Core Design Shift: Embracing a Hybrid, Code-Centric Architecture
-
-Our primary design decision is to evolve the `UnifiedAgent` from a rigid, structured tool-calling system into a powerful hybrid agent. This new architecture combines the dynamic tool management of the original `UnifiedAgent` with the expressive, direct code execution model pioneered by `smolagents`.
-
-### Clarification: `execute_ipython_cell` vs. Direct Code Execution
-
-It's important to clarify the distinction between the current `execute_ipython_cell` tool and the proposed direct code execution model. Both execute code, but the architectural difference is profound:
-
--   **Current Model (Structured Call):** The LLM's native output is a structured command (a JSON object) to call the `execute_ipython_cell` tool. The code to be executed is merely a *string argument* within that command. This creates a layer of indirection and treats code execution as just another rigid tool.
--   **Proposed Model (Direct Output):** The LLM's native output *is the code itself*. The agent's framework is responsible for parsing this code directly from the response and executing it. This makes code the agent's primary mode of expression.
-
-The key shift is to move from treating code execution as a constrained, structured tool call to making it the **agent's native output**. This is the foundation for unlocking greater power and statefulness.
-
-### Why We Are Moving to a Code-Centric Approach
-
-The initial structured-call model is safe and predictable but severely limits the agent's capabilities. By shifting to a model where the LLM's primary output is a Python code snippet, we unlock several key advantages that are critical for a general-purpose agent:
-
-1.  **Unlocks True Power and Composability:** Direct code output allows the agent to write scripts that use loops, conditionals, variables, and error handling. It can chain multiple tool calls together in a single, logical action, which is impossible with a one-tool-per-turn structured model. This moves the agent from a simple "tool caller" to a true "problem solver."
-
-2.  **Increases Efficiency and Reduces Cost:** By accomplishing more in a single turn, the agent requires fewer back-and-forth interactions with the LLM. This directly translates to lower latency (faster task completion) and reduced operational costs (fewer API calls).
-
-3.  **Enables On-the-Fly Data Manipulation:** An agent that thinks in code can process and transform data between tool calls without needing an extra LLM turn. It can reformat strings, perform calculations, and filter lists as part of a single, coherent script.
-
-4.  **Leverages the Core Strengths of Modern LLMs:** State-of-the-art models are exceptionally proficient at code generation. This approach allows the agent to "think" in Python, a language it excels at, rather than constraining it to a rigid JSON schema.
-
-### The Hybrid "Planner-Executor" Model and the Role of a Stateful Executor
-
-The goal is a hybrid "Planner-Executor" model. The Planner (the `UnifiedAgent`'s graph) sets high-level strategic goals, and the Executor (`smolagents`-style code generation) writes powerful scripts to accomplish each goal.
-
-This model **only works** if the execution environment is **stateful**. A variable or function defined in one Executor script (to complete step 1 of the plan) *must* be available to the next Executor script (to complete step 2).
-
-This is why **Step 4 and 5** of the plan are critical. We will replace the current stateless `Sandbox` with the **stateful `LocalPythonExecutor`** from `smolagents`. This executor acts like a persistent Python session, maintaining its memory across multiple turns of the Planner's graph. It is the glue that connects the Planner's strategic steps, allowing the agent to build complex solutions over time.
-
-### The Hybrid Toolset: Achieving Efficiency and Generality via Prompting
-
-A key challenge is balancing the power of dynamic tool discovery with the efficiency needed for simple tasks. A pure "Search, Load, Execute" workflow is too slow for common requests (e.g., "What is 2+2?").
-
-**Our Solution:** We will implement a **hybrid toolset** model, controlled entirely through prompting to keep the architecture simple.
-
-1.  **Pre-loaded Default Tools:** The agent will start with a small set of essential, always-available tools (e.g., `execute_ipython_cell`, `web_search`). These will be pre-loaded into the executor's environment.
-
-2.  **Prompt-Driven Logic:** The system prompt will be structured to guide the LLM's reasoning. It will instruct the agent to **always attempt to solve the task using the default tools first**.
-
-3.  **Fallback to Discovery:** The prompt will specify that the agent should **only use the `search_tools` meta-tool if it determines its default toolkit is insufficient** for the task at hand.
-
-This creates an efficient "fast path" for the majority of tasks while retaining the full power of dynamic tool discovery for specialized requests, all without adding complexity to the agent's graph architecture.
-
----
-
-# Comparison: Unified Agent vs. Smolagents' CodeAgent
-
-This document outlines the major differences, pros, and cons between the `unified` agent and the `CodeAgent` from the `smolagents` library.
-
-## 1. Core Architecture
-
-### Unified Agent
-- **Architecture:** State machine implemented with `langgraph`.
-- **Execution Model:** Relies on predefined tool calls (`search_tools`, `load_tools`, `execute_ipython_cell`). The LLM's output is a structured tool call.
-- **Flexibility:** Less flexible. The agent is constrained to the predefined tools and the logic of the graph.
-
-### Smolagents' CodeAgent
-- **Architecture:** ReAct-style loop (Reason, Act, Observe).
-- **Execution Model:** The LLM generates Python code directly, which is then executed in a `PythonExecutor`. This is a more direct and powerful approach.
-- **Flexibility:** Highly flexible. The agent can generate any Python code, allowing it to perform complex computations, define functions, and chain operations without being limited to a predefined set of tools.
-
-## 2. Prompting
-
-### Unified Agent
-- **Prompting:** A single, monolithic prompt that instructs the LLM on how to use the available tools.
-- **Few-shot Examples:** Lacks few-shot examples, which can make it harder for the LLM to understand the expected output format.
-
-### Smolagents' CodeAgent
-- **Prompting:** Uses a YAML file for prompts, which is cleaner and easier to manage.
-- **Few-shot Examples:** Incorporates few-shot examples to guide the LLM, which generally improves the quality and reliability of the generated code.
-
-## 3. Code Execution
-
-### Unified Agent
-- **Sandbox:** Uses a simple `Sandbox` to execute Python code snippets via `execute_ipython_cell`.
-- **State Management:** State is managed within the `langgraph` state, but the code execution environment is stateless between `execute_ipython_cell` calls unless explicitly handled.
-
-### Smolagents' CodeAgent
-- **Executor:** Uses a more advanced `PythonExecutor` that can be local, or remote (Docker, E2B).
-- **State Management:** The `PythonExecutor` maintains state between code executions, allowing the agent to define variables and functions that persist across turns.
-
-## 4. Pros and Cons
-
-### Unified Agent
-**Pros:**
-- **Structured:** The state machine provides a clear and predictable execution flow.
-- **Safe:** The agent is limited to a predefined set of tools, which can be seen as a safety feature.
-
-**Cons:**
-- **Rigid:** The predefined toolset and graph structure make it less flexible.
-- **Complex:** The `langgraph` implementation can be complex to understand and modify.
-- **Less Powerful:** The agent's capabilities are limited by the available tools.
-
-### Smolagents' CodeAgent
-**Pros:**
-- **Flexible:** The code-centric approach allows the agent to solve a wider range of tasks.
-- **Powerful:** The agent can leverage the full power of Python, including defining functions, classes, and using third-party libraries.
-- **Extensible:** Easy to add new tools by simply making them available in the Python execution environment.
-
-**Cons:**
-- **Less Structured:** The ReAct loop is less structured than a state machine, which can make it harder to debug.
-- **Security:** Executing arbitrary code from an LLM is a security risk, although this is mitigated by the use of sandboxed environments.
-
-## TODO: A Multi-Step Plan for a Hybrid Agent
-
-This plan outlines a series of small, atomic changes to evolve the `UnifiedAgent` into a more powerful hybrid agent that combines the structured, dynamic tool management of `langgraph` with the expressive code execution of `smolagents`.
-
-### Phase 1: Foundational Changes - Shifting to Code Generation
-
-- [x] **1. Externalize Prompting:**
-    - [x] Create a `prompts.yaml` file in `src/universal_mcp/agents/unified/`.
-    - [x] Move the `SYSTEM_PROMPT` from `prompts.py` into `prompts.yaml`.
-    - [x] Update `UnifiedAgent` in `agent.py` to load its system prompt from the new YAML file. This separates configuration from code and aligns with `smolagents` best practices.
-
-- [x] **2. Introduce a Code-Centric Prompt:**
-    - [x] In `prompts.yaml`, modify the system prompt to instruct the LLM to output Python code directly, using Markdown syntax for code blocks (e.g., ` ```python ... ``` `).
-    - [x] Add one or two few-shot examples to the prompt, demonstrating how to call a meta-tool (like `web_search`) directly within a code block.
-
-- [ ] **3. Adapt Graph for Direct Code Output:**
-    - [ ] In `graph.py`, modify the `agent_node` to parse the Python code block from the LLM's raw text response instead of expecting a structured `tool_calls` attribute.
-    - [ ] The output of the `agent_node` should now be the extracted code snippet (as a string).
-    - [ ] Update the `execute_tools_node` to wrap this code snippet into a call to the `execute_ipython_cell` tool. This maintains the existing execution logic while adapting to the new code-centric output from the LLM.
-
-### Phase 2: Integrating a More Powerful and Stateful Executor
-
-- [ ] **4. Replace Sandbox with `LocalPythonExecutor`:**
-    - [ ] Integrate `smolagents.local_python_executor.LocalPythonExecutor` into the `UnifiedAgent`.
-    - [ ] In `agent.py`, replace the `Sandbox` instance with a persistent `LocalPythonExecutor` instance.
-    - [ ] In `graph.py`, modify the `execute_tools_node` to call the `python_executor` directly with the code snippet.
-    - [ ] Remove the `execute_ipython_cell` meta-tool, as the executor now handles code execution directly.
-
-- [ ] **5. Enable Stateful Execution Across Turns:**
-    - [ ] Ensure the `LocalPythonExecutor` instance on the `UnifiedAgent` is the same one used across all steps in the graph.
-    - [ ] Verify that variables, functions, and imports defined in one turn are accessible in subsequent turns within the same `invoke` session.
-
-### Phase 3: Enhancing Tool Management and Workflow
-
-- [ ] **6. Dynamic Tool Injection into the Executor:**
-    - [ ] Modify the `load_tools` logic in `graph.py`. When a tool is loaded, inject it directly into the `python_executor`'s namespace (both static and custom tools).
-    - [ ] Update the system prompt in `prompts.yaml` to dynamically list the function signatures of the currently available tools in the executor's environment, making the LLM aware of what it can call.
-
-- [ ] **7. Simplify the Graph (Optional but Recommended):**
-    - [ ] Evaluate the necessity of the `validate_code_node`. Since `LocalPythonExecutor` can catch and report syntax errors, this validation might be redundant. Consider removing it and handling errors directly in the `execute_tools_node`.
-    - [ ] Consider merging the `format_final_answer_node`'s logic into the main agent prompt, instructing the agent to provide a user-friendly summary before calling `finish()`.
-
-- [ ] **8. Integrate Optional Planning:**
-    - [ ] Add a `planning_interval` parameter to the `UnifiedAgent`.
-    - [ ] Introduce a new `planning_node` in the graph that generates or updates a high-level plan.
-    - [ ] Add a conditional edge that routes the graph to the `planning_node` every N steps, injecting the plan back into the agent's state.