@langgraph-js/sdk/dist/server/swarm/handoff.js

The UI SDK for LangGraph - seamlessly integrate your AI agents with frontend interfaces

import { z } from "zod";
import { ToolMessage } from "@langchain/core/messages";
import { tool } from "@langchain/core/tools";
import { Command, getCurrentTaskInput, } from "@langchain/langgraph";
const WHITESPACE_RE = /\s+/g;
const METADATA_KEY_HANDOFF_DESTINATION = "__handoff_destination";
function _normalizeAgentName(agentName) {
    /**
     * Normalize an agent name to be used inside the tool name.
     */
    return agentName.trim().replace(WHITESPACE_RE, "_").toLowerCase();
}
// type guard
function isDynamicTool(tool) {
    return "schema" in tool && "name" in tool && "description" in tool && "responseFormat" in tool;
}
const createHandoffTool = ({ agentName, description, updateState }) => {
    /**
     * Create a tool that can handoff control to the requested agent.
     *
     * @param agentName - The name of the agent to handoff control to, i.e.
     *   the name of the agent node in the multi-agent graph.
     *   Agent names should be simple, clear and unique, preferably in snake_case,
     *   although you are only limited to the names accepted by LangGraph
     *   nodes as well as the tool names accepted by LLM providers
     *   (the tool name will look like this: `transfer_to_<agent_name>`).
     * @param description - Optional description for the handoff tool.
     * @param updateState - Optional function to customize state updates during handoff.
     */
    const toolName = `transfer_to_${_normalizeAgentName(agentName)}`;
    const toolDescription = description || `Ask agent '${agentName}' for help`;
    const handoffTool = tool(async (_, config) => {
        /**
         * Ask another agent for help.
         */
        const toolMessage = new ToolMessage({
            content: `Successfully transferred to ${agentName}`,
            name: toolName,
            tool_call_id: config.toolCall.id,
        });
        // inject the current agent state
        const state = getCurrentTaskInput();
        // Base update object containing essential state updates
        const baseUpdate = {
            messages: state.messages.concat(toolMessage),
            activeAgent: agentName,
        };
        // Merge custom updates with base updates if updateState function is provided
        const finalUpdate = updateState ? { ...baseUpdate, ...updateState(state) } : baseUpdate;
        return new Command({
            goto: agentName,
            graph: Command.PARENT,
            update: finalUpdate,
        });
    }, {
        name: toolName,
        schema: z.object({}),
        description: toolDescription,
    });
    handoffTool.metadata = { [METADATA_KEY_HANDOFF_DESTINATION]: agentName };
    return handoffTool;
};
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const getHandoffDestinations = (agent, toolNodeName = "tools") => {
    /**
     * Get a list of destinations from agent's handoff tools.
     *
     * @param agent - The compiled state graph
     * @param toolNodeName - The name of the tool node in the graph
     */
    const { nodes } = agent.getGraph();
    if (!(toolNodeName in nodes)) {
        return [];
    }
    const toolNode = nodes[toolNodeName].data;
    if (!toolNode || !("tools" in toolNode) || !toolNode.tools) {
        return [];
    }
    const { tools } = toolNode;
    return tools
        .filter((tool) => isDynamicTool(tool) && tool.metadata !== undefined && METADATA_KEY_HANDOFF_DESTINATION in tool.metadata)
        .map((tool) => tool.metadata[METADATA_KEY_HANDOFF_DESTINATION]);
};
export { createHandoffTool, getHandoffDestinations, METADATA_KEY_HANDOFF_DESTINATION };