LangGraph 的 createSupervisor 解析

[Pines-Cheng]

这是 LangGraph 中 createSupervisor 函数的 TypeScript 类型定义，用于创建多智能体监督者。让我详细解释一下各个参数：

核心参数

1. agents - 智能体列表

agents: Agent[]  // 要管理的智能体列表

2. llm - 语言模型

llm: LanguageModel  // 监督者使用的语言模型

3. tools - 工具集

tools: Tool[]  // 监督者可用的工具

可选参数

4. prompt - 提示词配置

prompt?: string | SystemMessage | Function | Runnable

• string: 转换为 SystemMessage 添加到消息开头
• SystemMessage: 直接添加到消息开头
• Function: 接收完整图状态，输出传给语言模型
• Runnable: 接收完整图状态，输出传给语言模型

5. responseFormat - 响应格式

responseFormat?: ZodSchema | JSONSchema | { prompt: string, schema: ZodSchema | JSONSchema }

• 用于结构化输出
• 支持 Zod schema 或 JSON schema
• 要求模型支持 .withStructuredOutput()

6. outputMode - 输出模式

outputMode?: 'full_history' | 'last_message'  // 默认: 'last_message'

• full_history: 添加完整的智能体消息历史
• last_message: 只添加最后一条消息

7. addHandoffBackMessages - 移交消息

addHandoffBackMessages?: boolean

是否在移交控制权时添加 (AIMessage, ToolMessage) 对

8. includeAgentName - 智能体名称显示

includeAgentName?: undefined | 'inline'

• undefined: 依赖 LLM 提供商的 name 属性（目前只有 OpenAI 支持）
• 'inline': 直接将智能体名称添加到消息内容中

  <name>agent_name</name><content>How can I help you?</content>

使用示例

import { createSupervisor } from '@langchain/langgraph';
import { ChatOpenAI } from '@langchain/openai';

const supervisor = createSupervisor({
  agents: [researchAgent, writerAgent, reviewerAgent],
  llm: new ChatOpenAI({ model: "gpt-4" }),
  tools: [webSearchTool, calculatorTool],
  prompt: "You are a supervisor managing a team of AI agents...",
  outputMode: 'last_message',
  addHandoffBackMessages: true,
  supervisorName: 'MainSupervisor',
  includeAgentName: 'inline'
});

返回值

返回一个 StateGraph 实例，可以用来构建和运行多智能体工作流。

重要注意事项

1. 结构化输出: responseFormat 需要模型支持 .withStructuredOutput()
2. 额外调用: 图会在智能体循环结束后单独调用 LLM 生成结构化响应
3. 状态管理: 使用 MessagesAnnotation 作为默认状态模式

这个函数是构建复杂多智能体系统的核心工具，允许你创建一个协调多个专门智能体工作的监督者。

[Pines-Cheng]

这两种类型的 prompt 配置适用于不同的场景，主要区别在于复杂度和可复用性：

Function 类型场景

1. 简单的动态提示生成

const dynamicPrompt = (state: GraphState) => {
  const messageCount = state.messages.length;
  const lastAgent = state.messages[state.messages.length - 1]?.name;
  
  return `You are supervising ${state.agents.length} agents. 
  Current conversation has ${messageCount} messages.
  Last active agent: ${lastAgent || 'none'}`;
};

const supervisor = createSupervisor({
  agents: [agent1, agent2],
  llm: model,
  prompt: dynamicPrompt,  // Function
  // ...
});

2. 基于状态的条件提示

const conditionalPrompt = (state: GraphState) => {
  if (state.taskType === 'research') {
    return "Focus on thorough research and fact-checking.";
  } else if (state.taskType === 'creative') {
    return "Encourage creative thinking and innovation.";
  }
  return "Maintain balanced oversight of all agents.";
};

3. 简单的上下文注入

const contextPrompt = (state: GraphState) => {
  const userPreferences = state.context?.userPreferences || {};
  return `User preferences: ${JSON.stringify(userPreferences)}. 
  Supervise agents accordingly.`;
};

Runnable 类型场景

1. 复杂的提示处理管道

import { RunnableSequence, RunnableLambda } from "@langchain/core/runnables";

const complexPromptPipeline = RunnableSequence.from([
  // 第一步：提取关键信息
  RunnableLambda.from((state: GraphState) => ({
    messages: state.messages,
    agentStatus: state.agentStatus,
    taskProgress: state.taskProgress
  })),
  
  // 第二步：分析对话模式
  RunnableLambda.from((data) => {
    const patterns = analyzeConversationPatterns(data.messages);
    return { ...data, patterns };
  }),
  
  // 第三步：生成个性化提示
  RunnableLambda.from((data) => {
    return generatePersonalizedPrompt(data);
  })
]);

const supervisor = createSupervisor({
  agents: [agent1, agent2],
  llm: model,
  prompt: complexPromptPipeline,  // Runnable
  // ...
});

2. 与外部服务集成

const externalPromptGenerator = RunnableSequence.from([
  // 调用外部 API 获取上下文
  RunnableLambda.from(async (state: GraphState) => {
    const context = await fetchExternalContext(state.userId);
    return { state, context };
  }),
  
  // 基于外部数据生成提示
  RunnableLambda.from(({ state, context }) => {
    return `Based on user history: ${context.summary}
    Current task: ${state.currentTask}
    Supervise agents with this context in mind.`;
  })
]);

3. 可复用的提示模板系统

// 可复用的提示构建器
const createPromptBuilder = (templateType: string) => {
  return RunnableSequence.from([
    RunnableLambda.from((state: GraphState) => ({
      template: templateType,
      state
    })),
    
    // 从模板库加载
    RunnableLambda.from(async ({ template, state }) => {
      const promptTemplate = await loadPromptTemplate(template);
      return promptTemplate.format(state);
    })
  ]);
};

// 在不同场景中复用
const researchSupervisor = createSupervisor({
  prompt: createPromptBuilder('research'),
  // ...
});

const creativeSupervisor = createSupervisor({
  prompt: createPromptBuilder('creative'),
  // ...
});

4. 多步骤提示优化

const optimizedPromptGenerator = RunnableSequence.from([
  // 分析当前状态
  RunnableLambda.from((state: GraphState) => {
    return {
      state,
      analysis: analyzeAgentPerformance(state)
    };
  }),
  
  // 生成基础提示
  RunnableLambda.from(({ state, analysis }) => {
    const basePrompt = generateBasePrompt(state);
    return { basePrompt, analysis, state };
  }),
  
  // 基于性能分析优化提示
  RunnableLambda.from(({ basePrompt, analysis, state }) => {
    return optimizePromptBasedOnPerformance(basePrompt, analysis);
  })
]);

选择建议

场景	推荐类型	原因
简单动态文本生成	Function	代码简洁，易于理解
复杂数据处理	Runnable	更好的可组合性和可测试性
需要异步操作	Runnable	天然支持异步处理
可复用逻辑	Runnable	更好的模块化和复用性
调试和监控	Runnable	更好的可观测性
快速原型	Function	开发速度快

总结：Function 适合简单场景，Runnable 适合复杂、可复用的场景。

SystemMessage 类型是最基础和常用的提示词配置方式，适用于静态、固定的监督者指令场景。

SystemMessage 使用场景

1. 固定的监督者角色定义

import { SystemMessage } from "@langchain/core/messages";

const supervisorPrompt = new SystemMessage(`
You are a project management supervisor overseeing a team of AI agents.

Your responsibilities:
- Coordinate tasks between research, writing, and review agents
- Ensure quality standards are met
- Make decisions about task delegation
- Provide final approval for deliverables

Always maintain professional communication and clear direction.
`);

const supervisor = createSupervisor({
  agents: [researchAgent, writerAgent, reviewAgent],
  llm: model,
  prompt: supervisorPrompt,  // SystemMessage
  // ...
});

2. 标准化的工作流程指令

const workflowPrompt = new SystemMessage(`
WORKFLOW SUPERVISION PROTOCOL:

1. TASK ANALYSIS: First understand the user's request
2. AGENT SELECTION: Choose the most appropriate agent
3. QUALITY CHECK: Review agent outputs before proceeding
4. HANDOFF DECISION: Determine if task needs another agent
5. FINAL REVIEW: Ensure all requirements are met

Use the following agents:
- ResearchAgent: For information gathering and fact-checking
- WriterAgent: For content creation and editing
- ReviewAgent: For quality assurance and final review
`);

3. 领域专业的监督指令

// 医疗领域监督者
const medicalSupervisor = new SystemMessage(`
You are a medical AI supervisor managing clinical decision support agents.

CRITICAL REQUIREMENTS:
- Always prioritize patient safety
- Ensure all recommendations are evidence-based
- Flag any potential drug interactions or contraindications
- Maintain strict HIPAA compliance
- Never provide definitive diagnoses - only support clinical decision-making

Available specialist agents:
- DiagnosticAgent: Symptom analysis and differential diagnosis
- PharmacologyAgent: Drug interactions and dosing
- ProtocolAgent: Treatment guidelines and protocols
`);

// 金融领域监督者
const financialSupervisor = new SystemMessage(`
You are a financial analysis supervisor managing investment research agents.

COMPLIANCE REQUIREMENTS:
- Ensure all analysis follows regulatory guidelines
- Verify data sources and methodology
- Flag potential conflicts of interest
- Maintain audit trail for all recommendations
- Never provide personal financial advice

Agent specializations:
- MarketAgent: Market analysis and trends
- RiskAgent: Risk assessment and modeling
- ComplianceAgent: Regulatory compliance checking
`);

4. 多语言支持的固定指令

const multilingualPrompt = new SystemMessage(`
You are a multilingual customer service supervisor.

LANGUAGE HANDLING:
- Detect user's preferred language automatically
- Route to appropriate language-specific agents
- Ensure cultural sensitivity in all interactions
- Maintain consistent service quality across languages

Available language agents:
- EnglishAgent: English customer service
- SpanishAgent: Spanish customer service  
- MandarinAgent: Mandarin customer service

Always respond in the user's preferred language.
`);

与其他类型的对比

SystemMessage vs String

// String (会被自动转换为 SystemMessage)
prompt: "You are a supervisor managing AI agents."

// SystemMessage (显式创建)
prompt: new SystemMessage("You are a supervisor managing AI agents.")

两者功能相同，但 SystemMessage 更明确表达意图。

SystemMessage vs Function vs Runnable

特性	SystemMessage	Function	Runnable
复杂度	最简单	中等	最复杂
动态性	静态	动态	动态
可复用性	高	中	最高
性能	最快	快	中等
调试难度	最低	中等	较高

实际使用示例

1. 电商客服监督者

const ecommerceSupport = new SystemMessage(`
You are an e-commerce customer support supervisor.

PRIORITY ORDER:
1. Order issues (highest priority)
2. Product inquiries
3. Account problems
4. General questions

ESCALATION RULES:
- Refund requests > $500: Require manager approval
- Technical issues: Route to TechAgent
- Billing disputes: Route to BillingAgent
- Product questions: Route to ProductAgent

Always aim for first-contact resolution when possible.
`);

2. 教育平台监督者

const educationSupervisor = new SystemMessage(`
You are an educational AI supervisor managing tutoring agents.

LEARNING PRINCIPLES:
- Adapt to student's learning pace
- Provide encouraging feedback
- Use multiple explanation methods
- Track learning progress
- Ensure age-appropriate content

Subject agents available:
- MathAgent: Mathematics tutoring
- ScienceAgent: Science concepts
- LanguageAgent: Language arts
- HistoryAgent: Historical topics

Focus on building understanding, not just providing answers.
`);

选择 SystemMessage 的场景

✅ 适合使用 SystemMessage 的场景：

• 固定的角色定义和职责
• 标准化的工作流程
• 合规要求和安全指令
• 领域专业知识的固定规则
• 简单明确的监督逻辑

❌ 不适合使用 SystemMessage 的场景：

• 需要根据状态动态调整指令
• 需要外部数据或API调用
• 复杂的条件逻辑
• 需要实时优化的提示

总结：SystemMessage 是最基础但也是最重要的提示类型，适合大多数标准化的监督场景。它提供了清晰、稳定、高性能的指令方式。

[Pines-Cheng]

outputMode 控制监督者在做决策时能看到多少智能体的对话历史，这对监督者的决策质量和性能有重要影响。

两种模式的区别

last_message (默认模式)

监督者只能看到每个智能体的最后一条消息

full_history

监督者可以看到完整的对话历史

具体示例对比

假设有这样一个对话流程：

// 对话历史
const conversationHistory = [
  { role: "user", content: "我需要写一篇关于AI的文章" },
  { role: "assistant", name: "ResearchAgent", content: "我找到了AI的最新发展趋势..." },
  { role: "assistant", name: "ResearchAgent", content: "补充一些技术细节..." },
  { role: "assistant", name: "WriterAgent", content: "基于研究，我开始写文章大纲..." },
  { role: "assistant", name: "WriterAgent", content: "这是完整的文章草稿..." },
  { role: "assistant", name: "ReviewAgent", content: "文章质量不错，但需要修改..." }
];

last_message 模式下监督者看到的：

// 监督者只看到每个智能体的最后一条消息
const supervisorInput = [
  { role: "user", content: "我需要写一篇关于AI的文章" },
  { role: "assistant", name: "ResearchAgent", content: "补充一些技术细节..." },      // 只有最后一条
  { role: "assistant", name: "WriterAgent", content: "这是完整的文章草稿..." },        // 只有最后一条  
  { role: "assistant", name: "ReviewAgent", content: "文章质量不错，但需要修改..." }    // 只有最后一条
];

full_history 模式下监督者看到的：

// 监督者看到完整历史
const supervisorInput = [
  { role: "user", content: "我需要写一篇关于AI的文章" },
  { role: "assistant", name: "ResearchAgent", content: "我找到了AI的最新发展趋势..." },
  { role: "assistant", name: "ResearchAgent", content: "补充一些技术细节..." },
  { role: "assistant", name: "WriterAgent", content: "基于研究，我开始写文章大纲..." },
  { role: "assistant", name: "WriterAgent", content: "这是完整的文章草稿..." },
  { role: "assistant", name: "ReviewAgent", content: "文章质量不错，但需要修改..." }
];

使用场景对比

last_message 适用场景

1. 简单任务协调

// 每个智能体职责明确，不需要了解详细过程
const simpleTaskSupervisor = createSupervisor({
  agents: [translatorAgent, summarizerAgent],
  llm: model,
  outputMode: 'last_message',  // 只需要知道最终结果
  prompt: "根据智能体的最终输出，决定下一步行动"
});

2. 性能优先场景

// 大量智能体，长对话历史，需要快速决策
const highPerformanceSupervisor = createSupervisor({
  agents: manyAgents,  // 10+ 智能体
  llm: model,
  outputMode: 'last_message',  // 减少token消耗
  prompt: "基于最新状态快速做出决策"
});

3. 状态驱动的工作流

// 每个智能体输出明确的状态信息
const statusDrivenSupervisor = createSupervisor({
  agents: [dataAgent, processAgent, outputAgent],
  llm: model,
  outputMode: 'last_message',
  prompt: `根据智能体的状态报告决定下一步：
  - COMPLETED: 继续下一个智能体
  - FAILED: 重试或终止
  - PENDING: 等待更多信息`
});

full_history 适用场景

1. 复杂推理任务

// 需要理解完整的推理过程
const complexReasoningSupervisor = createSupervisor({
  agents: [logicAgent, mathAgent, validationAgent],
  llm: model,
  outputMode: 'full_history',  // 需要看到完整推理链
  prompt: `分析整个推理过程，确保逻辑一致性：
  - 检查推理步骤是否正确
  - 验证中间结果
  - 确保最终结论有效`
});

2. 质量保证场景

// 需要追踪质量改进过程
const qualityAssuranceSupervisor = createSupervisor({
  agents: [writerAgent, editorAgent, reviewerAgent],
  llm: model,
  outputMode: 'full_history',  // 需要看到修改历史
  prompt: `基于完整的编辑历史评估：
  - 内容质量是否持续改进
  - 修改建议是否被正确执行
  - 是否需要进一步优化`
});

3. 学习和适应场景

// 需要从历史中学习
const adaptiveSupervisor = createSupervisor({
  agents: [explorerAgent, analyzerAgent, optimizerAgent],
  llm: model,
  outputMode: 'full_history',  // 需要完整学习历史
  prompt: `基于完整的探索和分析历史：
  - 识别成功的策略模式
  - 避免重复失败的方法
  - 调整后续探索方向`
});

4. 调试和诊断

// 需要诊断问题根源
const debuggingSupervisor = createSupervisor({
  agents: [testAgent, analyzeAgent, fixAgent],
  llm: model,
  outputMode: 'full_history',  // 需要完整错误轨迹
  prompt: `基于完整的测试和分析历史：
  - 追踪问题的根本原因
  - 评估修复尝试的效果
  - 决定最佳的解决方案`
});

性能和成本考虑

Token 消耗对比

// 假设每个智能体平均产生 100 tokens，有 5 个智能体，每个智能体说了 3 次话

// last_message 模式
const lastMessageTokens = 5 * 100;  // 500 tokens

// full_history 模式  
const fullHistoryTokens = 5 * 3 * 100;  // 1500 tokens

console.log(`Token消耗比例: ${fullHistoryTokens / lastMessageTokens}x`);  // 3倍

响应时间对比

// last_message: 更快的处理速度
// full_history: 需要处理更多上下文，速度较慢

选择建议

场景特征	推荐模式	原因
简单任务流	last_message	效率高，成本低
复杂推理	full_history	需要完整上下文
大量智能体	last_message	控制成本和延迟
质量要求高	full_history	更好的决策质量
实时应用	last_message	响应速度快
调试诊断	full_history	需要完整信息

总结：last_message 适合效率优先的场景，full_history 适合质量优先的场景。选择时需要在性能和决策质量之间找到平衡。

[Pines-Cheng]

addHandoffBackMessages 控制在智能体之间移交控制权时，是否在消息历史中添加特殊的移交消息对，用于记录和追踪控制权的转移过程。

移交消息对的结构

当 addHandoffBackMessages: true 时，每次移交都会添加：

// AIMessage: 监督者的移交决策
{
  role: "assistant",
  content: "", // 通常为空
  tool_calls: [{
    id: "handoff_123",
    name: "handoff_to_agent",
    args: { agent: "WriterAgent", reason: "需要基于研究结果写文章" }
  }]
}

// ToolMessage: 移交确认
{
  role: "tool", 
  tool_call_id: "handoff_123",
  content: "Successfully handed off to WriterAgent"
}

具体示例对比

场景：用户请求 → 研究智能体 → 写作智能体

addHandoffBackMessages: false (默认)

const conversationHistory = [
  { role: "user", content: "写一篇关于量子计算的文章" },
  
  // 监督者直接调用研究智能体
  { role: "assistant", name: "ResearchAgent", content: "我找到了量子计算的最新研究..." },
  
  // 监督者直接调用写作智能体  
  { role: "assistant", name: "WriterAgent", content: "基于研究，这是文章草稿..." }
];

addHandoffBackMessages: true

const conversationHistory = [
  { role: "user", content: "写一篇关于量子计算的文章" },
  
  // 监督者决定移交给研究智能体
  { 
    role: "assistant", 
    content: "",
    tool_calls: [{ 
      id: "handoff_1", 
      name: "handoff_to_agent", 
      args: { agent: "ResearchAgent", reason: "需要先收集量子计算相关资料" }
    }]
  },
  
  // 移交确认
  { 
    role: "tool", 
    tool_call_id: "handoff_1", 
    content: "Successfully handed off to ResearchAgent" 
  },
  
  // 研究智能体工作
  { role: "assistant", name: "ResearchAgent", content: "我找到了量子计算的最新研究..." },
  
  // 监督者决定移交给写作智能体
  { 
    role: "assistant", 
    content: "",
    tool_calls: [{ 
      id: "handoff_2", 
      name: "handoff_to_agent", 
      args: { agent: "WriterAgent", reason: "基于研究结果创作文章" }
    }]
  },
  
  // 移交确认
  { 
    role: "tool", 
    tool_call_id: "handoff_2", 
    content: "Successfully handed off to WriterAgent" 
  },
  
  // 写作智能体工作
  { role: "assistant", name: "WriterAgent", content: "基于研究，这是文章草稿..." }
];

使用场景

适合启用 addHandoffBackMessages: true 的场景

1. 复杂工作流追踪

const complexWorkflowSupervisor = createSupervisor({
  agents: [researchAgent, analysisAgent, writerAgent, reviewAgent],
  llm: model,
  addHandoffBackMessages: true,  // 追踪复杂的移交链
  prompt: `你需要协调多个智能体完成复杂任务：
  1. 研究阶段 → 分析阶段 → 写作阶段 → 审核阶段
  2. 记录每次移交的原因和目标
  3. 确保工作流程的透明度`
});

2. 审计和合规要求

const auditableSupervisor = createSupervisor({
  agents: [dataAgent, validationAgent, reportAgent],
  llm: model,
  addHandoffBackMessages: true,  // 审计追踪
  prompt: `在金融数据处理中：
  - 记录每次数据移交
  - 确保责任链清晰
  - 满足合规审计要求
  - 可追溯每个决策点`
});

3. 调试和优化

const debuggableSupervisor = createSupervisor({
  agents: [agent1, agent2, agent3],
  llm: model,
  addHandoffBackMessages: true,  // 便于调试
  prompt: "详细记录移交决策，便于后续分析和优化"
});

// 可以分析移交模式
function analyzeHandoffPatterns(messages) {
  const handoffs = messages.filter(msg => 
    msg.tool_calls?.some(call => call.name === "handoff_to_agent")
  );
  
  console.log("移交决策分析:", handoffs.map(h => ({
    target: h.tool_calls[0].args.agent,
    reason: h.tool_calls[0].args.reason
  })));
}

4. 学习和改进

const learningSystem = createSupervisor({
  agents: [explorerAgent, optimizerAgent],
  llm: model,
  addHandoffBackMessages: true,  // 学习移交模式
  prompt: `基于历史移交记录：
  - 学习最佳移交时机
  - 识别无效的移交模式
  - 优化智能体协作效率`
});

适合禁用 addHandoffBackMessages: false 的场景

1. 简单任务流

const simpleSupervisor = createSupervisor({
  agents: [translatorAgent, summarizerAgent],
  llm: model,
  addHandoffBackMessages: false,  // 简化消息历史
  prompt: "简单的翻译→总结流程，不需要详细追踪"
});

2. 性能敏感应用

const highPerformanceSupervisor = createSupervisor({
  agents: manyAgents,
  llm: model,
  addHandoffBackMessages: false,  // 减少消息开销
  prompt: "优先考虑响应速度和资源消耗"
});

3. 用户界面展示

const userFacingSupervisor = createSupervisor({
  agents: [chatAgent, helpAgent],
  llm: model,
  addHandoffBackMessages: false,  // 用户只看到最终结果
  prompt: "为用户提供流畅的对话体验，隐藏内部移交细节"
});

实际应用示例

启用移交消息的客服系统

const customerServiceSupervisor = createSupervisor({
  agents: [
    generalSupportAgent,
    technicalSupportAgent, 
    billingAgent,
    escalationAgent
  ],
  llm: model,
  addHandoffBackMessages: true,  // 追踪服务路径
  prompt: `客服移交追踪系统：
  - 记录每次转接的原因
  - 确保客户问题不会丢失
  - 分析服务路径效率
  - 提供完整的服务记录`
});

// 分析客服效率
function analyzeCustomerServiceFlow(messages) {
  const handoffs = messages.filter(msg => 
    msg.tool_calls?.some(call => call.name === "handoff_to_agent")
  );
  
  return {
    totalHandoffs: handoffs.length,
    averageResolutionPath: calculateAveragePathLength(handoffs),
    mostCommonTransitions: findCommonTransitions(handoffs)
  };
}

禁用移交消息的聊天助手

const chatAssistant = createSupervisor({
  agents: [conversationAgent, taskAgent, knowledgeAgent],
  llm: model,
  addHandoffBackMessages: false,  // 保持对话流畅
  prompt: "提供自然的对话体验，智能体切换对用户透明"
});

选择建议

需求	推荐设置	原因
工作流追踪	true	需要完整的执行记录
调试分析	true	便于问题诊断和优化
合规审计	true	满足审计要求
用户体验	false	简化用户看到的内容
性能优先	false	减少消息开销
简单流程	false	避免不必要的复杂性

总结：addHandoffBackMessages 主要用于需要透明度、可追踪性和调试能力的场景。对于面向用户的简单应用，通常设置为 false 以保持体验的流畅性。