universal-mcp-agents 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

universal_mcp/agents/codeact/prompts.py

@@ -1,8 +1,6 @@
 import inspect
 import re
-from collections.abc import Sequence
-
-from langchain_core.tools import StructuredTool
+from collections.abc import Callable
 
 
 def make_safe_function_name(name: str) -> str:
@@ -19,41 +17,52 @@ def make_safe_function_name(name: str) -> str:
 
 
 def create_default_prompt(
-    tools: Sequence[StructuredTool],
+    tools: dict[str, Callable],
     base_prompt: str | None = None,
 ):
     """Create default prompt for the CodeAct agent."""
     prompt = f"{base_prompt}\n\n" if base_prompt else ""
-    prompt += """You will be given a task to perform. You should output either
-- a Python code snippet that provides the solution to the task, or a step towards the solution. Any output you want to extract from the code should be printed to the console. Code should be output in a fenced code block.
-- text to be shown directly to the user, if you want to ask for more information or provide the final answer.
+    prompt += """You are a Python programmer. You will be given a task to perform.
+Your goal is to write a self-contained Python script to accomplish the task.
+
+In each turn, you will generate a complete Python script. The script will be executed in a fresh, stateless environment.
+You will be given the previous script you generated and the output it produced.
+Your task is to analyze the output to find errors or opportunities for improvement, and then generate a new, improved script.
+You must take the previous script as a starting point and replace it with a new one that moves closer to the final solution.
+Your final script must be a single, complete piece of code that can be executed independently.
+
+The script must follow this structure:
+1. All necessary imports at the top.
+2. An `async def main():` function containing the core logic.
+3. Do NOT include any code outside of the `async def main()` function, and do NOT call it. The execution environment handles this.
+
+Any output you want to see from the code should be printed to the console from within the `main` function.
+Code should be output in a fenced code block (e.g. ```python ... ```).
+
+If you need to ask for more information or provide the final answer, you can output text to be shown directly to the user.
 
 In addition to the Python Standard Library, you can use the following functions:"""
 
-    for tool in tools:
-        # Use coroutine if it exists, otherwise use func
-        tool_callable = tool.coroutine if hasattr(tool, "coroutine") and tool.coroutine is not None else tool.func
-        # Create a safe function name
-        safe_name = make_safe_function_name(tool.name)
+    for tool_name, tool_callable in tools.items():
         # Determine if it's an async function
         is_async = inspect.iscoroutinefunction(tool_callable)
         # Add appropriate function definition
-        prompt += f'''\n{"async " if is_async else ""}def {safe_name}{str(inspect.signature(tool_callable))}:
-    """{tool.description}"""
+        prompt += f'''\n{"async " if is_async else ""}def {tool_name}{str(inspect.signature(tool_callable))}:
+    """{tool_callable.__doc__}"""
     ...
 '''
 
-    prompt += """
-
-Variables defined at the top level of previous code snippets can be referenced in your code.
-
-Always use print() statements to explore data structures and function outputs. Simply returning values will not display them back to you for inspection. For example, use print(result) instead of just 'result'.
+    prompt += """\n\n\nAlways use print() statements to explore data structures and function outputs. Simply returning values will not display them back to you for inspection. For example, use print(result) instead of just 'result'.
 
 As you don't know the output schema of the additional Python functions you have access to, start from exploring their contents before building a final solution.
 
 IMPORTANT CODING STRATEGY:
-1. Only write code up to the point where you make an API call/tool usage with an output
-2. Print the type/shape and a sample entry of this output, and using that knowledge proceed to write the further code
+1. All your code must be inside an `async def main()` function.
+2. Do NOT import `asyncio` or call `main()`. The execution environment handles this.
+3. Since many of the provided tools are async, you must use `await` to call them from within `main()`.
+4. Write code up to the point where you make an API call/tool usage with an output.
+5. Print the type/shape and a sample entry of this output, and using that knowledge proceed to write the further code.
+6. The maximum number of characters that can be printed is 5000. Remove any unnecessary print statements.
 
 This means:
 - Write code that makes the API call or tool usage
@@ -64,28 +73,10 @@ This means:
 
 Reminder: use Python code snippets to call tools
 
-When you have completely finished the task and provided the final answer, you MUST end your response with the exact phrase "TASK_COMPLETE".
-"""
-    return prompt
-
-
-REFLECTION_PROMPT = """
-Review the assistant's latest code for as per the quality rules:
+When you have completely finished the task, present the final result from your script to the user in a clean and readable Markdown format. Do not just summarize what you did; provide the actual output. For example, if you were asked to find unsubscribe links and your script found them, your final response should be a Markdown-formatted list of those links.
 
-<conversation_history>
-{conversation_history}
-</conversation_history>
 
-If you find ANY of these issues, describe the problem briefly and clearly.
-If NO issues are found, respond with EXACTLY: "NONE"
-"""
-
-RETRY_PROMPT = """
-I need you to completely regenerate your previous response based on this feedback:
-
-'''
-{reflection_result}
-'''
-
-DO NOT reference the feedback directly. Instead, provide a completely new response that addresses the issues.
+Important:
+After you have provided the final output, you MUST set `task_complete` to `True` in your response.
 """
+    return prompt

universal_mcp/agents/codeact/sandbox.py

@@ -1,51 +1,89 @@
 import asyncio
-import builtins
 import contextlib
 import io
+from collections.abc import Callable
 from typing import Any
 
+from loguru import logger
+
+from .models import SandboxOutput
+
+# Define a whitelist of safe built-in functions
+SAFE_BUILTINS = {
+    "abs": abs,
+    "all": all,
+    "any": any,
+    "bool": bool,
+    "callable": callable,
+    "chr": chr,
+    "dict": dict,
+    "divmod": divmod,
+    "enumerate": enumerate,
+    "filter": filter,
+    "float": float,
+    "getattr": getattr,
+    "hasattr": hasattr,
+    "hash": hash,
+    "id": id,
+    "int": int,
+    "isinstance": isinstance,
+    "iter": iter,
+    "len": len,
+    "list": list,
+    "max": max,
+    "min": min,
+    "next": next,
+    "ord": ord,
+    "pow": pow,
+    "print": print,
+    "range": range,
+    "repr": repr,
+    "reversed": reversed,
+    "round": round,
+    "set": set,
+    "slice": slice,
+    "sorted": sorted,
+    "str": str,
+    "sum": sum,
+    "tuple": tuple,
+    "type": type,
+    "zip": zip,
+}
+
+
+# (The SAFE_BUILTINS definition remains the same)
+# ...
+
+
+async def eval_unsafe(
+    code: str, _locals: dict[str, Callable], timeout: int = 10
+) -> tuple[SandboxOutput, dict[str, Any]]:
+    """Executes a string of Python code in a sandboxed environment."""
+    original_keys = set(_locals.keys())
+    execution_context = _locals.copy()
+    execution_context["__builtins__"] = SAFE_BUILTINS
+
+    stdout_capture = io.StringIO()
+    output = SandboxOutput(stdout="")
 
-async def eval_unsafe(code: str, _locals: dict[str, Any], timeout: int = 10) -> tuple[str, dict[str, Any]]:
-    """
-    Execute code in a non-blocking way and return the output and changed variables.
-    """
-    result = f"Executing code...\n{code}\n\nOutput:\n"
-    result += "=" * 50 + "\n"
-
-    # Create a combined globals/locals environment that includes builtins
-    # and the provided context. This allows nested functions to access tools.
-    execution_env = {**builtins.__dict__, **_locals}
-
-    def sync_eval_in_thread():
-        """Synchronously execute code and capture output."""
-        try:
-            with contextlib.redirect_stdout(io.StringIO()) as f:
-                exec(code, execution_env)
-            output = f.getvalue()
-            if not output:
-                output = "<code ran, no output printed to stdout>"
-            return output
-        except Exception as e:
-            return f"Error during execution: {repr(e)}"
-
-    # Run the synchronous exec in a separate thread to avoid blocking the event loop.
     try:
-        output = await asyncio.wait_for(asyncio.to_thread(sync_eval_in_thread), timeout=timeout)
-    except asyncio.TimeoutError:
-        output = f"Error: Code execution timed out after {timeout} seconds."
-    result += output
+        logger.debug(f"Executing code with timeout {timeout}")
+        with contextlib.redirect_stdout(stdout_capture):
+            exec(code, execution_context)
+
+            if "main" in execution_context and asyncio.iscoroutinefunction(execution_context["main"]):
+                return_val = await asyncio.wait_for(execution_context["main"](), timeout=timeout)
+                output.return_value = return_val
+            else:
+                output.error = "No `async def main()` function found in the script."
 
-    # Identify all variables that are not part of the original builtins
-    # and were not in the initial _locals, or were changed.
-    changed_vars = {}
-    builtin_keys = set(builtins.__dict__.keys())
+        output.stdout = stdout_capture.getvalue()
 
-    for key, value in execution_env.items():
-        if key in builtin_keys:
-            continue  # Skip builtins
+    except Exception as e:
+        output.error = f"{type(e).__name__}: {e}"
+        output.stdout = stdout_capture.getvalue()
 
-        # Check if the key is new or if the value has changed
-        if key not in _locals or _locals[key] is not value:
-            changed_vars[key] = value
+    new_keys = set(execution_context.keys()) - original_keys - {"__builtins__"}
+    new_vars = {key: execution_context[key] for key in new_keys}
 
-    return result, changed_vars
+    return output, new_vars

universal_mcp/agents/codeact/state.py

@@ -1,10 +1,11 @@
-from typing import Any
-
 from langgraph.graph import MessagesState
+from pydantic import Field
 
 
 class CodeActState(MessagesState):
     """State for CodeAct agent."""
 
-    script: str | None
-    """The Python code script to be executed."""
+    script: str | None = Field(default=None, description="The Python code script to be executed.")
+    sandbox_output: str | None = Field(default=None, description="The output of the Python code script execution.")
+    syntax_error: str | None = Field(default=None, description="The syntax error from the last script validation.")
+    task_complete: bool = Field(default=False, description="Whether the task is complete.")

universal_mcp/agents/codeact0/__init__.py

@@ -0,0 +1,3 @@
+from .agent import CodeActAgent
+
+__all__ = ["CodeActAgent"]

universal_mcp/agents/codeact0/__main__.py

@@ -0,0 +1,35 @@
+import asyncio
+
+from langgraph.checkpoint.memory import MemorySaver
+from rich import print
+from universal_mcp.agentr.registry import AgentrRegistry
+
+from universal_mcp.agents.codeact0.agent import CodeActAgent
+from universal_mcp.agents.utils import messages_to_list
+
+
+async def main():
+    memory = MemorySaver()
+    agent = CodeActAgent(
+        name="CodeAct Agent",
+        instructions="Be very concise in your answers.",
+        model="anthropic:claude-4-sonnet-20250514",
+        tools={"google_mail": ["list_messages"]},
+        registry=AgentrRegistry(),
+        memory=memory,
+    )
+    print("Starting agent...")
+    # await agent.ainit()
+    # await agent.run_interactive()
+    # async for event in agent.stream(
+    #     user_input="Fetch unsubscribe links from my Gmail inbox for promo emails I have received in the last 7 days"
+    # ):
+    #     print(event.content, end="")
+    result = await agent.invoke(
+        user_input="Fetch unsubscribe links from my Gmail inbox for promo emails I have received in the last 7 days"
+    )
+    print(messages_to_list(result["messages"]))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

universal_mcp/agents/codeact0/agent.py

@@ -0,0 +1,136 @@
+import inspect
+from collections.abc import Callable
+from typing import Literal, cast
+
+from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.tools import StructuredTool
+from langchain_core.tools import tool as create_tool
+from langgraph.checkpoint.base import BaseCheckpointSaver
+from langgraph.graph import START, StateGraph
+from langgraph.types import Command, RetryPolicy
+from universal_mcp.tools.registry import ToolRegistry
+from universal_mcp.types import ToolConfig, ToolFormat
+
+from universal_mcp.agents.base import BaseAgent
+from universal_mcp.agents.codeact0.llm_tool import ai_classify, call_llm, data_extractor, smart_print
+from universal_mcp.agents.codeact0.prompts import (
+    create_default_prompt,
+)
+from universal_mcp.agents.codeact0.sandbox import eval_unsafe, execute_ipython_cell
+from universal_mcp.agents.codeact0.state import CodeActState
+from universal_mcp.agents.codeact0.utils import filter_retry_on, inject_context
+from universal_mcp.agents.llm import load_chat_model
+
+
+class CodeActAgent(BaseAgent):
+    def __init__(
+        self,
+        name: str,
+        instructions: str,
+        model: str,
+        memory: BaseCheckpointSaver | None = None,
+        tools: ToolConfig | None = None,
+        registry: ToolRegistry | 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, thinking=True)
+        self.tools_config = tools or {}
+        self.registry = registry
+        self.eval_fn = eval_unsafe
+        self.sandbox_timeout = sandbox_timeout
+        self.processed_tools: list[StructuredTool | Callable] = []
+
+        # TODO(manoj): Use toolformat native instead of langchain
+        # TODO(manoj, later): Add better sandboxing
+        # Old Nishant TODO s:
+        # - Make codeact faster by calling upto API call (this done but should be tested)
+        # - Add support for async eval_fn
+        # - Throw Error if code snippet is too long (> 1000 characters) and suggest to split it into smaller parts
+        # - Multiple models from config
+
+    async def _build_graph(self):
+        exported_tools = []
+        if self.tools_config:
+            if not self.registry:
+                raise ValueError("Tools are configured but no registry is provided")
+            # Langchain tools are fine
+            exported_tools = await self.registry.export_tools(self.tools_config, ToolFormat.LANGCHAIN)
+        exported_tools.extend([smart_print, data_extractor, ai_classify, call_llm])
+        self.processed_tools = [t if isinstance(t, StructuredTool) else create_tool(t) for t in exported_tools]
+        self.instructions, self.tools_context = create_default_prompt(self.processed_tools, self.instructions)
+
+        def call_model(state: CodeActState) -> Command[Literal["sandbox"]]:
+            messages = [{"role": "system", "content": self.instructions}] + state["messages"]
+
+            # Run the model and potentially loop for reflection
+            model_with_tools = self.model_instance.bind_tools(tools=[execute_ipython_cell], tool_choice="auto")
+            response = cast(AIMessage, model_with_tools.invoke(messages))
+
+            if response.tool_calls:
+                if len(response.tool_calls) > 1:
+                    raise Exception("Not possible in Claude with llm.bind_tools(tools=tools, tool_choice='auto')")
+                if response.tool_calls[0]["name"] != "execute_ipython_cell":
+                    raise Exception(
+                        f"Unexpected tool call: {response.tool_calls[0]['name']}. Expected 'execute_ipython_cell'."
+                    )
+                if (
+                    response.tool_calls[0]["args"].get("snippet") is None
+                    or not response.tool_calls[0]["args"]["snippet"].strip()
+                ):
+                    raise Exception("Tool call 'execute_ipython_cell' requires a non-empty 'snippet' argument.")
+                return Command(goto="sandbox", update={"messages": [response]})
+            else:
+                return Command(update={"messages": [response]})
+
+        # If eval_fn is a async, we define async node function.
+        if inspect.iscoroutinefunction(self.eval_fn):
+            raise ValueError("eval_fn must be a synchronous function, not a coroutine.")
+            # async def sandbox(state: StateSchema):
+            #     existing_context = state.get("context", {})
+            #     context = {**existing_context, **tools_context}
+            #     # Execute the script in the sandbox
+            #     output, new_vars = await eval_fn(state["script"], context)
+            #     new_context = {**existing_context, **new_vars}
+            #     return {
+            #         "messages": [{"role": "user", "content": output}],
+            #         "context": new_context,
+            #     }
+        else:
+
+            def sandbox(state: CodeActState) -> Command[Literal["call_model"]]:
+                tool_call = state["messages"][-1].tool_calls[0]  # type: ignore
+                code = tool_call["args"]["snippet"]
+                previous_add_context = state.get("add_context", {})
+                add_context = inject_context(previous_add_context, self.tools_context)
+                existing_context = state.get("context", {})
+                context = {**existing_context, **add_context}
+                # Execute the script in the sandbox
+                output, new_context, new_add_context = self.eval_fn(code, context, previous_add_context)
+                return Command(
+                    goto="call_model",
+                    update={
+                        "messages": [
+                            ToolMessage(
+                                content=output,
+                                name=tool_call["name"],
+                                tool_call_id=tool_call["id"],
+                            )
+                        ],
+                        "context": new_context,
+                        "add_context": new_add_context,
+                    },
+                )
+
+        agent = StateGraph(state_schema=CodeActState)
+        agent.add_node(call_model, retry_policy=RetryPolicy(max_attempts=3, retry_on=filter_retry_on))
+        agent.add_node(sandbox)
+        agent.add_edge(START, "call_model")
+        return agent.compile(checkpointer=self.memory)

universal_mcp/agents/codeact0/config.py

@@ -0,0 +1,77 @@
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+# Literal type for all available usecase filenames
+UseCaseName = Literal[
+    " ",
+    "1-unsubscribe",
+    "2-reddit",
+    "2.1-reddit",
+    "3-earnings",
+    "4-maps",
+    "4.1-maps",
+    "5-gmailreply",
+    "6-contract",
+    "7-overnight",
+    "8-sheets_chart",
+    "9-learning",
+    "10-reddit2",
+    "11-github",
+]
+
+
+class ContextSchema(BaseModel):
+    """The configuration for the agent."""
+
+    base_prompt: str = Field(
+        default=" ",
+        description="The base prompt to use for the agent's interactions. Leave blank if using a JSON prompt from the dropdown.",
+    )
+    model_provider: Annotated[
+        Literal[
+            "openai",
+            "anthropic",
+            "azure_openai",
+            "azure_ai",
+            "google_vertexai",
+            "google_genai",
+            "bedrock",
+            "bedrock_converse",
+            "cohere",
+            "fireworks",
+            "together",
+            "mistralai",
+            "huggingface",
+            "groq",
+            "ollama",
+            "google_anthropic_vertex",
+            "deepseek",
+            "ibm",
+            "nvidia",
+            "xai",
+            "perplexity",
+        ],
+        {"__template_metadata__": {"kind": "provider"}},
+    ] = Field(
+        default="anthropic",
+        description="The name of the model provider to use for the agent's main interactions. ",
+    )
+    model: Annotated[
+        Literal[
+            "claude-4-sonnet-20250514",
+            "claude-sonnet-4@20250514",
+        ],
+        {"__template_metadata__": {"kind": "llm"}},
+    ] = Field(
+        default="claude-4-sonnet-20250514",
+        description="The name of the language model to use for the agent's main interactions. ",
+    )
+    tool_names: list[str] = Field(
+        default=[],
+        description="The names of the tools to use for the agent's main interactions. Leave blank if using a JSON prompt from the dropdown.",
+    )
+    json_prompt_name: UseCaseName = Field(
+        default=" ",
+        description="The name of the JSON prompt to use for the agent's main interactions, instead of providing a base prompt and tool names. ",
+    )

universal_mcp/agents/codeact0/langgraph_graph.py

@@ -0,0 +1,17 @@
+from langgraph.checkpoint.memory import MemorySaver
+from universal_mcp.agentr.registry import AgentrRegistry
+
+from universal_mcp.agents.codeact0.agent import CodeActAgent
+
+
+async def agent():
+    memory = MemorySaver()
+    agent_object = await CodeActAgent(
+        name="CodeAct Agent",
+        instructions="Be very concise in your answers.",
+        model="anthropic:claude-4-sonnet-20250514",
+        tools={"google_mail": ["list_messages"]},
+        registry=AgentrRegistry(),
+        memory=memory,
+    )._build_graph()
+    return agent_object

universal_mcp/agents/codeact0/legacy_codeact.py

@@ -0,0 +1,104 @@
+import contextlib
+import inspect
+import io
+import queue
+import re
+import socket
+import threading
+import types
+from typing import Any
+
+import yaml
+from langchain.chat_models import init_chat_model
+from langchain_anthropic import ChatAnthropic
+from langchain_core.runnables import RunnableConfig
+from langchain_google_vertexai.model_garden import ChatAnthropicVertex
+from universal_mcp.agentr import Agentr
+from universal_mcp.types import ToolFormat
+
+from universal_mcp.agents.codeact0 import create_codeact
+from universal_mcp.agents.codeact0.config import ContextSchema
+from universal_mcp.agents.codeact0.utils import derive_context
+
+
+def eval(code: str, _locals: dict[str, Any], add_context: dict[str, Any]) -> tuple[str, dict[str, Any], dict[str, Any]]:
+    # print(_locals)
+    EXCLUDE_TYPES = (
+        types.ModuleType,  # modules
+        type(re.match("", "")),
+        type(threading.Lock()),  # instead of threading.Lock
+        type(threading.RLock()),  # reentrant lock
+        threading.Event,  # events
+        threading.Condition,  # condition vars
+        threading.Semaphore,  # semaphores
+        queue.Queue,  # thread-safe queues
+        socket.socket,  # network sockets
+        io.IOBase,  # file handles (and StringIO/BytesIO)
+    )
+    try:
+        with contextlib.redirect_stdout(io.StringIO()) as f:
+            # Execute the code in the provided locals context
+            # Using exec to allow dynamic code execution
+            # This is a simplified version; in production, consider security implications
+            exec(code, _locals, _locals)
+        result = f.getvalue()
+        if not result:
+            result = "<code ran, no output printed to stdout>"
+    except Exception as e:
+        result = f"Error during execution: {repr(e)}"
+
+    # Return all variables in locals except __builtins__ and unpicklable objects (including tools)
+    all_vars = {}
+    for key, value in _locals.items():
+        if key == "__builtins__":
+            continue
+
+        # Skip coroutines, async generators, and coroutine functions
+        if inspect.iscoroutine(value) or inspect.iscoroutinefunction(value):
+            continue
+        if inspect.isasyncgen(value) or inspect.isasyncgenfunction(value):
+            continue
+
+        # Skip "obviously unpicklable" types
+        if isinstance(value, EXCLUDE_TYPES):
+            continue
+
+        # Keep if it's not a callable OR if it has no __name__ attribute
+        if not callable(value) or not hasattr(value, "__name__"):
+            all_vars[key] = value
+
+    new_add_context = derive_context(code, add_context)
+    return result, all_vars, new_add_context
+
+
+async def agent(config: RunnableConfig):
+    cfg = ContextSchema(**config.get("configurable", {}))
+
+    if cfg.json_prompt_name and cfg.json_prompt_name.strip():
+        with open(f"usecases/{cfg.json_prompt_name}.yaml", encoding="utf-8") as f:
+            content = f.read()
+            data = yaml.safe_load(content)
+            if cfg.base_prompt and cfg.base_prompt.strip():
+                pass
+            else:
+                cfg.base_prompt = data["base_prompt"]
+            cfg.tool_names = data["tools"]
+    agentr = Agentr()
+    agentr.load_tools(cfg.tool_names)
+    tools = []  # can add custom tools here like get_weather, get_simple_weather, etc.
+
+    tools_agentr = agentr.list_tools(format=ToolFormat.NATIVE)
+    tools.extend(tools_agentr)
+
+    if cfg.model_provider == "google_anthropic_vertex":
+        # For Google Anthropic Vertex, we need to use the specific model initialization due to location
+        model = ChatAnthropicVertex(model=cfg.model, temperature=0.2, location="asia-east1")
+    elif cfg.model == "claude-4-sonnet-20250514":
+        model = ChatAnthropic(
+            model=cfg.model, temperature=1, thinking={"type": "enabled", "budget_tokens": 2048}, max_tokens=4096
+        )  # pyright: ignore[reportCallIssue]
+    else:
+        model = init_chat_model(model=cfg.model, model_provider=cfg.model_provider, temperature=0.2)
+
+    code_act = create_codeact(model, cfg.base_prompt, tools, eval)
+    return code_act.compile()