orchestration

langroid/agent/tools/orchestration.py

Various tools to for agents to be able to control flow of Task, e.g. termination, routing to another agent, etc.

AgentDoneTool

Bases: ToolMessage

Tool for AGENT entity (i.e. agent_response or downstream tool handling fns) to signal the current task is done.

DoneTool

Bases: 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.

ResultTool

Bases: 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.

FinalResultTool

Bases: 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.

PassTool

Bases: 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.

response(agent, chat_doc)

When this tool is enabled for an Agent, this will result in a method added to the Agent with signature: forward_tool(self, tool: PassTool, chat_doc: ChatDocument) -> ChatDocument:

Source code in langroid/agent/tools/orchestration.py

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: 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

DonePassTool

Bases: 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.

ForwardTool

Bases: PassTool

Tool for forwarding the received msg (ChatDocument) to another agent or entity. Similar to PassTool, but with a specified recipient agent.

response(agent, chat_doc)

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:

Source code in langroid/agent/tools/orchestration.py

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

SendTool

Bases: ToolMessage

Tool for agent or LLM to send content to a specified agent. Similar to RecipientTool.

AgentSendTool

Bases: 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.