langroid 0.58.2__py3-none-any.whl → 0.59.0b1__py3-none-any.whl

langroid/agent/tools/orchestration.py-e

@@ -0,0 +1,301 @@
+"""
+Various tools to for agents to be able to control flow of Task, e.g.
+termination, routing to another agent, etc.
+"""
+
+from typing import Any, List, Tuple
+
+from langroid.agent.chat_agent import ChatAgent
+from langroid.agent.chat_document import ChatDocument
+from langroid.agent.tool_message import ToolMessage
+from langroid.mytypes import Entity
+from pydantic import ConfigDict
+from langroid.utils.types import to_string
+
+
+class AgentDoneTool(ToolMessage):
+    """Tool for AGENT entity (i.e. agent_response or downstream tool handling fns) to
+    signal the current task is done."""
+
+    purpose: str = """
+    To signal the current task is done, along with an optional message <content>
+    of arbitrary type (default None) and an 
+    optional list of <tools> (default empty list).
+    """
+    request: str = "agent_done_tool"
+    content: Any = None
+    tools: List[ToolMessage] = []
+    # only meant for agent_response or tool-handlers, not for LLM generation:
+    _allow_llm_use: bool = False
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        content_str = "" if self.content is None else to_string(self.content)
+        return agent.create_agent_response(
+            content=content_str,
+            content_any=self.content,
+            tool_messages=[self] + self.tools,
+        )
+
+
+class DoneTool(ToolMessage):
+    """Tool for Agent Entity (i.e. agent_response) or LLM entity (i.e. llm_response) to
+    signal the current task is done, with some content as the result."""
+
+    purpose: str = """
+    To signal the current task is done, along with an optional message <content>
+    of arbitrary type (default None).
+    """
+    request: str = "done_tool"
+    content: str = ""
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        return agent.create_agent_response(
+            content=self.content,
+            content_any=self.content,
+            tool_messages=[self],
+        )
+
+    @classmethod
+    def instructions(cls) -> str:
+        tool_name = cls.default_value("request")
+        return f"""
+        When you determine your task is finished, 
+        use the tool `{tool_name}` to signal this,
+        along with any message or result, in the `content` field. 
+        """
+
+
+class ResultTool(ToolMessage):
+    """Class to use as a wrapper for sending arbitrary results from an Agent's
+    agent_response or tool handlers, to:
+    (a) trigger completion of the current task (similar to (Agent)DoneTool), and
+    (b) be returned as the result of the current task, i.e. this tool would appear
+         in the resulting ChatDocument's `tool_messages` list.
+    See test_tool_handlers_and_results in test_tool_messages.py, and
+    examples/basic/tool-extract-short-example.py.
+
+    Note:
+        - when defining a tool handler or agent_response, you can directly return
+            ResultTool(field1 = val1, ...),
+            where the values can be arbitrary data structures, including nested
+            Pydantic objs, or you can define a subclass of ResultTool with the
+            fields you want to return.
+        - This is a special ToolMessage that is NOT meant to be used or handled
+            by an agent.
+        - AgentDoneTool is more restrictive in that you can only send a `content`
+            or `tools` in the result.
+    """
+
+    request: str = "result_tool"
+    purpose: str = "Ignored; Wrapper for a structured message"
+    id: str = ""  # placeholder for OpenAI-API tool_call_id
+
+    model_config = ConfigDict(
+        extra="allow",
+        arbitrary_types_allowed=False,
+        validate_default=True,
+        validate_assignment=True,
+        json_schema_extra={"exclude": {"purpose", "id", "strict"}},
+    )
+
+    def handle(self) -> AgentDoneTool:
+        return AgentDoneTool(tools=[self])
+
+
+class FinalResultTool(ToolMessage):
+    """Class to use as a wrapper for sending arbitrary results from an Agent's
+    agent_response or tool handlers, to:
+    (a) trigger completion of the current task as well as all parent tasks, and
+    (b) be returned as the final result of the root task, i.e. this tool would appear
+         in the final ChatDocument's `tool_messages` list.
+    See test_tool_handlers_and_results in test_tool_messages.py, and
+    examples/basic/chat-tool-function.py.
+
+    Note:
+        - when defining a tool handler or agent_response, you can directly return
+            FinalResultTool(field1 = val1, ...),
+            where the values can be arbitrary data structures, including nested
+            Pydantic objs, or you can define a subclass of FinalResultTool with the
+            fields you want to return.
+        - This is a special ToolMessage that is NOT meant to be used by an agent's
+            llm_response, but only by agent_response or tool handlers.
+        - A subclass of this tool can be defined, with specific fields, and
+          with _allow_llm_use = True, to allow the LLM to generate this tool,
+          and have the effect of terminating the current and all parent tasks,
+          with the tool appearing in the final ChatDocument's `tool_messages` list.
+          See examples/basic/multi-agent-return-result.py.
+    """
+
+    request: str = ""
+    purpose: str = "Ignored; Wrapper for a structured message"
+    id: str = ""  # placeholder for OpenAI-API tool_call_id
+    _allow_llm_use: bool = False
+
+    model_config = ConfigDict(
+        extra="allow",
+        arbitrary_types_allowed=False,
+        validate_default=True,
+        validate_assignment=True,
+        json_schema_extra={"exclude": {"purpose", "id", "strict"}},
+    )
+
+
+class PassTool(ToolMessage):
+    """Tool for "passing" on the received msg (ChatDocument),
+    so that an as-yet-unspecified agent can handle it.
+    Similar to ForwardTool, but without specifying the recipient agent.
+    """
+
+    purpose: str = """
+    To pass the current message so that other agents can handle it.
+    """
+    request: str = "pass_tool"
+
+    def response(self, agent: ChatAgent, chat_doc: ChatDocument) -> ChatDocument:
+        """When this tool is enabled for an Agent, this will result in a method
+        added to the Agent with signature:
+        `pass_tool(self, tool: PassTool, chat_doc: ChatDocument) -> ChatDocument:`
+        """
+        # if PassTool is in chat_doc, pass its parent, else pass chat_doc itself
+        doc = chat_doc
+        while True:
+            tools = agent.get_tool_messages(doc)
+            if not any(isinstance(t, type(self)) for t in tools):
+                break
+            if doc.parent is None:
+                break
+            doc = doc.parent
+        assert doc is not None, "PassTool: parent of chat_doc must not be None"
+        new_doc = ChatDocument.deepcopy(doc)
+        new_doc.metadata.sender = Entity.AGENT
+        return new_doc
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        Use the `pass_tool` to PASS the current message 
+        so that another agent can handle it.
+        """
+
+
+class DonePassTool(PassTool):
+    """Tool to signal DONE, AND Pass incoming/current msg as result.
+    Similar to PassTool, except we append a DoneTool to the result tool_messages.
+    """
+
+    purpose: str = """
+    To signal the current task is done, with results set to the current/incoming msg.
+    """
+    request: str = "done_pass_tool"
+
+    def response(self, agent: ChatAgent, chat_doc: ChatDocument) -> ChatDocument:
+        # use PassTool to get the right ChatDocument to pass...
+        new_doc = PassTool.response(self, agent, chat_doc)
+        tools = agent.get_tool_messages(new_doc)
+        # ...then return an AgentDoneTool with content, tools from this ChatDocument
+        return AgentDoneTool(content=new_doc.content, tools=tools)  # type: ignore
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        When you determine your task is finished,
+        and want to pass the current message as the result of the task,  
+        use the `done_pass_tool` to signal this.
+        """
+
+
+class ForwardTool(PassTool):
+    """Tool for forwarding the received msg (ChatDocument) to another agent or entity.
+    Similar to PassTool, but with a specified recipient agent.
+    """
+
+    purpose: str = """
+    To forward the current message to an <agent>, where <agent> 
+    could be the name of an agent, or an entity such as "user", "llm".
+    """
+    request: str = "forward_tool"
+    agent: str
+
+    def response(self, agent: ChatAgent, chat_doc: ChatDocument) -> ChatDocument:
+        """When this tool is enabled for an Agent, this will result in a method
+        added to the Agent with signature:
+        `forward_tool(self, tool: ForwardTool, chat_doc: ChatDocument) -> ChatDocument:`
+        """
+        # if chat_doc contains ForwardTool, then we forward its parent ChatDocument;
+        # else forward chat_doc itself
+        new_doc = PassTool.response(self, agent, chat_doc)
+        new_doc.metadata.recipient = self.agent
+        return new_doc
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        If you need to forward the current message to another agent, 
+        use the `forward_tool` to do so, 
+        setting the `recipient` field to the name of the recipient agent.
+        """
+
+
+class SendTool(ToolMessage):
+    """Tool for agent or LLM to send content to a specified agent.
+    Similar to RecipientTool.
+    """
+
+    purpose: str = """
+    To send message <content> to agent specified in <to> field.
+    """
+    request: str = "send_tool"
+    to: str
+    content: str = ""
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        return agent.create_agent_response(
+            self.content,
+            recipient=self.to,
+        )
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        If you need to send a message to another agent, 
+        use the `send_tool` to do so, with these field values:
+        - `to` field = name of the recipient agent,
+        - `content` field = the message to send.
+        """
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
+        return [
+            cls(to="agent1", content="Hello, agent1!"),
+            (
+                """
+                I need to send the content 'Who built the Gemini model?', 
+                to the 'Searcher' agent.
+                """,
+                cls(to="Searcher", content="Who built the Gemini model?"),
+            ),
+        ]
+
+
+class AgentSendTool(ToolMessage):
+    """Tool for Agent (i.e. agent_response) to send content or tool_messages
+    to a specified agent. Similar to SendTool except that AgentSendTool is only
+    usable by agent_response (or handler of another tool), to send content or
+    tools to another agent. SendTool does not allow sending tools.
+    """
+
+    purpose: str = """
+    To send message <content> and <tools> to agent specified in <to> field. 
+    """
+    request: str = "agent_send_tool"
+    to: str
+    content: str = ""
+    tools: List[ToolMessage] = []
+    _allow_llm_use: bool = False
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        return agent.create_agent_response(
+            self.content,
+            tool_messages=self.tools,
+            recipient=self.to,
+        )

langroid/agent/tools/recipient_tool.py

@@ -17,7 +17,7 @@ especially with weaker LLMs.
 
 """
 
-from typing import List, Type
+from typing import ClassVar, List, Type
 
 from rich import print
 
@@ -106,8 +106,8 @@ class RecipientTool(ToolMessage):
         only allows certain recipients, and possibly sets a default recipient."""
 
         class RecipientToolRestricted(cls):  # type: ignore
-            allowed_recipients = recipients
-            default_recipient = default
+            allowed_recipients: ClassVar[List[str]] = recipients
+            default_recipient: ClassVar[str] = default
 
         return RecipientToolRestricted
 

langroid/agent/tools/task_tool.py

@@ -6,13 +6,15 @@ TaskTool: A tool that allows agents to delegate a task to a sub-agent with
 import uuid
 from typing import List, Optional
 
+from pydantic import Field
+from pydantic.fields import ModelPrivateAttr
+
 import langroid.language_models as lm
 from langroid import ChatDocument
 from langroid.agent.chat_agent import ChatAgent, ChatAgentConfig
 from langroid.agent.task import Task
 from langroid.agent.tool_message import ToolMessage
 from langroid.agent.tools.orchestration import DoneTool
-from langroid.pydantic_v1 import Field
 
 
 class TaskTool(ToolMessage):
@@ -83,7 +85,7 @@ class TaskTool(ToolMessage):
         """,
     )
     # TODO: ensure valid model name
-    model: str = Field(
+    model: Optional[str] = Field(
         default=None,
         description="""
             Optional name of the LLM model to use for the sub-agent, e.g. 'gpt-4.1'
@@ -148,25 +150,29 @@ class TaskTool(ToolMessage):
         if self.tools == ["ALL"]:
             # Enable all tools from the parent agent:
             # This is the list of all tools KNOWN (whether usable or handle-able or not)
-            tool_classes = [
-                agent.llm_tools_map[t]
-                for t in agent.llm_tools_known
-                if t in agent.llm_tools_map
-                and t != self.request
-                and agent.llm_tools_map[t]._allow_llm_use
-                # Exclude the TaskTool itself!
-            ]
+            tool_classes = []
+            for t in agent.llm_tools_known:
+                if t in agent.llm_tools_map and t != self.request:
+                    tool_class = agent.llm_tools_map[t]
+                    allow_llm_use = tool_class._allow_llm_use
+                    if isinstance(allow_llm_use, ModelPrivateAttr):
+                        allow_llm_use = allow_llm_use.default
+                    if allow_llm_use:
+                        tool_classes.append(tool_class)
         elif self.tools == ["NONE"]:
             # No tools enabled
             tool_classes = []
         else:
             # Enable only specified tools
-            tool_classes = [
-                agent.llm_tools_map[tool_name]
-                for tool_name in self.tools
-                if tool_name in agent.llm_tools_map
-                and agent.llm_tools_map[tool_name]._allow_llm_use
-            ]
+            tool_classes = []
+            for tool_name in self.tools:
+                if tool_name in agent.llm_tools_map:
+                    tool_class = agent.llm_tools_map[tool_name]
+                    allow_llm_use = tool_class._allow_llm_use
+                    if isinstance(allow_llm_use, ModelPrivateAttr):
+                        allow_llm_use = allow_llm_use.default
+                    if allow_llm_use:
+                        tool_classes.append(tool_class)
 
         # always enable the DoneTool to signal task completion
         sub_agent.enable_message(tool_classes + [DoneTool], use=True, handle=True)

langroid/agent/tools/task_tool.py-e

@@ -0,0 +1,249 @@
+"""
+TaskTool: A tool that allows agents to delegate a task to a sub-agent with
+    specific tools enabled.
+"""
+
+import uuid
+from typing import List, Optional
+
+import langroid.language_models as lm
+from langroid import ChatDocument
+from langroid.agent.chat_agent import ChatAgent, ChatAgentConfig
+from langroid.agent.task import Task
+from langroid.agent.tool_message import ToolMessage
+from langroid.agent.tools.orchestration import DoneTool
+from pydantic import Field
+
+
+class TaskTool(ToolMessage):
+    """
+    Tool that spawns a sub-agent with specified tools to handle a task.
+
+    The sub-agent can be given a custom name for identification in logs.
+    If no name is provided, a random unique name starting with 'agent'
+    will be generated.
+    """
+
+    # TODO: setting up termination conditions of sub-task needs to be improved
+    request: str = "task_tool"
+    purpose: str = """
+        <HowToUse>
+        Use this tool to delegate a task to a sub-agent with specific tools enabled.
+        The sub-agent will be created with the specified tools and will run the task
+        non-interactively.
+    """
+
+    # Parameters for the agent tool
+
+    system_message: Optional[str] = Field(
+        ...,
+        description="""
+        Optional system message to configure the sub-agent's general behavior and 
+        to specify the task and its context.
+            A good system message will have these components:
+            - Inform the sub-agent of its role, e.g. "You are a financial analyst."
+            - Clear spec of the task, with sufficient context for the sub-agent to 
+              understand what it needs to do, since the sub-agent does 
+              NOT have access to your conversation history!
+            - Any additional general context needed for the task, such as a
+              (part of a) document, or data items, etc.
+            - Specify when to use certain tools, e.g. 
+                "You MUST use the 'stock_data' tool to extract stock information.
+        """,
+    )
+
+    prompt: str = Field(
+        ...,
+        description="""
+            The prompt to run the sub-agent with. This differs from the agent's
+            system message: Whereas the system message configures the sub-agent's
+            GENERAL role and goals, the `prompt` is the SPECIFIC input that the 
+            sub-agent will process. In LLM terms, the system message is sent to the 
+            LLM as the first message, with role = "system" or "developer", and 
+            the prompt is sent as a message with role = "user".
+            EXAMPLE: system_message = "You are a financial analyst, when the 
+                user asks about the share-price of a company, 
+                you must use your tools to do the research, and 
+                return the final answer to the user."
+            
+            prompt = "What is the share-price of Apple Inc.?"
+            """,
+    )
+
+    tools: List[str] = Field(
+        ...,
+        description="""
+        A list of tool names to enable for the sub-agent.
+        This must be a list of strings referring to the names of tools
+        that are known to you. 
+        If you want to enable all tools, or you do not have any preference
+        on what tools are enabled for the sub-agent, you can set 
+        this field to a singleton list ['ALL']
+        To disable all tools, set it to a singleton list ['NONE']
+        """,
+    )
+    # TODO: ensure valid model name
+    model: str = Field(
+        default=None,
+        description="""
+            Optional name of the LLM model to use for the sub-agent, e.g. 'gpt-4.1'
+            If omitted, the sub-agent will use the same model as yours.
+            """,
+    )
+    max_iterations: Optional[int] = Field(
+        default=None,
+        description="Optional max iterations for the sub-agent to run the task",
+    )
+    agent_name: Optional[str] = Field(
+        default=None,
+        description="""
+            Optional name for the sub-agent. This will be used as the agent's name
+            in logs and for identification purposes. If not provided, a random unique
+            name starting with 'agent' will be generated.
+            """,
+    )
+
+    def _set_up_task(self, agent: ChatAgent) -> Task:
+        """
+        Helper method to set up a task for the sub-agent.
+
+        Args:
+            agent: The parent ChatAgent that is handling this tool
+        """
+        # Generate a random name if not provided
+        agent_name = self.agent_name or f"agent-{str(uuid.uuid4())[:8]}"
+
+        # Create chat agent config with system message if provided
+        # TODO: Maybe we just copy the parent agent's config and override chat_model?
+        #   -- but what if parent agent has a MockLMConfig?
+        llm_config = lm.OpenAIGPTConfig(
+            chat_model=self.model or lm.OpenAIChatModel.GPT4_1_MINI,
+        )
+        config = ChatAgentConfig(
+            name=agent_name,
+            llm=llm_config,
+            handle_llm_no_tool=f"""
+                You forgot to use one of your TOOLs! Remember that you must either:
+                - use a tool, or a sequence of tools, to complete your task, OR
+                - if you are done with your task, use the `{DoneTool.name()}` tool
+                to return the result.
+                
+                As a reminder, this was your task:
+                {self.prompt}
+                """,
+            system_message=f"""
+                {self.system_message}
+                
+                When you are finished with your task, you MUST
+                use the TOOL `{DoneTool.name()}` to end the task
+                and return the result.                
+            """,
+        )
+
+        # Create the sub-agent
+        sub_agent = ChatAgent(config)
+
+        # Enable the specified tools for the sub-agent
+        # Convert tool names to actual tool classes using parent agent's tools_map
+        if self.tools == ["ALL"]:
+            # Enable all tools from the parent agent:
+            # This is the list of all tools KNOWN (whether usable or handle-able or not)
+            tool_classes = [
+                agent.llm_tools_map[t]
+                for t in agent.llm_tools_known
+                if t in agent.llm_tools_map
+                and t != self.request
+                and agent.llm_tools_map[t]._allow_llm_use
+                # Exclude the TaskTool itself!
+            ]
+        elif self.tools == ["NONE"]:
+            # No tools enabled
+            tool_classes = []
+        else:
+            # Enable only specified tools
+            tool_classes = [
+                agent.llm_tools_map[tool_name]
+                for tool_name in self.tools
+                if tool_name in agent.llm_tools_map
+                and agent.llm_tools_map[tool_name]._allow_llm_use
+            ]
+
+        # always enable the DoneTool to signal task completion
+        sub_agent.enable_message(tool_classes + [DoneTool], use=True, handle=True)
+
+        # Create a non-interactive task
+        task = Task(sub_agent, interactive=False)
+
+        return task
+
+    def handle(
+        self, agent: ChatAgent, chat_doc: Optional[ChatDocument] = None
+    ) -> Optional[ChatDocument]:
+        """
+
+        Handle the TaskTool by creating a sub-agent with specified tools
+        and running the task non-interactively.
+
+        Args:
+            agent: The parent ChatAgent that is handling this tool
+            chat_doc: The ChatDocument containing this tool message
+        """
+
+        task = self._set_up_task(agent)
+
+        # Create a ChatDocument for the prompt with parent pointer
+        prompt_doc = None
+        if chat_doc is not None:
+            from langroid.agent.chat_document import ChatDocMetaData
+
+            prompt_doc = ChatDocument(
+                content=self.prompt,
+                metadata=ChatDocMetaData(
+                    parent_id=chat_doc.id(),
+                    agent_id=agent.id,
+                    sender=chat_doc.metadata.sender,
+                ),
+            )
+            # Set bidirectional parent-child relationship
+            chat_doc.metadata.child_id = prompt_doc.id()
+
+        # Run the task with the ChatDocument or string prompt
+        result = task.run(prompt_doc or self.prompt, turns=self.max_iterations or 10)
+        return result
+
+    async def handle_async(
+        self, agent: ChatAgent, chat_doc: Optional[ChatDocument] = None
+    ) -> Optional[ChatDocument]:
+        """
+        Async method to handle the TaskTool by creating a sub-agent with specified tools
+        and running the task non-interactively.
+
+        Args:
+            agent: The parent ChatAgent that is handling this tool
+            chat_doc: The ChatDocument containing this tool message
+        """
+        task = self._set_up_task(agent)
+
+        # Create a ChatDocument for the prompt with parent pointer
+        prompt_doc = None
+        if chat_doc is not None:
+            from langroid.agent.chat_document import ChatDocMetaData
+
+            prompt_doc = ChatDocument(
+                content=self.prompt,
+                metadata=ChatDocMetaData(
+                    parent_id=chat_doc.id(),
+                    agent_id=agent.id,
+                    sender=chat_doc.metadata.sender,
+                ),
+            )
+            # Set bidirectional parent-child relationship
+            chat_doc.metadata.child_id = prompt_doc.id()
+
+        # Run the task with the ChatDocument or string prompt
+        # TODO eventually allow the various task setup configs,
+        #  including termination conditions
+        result = await task.run_async(
+            prompt_doc or self.prompt, turns=self.max_iterations or 10
+        )
+        return result