universal-mcp-agents 0.1.23rc11__tar.gz → 0.1.24__tar.gz

universal_mcp_agents-0.1.24/.gemini/settings.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "langchain": {
+      "httpUrl": "https://docs.langchain.com/mcp"
+    }
+  }
+}

{universal_mcp_agents-0.1.23rc11 → universal_mcp_agents-0.1.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: universal-mcp-agents
-Version: 0.1.23rc11
+Version: 0.1.24
 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.23rc11 → universal_mcp_agents-0.1.24}/pyproject.toml

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

{universal_mcp_agents-0.1.23rc11 → universal_mcp_agents-0.1.24}/src/universal_mcp/agents/__init__.py

@@ -11,6 +11,7 @@ from universal_mcp.agents.simple import SimpleAgent
 def get_agent(
     agent_name: Literal["react", "simple", "builder", "bigtool", "codeact-repl"],
 ):
+    print("agent_name", agent_name)
     if agent_name == "react":
         return ReactAgent
     elif agent_name == "simple":

{universal_mcp_agents-0.1.23rc11 → universal_mcp_agents-0.1.24}/src/universal_mcp/agents/base.py

@@ -67,13 +67,10 @@ class BaseAgent:
             ):
                 if event == "messages" and isinstance(meta, (tuple, list)) and len(meta) == 2:  # noqa: PLR2004
                     payload, meta_dict = meta
-                    if meta_dict.get("tags") and "quiet" in meta_dict.get("tags"):
+                    metadata = getattr(payload, "metadata", {}) or {}
+                    if metadata and "quiet" in metadata.get("tags"):
                         continue
-                    is_agent_builder = (
-                        isinstance(meta_dict, dict) and meta_dict.get("langgraph_node") == "agent_builder"
-                    )
-                    additional_kwargs = getattr(payload, "additional_kwargs", {}) or {}
-                    if is_agent_builder and not additional_kwargs.get("stream"):
+                    if meta_dict.get("tags") and "quiet" in meta_dict.get("tags"):
                         continue
                     if isinstance(payload, AIMessageChunk):
                         last_ai_chunk = payload

universal_mcp_agents-0.1.24/src/universal_mcp/agents/codeact0/agent.py

@@ -0,0 +1,373 @@
+import copy
+import json
+import re
+import uuid
+from typing import Literal, cast
+
+from langchain_anthropic import ChatAnthropic
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+from langgraph.checkpoint.base import BaseCheckpointSaver
+from langgraph.graph import START, StateGraph
+from langgraph.types import Command, RetryPolicy, StreamWriter
+from universal_mcp.tools.registry import ToolRegistry
+from universal_mcp.types import ToolFormat
+
+from universal_mcp.agents.base import BaseAgent
+from universal_mcp.agents.codeact0.llm_tool import smart_print
+from universal_mcp.agents.codeact0.prompts import (
+    AGENT_BUILDER_GENERATING_PROMPT,
+    AGENT_BUILDER_META_PROMPT,
+    AGENT_BUILDER_PLANNING_PROMPT,
+    AGENT_BUILDER_PLAN_PATCH_PROMPT,
+    AGENT_BUILDER_CODE_PATCH_PROMPT,
+    build_tool_definitions,
+    create_default_prompt,
+)
+from universal_mcp.agents.codeact0.sandbox import eval_unsafe, execute_ipython_cell, handle_execute_ipython_cell
+from universal_mcp.agents.codeact0.state import AgentBuilderCode, AgentBuilderMeta, AgentBuilderPlan, AgentBuilderPatch, CodeActState
+from universal_mcp.agents.codeact0.tools import (
+    create_agent_builder_tools,
+    create_meta_tools,
+)
+from universal_mcp.agents.codeact0.utils import build_anthropic_cache_message, extract_plan_parameters, get_connected_apps_string, strip_thinking
+from universal_mcp.agents.codeact0.utils import apply_patch_or_use_proposed
+from universal_mcp.agents.llm import load_chat_model
+from universal_mcp.agents.utils import convert_tool_ids_to_dict, filter_retry_on
+
+
+class CodeActPlaybookAgent(BaseAgent):
+    def __init__(
+        self,
+        name: str,
+        instructions: str,
+        model: str,
+        memory: BaseCheckpointSaver | None = None,
+        registry: ToolRegistry | None = None,
+        agent_builder_registry: object | None = None,
+        sandbox_timeout: int = 20,
+        **kwargs,
+    ):
+        super().__init__(
+            name=name,
+            instructions=instructions,
+            model=model,
+            memory=memory,
+            **kwargs,
+        )
+        self.model_instance = load_chat_model(model)
+        self.agent_builder_model_instance = load_chat_model("anthropic:claude-sonnet-4-5-20250929", thinking=False, disable_streaming = True, tags=("quiet",))
+        self.registry = registry
+        self.agent_builder_registry = agent_builder_registry
+        self.agent = agent_builder_registry.get_agent() if agent_builder_registry else None
+
+        self.tools_config = self.agent.tools if self.agent else {}
+        self.eval_fn = eval_unsafe
+        self.sandbox_timeout = sandbox_timeout
+        self.default_tools_config = {
+            "llm": ["generate_text", "classify_data", "extract_data", "call_llm"],
+        }
+        self.final_instructions = ""
+        self.tools_context = {}
+        self.eval_mode = kwargs.get("eval_mode", False)
+
+    async def _build_graph(self):  # noqa: PLR0915
+        """Build the graph for the CodeAct Playbook Agent."""
+        meta_tools = create_meta_tools(self.registry)
+        agent_builder_tools = create_agent_builder_tools()
+        self.additional_tools = [
+            smart_print,
+            meta_tools["web_search"],
+            meta_tools["read_file"],
+            meta_tools["save_file"],
+            meta_tools["upload_file"],
+        ]
+
+        if self.tools_config:
+            await self.registry.load_tools(self.tools_config)  # Load provided tools
+        if self.default_tools_config:
+            await self.registry.load_tools(self.default_tools_config)  # Load default tools
+
+        async def call_model(state: CodeActState) -> Command[Literal["execute_tools"]]:
+            """This node now only ever binds the four meta-tools to the LLM."""
+            messages = build_anthropic_cache_message(self.final_instructions) + state["messages"]
+            agent_facing_tools = [
+                execute_ipython_cell,
+                agent_builder_tools["plan_agent"],
+                agent_builder_tools["code_and_save_agent"],
+                meta_tools["search_functions"],
+                meta_tools["load_functions"],
+            ]
+
+            if isinstance(self.model_instance, ChatAnthropic):
+                model_with_tools = self.model_instance.bind_tools(
+                    tools=agent_facing_tools,
+                    tool_choice="auto",
+                    cache_control={"type": "ephemeral", "ttl": "1h"},
+                )
+                if isinstance(messages[-1].content, str):
+                    pass
+                else:
+                    last = copy.deepcopy(messages[-1])
+                    last.content[-1]["cache_control"] = {"type": "ephemeral", "ttl": "5m"}
+                    messages[-1] = last
+            else:
+                model_with_tools = self.model_instance.bind_tools(
+                    tools=agent_facing_tools,
+                    tool_choice="auto",
+                )
+            response = cast(AIMessage, await model_with_tools.ainvoke(messages))
+            if response.tool_calls:
+                return Command(goto="execute_tools", update={"messages": [response]})
+            else:
+                return Command(update={"messages": [response], "model_with_tools": model_with_tools})
+
+        async def execute_tools(state: CodeActState, writer: StreamWriter) -> Command[Literal["call_model"]]:
+            """Execute tool calls"""
+            last_message = state["messages"][-1]
+            tool_calls = last_message.tool_calls if isinstance(last_message, AIMessage) else []
+
+            tool_messages = []
+            new_tool_ids = []
+            tool_result = ""
+            ask_user = False
+            ai_msg = None
+            effective_previous_add_context = state.get("add_context", {})
+            effective_existing_context = state.get("context", {})
+            plan = state.get("plan", None)
+            agent_name = state.get("agent_name", None)
+            agent_description = state.get("agent_description", None)
+            # logging.info(f"Initial new_tool_ids_for_context: {new_tool_ids_for_context}")
+
+            for tool_call in tool_calls:
+                tool_name = tool_call["name"]
+                tool_args = tool_call["args"]
+                try:
+                    if tool_name == "execute_ipython_cell":
+                        code = tool_call["args"]["snippet"]
+                        output, new_context, new_add_context = await handle_execute_ipython_cell(
+                            code,
+                            self.tools_context,  # Uses the dynamically updated context
+                            self.eval_fn,
+                            effective_previous_add_context,
+                            effective_existing_context,
+                        )
+                        effective_existing_context = new_context
+                        effective_previous_add_context = new_add_context
+                        tool_result = output
+                    elif tool_name == "load_functions":
+                        # The tool now does all the work of validation and formatting.
+                        tool_result, new_context_for_sandbox, valid_tools, unconnected_links = await meta_tools[
+                            "load_functions"
+                        ].ainvoke(tool_args)
+                        # We still need to update the sandbox context for `execute_ipython_cell`
+                        new_tool_ids.extend(valid_tools)
+                        if new_tool_ids:
+                            self.tools_context.update(new_context_for_sandbox)
+                        if unconnected_links:
+                            ask_user = True
+                            ai_msg = f"Please login to the following app(s) using the following links and let me know in order to proceed:\n {unconnected_links} "
+
+                    elif tool_name == "search_functions":
+                        tool_result = await meta_tools["search_functions"].ainvoke(tool_args)
+                    
+                    elif tool_name == "plan_agent":
+                        plan, tool_result = await self._create_or_update_plan(state=state, writer=writer, plan=plan)
+                        ask_user = True
+
+                    elif tool_name == "code_and_save_agent":
+                        tool_result, effective_previous_add_context, agent_name, agent_description = await self._build_or_patch_code(
+                            state=state,
+                            writer=writer,
+                            plan=plan,
+                            agent_name=agent_name,
+                            agent_description=agent_description,
+                            effective_previous_add_context=effective_previous_add_context,
+                        )    
+                    else:
+                        raise Exception(
+                            f"Unexpected tool call: {tool_call['name']}. "
+                            "tool calls must be one of 'execute_ipython_cell', 'load_functions', 'search_functions', 'plan_agent', or 'code_and_save_agent'. For using functions, call them in code using 'execute_ipython_cell'."
+                        )
+                except Exception as e:
+                    tool_result = str(e)
+
+                tool_message = ToolMessage(
+                    content=json.dumps(tool_result),
+                    name=tool_call["name"],
+                    tool_call_id=tool_call["id"],
+                )
+                tool_messages.append(tool_message)
+
+            if ask_user:
+                if ai_msg:
+                    tool_messages.append(AIMessage(content=ai_msg))
+                return Command(
+                    update={
+                        "messages": tool_messages,
+                        "selected_tool_ids": new_tool_ids,
+                        "context": effective_existing_context,
+                        "add_context": effective_previous_add_context,
+                        "agent_name": agent_name,
+                        "agent_description": agent_description,
+                        "plan": plan,
+                    }
+                )
+
+            return Command(
+                goto="call_model",
+                update={
+                    "messages": tool_messages,
+                    "selected_tool_ids": new_tool_ids,
+                    "context": effective_existing_context,
+                    "add_context": effective_previous_add_context,
+                    "agent_name": agent_name,
+                    "agent_description": agent_description,
+                    "plan": plan,
+                },
+            )
+
+        async def route_entry(state: CodeActState) -> Command[Literal["call_model", "execute_tools"]]:
+            """Route to either normal mode or agent builder creation"""
+            pre_tools = await self.registry.export_tools(format=ToolFormat.NATIVE)
+
+            # Create the initial system prompt and tools_context in one go
+            self.final_instructions, self.tools_context = create_default_prompt(
+                pre_tools,
+                self.additional_tools,
+                self.instructions,
+                await get_connected_apps_string(self.registry),
+                self.agent,
+                is_initial_prompt=True,
+            )
+            self.preloaded_defs, _ = build_tool_definitions(pre_tools)
+            self.preloaded_defs = "\n".join(self.preloaded_defs)
+            await self.registry.load_tools(state["selected_tool_ids"])
+            exported_tools = await self.registry.export_tools(
+                state["selected_tool_ids"], ToolFormat.NATIVE
+            )  # Get definition for only the new tools
+            _, loaded_tools_context = build_tool_definitions(exported_tools)
+            self.tools_context.update(loaded_tools_context)
+
+            if (
+                len(state["messages"]) == 1 and self.agent
+            ):  # Inject the agent's script function into add_context for execution
+                script = self.agent.instructions.get("script")
+                add_context = {"functions": [script]}
+                return Command(goto="call_model", update={"add_context": add_context})
+            return Command(goto="call_model")
+
+        agent = StateGraph(state_schema=CodeActState)
+        agent.add_node(call_model, retry_policy=RetryPolicy(max_attempts=3, retry_on=filter_retry_on))
+        agent.add_node(execute_tools)
+        agent.add_node(route_entry)
+        agent.add_edge(START, "route_entry")
+        return agent.compile(checkpointer=self.memory)
+
+    async def _create_or_update_plan(self, state: "CodeActState", writer: StreamWriter, plan: list[str] | None):
+        """Sub-agent helper: create or patch-update the agent plan and emit UI updates.
+        Returns: (plan: list[str], tool_result: str)
+        """
+        plan_id = str(uuid.uuid4())
+        writer({"type": "custom", id: plan_id, "name": "planning", "data": {"update": bool(plan)}})
+
+        # Determine existing plan (prefer persisted agent's plan) and base messages
+        existing_plan_steps = (self.agent.instructions.get("plan") if self.agent and getattr(self.agent, "instructions", None) else None) or plan
+        base = strip_thinking(state["messages"])
+        def with_sys(text: str):
+            return [{"role": "system", "content": text}] + base
+
+        if existing_plan_steps:
+            current = "\n".join(map(str, existing_plan_steps or []))
+            sys_prompt = self.instructions + "\n" + AGENT_BUILDER_PLAN_PATCH_PROMPT + self.preloaded_defs
+            msgs = with_sys(sys_prompt) + [HumanMessage(content=f"Current plan (one step per line):\n{current}")]
+            patch_model = self.agent_builder_model_instance.with_structured_output(AgentBuilderPatch)
+            proposed = cast(AgentBuilderPatch, await patch_model.ainvoke(msgs)).patch
+            updated = apply_patch_or_use_proposed(current, proposed)
+            plan = [line for line in updated.splitlines() if line.strip()]
+        else:
+            sys_prompt = self.instructions + AGENT_BUILDER_PLANNING_PROMPT + self.preloaded_defs
+            plan_model = self.agent_builder_model_instance.with_structured_output(AgentBuilderPlan)
+            plan = cast(AgentBuilderPlan, await plan_model.ainvoke(with_sys(sys_prompt))).steps
+
+        writer({"type": "custom", id: plan_id, "name": "planning", "data": {"plan": plan}})
+        tool_result = {"plan": plan, "update": bool(plan), "message": f"Successfully generated the agent plan."}
+        return plan, tool_result
+
+    async def _build_or_patch_code(
+        self,
+        state: "CodeActState",
+        writer: StreamWriter,
+        plan: list[str] | None,
+        agent_name: str | None,
+        agent_description: str | None,
+        effective_previous_add_context: dict,
+    ):
+        """Sub-agent helper: generate new code or patch existing code, save, and emit UI updates.
+        Returns: (tool_result: str, effective_previous_add_context: dict, agent_name: str | None, agent_description: str | None)
+        """
+        generation_id = str(uuid.uuid4())
+        writer({"type": "custom", "id": generation_id, "name": "generating", "data": {"update": bool(self.agent)}})
+
+        base = strip_thinking(state["messages"])
+        def with_sys(text: str):
+            return [{"role": "system", "content": text}] + base
+        plan_text = "\n".join(map(str, plan)) if plan else None
+        existing_code = self.agent.instructions.get("script") if self.agent and getattr(self.agent, "instructions", None) else None
+
+        if self.agent:
+            agent_name = getattr(self.agent, "name", None)
+            agent_description = getattr(self.agent, "description", None)
+
+        if not agent_name or not agent_description:
+            meta_model = self.agent_builder_model_instance.with_structured_output(AgentBuilderMeta)
+            meta = cast(AgentBuilderMeta, await meta_model.ainvoke(with_sys(self.instructions + AGENT_BUILDER_META_PROMPT)))
+            agent_name, agent_description = meta.name, meta.description
+
+        writer({"type": "custom", "id": generation_id, "name": "generating", "data": {"update": bool(self.agent), "name": agent_name, "description": agent_description}})
+
+        if existing_code:
+            generating_instructions = self.instructions + AGENT_BUILDER_CODE_PATCH_PROMPT + self.preloaded_defs
+            messages = with_sys(generating_instructions)
+            if plan_text:
+                messages.append(HumanMessage(content=f"Confirmed plan (one step per line):\n{plan_text}"))
+            messages.append(HumanMessage(content=f"Current code to update:\n```python\n{existing_code}\n```"))
+            patch_model = self.agent_builder_model_instance.with_structured_output(AgentBuilderPatch)
+            proposed = cast(AgentBuilderPatch, await patch_model.ainvoke(messages)).patch
+            python_code = apply_patch_or_use_proposed(existing_code, proposed)
+        else:
+            code_model = self.agent_builder_model_instance.with_structured_output(AgentBuilderCode)
+            python_code = cast(AgentBuilderCode, await code_model.ainvoke(with_sys(self.instructions + AGENT_BUILDER_GENERATING_PROMPT + self.preloaded_defs))).code
+
+        try:
+            if not self.agent_builder_registry:
+                raise ValueError("AgentBuilder registry is not configured")
+
+            plan_params = extract_plan_parameters(state["plan"])
+            instructions_payload = {
+                "plan": state["plan"],
+                "script": python_code,
+                "params": plan_params,
+            }
+            tool_dict = convert_tool_ids_to_dict(state["selected_tool_ids"])
+            res = self.agent_builder_registry.upsert_agent(
+                name=agent_name,
+                description=agent_description,
+                instructions=instructions_payload,
+                tools=tool_dict,
+            )
+            writer({"type": "custom", "id": generation_id, "name": "generating", "data": {"id": str(res.id), "update": bool(self.agent), "name": agent_name, "description": agent_description}})
+            tool_result = {
+                "id": str(res.id),
+                "update": bool(self.agent),
+                "name": agent_name,
+                "description": agent_description,
+                "message": f"Successfully saved the agent code and plan.",
+            }
+        except Exception:
+            tool_result = f"Displaying the final saved code:\n\n{python_code}\nFinal Name: {agent_name}\nDescription: {agent_description}"
+
+        if "functions" not in effective_previous_add_context:
+            effective_previous_add_context["functions"] = []
+        effective_previous_add_context["functions"].append(python_code)
+
+        return tool_result, effective_previous_add_context, agent_name, agent_description

{universal_mcp_agents-0.1.23rc11 → universal_mcp_agents-0.1.24}/src/universal_mcp/agents/codeact0/prompts.py

@@ -9,44 +9,28 @@ Your job is to answer the user's question or perform the task they ask for.
 - Answer simple questions (which do not require you to write any code or access any external resources) directly. Note that any operation that involves using ONLY print functions should be answered directly in the chat. NEVER write a string or sequences of strings yourself and print it.
 - For task requiring operations or access to external resources, you should achieve the task by executing Python code snippets.
 - You have access to `execute_ipython_cell` tool that allows you to execute Python code in an IPython notebook cell.
-- For writing, text/document generation (like HTML/markdown document generation) or language processing tasks DO NOT answer directly. Instead you MUST use `execute_ipython_cell` tool with the llm functions provided to you for tasks like summarizing, text generation, classification, data extraction from text or unstructured data, etc. Avoid hardcoded approaches to classification, data extraction, or creative writing.
 - You also have access to two tools for finding and loading more python functions- `search_functions` and `load_functions`, which you must use for finding functions for using different external applications or additional functionality.
     - Prioritize connected applications over unconnected ones from the output of `search_functions`. However, if the user specifically asks for an application, you MUST use that irrespective of connection status.
-    - When multiple apps are connected, or none of the apps are connected, YOU MUST ask the user to choose the application(s). The search results will inform you when such a case occurs, and you must stop and ask the user if multiple apps are relevant.
-- The code you write will be executed in a sandbox environment, and you can use the output of previous executions in your code. variables, functions, imports are retained.
-- Read and understand the output of the previous code snippet and use it to answer the user's request. Note that the code output is NOT visible to the user, so after the task is complete, you have to give the output to the user in a markdown format. Similarly, you should only use print/smart_print for your own analysis, the user does not get the output.
+    - When multiple relevant apps are connected, or none of the apps are connected, YOU MUST ask the user to choose the application(s). Do not assume the application.
 - If needed, feel free to ask for more information from the user (without using the `execute_ipython_cell` tool) to clarify the task.
 
-**Code Execution Guidelines:**
-- The code you write will be executed in a sandbox environment, and you can use the output of previous executions in your code. Variables, functions, imports are retained.
-- Read and understand the output of the previous code snippet and use it to answer the user's request. Note that the code output is NOT visible to the user, so after the task is complete, you have to give the output to the user in a markdown format. Similarly, you should only use print/smart_print for your own analysis, the user does not get the output.
-- If needed, feel free to ask for more information from the user (without using the `execute_ipython_cell` tool) to clarify the task.
-- DO NOT use the code execution to communicate/show anything to the user. The user is not able to see the output of the code cells, it is only for your processing and actions.
-- Whenever you need to generate a large body of text, such as a document, an HTML file, or a report, use llm functions and save the output file using save functions. Do not generate text yourself and do not print the entire text in order to save your memory.
-
-**Coding Best Practices:**
-- Structure your code into multiple small, well-defined functions within a single execution snippet. This ensures modularity and makes it easier to debug or update specific logic without rewriting or re-executing large portions of code. You can only rewrite the function/portion that you need to edit since the others are retained in context.
-- Variables, functions, classes defined at the top level of previous code snippets can be referenced in your code.
-- External functions which return a dict or list[dict] are ambiguous. Therefore, you MUST explore the structure of the returned data using `smart_print()` statements before using it, printing keys and values. `smart_print` truncates long strings from data, preventing huge output logs.
-- When an operation involves running a fixed set of steps on a list of items, run one run correctly and then use a for loop to run the steps on each item in the list.
-- You can only import libraries that come pre-installed with Python. However, do consider searching for external functions first, using the search and load tools to access them in the code.
-- For displaying final results to the user, you must present your output in markdown format, including image links, so that they are rendered and displayed to the user. The code output is NOT visible to the user.
-- Call all functions using keyword arguments only, never positional arguments.
-- NEVER use execute_ipython_cell for:
-    - Static analysis or commentary
-    - Text that could be written as markdown
-    - Final output summarization after analysis
-    - Anything that's just formatted print statements
+Agent Builder Scope: The following responsibilities apply when you are building/creating a reusable agent for the user.
+- The tools `plan_agent` and `code_and_save_agent` are non-interactive sub-agents; they only draft a plan or produce code for the agent (and save it) from the context you provide.
+- They cannot talk to the user or fetch context. YOU (the main agent) must gather all requirements, and must ensure all required context and inputs are present in the conversation history.
+- Flow: first call `plan_agent`, share the plan and collect user feedback; only after an explicit go-ahead call `code_and_save_agent` to generate code and save the agent.
+- If the user requests a feature you don't recognize, first use `search_functions` and `load_functions` to discover and load capabilities before invoking the sub-agents.
 
 **Final Output Requirements:**
-- Once you have all the information about the task, return the text directly to user in markdown format. Do NOT call `execute_ipython_cell` or any LLM tools again just for summarization. Do NOT use llm__generate_text for this purpose.
+- Once you have all the information about the task, return the text directly to user in markdown format. Do NOT call `execute_ipython_cell` or any LLM tools again just for summarization.
 - Always respond in github flavoured markdown format.
 - For charts and diagrams, use mermaid chart in markdown directly.
 - Your final response should contain the complete answer to the user's request in a clear, well-formatted manner that directly addresses what they asked for.
-- For file types like images, audio, documents, etc., you must use the `upload_file` tool to upload the file to the server and render the link in the markdown response.
+- For file types like images, audio, documents, etc., you must use the `upload_file`/`save_file` function to upload the file to the server and render the link/path in the markdown response.
 """
 
 AGENT_BUILDER_PLANNING_PROMPT = """TASK: Analyze the conversation history and code execution to create a step-by-step non-technical plan for a reusable function.
+You are a sub-agent invoked by the main agent. You do not interact with the user and you do not call tools; you rely solely on the provided conversation/code history.
+If essential details are missing, represent them as external variables in the plan (backticks), do NOT fabricate values.
 Rules:
 - Do NOT include the searching and loading of functions. Assume that the functions have already been loaded.
 - The plan is a sequence of steps corresponding to the key logical steps taken to achieve the user's task in the conversation history, without focusing on technical specifics.
@@ -91,16 +75,26 @@ Note that the following tools are pre-loaded for the agent's use, and can be inl
 
 
 AGENT_BUILDER_GENERATING_PROMPT = """
-You are tasked with generating a reusable agent function based on the final confirmed agent plan and preceding conversation history including user messages, assistant messages, and code executions.
-Create an appropriately named python function that combines relevent previously executed code from the conversation history to achieve the plan objectives.
+You are tasked with generating granular, reusable Python code for an agent based on the final confirmed plan and the conversation history (user messages, assistant messages, and code executions).
+
+You are a sub-agent invoked by the main agent. You do not interact with the user and you do not call tools. Assume any required functions are already loaded by the main agent. If a capability is referenced but not shown, still write code that calls the expected function entry points; the main agent is responsible for ensuring they are loaded.
+
+Produce a set of small, single-purpose functions—typically one function per plan step—plus one top-level orchestrator function that calls the step functions in order to complete the task.
+
 Rules-
-- Do NOT include the searching and loading of functions. Assume that the functions have already been loaded. Imports should be included.
-- Your response must be **ONLY Python code** for the function.
-- Do not include any text, explanations, or Markdown.
-- The response must start with `def` or `async def` and define a single, complete, executable function.
-- The function parameters **must exactly match the external variables** in the agent plan. External variables are marked using backticks `` `variable_name` ``.  Any variables in italics (i.e. enclosed in *...*) are to be used internally, but not as the main function paramters.
-- Any imports, variables, helper or child functions required must be defined **inside the main top-level function**.
-- Ensure that the outer function is self-contained and can run independently, based on previously validated code snippets.
+- Do NOT include the searching and loading of functions. Assume required functions have already been loaded. Include imports you need.
+- Your response must be **ONLY Python code**. No markdown or explanations.
+- Define multiple top-level functions:
+  1) One small, clear function for each plan step (as granular as practical).
+  2) One top-level orchestrator function that calls the step functions in sequence to achieve the plan objectives.
+- The orchestrator function's parameters **must exactly match the external variables** in the agent plan (the ones marked with backticks `` `variable_name` ``). Provide defaults exactly as specified in the plan when present. Variables in italics (i.e. enclosed in *...*) are internal and must not be orchestrator parameters.
+- The orchestrator function MUST be declared with `def` or `async def` and be directly runnable with a single Python command (e.g., `image_generator(...)`). If it is async, assume the caller will `await` it.
+- NEVER use asyncio or asyncio.run(). The code is executed in a ipython environment, so using await is enough.
+- Step functions should accept only the inputs they need, return explicit outputs, and pass intermediate results forward via return values—not globals.
+- Name functions in snake_case derived from their purpose/step. Use keyword arguments in calls; avoid positional-only calls.
+- Keep the code self-contained and executable. Put imports at the top of the code. Do not nest functions unless strictly necessary.
+- If previously executed code snippets exist, adapt and reuse their validated logic inside the appropriate step functions.
+- Do not print the final output; return it from the orchestrator.
 
 Example:
 
@@ -113,23 +107,96 @@ If the plan has:
 "Upload *temp_file_path* to OneDrive folder onedrive_parent_folder(default = 'root')"
 ]
 
-Then the function signature should be:
+Then the functions should look like:
 
 ```python
-def image_generator(image_prompt, style="comic", onedrive_parent_folder="root"):
-    #Code based on previously executed snippets
+from typing import Dict
 
-And all internal variables (e.g., *temp_file_path*) should be defined inside the function.
+def generate_image(image_prompt: str, style: str = "comic") -> Dict:
+    # previously validated code to call Gemini
+    ...
 
+def save_temp_image(image_result: Dict) -> str:
+    # previously validated code to write bytes to a temp file
+    ...
 
-Use this convention consistently to generate the final agent function.
+def upload_to_onedrive(temp_file_path: str, onedrive_parent_folder: str = "root") -> Dict:
+    # previously validated code to upload
+    ...
+
+def image_generator(image_prompt: str, style: str = "comic", onedrive_parent_folder: str = "root") -> Dict:
+    image_result = generate_image(image_prompt=image_prompt, style=style)
+    temp_file_path = save_temp_image(image_result=image_result)
+    upload_result = upload_to_onedrive(temp_file_path=temp_file_path, onedrive_parent_folder=onedrive_parent_folder)
+    return upload_result
+```
+
+Use this convention consistently to generate the final code.
 Note that the following tools are pre-loaded for the agent's use, and can be included in your code-\n
 """
 
 
+AGENT_BUILDER_PLAN_PATCH_PROMPT = """
+You are updating an existing agent plan represented as plain text (one step per line).
+
+Output Requirements:
+- ALWAYS output ONLY an OpenAI-style patch between the exact fences:
+  *** Begin Patch\n ... \n*** End Patch
+- Use one or more @@ hunks with context lines (' '), deletions ('-'), and additions ('+').
+- Make minimal edits; preserve unrelated lines and preserve step order unless a reordering is explicitly required.
+- Do NOT include any prose, markdown, or code fences other than the patch fences.
+
+Plan content constraints (apply while patching; do not rewrite the whole plan):
+- Keep steps non-technical and human-friendly, describing goals/actions rather than implementation details.
+- External inputs must be denoted as `variable_name`; include defaults as `variable_name(default = value)` when appropriate.
+- Intermediate/internal variables must be italicized like *temp_file_path* (never in backticks).
+- Avoid using internal IDs/keys as plan inputs. Keep inputs human-facing.
+- Be concise; avoid unnecessary sub-steps. Prefer a small number of clear steps.
+- Preserve existing variable names and defaults unless the context clearly requires a change.
+- If removing or reordering steps, ensure downstream references remain coherent (do not reference a removed step).
+- Preserve existing bullet/line formatting; one step per line.
+- Idempotence: make the smallest delta that satisfies the requested update.
+- For steps where the assistant's intelligence was used outside of the code to infer/decide/analyse something, replace it with the use of *llm__* functions in the plan if required.
+
+Context will include the current plan and conversation history.
+"""
+
+
+AGENT_BUILDER_CODE_PATCH_PROMPT = """
+You are updating existing Python code for an agent.
+
+Output Requirements:
+- ALWAYS output ONLY an OpenAI-style patch between the exact fences:
+  *** Begin Patch\n ... \n*** End Patch
+- Use one or more @@ hunks with context (' '), deletions ('-'), additions ('+').
+- Make minimal edits; preserve unrelated code and keep function/public API signatures stable unless the plan demands changes.
+- Do NOT include any prose or markdown outside the patch.
+ - Do NOT wrap the patch in triple backticks; only use the patch fences shown above.
+
+Context will include the current code and the confirmed plan.
+
+Structural constraints (apply while patching; do not rewrite whole file):
+- Maintain small, single-purpose functions (typically one per plan step) plus ONE top-level orchestrator that invokes them in order.
+- The orchestrator parameters must exactly match the external variables in the plan, including defaults.
+- Preserve function names and public signatures unless the plan explicitly requires a change; if a signature changes, update orchestrator and all call sites consistently in the same patch.
+- Keep imports at the top; pass data via return values (no new globals); avoid nested functions unless necessary.
+- Do not print final results; ensure the orchestrator returns the final value.
+- Prefer adapting and reusing previously validated logic inside affected functions; do not rewrite unrelated functions.
+
+ Additional rules to ensure reliable, minimal patches:
+ - Environment: Code runs in IPython; if a function is async, callers will `await` it. Do NOT use `asyncio.run()` or create event loops.
+ - Calling style: Use keyword arguments (no positional-only calls) when you modify call sites.
+ - Imports: Add only necessary imports; deduplicate and keep existing import order/formatting when possible.
+ - Formatting: Preserve existing formatting, indentation, comments, and docstrings for unchanged code. Do NOT reformat the file.
+ - Exceptions/IO: Preserve existing error handling semantics; do not introduce interactive input or random printing.
+ - Idempotence: Make the smallest change set that satisfies the plan; avoid broad refactors.
+"""
+
 AGENT_BUILDER_META_PROMPT = """
 You are preparing metadata for a reusable agent based on the confirmed step-by-step plan.
 
+You are a sub-agent invoked by the main agent. You do not interact with the user and you do not call tools; rely only on the provided context.
+
 TASK: Create a concise, human-friendly name and a short description for the agent.
 
 INPUTS: