Add forward_message tool

Author: hinthornw

langgraph_supervisor/handoff.py

@@ -127,3 +127,64 @@ def create_handoff_back_messages(
             response_metadata={METADATA_KEY_IS_HANDOFF_BACK: True},
         ),
     )
+
+
+def create_forward_message_tool(supervisor_name: str = "supervisor") -> BaseTool:
+    """Create a tool the supervisor can use to forward a worker message by name.
+
+    This helps avoid information loss any time the supervisor rewrites a worker query
+    to the user and also can save some tokens.
+
+    Args:
+        supervisor_name: The name of the supervisor node (used for namespacing the tool).
+
+    Returns:
+        BaseTool: The 'forward_message' tool.
+    """
+    tool_name = "forward_message"
+    desc = (
+        "Forwards the latest message from the specified agent to the user"
+        " without any changes. Use this to preserve information fidelity, avoid"
+        " misinterpretation of questions or responses, and save time."
+    )
+
+    @tool(tool_name, description=desc)
+    def forward_message(
+        from_agent: str,
+        state: Annotated[dict, InjectedState],
+    ):
+        target_message = next(
+            (
+                (i, m)
+                for i, m in enumerate(reversed(state["messages"]))
+                if isinstance(m, AIMessage)
+                and (m.name or "").lower() == from_agent.lower()
+                and not m.response_metadata.get(METADATA_KEY_IS_HANDOFF_BACK)
+            ),
+            None,
+        )
+        if not target_message:
+            found_names = set(
+                m.name for m in state["messages"] if isinstance(m, AIMessage) and m.name
+            )
+            return (
+                f"Could not find message from source agent {from_agent}. Found names: {found_names}"
+            )
+        updates = [
+            AIMessage(
+                content=target_message[1].content,
+                name=supervisor_name,
+                id=str(uuid.uuid4()),
+            ),
+        ]
+
+        return Command(
+            graph=Command.PARENT,
+            # NOTE: this does nothing.
+            goto="__end__",
+            # we also propagate the update to make sure the handoff messages are applied
+            # to the parent graph's state
+            update={"messages": updates},
+        )
+
+    return forward_message

langgraph_supervisor/supervisor.py

@@ -17,6 +17,7 @@
 from langgraph_supervisor.agent_name import AgentNameMode, with_agent_name
 from langgraph_supervisor.handoff import (
     METADATA_KEY_HANDOFF_DESTINATION,
+    create_forward_message_tool,
     create_handoff_back_messages,
     create_handoff_tool,
 )
@@ -116,6 +117,7 @@ def create_supervisor(
     add_handoff_back_messages: bool = True,
     supervisor_name: str = "supervisor",
     include_agent_name: AgentNameMode | None = None,
+    enable_forwarding: bool = False,
 ) -> StateGraph:
     """Create a multi-agent supervisor.
 
@@ -170,6 +172,9 @@ def create_supervisor(
             - None: Relies on the LLM provider using the name attribute on the AI message. Currently, only OpenAI supports this.
             - "inline": Add the agent name directly into the content field of the AI message using XML-style tags.
                 Example: "How can I help you" -> "<name>agent_name</name><content>How can I help you?</content>"
+        enable_forwarding: Whether to add a forward_message tool to the supervisor.
+            This permits the supervisor to forward the latest message from a specific agent to the user.
+            Recommended that you set "add_handoff_back_messages" to False when using this option.
     """
     agent_names = set()
     for agent in agents:
@@ -200,6 +205,9 @@ def create_supervisor(
         handoff_destinations = [create_handoff_tool(agent_name=agent.name) for agent in agents]
         all_tools = (tools or []) + handoff_destinations
 
+    if enable_forwarding:
+        all_tools.append(create_forward_message_tool(supervisor_name))
+
     if _supports_disable_parallel_tool_calls(model):
         model = model.bind_tools(all_tools, parallel_tool_calls=parallel_tool_calls)
     else:

tests/test_supervisor.py

@@ -275,3 +275,134 @@ def web_search(query: str) -> str:
     assert result_full_history["messages"][17] == math_agent_messages[2]
     # final supervisor message
     assert result_full_history["messages"][-1] == supervisor_messages[-1]
+
+
+def test_supervisor_message_forwarding():
+    """Test that the supervisor forwards a message to a specific agent and receives the correct response."""
+
+    @tool
+    def echo_tool(text: str) -> str:
+        """Echo the input text."""
+        return text
+
+    # Agent that simply echoes the message
+    echo_model = FakeChatModel(
+        responses=[
+            AIMessage(content="Echo: test forwarding!"),
+        ]
+    )
+    echo_agent = create_react_agent(
+        model=echo_model.bind_tools([echo_tool]),
+        tools=[echo_tool],
+        name="echo_agent",
+    )
+
+    supervisor_messages = [
+        AIMessage(
+            content="",
+            tool_calls=[
+                {
+                    "name": "transfer_to_echo_agent",
+                    "args": {},
+                    "id": "call_gyQSgJQm5jJtPcF5ITe8GGGF",
+                    "type": "tool_call",
+                }
+            ],
+        ),
+        AIMessage(
+            content="",
+            tool_calls=[
+                {
+                    "name": "forward_message",
+                    "args": {"from_agent": "echo_agent"},
+                    "id": "abcd123",
+                    "type": "tool_call",
+                }
+            ],
+        ),
+    ]
+
+    workflow = create_supervisor(
+        [echo_agent],
+        model=FakeChatModel(responses=supervisor_messages),
+        enable_forwarding=True,
+    )
+    app = workflow.compile()
+
+    result = app.invoke({"messages": [HumanMessage(content="Scooby-dooby-doo")]})
+
+    def get_tool_calls(msg):
+        tool_calls = getattr(msg, "tool_calls", None)
+        if tool_calls is None:
+            return None
+        return [
+            {"name": tc["name"], "args": tc["args"]}
+            for tc in tool_calls
+            if tc["type"] == "tool_call"
+        ]
+
+    received = [
+        {
+            "name": msg.name,
+            "content": msg.content,
+            "tool_calls": get_tool_calls(msg),
+            "type": msg.type,
+        }
+        for msg in result["messages"]
+    ]
+
+    expected = [
+        {
+            "name": None,
+            "content": "Scooby-dooby-doo",
+            "tool_calls": None,
+            "type": "human",
+        },
+        {
+            "name": "supervisor",
+            "content": "",
+            "tool_calls": [
+                {
+                    "name": "transfer_to_echo_agent",
+                    "args": {},
+                }
+            ],
+            "type": "ai",
+        },
+        {
+            "name": "transfer_to_echo_agent",
+            "content": "Successfully transferred to echo_agent",
+            "tool_calls": None,
+            "type": "tool",
+        },
+        {
+            "name": "echo_agent",
+            "content": "Echo: test forwarding!",
+            "tool_calls": [],
+            "type": "ai",
+        },
+        {
+            "name": "echo_agent",
+            "content": "Transferring back to supervisor",
+            "tool_calls": [
+                {
+                    "name": "transfer_back_to_supervisor",
+                    "args": {},
+                }
+            ],
+            "type": "ai",
+        },
+        {
+            "name": "transfer_back_to_supervisor",
+            "content": "Successfully transferred back to supervisor",
+            "tool_calls": None,
+            "type": "tool",
+        },
+        {
+            "name": "supervisor",
+            "content": "Echo: test forwarding!",
+            "tool_calls": [],
+            "type": "ai",
+        },
+    ]
+    assert received == expected