langchain-ai/langgraphjs
1
0
Fork 0
mirror of https://github.com/langchain-ai/langgraphjs.git synced 2026-07-23 01:26:57 -04:00
Code Issues 108 Packages Projects Releases 20 Wiki Activity

Support custom descriptions for handoff tools in supervisor agents #336

New Issue
Closed
opened 2026-02-15 18:15:59 -05:00 by yindo · 0 comments
yindo commented 2026-02-15 18:15:59 -05:00
Owner
Copy Link
Copy Source

Originally created by @lzj960515 on GitHub (Aug 7, 2025).

Checked other resources

  • I added a very descriptive title to this issue.
  • I searched the LangGraph.js documentation with the integrated search.
  • I used the GitHub search to find a similar question and didn't find it.
  • I am sure that this is a bug in LangGraph.js rather than my code.
  • The bug is not resolved by updating to the latest stable version of LangGraph (or the specific integration package).

Example Code

Currently, when using createSupervisor from @langchain/langgraph-supervisor, all handoff tools generated for agent transitions use the same generic description: "Ask another agent for help." This makes it difficult for the supervisor LLM to understand what each specific agent does and when to transfer control to them.

Proposed Solution

Allow passing custom descriptions for each agent when creating a supervisor, similar to how individual tools can have specific descriptions.

Current API:

  const supervisor = createSupervisor({
    agents: [agentA, agentB, agentC], // CompiledStateGraph[]
    // ... other options
  });

Proposed API:

  const supervisor = createSupervisor({
    agents: [
      { agent: agentA, description: "Handles user queries and customer support" },
      { agent: agentB, description: "Processes data analysis and generates reports" },
      { agent: agentC, description: "Manages file operations and document processing" }
    ],
    // ... other options
  });

Implementation Details

The proposed changes would involve:

  1. Update AgentConfig type to support both formats for backward compatibility:
  type AgentConfig<T> = CompiledStateGraph<...> | {
    agent: CompiledStateGraph<...>;
    description?: string;
  };
  1. Modify createHandoffTool to accept custom descriptions:
  const createHandoffTool = ({ 
    agentName, 
    description = "Ask another agent for help." 
  }: { 
    agentName: string; 
    description?: string; 
  }) => {
    // ... existing logic with custom description
  }
  1. Update supervisor creation logic to pass descriptions to handoff tools:
  const handoffTools = agents.map((agentConfig) => {
    const { agent, description } = getAgentInfo(agentConfig);
    return createHandoffTool({
      agentName: agent.name!,
      description
    });
  });

Benefits

  • Better Agent Selection: The supervisor LLM can make more informed decisions about which agent to transfer to based on meaningful descriptions
  • Improved User Experience: More accurate agent routing leads to better task completion
  • Backward Compatibility: Existing code continues to work unchanged
  • Self-Documenting: Agent purposes are clearly defined in the configuration

Use Case Example

In a customer service system with multiple specialized agents:

  const customerServiceSupervisor = createSupervisor({
    agents: [
      {
        agent: billingAgent,
        description: "Handles billing inquiries, payment issues, and subscription management"
      },
      {
        agent: techSupportAgent,
        description: "Provides technical support, troubleshooting, and product guidance"
      },
      {
        agent: salesAgent,
        description: "Manages sales inquiries, product recommendations, and upgrade consultations"
      }
    ],
    llm: model,
    prompt: "You are a customer service supervisor. Direct users to the most appropriate specialist agent based on their needs."
  });

The generated handoff tools would have meaningful descriptions that help the supervisor understand when to use each one, instead of the generic "Ask another agent for help."

Related Files

The main files that would need updates:

  • packages/langgraph-supervisor/src/supervisor.ts
  • packages/langgraph-supervisor/src/handoff.ts

Would you like me to submit a PR with this implementation?

Error Message and Stack Trace (if applicable)

No response

Description

1

System Info

1

Originally created by @lzj960515 on GitHub (Aug 7, 2025). ### Checked other resources - [x] I added a very descriptive title to this issue. - [x] I searched the LangGraph.js documentation with the integrated search. - [x] I used the GitHub search to find a similar question and didn't find it. - [x] I am sure that this is a bug in LangGraph.js rather than my code. - [x] The bug is not resolved by updating to the latest stable version of LangGraph (or the specific integration package). ### Example Code Currently, when using createSupervisor from @langchain/langgraph-supervisor, all handoff tools generated for agent transitions use the same generic description: "Ask another agent for help." This makes it difficult for the supervisor LLM to understand what each specific agent does and when to transfer control to them. Proposed Solution Allow passing custom descriptions for each agent when creating a supervisor, similar to how individual tools can have specific descriptions. Current API: ```typescript const supervisor = createSupervisor({ agents: [agentA, agentB, agentC], // CompiledStateGraph[] // ... other options }); ``` Proposed API: ```typescript const supervisor = createSupervisor({ agents: [ { agent: agentA, description: "Handles user queries and customer support" }, { agent: agentB, description: "Processes data analysis and generates reports" }, { agent: agentC, description: "Manages file operations and document processing" } ], // ... other options }); ``` Implementation Details The proposed changes would involve: 1. Update AgentConfig type to support both formats for backward compatibility: ```typescript type AgentConfig<T> = CompiledStateGraph<...> | { agent: CompiledStateGraph<...>; description?: string; }; ``` 2. Modify createHandoffTool to accept custom descriptions: ```typescript const createHandoffTool = ({ agentName, description = "Ask another agent for help." }: { agentName: string; description?: string; }) => { // ... existing logic with custom description } ``` 3. Update supervisor creation logic to pass descriptions to handoff tools: ```typescript const handoffTools = agents.map((agentConfig) => { const { agent, description } = getAgentInfo(agentConfig); return createHandoffTool({ agentName: agent.name!, description }); }); ``` Benefits - Better Agent Selection: The supervisor LLM can make more informed decisions about which agent to transfer to based on meaningful descriptions - Improved User Experience: More accurate agent routing leads to better task completion - Backward Compatibility: Existing code continues to work unchanged - Self-Documenting: Agent purposes are clearly defined in the configuration Use Case Example In a customer service system with multiple specialized agents: ```typescript const customerServiceSupervisor = createSupervisor({ agents: [ { agent: billingAgent, description: "Handles billing inquiries, payment issues, and subscription management" }, { agent: techSupportAgent, description: "Provides technical support, troubleshooting, and product guidance" }, { agent: salesAgent, description: "Manages sales inquiries, product recommendations, and upgrade consultations" } ], llm: model, prompt: "You are a customer service supervisor. Direct users to the most appropriate specialist agent based on their needs." }); ``` The generated handoff tools would have meaningful descriptions that help the supervisor understand when to use each one, instead of the generic "Ask another agent for help." Related Files The main files that would need updates: - packages/langgraph-supervisor/src/supervisor.ts - packages/langgraph-supervisor/src/handoff.ts Would you like me to submit a PR with this implementation? ### Error Message and Stack Trace (if applicable) _No response_ ### Description 1 ### System Info 1
yindo closed this issue 2026-02-15 18:15:59 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
checkpointer
docs-needed
documentation
enhancement
good first issue
good writeup
help wanted
invalid
langgraph-supervisor
open-swe-auto
platform
prebuilt
pull-request
Mirrored from GitHub Pull Request
 question
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/langgraphjs#336
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?