universal-mcp-agents 0.1.23rc1__py3-none-any.whl → 0.1.23rc3__py3-none-any.whl

universal_mcp/agents/__init__.py

@@ -9,7 +9,7 @@ from universal_mcp.agents.simple import SimpleAgent
 
 
 def get_agent(
-    agent_name: Literal["react", "simple", "builder", "bigtool", "codeact-script", "codeact-repl"],
+    agent_name: Literal["react", "simple", "builder", "bigtool", "codeact-repl"],
 ):
     if agent_name == "react":
         return ReactAgent
@@ -23,7 +23,7 @@ def get_agent(
         return CodeActPlaybookAgent
     else:
         raise ValueError(
-            f"Unknown agent: {agent_name}. Possible values:  react, simple, builder, bigtool, codeact-script, codeact-repl"
+            f"Unknown agent: {agent_name}. Possible values:  react, simple, builder, bigtool, codeact-repl"
         )
 
 

universal_mcp/agents/base.py

@@ -66,9 +66,9 @@ class BaseAgent:
         ):
             if event == "messages" and isinstance(meta, (tuple, list)) and len(meta) == 2:
                 payload, meta_dict = meta
-                is_playbook = isinstance(meta_dict, dict) and meta_dict.get("langgraph_node") == "playbook"
+                is_agent_builder = isinstance(meta_dict, dict) and meta_dict.get("langgraph_node") == "agent_builder"
                 additional_kwargs = getattr(payload, "additional_kwargs", {}) or {}
-                if is_playbook and not additional_kwargs.get("stream"):
+                if is_agent_builder and not additional_kwargs.get("stream"):
                     continue
                 if isinstance(payload, AIMessageChunk):
                     last_ai_chunk = payload

universal_mcp/agents/cli.py

@@ -25,7 +25,7 @@ def run(name: str = "react"):
     client = AgentrClient()
     params = {
         "instructions": "You are a helpful assistant",
-        "model": "anthropic/claude-sonnet-4-20250514",
+        "model": "azure/gpt-4.1",
         "registry": AgentrRegistry(client=client),
         "memory": MemorySaver(),
     }

universal_mcp/agents/codeact0/__main__.py

@@ -13,15 +13,12 @@ async def main():
     agent = CodeActPlaybookAgent(
         name="CodeAct Agent",
         instructions="Be very concise in your answers.",
-        model="anthropic:claude-4-sonnet-20250514",
-        tools={"google_mail": ["list_messages"]},
+        model="azure/gpt-4.1",
         registry=AgentrRegistry(),
         memory=memory,
     )
     print("Starting agent...")
-    result = await agent.invoke(
-        user_input="Fetch unsubscribe links from my Gmail inbox for promo emails I have received in the last 7 days"
-    )
+    result = await agent.invoke(user_input="load all the tools of reddit which can be used to search subreddit")
     print(messages_to_list(result["messages"]))
 
 

universal_mcp/agents/codeact0/agent.py

@@ -1,35 +1,36 @@
+import copy
 import json
 import re
-from typing import Literal, cast
 import uuid
+from typing import Literal, cast
 
+from langchain_anthropic import ChatAnthropic
 from langchain_core.messages import AIMessage, ToolMessage
 from langchain_core.tools import StructuredTool
 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 ToolConfig, ToolFormat
+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 (
-    PLAYBOOK_GENERATING_PROMPT,
-    PLAYBOOK_PLANNING_PROMPT,
-    PLAYBOOK_META_PROMPT,
+    AGENT_BUILDER_GENERATING_PROMPT,
+    AGENT_BUILDER_META_PROMPT,
+    AGENT_BUILDER_PLANNING_PROMPT,
     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 CodeActState, PlaybookCode, PlaybookPlan, PlaybookMeta
+from universal_mcp.agents.codeact0.state import CodeActState, AgentBuilderCode, AgentBuilderMeta, AgentBuilderPlan
 from universal_mcp.agents.codeact0.tools import (
     create_meta_tools,
-    enter_playbook_mode,
+    enter_agent_builder_mode,
     get_valid_tools,
 )
-from universal_mcp.agents.codeact0.utils import add_tools
+from universal_mcp.agents.codeact0.utils import build_anthropic_cache_message, get_connected_apps_string
 from universal_mcp.agents.llm import load_chat_model
 from universal_mcp.agents.utils import convert_tool_ids_to_dict, filter_retry_on, get_message_text
-from universal_mcp.agents.codeact0.utils import get_connected_apps_string
 
 
 class CodeActPlaybookAgent(BaseAgent):
@@ -40,7 +41,7 @@ class CodeActPlaybookAgent(BaseAgent):
         model: str,
         memory: BaseCheckpointSaver | None = None,
         registry: ToolRegistry | None = None,
-        playbook_registry: object | None = None,
+        agent_builder_registry: object | None = None,
         sandbox_timeout: int = 20,
         **kwargs,
     ):
@@ -52,18 +53,19 @@ class CodeActPlaybookAgent(BaseAgent):
             **kwargs,
         )
         self.model_instance = load_chat_model(model)
-        self.playbook_model_instance = load_chat_model("azure/gpt-4.1")
+        self.agent_builder_model_instance = load_chat_model("azure/gpt-4.1")
         self.registry = registry
-        self.playbook_registry = playbook_registry
-        self.playbook = playbook_registry.get_agent() if playbook_registry else None
-        self.tools_config = self.playbook.tools if self.playbook else {}
+        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 = {
+        self.default_tools_config = {
             "llm": ["generate_text", "classify_data", "extract_data", "call_llm"],
         }
-        add_tools(self.tools_config, self.default_tools)
-
+        self.final_instructions = ""
+        self.tools_context = {}
+        self.exported_tools = []
 
     async def _build_graph(self):
         meta_tools = create_meta_tools(self.registry)
@@ -71,64 +73,86 @@ class CodeActPlaybookAgent(BaseAgent):
         self.additional_tools = [
             t if isinstance(t, StructuredTool) else StructuredTool.from_function(t) for t in additional_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")
+                if not self.registry:
+                    raise ValueError("Tools are configured but no registry is provided")
+            await self.registry.export_tools(self.tools_config, ToolFormat.LANGCHAIN)
+
+        await self.registry.export_tools(self.default_tools_config, ToolFormat.LANGCHAIN)
 
         async def call_model(state: CodeActState) -> Command[Literal["execute_tools"]]:
-            messages = [{"role": "system", "content": self.final_instructions}] + state["messages"]
-
-            # Run the model and potentially loop for reflection
-            model_with_tools = self.model_instance.bind_tools(
-                tools=[
-                    execute_ipython_cell,
-                    enter_playbook_mode,
-                    meta_tools["search_functions"],
-                    meta_tools["load_functions"],
-                ],
-                tool_choice="auto",
-            )
+            """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,
+                enter_agent_builder_mode,
+                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, model_with_tools.invoke(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) -> Command[Literal["call_model", "playbook"]]:
+        async def execute_tools(state: CodeActState) -> Command[Literal["call_model", "agent_builder"]]:
             """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 = ""
-            tool_result = ""
             effective_previous_add_context = state.get("add_context", {})
             effective_existing_context = state.get("context", {})
+            # 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_call["name"] == "enter_playbook_mode":
+                    if tool_name == "enter_agent_builder_mode":
                         tool_message = ToolMessage(
-                            content=json.dumps("Entered Playbook Mode."),
+                            content=json.dumps("Entered Agent Builder Mode."),
                             name=tool_call["name"],
                             tool_call_id=tool_call["id"],
                         )
                         return Command(
-                            goto="playbook",
-                            update={"playbook_mode": "planning", "messages": [tool_message]},  # Entered Playbook mode
+                            goto="agent_builder",
+                            update={"agent_builder_mode": "planning", "messages": [tool_message]},  # Entered Agent Builder mode
                         )
-                    elif tool_call["name"] == "execute_ipython_cell":
+                    elif 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,
+                            self.tools_context,  # Uses the dynamically updated context
                             self.eval_fn,
                             effective_previous_add_context,
                             effective_existing_context,
@@ -136,23 +160,23 @@ class CodeActPlaybookAgent(BaseAgent):
                         effective_existing_context = new_context
                         effective_previous_add_context = new_add_context
                         tool_result = output
-                    elif tool_call["name"] == "load_functions":  # Handle load_functions separately
-                        valid_tools, unconnected_links = await get_valid_tools(
-                            tool_ids=tool_call["args"]["tool_ids"], registry=self.registry
-                        )
+                    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)
-                        # Create tool message response
-                        tool_result = f"Successfully loaded {len(valid_tools)} tools: {valid_tools}"
-                        links = "\n".join(unconnected_links)
-                        if links:
+                        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 {links} "
-                    elif tool_call["name"] == "search_functions":
-                        tool_result = await meta_tools["search_functions"].ainvoke(tool_call["args"])
+                            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)
                     else:
                         raise Exception(
                             f"Unexpected tool call: {tool_call['name']}. "
-                            "tool calls must be one of 'enter_playbook_mode', 'execute_ipython_cell', 'load_functions', or 'search_functions'. For using functions, call them in code using 'execute_ipython_cell'."
+                            "tool calls must be one of 'enter_agent_builder_mode', 'execute_ipython_cell', 'load_functions', or 'search_functions'. For using functions, call them in code using 'execute_ipython_cell'."
                         )
                 except Exception as e:
                     tool_result = str(e)
@@ -163,13 +187,7 @@ class CodeActPlaybookAgent(BaseAgent):
                     tool_call_id=tool_call["id"],
                 )
                 tool_messages.append(tool_message)
-
-            if new_tool_ids:
-                self.tools_config.extend(new_tool_ids)
-                self.exported_tools = await self.registry.export_tools(new_tool_ids, ToolFormat.LANGCHAIN)
-                self.final_instructions, self.tools_context = create_default_prompt(
-                    self.exported_tools, self.additional_tools, self.instructions, await get_connected_apps_string(self.registry), self.playbook
-                )
+            
             if ask_user:
                 tool_messages.append(AIMessage(content=ai_msg))
                 return Command(
@@ -191,27 +209,37 @@ class CodeActPlaybookAgent(BaseAgent):
                 },
             )
 
-        def playbook(state: CodeActState, writer: StreamWriter) -> Command[Literal["call_model"]]:
-            playbook_mode = state.get("playbook_mode")
-            if playbook_mode == "planning":
+        def agent_builder(state: CodeActState, writer: StreamWriter) -> Command[Literal["call_model"]]:
+            agent_builder_mode = state.get("agent_builder_mode")
+            if agent_builder_mode == "planning":
                 plan_id = str(uuid.uuid4())
-                writer({
-                    "type": "custom",
-                    id: plan_id,
-                    "name": "planning",
-                    "data": {"update": bool(self.playbook)}
-                })
-                planning_instructions = self.instructions + PLAYBOOK_PLANNING_PROMPT
+                writer({"type": "custom", id: plan_id, "name": "planning", "data": {"update": bool(self.agent)}})
+                planning_instructions = self.instructions + AGENT_BUILDER_PLANNING_PROMPT
                 messages = [{"role": "system", "content": planning_instructions}] + state["messages"]
 
-                model_with_structured_output = self.playbook_model_instance.with_structured_output(PlaybookPlan)
+                model_with_structured_output = self.agent_builder_model_instance.with_structured_output(AgentBuilderPlan)
                 response = model_with_structured_output.invoke(messages)
-                plan = cast(PlaybookPlan, response)
-                
+                plan = cast(AgentBuilderPlan, response)
+
                 writer({"type": "custom", id: plan_id, "name": "planning", "data": {"plan": plan.steps}})
-                return Command(update={"messages": [AIMessage(content=json.dumps(plan.dict()), additional_kwargs={"type": "planning", "plan": plan.steps, "update": bool(self.playbook)})], "playbook_mode": "confirming", "plan": plan.steps})
+                return Command(
+                    update={
+                        "messages": [
+                            AIMessage(
+                                content=json.dumps(plan.model_dump()),
+                                additional_kwargs={
+                                    "type": "planning",
+                                    "plan": plan.steps,
+                                    "update": bool(self.agent),
+                                },
+                            )
+                        ],
+                        "agent_builder_mode": "confirming",
+                        "plan": plan.steps,
+                    }
+                )
 
-            elif playbook_mode == "confirming":
+            elif agent_builder_mode == "confirming":
                 # Deterministic routing based on three exact button inputs from UI
                 user_text = ""
                 for m in reversed(state["messages"]):
@@ -227,139 +255,152 @@ class CodeActPlaybookAgent(BaseAgent):
                 if t == "yes, this is great":
                     self.meta_id = str(uuid.uuid4())
                     name, description = None, None
-                    if self.playbook:
+                    if self.agent:
                         # Update flow: use existing name/description and do not re-generate
-                        name = getattr(self.playbook, "name", None)
-                        description = getattr(self.playbook, "description", None)
-                        writer({
-                            "type": "custom",
-                            id: self.meta_id,
-                            "name": "generating",
-                            "data": {
-                                "update": True,
-                                "name": name,
-                                "description": description,
+                        name = getattr(self.agent, "name", None)
+                        description = getattr(self.agent, "description", None)
+                        writer(
+                            {
+                                "type": "custom",
+                                id: self.meta_id,
+                                "name": "generating",
+                                "data": {
+                                    "update": True,
+                                    "name": name,
+                                    "description": description,
+                                },
                             }
-                        })
+                        )
                     else:
-                        writer({
-                            "type": "custom",
-                            id: self.meta_id,
-                            "name": "generating",
-                            "data": {"update": False}
-                        })
-
-                        meta_instructions = self.instructions + PLAYBOOK_META_PROMPT
+                        writer({"type": "custom", id: self.meta_id, "name": "generating", "data": {"update": False}})
+
+                        meta_instructions = self.instructions + AGENT_BUILDER_META_PROMPT
                         messages = [{"role": "system", "content": meta_instructions}] + state["messages"]
 
-                        model_with_structured_output = self.playbook_model_instance.with_structured_output(PlaybookMeta)
+                        model_with_structured_output = self.agent_builder_model_instance.with_structured_output(AgentBuilderMeta)
                         meta_response = model_with_structured_output.invoke(messages)
-                        meta = cast(PlaybookMeta, meta_response)
+                        meta = cast(AgentBuilderMeta, meta_response)
                         name, description = meta.name, meta.description
 
                         # Emit intermediary UI update with created name/description
-                        writer({
-                            "type": "custom",
-                            id: self.meta_id,
-                            "name": "generating",
-                            "data": {"update": False, "name": name, "description": description}
-                        })
-
-                    return Command(goto="playbook", update={"playbook_mode": "generating", "playbook_name": name, "playbook_description": description})
+                        writer(
+                            {
+                                "type": "custom",
+                                id: self.meta_id,
+                                "name": "generating",
+                                "data": {"update": False, "name": name, "description": description},
+                            }
+                        )
+
+                    return Command(
+                        goto="agent_builder",
+                        update={
+                            "agent_builder_mode": "generating",
+                            "agent_name": name,
+                            "agent_description": description,
+                        },
+                    )
                 if t == "i would like to modify the plan":
-                    prompt_ai = AIMessage(content="What would you like to change about the plan? Let me know and I'll update the plan accordingly.", additional_kwargs={"stream": "true"})
-                    return Command(update={"playbook_mode": "planning", "messages": [prompt_ai]})
+                    prompt_ai = AIMessage(
+                        content="What would you like to change about the plan? Let me know and I'll update the plan accordingly.",
+                        additional_kwargs={"stream": "true"},
+                    )
+                    return Command(update={"agent_builder_mode": "planning", "messages": [prompt_ai]})
                 if t == "let's do something else":
-                    return Command(goto="call_model", update={"playbook_mode": "inactive"})
+                    return Command(goto="call_model", update={"agent_builder_mode": "inactive"})
 
                 # Fallback safe default
-                return Command(goto="call_model", update={"playbook_mode": "inactive"})
+                return Command(goto="call_model", update={"agent_builder_mode": "inactive"})
 
-            elif playbook_mode == "generating":
-                generating_instructions = self.instructions + PLAYBOOK_GENERATING_PROMPT
+            elif agent_builder_mode == "generating":
+                generating_instructions = self.instructions + AGENT_BUILDER_GENERATING_PROMPT
                 messages = [{"role": "system", "content": generating_instructions}] + state["messages"]
-                
-                model_with_structured_output = self.playbook_model_instance.with_structured_output(PlaybookCode)
+
+                model_with_structured_output = self.agent_builder_model_instance.with_structured_output(AgentBuilderCode)
                 response = model_with_structured_output.invoke(messages)
-                func_code = cast(PlaybookCode, response).code
+                func_code = cast(AgentBuilderCode, response).code
 
                 # Extract function name (handle both regular and async functions)
                 match = re.search(r"^\s*(?:async\s+)?def\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(", func_code, re.MULTILINE)
                 if match:
                     function_name = match.group(1)
                 else:
-                    function_name = "generated_playbook"
+                    function_name = "generated_agent"
 
                 # Use generated metadata if available
-                final_name = state.get("playbook_name") or function_name
-                final_description = state.get("playbook_description") or f"Generated playbook: {function_name}"
+                final_name = state.get("agent_name") or function_name
+                final_description = state.get("agent_description") or f"Generated agent: {function_name}"
 
                 # Save or update an Agent using the helper registry
                 try:
-                    if not self.playbook_registry:  
-                        raise ValueError("Playbook registry is not configured")
+                    if not self.agent_builder_registry:
+                        raise ValueError("AgentBuilder registry is not configured")
 
                     # Build instructions payload embedding the plan and function code
                     instructions_payload = {
-                        "playbookPlan": state["plan"],
-                        "playbookScript": func_code,
+                        "plan": state["plan"],
+                        "script": func_code,
                     }
 
                     # Convert tool ids list to dict
                     tool_dict = convert_tool_ids_to_dict(state["selected_tool_ids"])
 
-                    res = self.playbook_registry.upsert_agent(
+                    res = self.agent_builder_registry.upsert_agent(
                         name=final_name,
                         description=final_description,
                         instructions=instructions_payload,
                         tools=tool_dict,
-                        visibility="private",
                     )
                 except Exception as e:
                     raise e
 
-                writer({
-                    "type": "custom",
-                    id: self.meta_id,
-                    "name": "generating",
-                    "data": {
-                        "id": str(res.id),
-                        "update": bool(self.playbook),
-                        "name": final_name,
-                        "description": final_description,
+                writer(
+                    {
+                        "type": "custom",
+                        id: self.meta_id,
+                        "name": "generating",
+                        "data": {
+                            "id": str(res.id),
+                            "update": bool(self.agent),
+                            "name": final_name,
+                            "description": final_description,
+                        },
                     }
-                })
+                )
                 mock_assistant_message = AIMessage(
-                    content=json.dumps(response.dict()),
+                    content=json.dumps(response.model_dump()),
                     additional_kwargs={
                         "type": "generating",
                         "id": str(res.id),
-                        "update": bool(self.playbook),
+                        "update": bool(self.agent),
                         "name": final_name,
                         "description": final_description,
                     },
                 )
 
-                return Command(
-                    update={"messages": [mock_assistant_message], "playbook_mode": "normal"}
-                )
+                return Command(update={"messages": [mock_assistant_message], "agent_builder_mode": "normal"})
+
+        async def route_entry(state: CodeActState) -> Literal["call_model", "agent_builder"]:
+            """Route to either normal mode or agent builder creation"""
+            all_tools = await self.registry.export_tools(state["selected_tool_ids"], ToolFormat.LANGCHAIN)
+            # print(all_tools)
 
-        async def route_entry(state: CodeActState) -> Literal["call_model", "playbook"]:
-            """Route to either normal mode or playbook creation"""
-            self.exported_tools = []
-            self.tools_config.extend(state.get("selected_tool_ids", []))
-            self.exported_tools = await self.registry.export_tools(self.tools_config, ToolFormat.LANGCHAIN)
+            # Create the initial system prompt and tools_context in one go
             self.final_instructions, self.tools_context = create_default_prompt(
-                self.exported_tools, self.additional_tools, self.instructions, await get_connected_apps_string(self.registry), self.playbook
+                all_tools,
+                self.additional_tools,
+                self.instructions,
+                await get_connected_apps_string(self.registry),
+                self.agent,
+                is_initial_prompt=True,
             )
-            if state.get("playbook_mode") in ["planning", "confirming", "generating"]:
-                return "playbook"
+            if state.get("agent_builder_mode") in ["planning", "confirming", "generating"]:
+                return "agent_builder"
             return "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(playbook)
+        agent.add_node(agent_builder)
         agent.add_node(execute_tools)
         agent.add_conditional_edges(START, route_entry)
-        # agent.add_edge(START, "call_model")
         return agent.compile(checkpointer=self.memory)

universal_mcp/agents/codeact0/prompts.py

@@ -3,6 +3,7 @@ import re
 from collections.abc import Sequence
 
 from langchain_core.tools import StructuredTool
+
 from universal_mcp.agents.codeact0.utils import schema_to_signature
 
 uneditable_prompt = """
@@ -62,16 +63,16 @@ Rules:
 - 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.
 """
 
-PLAYBOOK_PLANNING_PROMPT = """Now, you are tasked with creating a reusable playbook from the user's previous workflow.
+AGENT_BUILDER_PLANNING_PROMPT = """Now, you are tasked with creating a reusable agent from the user's previous workflow.
 
 TASK: Analyze the conversation history and code execution to create a step-by-step plan for a reusable function.
 Do not include the searching and loading of tools. Assume that the tools have already been loaded.
 The plan is a sequence of steps.
-You must output a JSON object with a single key "steps", which is a list of strings. Each string is a step in the playbook.
+You must output a JSON object with a single key "steps", which is a list of strings. Each string is a step in the agent.
 
 Your plan should:
 1. Identify the key steps in the workflow
-2. Mark user-specific variables that should become the main playbook function parameters using `variable_name` syntax. Intermediate variables should not be highlighted using ``
+2. Mark user-specific variables that should become the main agent function parameters using `variable_name` syntax. Intermediate variables should not be highlighted using ``
 3. Keep the logic generic and reusable
 4. Be clear and concise
 
@@ -89,26 +90,26 @@ Now create a plan based on the conversation history. Do not include any other te
 """
 
 
-PLAYBOOK_GENERATING_PROMPT = """Now, you are tasked with generating the playbook function.
+AGENT_BUILDER_GENERATING_PROMPT = """Now, you are tasked with generating the agent function.
 Your response must be ONLY the Python code for the function.
 Do not include any other text, markdown, or explanations in your response.
 Your response should start with `def` or `async def`.
 The function should be a single, complete piece of code that can be executed independently, based on previously executed code snippets that executed correctly.
-The parameters of the function should be the same as the final confirmed playbook plan.
+The parameters of the function should be the same as the final confirmed agent plan.
 """
 
 
-PLAYBOOK_META_PROMPT = """
-You are preparing metadata for a reusable playbook based on the confirmed step-by-step plan.
+AGENT_BUILDER_META_PROMPT = """
+You are preparing metadata for a reusable agent based on the confirmed step-by-step plan.
 
-TASK: Create a concise, human-friendly name and a short description for the playbook.
+TASK: Create a concise, human-friendly name and a short description for the agent.
 
 INPUTS:
 - Conversation context and plan steps will be provided in prior messages
 
 REQUIREMENTS:
 1. Name: 3-6 words, Title Case, no punctuation except hyphens if needed
-2. Description: Single sentence, <= 140 characters, clearly states what the playbook does
+2. Description: Single sentence, <= 140 characters, clearly states what the agent does
 
 OUTPUT: Return ONLY a JSON object with exactly these keys:
 {
@@ -136,14 +137,21 @@ def create_default_prompt(
     additional_tools: Sequence[StructuredTool],
     base_prompt: str | None = None,
     apps_string: str | None = None,
-    playbook: object | None = None,
+    agent: object | None = None,
+    is_initial_prompt: bool = False,
 ):
-    system_prompt = uneditable_prompt.strip()
-    if apps_string:
-        system_prompt += f"\n\n**Connected external applications (These apps have been logged into by the user):**\n{apps_string}\n\n Use `search_functions` to search for functions you can perform using the above. You can also discover more applications using the `search_functions` tool to find additional tools and integrations, if required.\n"
-    system_prompt += "\n\nIn addition to the Python Standard Library, you can use the following external functions:\n"
-    
+    if is_initial_prompt:
+        system_prompt = uneditable_prompt.strip()
+        if apps_string:
+            system_prompt += f"\n\n**Connected external applications (These apps have been logged into by the user):**\n{apps_string}\n\n Use `search_functions` to search for functions you can perform using the above. You can also discover more applications using the `search_functions` tool to find additional tools and integrations, if required.\n"
+        system_prompt += (
+            "\n\nIn addition to the Python Standard Library, you can use the following external functions:\n"
+        )
+    else:
+        system_prompt = ""
+
     tools_context = {}
+    tool_definitions = []
 
     for tool in tools:
         if hasattr(tool, "func") and tool.func is not None:
@@ -152,10 +160,11 @@ def create_default_prompt(
         elif hasattr(tool, "coroutine") and tool.coroutine is not None:
             tool_callable = tool.coroutine
             is_async = True
-        system_prompt += f'''{"async " if is_async else ""}{schema_to_signature(tool.args, tool.name)}:
+        tool_definitions.append(
+            f'''{"async " if is_async else ""}{schema_to_signature(tool.args, tool.name)}:
     """{tool.description}"""
-    ...
-'''
+    ...'''
+        )
         safe_name = make_safe_function_name(tool.name)
         tools_context[safe_name] = tool_callable
 
@@ -166,34 +175,40 @@ def create_default_prompt(
         elif hasattr(tool, "coroutine") and tool.coroutine is not None:
             tool_callable = tool.coroutine
             is_async = True
-        system_prompt += f'''{"async " if is_async else ""}def {tool.name} {str(inspect.signature(tool_callable))}:
+        tool_definitions.append(
+            f'''{"async " if is_async else ""}def {tool.name} {str(inspect.signature(tool_callable))}:
     """{tool.description}"""
-    ...
-'''
+    ...'''
+        )
         safe_name = make_safe_function_name(tool.name)
         tools_context[safe_name] = tool_callable
 
-    if base_prompt and base_prompt.strip():
-        system_prompt += f"Your goal is to perform the following task:\n\n{base_prompt}"
-
-    # Append existing playbook (plan + code) if provided
-    try:
-        if playbook and hasattr(playbook, "instructions"):
-            pb = playbook.instructions or {}
-            plan = pb.get("playbookPlan")
-            code = pb.get("playbookScript")
-            if plan or code:
-                system_prompt += "\n\nExisting Playbook Provided:\n"
-                if plan:
-                    if isinstance(plan, list):
-                        plan_block = "\n".join(f"- {str(s)}" for s in plan)
-                    else:
-                        plan_block = str(plan)
-                    system_prompt += f"Plan Steps:\n{plan_block}\n"
-                if code:
-                    system_prompt += f"\nScript:\n```python\n{str(code)}\n```\n"
-    except Exception:
-        # Silently ignore formatting issues
-        pass
+    system_prompt += "\n".join(tool_definitions)
+
+    if is_initial_prompt:
+        if base_prompt and base_prompt.strip():
+            system_prompt += (
+                f"\n\nUse the following information/instructions while completing your tasks:\n\n{base_prompt}"
+            )
+
+        # Append existing agent (plan + code) if provided
+        try:
+            if agent and hasattr(agent, "instructions"):
+                pb = agent.instructions or {}
+                plan = pb.get("plan")
+                code = pb.get("script")
+                if plan or code:
+                    system_prompt += "\n\nExisting Agent Provided:\n"
+                    if plan:
+                        if isinstance(plan, list):
+                            plan_block = "\n".join(f"- {str(s)}" for s in plan)
+                        else:
+                            plan_block = str(plan)
+                        system_prompt += f"Plan Steps:\n{plan_block}\n"
+                    if code:
+                        system_prompt += f"\nScript:\n```python\n{str(code)}\n```\n"
+        except Exception:
+            # Silently ignore formatting issues
+            pass
 
     return system_prompt, tools_context

universal_mcp/agents/codeact0/state.py

@@ -1,19 +1,19 @@
-from typing import Annotated, Any, List
+from typing import Annotated, Any
 
 from langgraph.prebuilt.chat_agent_executor import AgentState
 from pydantic import BaseModel, Field
 
 
-class PlaybookPlan(BaseModel):
-    steps: List[str] = Field(description="The steps of the playbook.")
+class AgentBuilderPlan(BaseModel):
+    steps: list[str] = Field(description="The steps of the agent.")
 
 
-class PlaybookCode(BaseModel):
-    code: str = Field(description="The Python code for the playbook.")
+class AgentBuilderCode(BaseModel):
+    code: str = Field(description="The Python code for the agent.")
 
 
-class PlaybookMeta(BaseModel):
-    name: str = Field(description="Concise, title-cased playbook name (3-6 words).")
+class AgentBuilderMeta(BaseModel):
+    name: str = Field(description="Concise, title-cased agent name (3-6 words).")
     description: str = Field(description="Short, one-sentence description (<= 140 chars).")
 
 
@@ -46,13 +46,13 @@ class CodeActState(AgentState):
     """Dictionary containing the execution context with available tools and variables."""
     add_context: dict[str, Any]
     """Dictionary containing the additional context (functions, classes, imports) to be added to the execution context."""
-    playbook_mode: str | None
-    """State for the playbook agent."""
+    agent_builder_mode: str | None
+    """State for the agent builder agent."""
     selected_tool_ids: Annotated[list[str], _enqueue]
     """Queue for tools exported from registry"""
     plan: list[str] | None
-    """Plan for the playbook agent."""
-    playbook_name: str | None
-    """Generated playbook name after confirmation."""
-    playbook_description: str | None
+    """Plan for the agent builder agent."""
+    agent_name: str | None
+    """Generated agent name after confirmation."""
+    agent_description: str | None
     """Generated short description after confirmation."""

universal_mcp/agents/codeact0/tools.py

@@ -4,16 +4,18 @@ from collections import defaultdict
 from typing import Annotated, Any
 
 from langchain_core.tools import tool
-from loguru import logger
 from pydantic import Field
 from universal_mcp.agentr.registry import AgentrRegistry
 from universal_mcp.types import ToolFormat
 
+from universal_mcp.agents.codeact0.prompts import create_default_prompt
 
-def enter_playbook_mode():
-    """Call this function to enter playbook mode. Playbook mode is when the user wants to store a repeated task as a script with some inputs for the future."""
+
+def enter_agent_builder_mode():
+    """Call this function to enter agent builder mode. Agent builder mode is when the user wants to store a repeated task as a script with some inputs for the future."""
     return
 
+
 def create_meta_tools(tool_registry: AgentrRegistry) -> dict[str, Any]:
     """Create the meta tools for searching and loading tools"""
 
@@ -99,7 +101,9 @@ def create_meta_tools(tool_registry: AgentrRegistry) -> dict[str, Any]:
                 prioritized_app_id_list = [canonical_app_id]
             else:
                 # 1. Perform an initial broad search for tools.
-                initial_tool_search_tasks = [registry.search_tools(query=q, distance_threshold=THRESHOLD) for q in queries]
+                initial_tool_search_tasks = [
+                    registry.search_tools(query=q, distance_threshold=THRESHOLD) for q in queries
+                ]
                 initial_tool_results = await asyncio.gather(*initial_tool_search_tasks)
 
                 # 2. Search for relevant apps.
@@ -192,15 +196,44 @@ def create_meta_tools(tool_registry: AgentrRegistry) -> dict[str, Any]:
 
     @tool
     async def load_functions(tool_ids: list[str]) -> str:
-        """Load specific functions by their IDs for use in subsequent steps.
+        """
+        Loads specified functions and returns their Python signatures and docstrings.
+        This makes the functions available for use inside the 'execute_ipython_cell' tool.
+        The agent MUST use the returned information to understand how to call the functions correctly.
 
         Args:
-            tool_ids: Function ids in the form 'app__function'. Example: 'google_mail__send_email'
+            tool_ids: A list of function IDs in the format 'app__function'. Example: ['google_mail__send_email']
 
         Returns:
-            Confirmation message about loaded functions
+            A string containing the signatures and docstrings of the successfully loaded functions,
+            ready for the agent to use in its code.
         """
-        return f"Successfully loaded {len(tool_ids)} functions: {tool_ids}"
+        if not tool_ids:
+            return "No tool IDs provided to load."
+
+        # Step 1: Validate which tools are usable and get login links for others.
+        valid_tools, unconnected_links = await get_valid_tools(tool_ids=tool_ids, registry=tool_registry)
+
+        if not valid_tools:
+            return "Error: None of the provided tool IDs could be validated or loaded."
+
+        # Step 2: Export the schemas of the valid tools.
+        all_exported_tools = await tool_registry.export_tools(valid_tools, ToolFormat.LANGCHAIN)
+        exported_tools = [tool for tool in all_exported_tools if tool.name in valid_tools]
+
+
+        # Step 3: Build the informational string for the agent.
+        tool_definitions, new_tools_context = create_default_prompt(exported_tools, [], is_initial_prompt=False)
+
+        result_parts = [
+            f"Successfully loaded {len(exported_tools)} functions. They are now available for use inside `execute_ipython_cell`:",
+            tool_definitions,
+        ]
+
+        response_string = "\n\n".join(result_parts)
+        unconnected_links = "\n".join(unconnected_links)
+
+        return response_string, new_tools_context, valid_tools, unconnected_links
 
     @tool
     async def web_search(query: str) -> dict:

universal_mcp/agents/codeact0/utils.py

@@ -10,6 +10,26 @@ from universal_mcp.types import ToolConfig
 MAX_CHARS = 5000
 
 
+def build_anthropic_cache_message(text: str, role: str = "system", ttl: str = "1h") -> list[dict[str, Any]]:
+    """Build a complete Anthropic cache messages array from text.
+
+    Returns a list with a single cache message whose content is the
+    cached Anthropic content array with ephemeral cache control and TTL.
+    """
+    return [
+        {
+            "role": role,
+            "content": [
+                {
+                    "type": "text",
+                    "text": text,
+                    "cache_control": {"type": "ephemeral", "ttl": ttl},
+                }
+            ],
+        }
+    ]
+
+
 def add_tools(tool_config: ToolConfig, tools_to_add: ToolConfig):
     for app_id, new_tools in tools_to_add.items():
         all_tools = tool_config.get(app_id, []) + new_tools
@@ -375,6 +395,7 @@ def schema_to_signature(schema: dict, func_name: str = "my_function") -> str:
     param_str = ",\n    ".join(params)
     return f"def {func_name}(\n    {param_str},\n):"
 
+
 def smart_truncate(
     output: str, max_chars_full: int = 2000, max_lines_headtail: int = 20, summary_threshold: int = 10000
 ) -> str:
@@ -413,21 +434,21 @@ async def get_connected_apps_string(registry) -> str:
     """Get a formatted string of connected applications from the registry."""
     if not registry:
         return ""
-    
+
     try:
         # Get connected apps from registry
         connections = await registry.list_connected_apps()
         if not connections:
             return "No applications are currently connected."
-        
+
         # Extract app names from connections
         connected_app_ids = {connection["app_id"] for connection in connections}
-        
+
         # Format the apps list
         apps_list = []
         for app_id in connected_app_ids:
             apps_list.append(f"- {app_id}")
-        
+
         return "\n".join(apps_list)
     except Exception:
-        return "Unable to retrieve connected applications."
+        return "Unable to retrieve connected applications."

{universal_mcp_agents-0.1.23rc1.dist-info → universal_mcp_agents-0.1.23rc3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: universal-mcp-agents
-Version: 0.1.23rc1
+Version: 0.1.23rc3
 Summary: Add your description here
 Project-URL: Homepage, https://github.com/universal-mcp/applications
 Project-URL: Repository, https://github.com/universal-mcp/applications
@@ -12,8 +12,8 @@ Requires-Dist: langchain-google-genai>=2.1.10
 Requires-Dist: langchain-openai>=0.3.32
 Requires-Dist: langgraph>=0.6.6
 Requires-Dist: typer>=0.17.4
-Requires-Dist: universal-mcp-applications>=0.1.24
-Requires-Dist: universal-mcp>=0.1.24rc25
+Requires-Dist: universal-mcp-applications>=0.1.25
+Requires-Dist: universal-mcp>=0.1.24rc26
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'

{universal_mcp_agents-0.1.23rc1.dist-info → universal_mcp_agents-0.1.23rc3.dist-info}/RECORD

@@ -1,6 +1,6 @@
-universal_mcp/agents/__init__.py,sha256=Rh6vKqpwuZ2joC9nzLFHUI1G7jzbwwC3p0mgpH5qRgo,1112
-universal_mcp/agents/base.py,sha256=CEnY8y2as_XR311t9v2iqd4DOCSyhpOPOBDcZKNJMpc,7378
-universal_mcp/agents/cli.py,sha256=bXdpgxsOMjclm1STHJgx10ocX9EebQ11DrxH0p6KMZk,943
+universal_mcp/agents/__init__.py,sha256=bW7WJopR6YZSLxghLf8nhohhHPWzm0wdGoZlmKDAcZ4,1078
+universal_mcp/agents/base.py,sha256=sSC217rac89dEheeIRZoMSU_nk9UfSfQw-0E1BjNSIc,7393
+universal_mcp/agents/cli.py,sha256=9CG7majpWUz7C6t0d8xr-Sg2ZPKBuQdykTbYS6KIZ3A,922
 universal_mcp/agents/hil.py,sha256=_5PCK6q0goGm8qylJq44aSp2MadP-yCPvhOJYKqWLMo,3808
 universal_mcp/agents/llm.py,sha256=hVRwjZs3MHl5_3BWedmurs2Jt1oZDfFX0Zj9F8KH7fk,1787
 universal_mcp/agents/react.py,sha256=8XQvJ0HLVgc-K0qn9Ml48WGcgUGuIKtL67HatlT6Da0,3334
@@ -21,16 +21,16 @@ universal_mcp/agents/builder/helper.py,sha256=8igR1b3Gy_N2u3WxHYKIWzvw7F5BMnfpO2
 universal_mcp/agents/builder/prompts.py,sha256=8Xs6uzTUHguDRngVMLak3lkXFkk2VV_uQXaDllzP5cI,4670
 universal_mcp/agents/builder/state.py,sha256=7DeWllxfN-yD6cd9wJ3KIgjO8TctkJvVjAbZT8W_zqk,922
 universal_mcp/agents/codeact0/__init__.py,sha256=8-fvUo1Sm6dURGI-lW-X3Kd78LqySYbb5NMkNJ4NDwg,76
-universal_mcp/agents/codeact0/__main__.py,sha256=_7qSz97YnRgYJTESkALS5_eBIGHiMjA5rhr3IAeBvVo,896
-universal_mcp/agents/codeact0/agent.py,sha256=--cAjQ05VntXga2ofpnL9oFXAk6ANZ2SftwtLkQgy00,17844
+universal_mcp/agents/codeact0/__main__.py,sha256=EHW9ePVePEemGI5yMUBc2Mp_JlrP6Apk1liab1y2Rd8,782
+universal_mcp/agents/codeact0/agent.py,sha256=LzCshVduxT8weYbZ2mOyL1-rp4o-8H1ODoZAaONAV6o,19322
 universal_mcp/agents/codeact0/config.py,sha256=H-1woj_nhSDwf15F63WYn723y4qlRefXzGxuH81uYF0,2215
 universal_mcp/agents/codeact0/langgraph_agent.py,sha256=8nz2wq-LexImx-l1y9_f81fK72IQetnCeljwgnduNGY,420
 universal_mcp/agents/codeact0/llm_tool.py,sha256=-pAz04OrbZ_dJ2ueysT1qZd02DrbLY4EbU0tiuF_UNU,798
-universal_mcp/agents/codeact0/prompts.py,sha256=Gk6WTx2X7IOlbC3wYtGwKWDoeUtgpkMeiyfhj6LEq2I,11221
+universal_mcp/agents/codeact0/prompts.py,sha256=PEBPHvw4yItNVMAaaVUfNVhp53iijxs283Ln6xhew-4,11623
 universal_mcp/agents/codeact0/sandbox.py,sha256=Xw4tbUV_6haYIZZvteJi6lIYsW6ni_3DCRCOkslTKgM,4459
-universal_mcp/agents/codeact0/state.py,sha256=co3BZBuMIt1FP2qzgsbsLkyKbddCG1ieKyAw9TAskSU,1944
-universal_mcp/agents/codeact0/tools.py,sha256=1EBStJQQQCuNeWOqt0VP-XFiT0fE4oCR9nvUiwzRhe4,13164
-universal_mcp/agents/codeact0/utils.py,sha256=PgisAxmqYIzimc4lFA1nV-R7gxkICIrtO1q0FQZ-UoY,17580
+universal_mcp/agents/codeact0/state.py,sha256=241G-ZDIs4dqm_RnfLZuZOBr7llJOh4dQoDc0aiRcPo,1947
+universal_mcp/agents/codeact0/tools.py,sha256=ZvAqi2vwarTlPizVdu9cZIAoujtBTF4OWnd69rdIIyA,14711
+universal_mcp/agents/codeact0/utils.py,sha256=Gvft0W0Sg1qlFWm8ciX14yssCa8y3x037lql92yGsBQ,18164
 universal_mcp/agents/shared/__main__.py,sha256=XxH5qGDpgFWfq7fwQfgKULXGiUgeTp_YKfcxftuVZq8,1452
 universal_mcp/agents/shared/prompts.py,sha256=yjP3zbbuKi87qCj21qwTTicz8TqtkKgnyGSeEjMu3ho,3761
 universal_mcp/agents/shared/tool_node.py,sha256=DC9F-Ri28Pam0u3sXWNODVgmj9PtAEUb5qP1qOoGgfs,9169
@@ -39,6 +39,6 @@ universal_mcp/applications/filesystem/app.py,sha256=0TRjjm8YnslVRSmfkXI7qQOAlqWl
 universal_mcp/applications/llm/__init__.py,sha256=_XGRxN3O1--ZS5joAsPf8IlI9Qa6negsJrwJ5VJXno0,46
 universal_mcp/applications/llm/app.py,sha256=g9mK-luOLUshZzBGyQZMOHBeCSXmh2kCKir40YnsGUo,12727
 universal_mcp/applications/ui/app.py,sha256=c7OkZsO2fRtndgAzAQbKu-1xXRuRp9Kjgml57YD2NR4,9459
-universal_mcp_agents-0.1.23rc1.dist-info/METADATA,sha256=Fa-ACWH1oawoVDBAbp2iSSDGSCRovD2rWP9e9lUhcYE,881
-universal_mcp_agents-0.1.23rc1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-universal_mcp_agents-0.1.23rc1.dist-info/RECORD,,
+universal_mcp_agents-0.1.23rc3.dist-info/METADATA,sha256=-Bv-20WOl1vY3WTMTmZe0eUShg6RG7vcmPt9HuUFXnU,881
+universal_mcp_agents-0.1.23rc3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+universal_mcp_agents-0.1.23rc3.dist-info/RECORD,,