universal-mcp-agents 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

universal_mcp/agents/builder/prompts.py

@@ -1,173 +1,107 @@
-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.
+import json
 
----
-**EXAMPLE 4: Altering the final action of a multi-step task**
+from universal_mcp.types import ToolConfig
 
-**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."
+def _build_prompt(
+    user_task: str | None = None,
+    conversation_history: list[dict] | None = None,
+    existing_instructions: str | None = None,
+    modification_request: str | None = None,
+    tool_config: ToolConfig | None = None,
+) -> str:
+    """Dynamically builds a cohesive and effective prompt for the LLM based on the provided inputs."""
 
-**New Synthesized Task:**
-search reddit for posts on elon musk and then summarize the key points into a text file
+    core_prompt = r"""
+You are a master AI Agent Architect. Your purpose is to design and define highly effective AI agents by interpreting user requests and generating a precise agent profile in JSON format.
 
----
-# YOUR TASK
-
-Now, perform this synthesis for the following inputs.
-
-**Original Task:**
-{original_task}
-
-**Modification Request:**
-{modification_request}
-
-**New Synthesized Task:**
+Your process is systematic and thorough. You will analyze all provided information to construct a complete and coherent agent definition.
 """
 
-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
+    analysis_sections = ["\n# I. Analysis of Provided Inputs\n"]
+    analysis_sections.append("You are to analyze the following information to understand the user's requirements:\n")
+
+    if user_task:
+        analysis_sections.append(f"## Primary User Task:\n```\n{user_task}\n```\n")
+
+    if conversation_history:
+        analysis_sections.append(
+            "## Conversation History:\n"
+            "Pay special attention to the messages from the 'human' user. These are direct expressions of their needs and expectations for the agent's behavior. Include the user specific personal information like email-id or anything else which is personal in the agent's instruction.\n"
+            f"```json\n{json.dumps(conversation_history, indent=2)}\n```\n"
+        )
+
+    if existing_instructions:
+        analysis_sections.append(
+            "## Existing Agent Instructions:\n"
+            "This is the baseline definition for the current agent. Your task will be to modify this based on the user's new requests.\n"
+            f"```\n{existing_instructions}\n```\n"
+        )
+
+    if modification_request:
+        analysis_sections.append(
+            "## Modification Request:\n"
+            "The user wants to change the existing agent. You must incorporate these changes into the new agent definition.\n"
+            f"```\n{modification_request}\n```\n"
+        )
+
+    if tool_config:
+        analysis_sections.append(
+            "## Tool Configuration:\n"
+            "The agent has access to the following tools. The agent's instructions should reflect the appropriate use of these tools.\n"
+            f"```json\n{json.dumps(tool_config, indent=2)}\n```\n"
+        )
+
+    framework_prompt = r"""
+# II. Agent Definition Framework
+
+Based on your analysis, you will now define the agent's profile.
+
+## 1. Intent Synthesis
+- **Primary Goal:** In a single sentence, what is the core objective of this agent?
+- **Key Requirements & Constraints:** List any specific requirements, rules, or limitations the agent must adhere to.
+
+## 2. Agent Profile Generation
+You will now construct the complete agent profile.
+
+- **Name (2-4 words):** A concise and memorable name that reflects the agent's core function.
+- **Description (1-2 sentences):** A clear and compelling summary of the agent's purpose and value.
+- **Expertise:** A specific, well-defined area of expertise (e.g., "Python Code Generation and Debugging," not "Programming").
+- **Instructions:**
+    - This is the most critical part of your output. Write a comprehensive set of system instructions for the agent.
+    - The instructions should contain all the necessary details for the agent to call the tools , use the information from the conversation history, and fulfill the user's primary task.
+    - The instructions should be written in markdown and be direct, actionable commands.
+    - Start with the user's primary task.
+    - Clearly define the agent's role and responsibilities.
+    - Provide explicit rules for its behavior and interaction style.
+    - If tools are provided, explain how and when the agent should use them.
+    - Specify the desired output format (e.g., JSON, markdown, plain text).
+- **Schedule:**
+    - If the user specifies a schedule, provide a cron expression for when the agent should run.
+    - The output for the schedule should only be the cron expression itself (e.g., "0 9 * * *"). Do not add any explanatory text.
+"""
 
-Now, perform this analysis for the following inputs.
+    final_task_prompt = r"""
+# III. Your Task
 
-**INPUT - Conversation History:**
-{conversation_history}
+Generate a single JSON object that represents the complete agent profile. The JSON object should have the following structure:
 
-**INPUT - Used Tools:**
-{tool_config}
+{
+  "name": "...",
+  "description": "...",
+  "expertise": "...",
+  "instructions": "...",
+  "schedule": "..."
+}
 
 **YOUR JSON OUTPUT:**
 """
+
+    full_prompt = [
+        core_prompt,
+        "".join(analysis_sections),
+        framework_prompt,
+        final_task_prompt,
+    ]
+
+    return "\n".join(full_prompt)

universal_mcp/agents/codeact0/__init__.py

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

universal_mcp/agents/codeact0/agent.py

@@ -18,8 +18,9 @@ from universal_mcp.agents.codeact0.prompts import (
 )
 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.codeact0.utils import inject_context, smart_truncate
 from universal_mcp.agents.llm import load_chat_model
+from universal_mcp.agents.utils import filter_retry_on
 
 
 class CodeActAgent(BaseAgent):
@@ -63,9 +64,11 @@ class CodeActAgent(BaseAgent):
                 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)
+        additional_tools = [smart_print, data_extractor, ai_classify, call_llm]
+        additional_tools = [t if isinstance(t, StructuredTool) else create_tool(t) for t in additional_tools]
+        self.instructions, self.tools_context = create_default_prompt(
+            exported_tools, additional_tools, self.instructions
+        )
 
         def call_model(state: CodeActState) -> Command[Literal["sandbox"]]:
             messages = [{"role": "system", "content": self.instructions}] + state["messages"]
@@ -113,7 +116,12 @@ class CodeActAgent(BaseAgent):
                 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)
+
+                output, new_context, new_add_context = self.eval_fn(
+                    code, context, previous_add_context, 180
+                )  # default timeout 3 min
+                output = smart_truncate(output)
+
                 return Command(
                     goto="call_model",
                     update={

universal_mcp/agents/codeact0/langgraph_agent.py

@@ -0,0 +1,14 @@
+from universal_mcp.agentr.registry import AgentrRegistry
+
+from universal_mcp.agents.codeact0.playbook_agent import CodeActPlaybookAgent
+
+
+async def agent():
+    agent_obj = CodeActPlaybookAgent(
+        name="CodeAct Agent",
+        instructions="Be very concise in your answers.",
+        model="anthropic:claude-4-sonnet-20250514",
+        tools=[],
+        registry=AgentrRegistry(),
+    )
+    return await agent_obj._build_graph()

universal_mcp/agents/codeact0/llm_tool.py

@@ -5,7 +5,7 @@ from typing import Any, Literal, cast
 from langchain.chat_models import init_chat_model
 from langchain_openai import AzureChatOpenAI
 
-from universal_mcp.agents.codeact0.utils import get_message_text, light_copy
+from universal_mcp.agents.codeact0.utils import get_message_text
 
 MAX_RETRIES = 3
 
@@ -27,7 +27,6 @@ def smart_print(data: Any) -> None:
     Args:
         data: Either a dictionary with string keys, or a list of such dictionaries
     """
-    light_copy(data)
 
 
 def creative_writer(