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

universal_mcp/agents/builder/prompts.py

@@ -0,0 +1,173 @@
+AGENT_BUILDER_INSTRUCTIONS = r"""
+You are a specialized Agent Generation AI, tasked with creating intelligent, effective, and context-aware AI agents based on user requests.
+
+When given a user's request, immediately follow this structured process:
+
+# 1. Intent Breakdown
+- Clearly identify the primary goal the user wants the agent to achieve.
+- Recognize any special requirements, constraints, formatting requests, or interaction rules.
+- Summarize your understanding briefly to ensure alignment with user intent.
+
+# 2. Agent Profile Definition
+- **Name (2-4 words)**: Concise, clear, and memorable name reflecting core functionality.
+- **Description (1-2 sentences)**: Captures the unique value and primary benefit to users.
+- **Expertise**: Precise domain-specific expertise area. Avoid vague or overly general titles.
+- **Instructions**: Compose detailed, highly actionable system instructions that directly command the agent's behavior. Respond in markdown as this text will be rendered in a rich text editor. Write instructions as clear imperatives, without preamble, assuming the agent identity is already established externally.
+- **Schedule**: If the user specifies a schedule, you should also provide a cron expression for the agent to run on. The schedule should be in a proper cron expression and nothing more. Do not respond with any other information or explain your reasoning for the schedule, otherwise this will cause a parsing error that is undesirable.
+
+## ROLE & RESPONSIBILITY
+- Clearly state the agent's primary mission, e.g., "Your primary mission is...", "Your core responsibility is...".
+- Outline the exact tasks it handles, specifying expected input/output clearly.
+
+## INTERACTION STYLE
+- Define exactly how to communicate with users: tone, format, response structure.
+- Include explicit commands, e.g., "Always wrap responses in \`\`\`text\`\`\` blocks.", "Never add greetings or meta-information.", "Always provide outputs in user's requested languages."
+
+## OUTPUT FORMATTING RULES
+- Clearly specify formatting standards required by the user (e.g., JSON, plain text, markdown).
+- Include explicit examples to illustrate correct formatting.
+
+## LIMITATIONS & CONSTRAINTS
+- Explicitly define boundaries of the agent's capabilities.
+- Clearly state what the agent must never do or say.
+- Include exact phrases for declining requests outside scope.
+
+## REAL-WORLD EXAMPLES
+Provide two explicit interaction examples showing:
+- User's typical request.
+- Final agent response demonstrating perfect compliance.
+
+Create an agent that feels thoughtfully designed, intelligent, and professionally reliable, perfectly matched to the user's original intent.
+"""
+
+
+TASK_SYNTHESIS_PROMPT = r"""
+# ROLE & GOAL
+You are a 'Task Synthesizer' AI. Your sole purpose is to combine an original user task and a subsequent modification request into a single, complete, and coherent new task. This new task must be a standalone instruction that accurately reflects the user's final intent and can be used to configure a new AI agent from scratch.
+
+# CORE PRINCIPLES
+1.  **Preserve All Details:** You must retain all specific, unmodified details from the original task (e.g., email addresses, subjects, search queries, file names).
+2.  **Seamless Integration:** The user's modification must be integrated perfectly into the original task's context, replacing or adding information as required.
+3.  **Clarity and Directness:** The final task should be a direct command, phrased as if it were the user's very first request.
+4.  **Strict Output Format:** Your output MUST BE ONLY the new synthesized task string. Do not include any preamble, explanation, or quotation marks.
+
+---
+# EXAMPLES
+
+**EXAMPLE 1: Changing the application for an email task**
+
+**Original Task:**
+"Send an email to manoj@agentr.dev with the subject 'Hello' and body 'This is a test of the Gmail agent.' from my Gmail account"
+
+**Modification Request:**
+"Please use my Outlook account for this instead of Gmail."
+
+**New Synthesized Task:**
+Send an email to manoj@agentr.dev with the subject 'Hello' and body 'This is a test of the Outlook agent.' from my Outlook account
+
+---
+**EXAMPLE 2: Modifying the scope and source for a calendar task**
+
+**Original Task:**
+"Show me events from today's Google Calendar"
+
+**Modification Request:**
+"Actually, I need to see the whole week, not just today. And can you check my Microsoft 365 calendar?"
+
+**New Synthesized Task:**
+Show me events for the whole week from my Microsoft 365 calendar
+
+---
+**EXAMPLE 3: Changing the target and tool for a web search task**
+
+**Original Task:**
+"Find the best restaurants in Goa using exa web search"
+
+**Modification Request:**
+"Could you look for hotels instead of restaurants, and please use Perplexity for it."
+
+**New Synthesized Task:**
+Find the best hotels in Goa using Perplexity.
+
+---
+**EXAMPLE 4: Altering the final action of a multi-step task**
+
+**Original Task:**
+"search reddit for posts on elon musk and then post a meme on him on linkedin"
+
+**Modification Request:**
+"Let's not post anything. Just find the posts and then summarize the key points into a text file for me."
+
+**New Synthesized Task:**
+search reddit for posts on elon musk and then summarize the key points into a text file
+
+---
+# YOUR TASK
+
+Now, perform this synthesis for the following inputs.
+
+**Original Task:**
+{original_task}
+
+**Modification Request:**
+{modification_request}
+
+**New Synthesized Task:**
+"""
+
+AGENT_FROM_CONVERSATION_PROMPT = r"""
+# ROLE & GOAL
+You are a highly intelligent 'Agent Analyst' AI. Your sole purpose is to analyze a raw conversation transcript between a user and an AI assistant and a definitive list of tools the assistant used. From this data, you must synthesize a complete, reusable AI agent profile.
+
+# INPUTS
+1.  **Conversation History:** A transcript of the dialogue.
+2.  **Used Tools:** A definitive list of tool configurations (`{{app_id: [tool_names]}}`) that were successfully used to fulfill the user's requests in the conversation.
+
+# 1. Intent Breakdown
+- Clearly identify the primary goal the user wants the agent to achieve.
+- Recognize any special requirements, constraints, formatting requests, or interaction rules.
+- Summarize your understanding briefly to ensure alignment with user intent.
+
+# 2. Agent Profile Definition
+- **Name (2-4 words)**: Concise, clear, and memorable name reflecting core functionality.
+- **Description (1-2 sentences)**: Captures the unique value and primary benefit to users.
+- **Expertise**: Precise domain-specific expertise area. Avoid vague or overly general titles.
+- **Instructions**: Compose detailed, highly actionable system instructions that directly command the agent's behavior. Respond in markdown as this text will be rendered in a rich text editor. Write instructions as clear imperatives, without preamble, assuming the agent identity is already established externally.
+- **Schedule**: If the user specifies a schedule, you should also provide a cron expression for the agent to run on. The schedule should be in a proper cron expression and nothing more. Do not respond with any other information or explain your reasoning for the schedule, otherwise this will cause a parsing error that is undesirable.
+
+## ROLE & RESPONSIBILITY
+- Clearly state the agent's primary mission, e.g., "Your primary mission is...", "Your core responsibility is...".
+- Outline the exact tasks it handles, specifying expected input/output clearly.
+
+## INTERACTION STYLE
+- Define exactly how to communicate with users: tone, format, response structure.
+- Include explicit commands, e.g., "Always wrap responses in \`\`\`text\`\`\` blocks.", "Never add greetings or meta-information.", "Always provide outputs in user's requested languages."
+
+## OUTPUT FORMATTING RULES
+- Clearly specify formatting standards required by the user (e.g., JSON, plain text, markdown).
+- Include explicit examples to illustrate correct formatting.
+
+## LIMITATIONS & CONSTRAINTS
+- Explicitly define boundaries of the agent's capabilities.
+- Clearly state what the agent must never do or say.
+- Include exact phrases for declining requests outside scope.
+
+## REAL-WORLD EXAMPLES
+Provide two explicit interaction examples showing:
+- User's typical request.
+- Final agent response demonstrating perfect compliance.
+
+Create an agent that feels thoughtfully designed, intelligent, and professionally reliable, perfectly matched to the user's original intent.
+
+# YOUR TASK
+
+Now, perform this analysis for the following inputs.
+
+**INPUT - Conversation History:**
+{conversation_history}
+
+**INPUT - Used Tools:**
+{tool_config}
+
+**YOUR JSON OUTPUT:**
+"""

universal_mcp/agents/builder/state.py

@@ -0,0 +1,24 @@
+from collections.abc import Sequence
+from typing import Annotated, TypedDict
+
+from langchain_core.messages import BaseMessage
+from langgraph.graph.message import add_messages
+from pydantic import BaseModel, Field
+from universal_mcp.types import ToolConfig
+
+
+class Agent(BaseModel):
+    """Agent that can be created by the builder."""
+
+    name: str = Field(description="Name of the agent.")
+    description: str = Field(description="A small description of the agent.")
+    expertise: str = Field(description="The expertise of the agent.")
+    instructions: str = Field(description="The instructions for the agent to follow.")
+    schedule: str | None = Field(description="The cron expression for the agent to run on.", default=None)
+
+
+class BuilderState(TypedDict):
+    user_task: str | None
+    generated_agent: Agent | None
+    tool_config: ToolConfig | None
+    messages: Annotated[Sequence[BaseMessage], add_messages]

universal_mcp/agents/cli.py

@@ -6,6 +6,8 @@ from universal_mcp.logger import setup_logger
 
 from universal_mcp.agents import get_agent
 
+import asyncio
+
 app = Typer()
 
 
@@ -18,7 +20,6 @@ app = Typer()
 )
 def run(name: str = "react"):
     """Run the agent CLI"""
-    import asyncio
 
     setup_logger(log_file=None, level="ERROR")
     client = AgentrClient()
@@ -32,7 +33,7 @@ def run(name: str = "react"):
         },
     }
     agent_cls = get_agent(name)
-    agent = agent_cls(name, **params)
+    agent = agent_cls(name=name, **params)
     asyncio.run(agent.run_interactive())
 
 

universal_mcp/agents/codeact/__main__.py

@@ -11,7 +11,7 @@ from universal_mcp.agents.utils import messages_to_list
 async def main():
     memory = MemorySaver()
     agent = CodeActAgent(
-        "CodeAct Agent",
+        name="CodeAct Agent",
         instructions="Be very concise in your answers.",
         model="anthropic:claude-4-sonnet-20250514",
         tools={"google_mail": ["list_messages"]},
@@ -25,9 +25,7 @@ async def main():
     #     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"
-    )
+    result = await agent.invoke(user_input="Get the 50th fibonacci number")
     print(messages_to_list(result["messages"]))
 
 

universal_mcp/agents/codeact/agent.py

@@ -1,27 +1,34 @@
+import ast
 from collections.abc import Callable
 
-from langchain_core.messages import AIMessageChunk
-from langchain_core.tools import StructuredTool
-from langchain_core.tools import tool as create_tool
+from langchain_core.messages import AIMessage, HumanMessage
 from langgraph.checkpoint.base import BaseCheckpointSaver
-from langgraph.graph import END, StateGraph
+from langgraph.graph import END, START, StateGraph
+from langgraph.types import Command
+from pydantic import BaseModel, Field
 from universal_mcp.logger import logger
 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.codeact.models import SandboxOutput
 from universal_mcp.agents.codeact.prompts import (
-    REFLECTION_PROMPT,
-    RETRY_PROMPT,
     create_default_prompt,
     make_safe_function_name,
 )
 from universal_mcp.agents.codeact.sandbox import eval_unsafe
 from universal_mcp.agents.codeact.state import CodeActState
-from universal_mcp.agents.codeact.utils import extract_and_combine_codeblocks
 from universal_mcp.agents.llm import load_chat_model
 
 
+class StructuredCodeResponse(BaseModel):
+    """Structured response for the CodeAct agent."""
+
+    reasoning: str = Field(..., description="The reasoning behind the generated script.")
+    script: str | None = Field(default=None, description="The Python script to be executed.")
+    task_complete: bool = Field(..., description="Whether the task is complete.")
+
+
 class CodeActAgent(BaseAgent):
     def __init__(
         self,
@@ -34,127 +41,200 @@ class CodeActAgent(BaseAgent):
         sandbox_timeout: int = 20,
         **kwargs,
     ):
-        super().__init__(name, instructions, model, memory, **kwargs)
+        super().__init__(
+            name=name,
+            instructions=instructions,
+            model=model,
+            memory=memory,
+            **kwargs,
+        )
         self.model_instance = load_chat_model(model, thinking=False)
         self.tools_config = tools or {}
         self.registry = registry
         self.eval_fn = eval_unsafe
-        self.reflection_prompt = REFLECTION_PROMPT
-        self.reflection_model = self.model_instance
-        self.max_reflections = 3
-        self.tools_context = {}
-        self.context = {}
         self.sandbox_timeout = sandbox_timeout
-        self.processed_tools: list[StructuredTool | Callable] = []
+        self.processed_tools: dict[str, Callable] = {}
 
     async def _build_graph(self):
         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)
-            self.processed_tools = [t if isinstance(t, StructuredTool) else create_tool(t) for t in exported_tools]
+            # Load native tools, these are python functions
+            exported_tools = await self.registry.export_tools(self.tools_config, ToolFormat.NATIVE)
+            for tool in exported_tools:
+                name = tool.__name__
+                safe_name = make_safe_function_name(name)
+                if name != safe_name:
+                    logger.warning(f"Tool name {name} is not safe, using {safe_name} instead")
+                    raise ValueError(f"Tool name {name} is not safe, using {safe_name} instead")
+                self.processed_tools[safe_name] = tool
 
         self.instructions = create_default_prompt(self.processed_tools, self.instructions)
 
-        for tool in self.processed_tools:
-            safe_name = make_safe_function_name(tool.name)
-            tool_callable = tool.coroutine if hasattr(tool, "coroutine") and tool.coroutine is not None else tool.func
-            self.tools_context[safe_name] = tool_callable
-        
-        self.context = {**self.context, **self.tools_context}
-
         agent = StateGraph(CodeActState)
         agent.add_node("call_model", self.call_model)
+        agent.add_node("validate_code", self.validate_code)
         agent.add_node("sandbox", self.sandbox)
+        agent.add_node("final_answer", self.final_answer)
 
-        agent.set_entry_point("call_model")
-        agent.add_conditional_edges(
-            "call_model",
-            self.should_run_sandbox,
-            {
-                "sandbox": "sandbox",
-                END: END,
-            },
-        )
-        agent.add_edge("sandbox", "call_model")
-        return agent.compile(checkpointer=self.memory)
-
-    def should_run_sandbox(self, state: CodeActState) -> str:
-        last_message = state["messages"][-1]
-        if isinstance(last_message.content, str) and "TASK_COMPLETE" in last_message.content:
-            return END
+        agent.add_edge(START, "call_model")
 
-        if state.get("script"):
-            return "sandbox"
-        return END
+        return agent.compile(checkpointer=self.memory)
 
-    def _extract_content(self, response: AIMessageChunk) -> str:
-        if isinstance(response.content, list):
-            content = " ".join([c.get("text", "") for c in response.content])
-        else:
-            content = response.content
-        return content
-
-    async def call_model(self, state: CodeActState) -> dict:
-        model = self.model_instance
-        reflection_model = self.reflection_model
-
-        messages = [{"role": "system", "content": self.instructions}] + state["messages"]
-
-        response = await model.ainvoke(messages)
-
-        text_content = self._extract_content(response)
-        if not isinstance(text_content, str):
-            raise ValueError(f"Content is not a string: {text_content}")
-        code = extract_and_combine_codeblocks(text_content)
-        logger.debug(f"Code: {code}")
-
-        if self.max_reflections > 0 and code:
-            reflection_count = 0
-            while reflection_count < self.max_reflections:
-                conversation_history = "\n".join(
-                    [
-                        f'<message role="{("user" if m.type == "human" else "assistant")}">\n{m.content}\n</message>'
-                        for m in state["messages"]
-                    ]
+    async def call_model(self, state: CodeActState) -> Command:
+        logger.debug(f"Calling model with state: {state}")
+        model = self.model_instance.with_structured_output(StructuredCodeResponse)
+
+        # Find the last script and its output in the message history
+        previous_script = state.get("script", "")
+        sandbox_output = state.get("sandbox_output", "")
+        syntax_error = state.get("syntax_error", "")
+
+        logger.debug(f"Previous script:\n {previous_script}")
+        logger.debug(f"Sandbox output:\n {sandbox_output}")
+        logger.debug(f"Syntax error:\n {syntax_error}")
+
+        prompt_messages = [
+            {"role": "system", "content": self.instructions},
+            *state["messages"],
+        ]
+        if previous_script:
+            feedback_message = (
+                f"Here is the script you generated in the last turn:\n\n```python\n{previous_script}\n```\n\n"
+            )
+            if syntax_error:
+                feedback_message += (
+                    f"When parsing the script, it produced the following syntax error:\n\n```\n{syntax_error}\n```\n\n"
+                    "Please fix the syntax and generate a new, correct script."
                 )
-                conversation_history += f'\n<message role="assistant">\n{response.content}\n</message>'
-
-                formatted_prompt = REFLECTION_PROMPT.format(conversation_history=conversation_history)
-
-                reflection_messages = [
-                    {"role": "system", "content": self.reflection_prompt},
-                    {"role": "user", "content": formatted_prompt},
-                ]
-                reflection_result = await reflection_model.ainvoke(reflection_messages)
-
-                if "NONE" in reflection_result.content:
-                    break
-
-                retry_prompt = RETRY_PROMPT.format(reflection_result=reflection_result.content)
-
-                regeneration_messages = [
-                    {"role": "system", "content": self.instructions},
-                    *state["messages"],
-                    {"role": "assistant", "content": response.content},
-                    {"role": "user", "content": retry_prompt},
-                ]
-                response = await model.ainvoke(regeneration_messages)
-
-                code = extract_and_combine_codeblocks(response.content)
-
-                if not code:
-                    break
+            elif sandbox_output:
+                feedback_message += (
+                    f"When executed, it produced the following output:\n\n```\n{sandbox_output}\n```\n\n"
+                )
+                feedback_message += "Based on this output, decide if the task is complete. If it is, respond the final answer to the user in clean and readable Markdown format. Important: set `task_complete` to `True` and no need to provide script. If the task is not complete, generate a new script to get closer to the solution."
+
+            prompt_messages.append({"role": "user", "content": feedback_message})
+
+        response: StructuredCodeResponse = await model.ainvoke(prompt_messages)
+
+        # We add the reasoning as the AI message content
+        ai_message = AIMessage(content=response.reasoning)
+
+        if response.task_complete:
+            return Command(
+                goto="final_answer",
+                update={
+                    "messages": [ai_message],
+                    "script": response.script,
+                    "task_complete": response.task_complete,
+                    "sandbox_output": sandbox_output,
+                    "syntax_error": None,
+                },
+            )
+        else:
+            return Command(
+                goto="validate_code",
+                update={
+                    "messages": [ai_message],
+                    "script": response.script,
+                    "task_complete": response.task_complete,
+                    "sandbox_output": None,
+                    "syntax_error": None,
+                },
+            )
+
+    async def validate_code(self, state: CodeActState) -> Command:
+        logger.debug(f"Validating code with script:\n {state['script']}")
+        script = state.get("script")
+
+        if not script:
+            return Command(
+                goto="call_model",
+                update={
+                    "syntax_error": "Model did not provide a script but task is not complete. Please provide a script or set task_complete to True."
+                },
+            )
+
+        try:
+            ast.parse(script)
+            logger.debug("AST parsing successful.")
+            return Command(
+                goto="sandbox",
+                update={
+                    "syntax_error": None,
+                },
+            )
+        except SyntaxError as e:
+            logger.warning(f"AST parsing failed: {e}")
+            return Command(
+                goto="call_model",
+                update={
+                    "syntax_error": f"Syntax Error: {e}",
+                },
+            )
+
+    async def sandbox(self, state: CodeActState) -> Command:
+        logger.debug(f"Running sandbox with script:\n {state['script']}")
+        tools_context = {}
+        for tool_name, tool_callable in self.processed_tools.items():
+            tools_context[tool_name] = tool_callable
+
+        output: SandboxOutput
+        output, _ = await self.eval_fn(state["script"], tools_context, self.sandbox_timeout)
+
+        # Format the output for the agent
+        formatted_output = "Code executed.\n\n"
+        MAX_OUTPUT_LEN = 20000  # Maximum number of characters to show for stdout/stderr
+
+        def truncate_output(text, max_len=MAX_OUTPUT_LEN):
+            if text is None:
+                return ""
+            text = text.strip()
+            if len(text) > max_len:
+                return text[:max_len] + "\n... (more output hidden)"
+            return text
+
+        if output.stdout:
+            truncated_stdout = truncate_output(output.stdout)
+            formatted_output += f"STDOUT:\n```\n{truncated_stdout}\n```\n\n"
+        if output.error:
+            truncated_stderr = truncate_output(output.error)
+            formatted_output += f"STDERR / ERROR:\n```\n{truncated_stderr}\n```\n"
+        if output.return_value is not None:
+            formatted_output += f"RETURN VALUE:\n```\n{repr(output.return_value)}\n```\n"
+
+        logger.debug(f"Sandbox output: {formatted_output}")
+        return Command(
+            goto="call_model",
+            update={"sandbox_output": formatted_output.strip()},
+        )
 
-                reflection_count += 1
+    async def final_answer(self, state: CodeActState) -> Command:
+        logger.debug("Formatting final answer using LLM for markdown formatting.")
+
+        # Extract the original user prompt
+        user_prompt = ""
+        for msg in state["messages"]:
+            if isinstance(msg, HumanMessage):
+                user_prompt = msg.content
+                break
+
+        # Compose a prompt for the LLM to generate a concise, markdown-formatted answer
+        llm_prompt = (
+            "Given the following task and answer, write a concise, well-formatted markdown response suitable for a user.\n\n"
+            f"Task:\n{user_prompt}\n\n"
+            f"Answer:\n{state['sandbox_output']}\n\n"
+            "Respond only with the markdown-formatted answer."
+        )
 
-        return {"messages": [response], "script": code}
+        # Use the model to generate the final formatted answer
+        response = await self.model_instance.ainvoke([{"role": "user", "content": llm_prompt}])
+        markdown_answer = response.content if hasattr(response, "content") else str(response)
+        logger.debug(f"Final answer:\n {markdown_answer}")
 
-    async def sandbox(self, state: CodeActState) -> dict:
-        output, new_vars = await self.eval_fn(state["script"], self.context, timeout=self.sandbox_timeout)
-        self.context = {**self.context, **new_vars}
-        return {
-            "messages": [AIMessageChunk(content=output.strip())],
-            "script": None,
-        }
+        return Command(
+            goto=END,
+            update={
+                "messages": [AIMessage(content=markdown_answer)],
+            },
+        )

universal_mcp/agents/codeact/models.py

@@ -0,0 +1,11 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class SandboxOutput(BaseModel):
+    """Structured output from the code sandbox."""
+
+    stdout: str
+    error: str | None = None
+    return_value: Any | None = None