Classify intent

- 静态上下文（提示词）：分类类别、紧急程度定义、回复格式 - 动态上下文（来自状态）：邮件内容、发件人信息 - 期望结果：决定路由的结构化分类

Draft reply

- 静态上下文（提示词）：语调指南、公司政策、回复模板 - 动态上下文（来自状态）：分类结果、搜索结果、客户历史 - 期望结果：可供审阅的专业邮件回复

Document search

- 参数：从意图和主题构建的查询 - 重试策略：是，对于暂时性故障使用指数退避 - 缓存：可以缓存常见查询以减少 API 调用

Customer history lookup

- 参数：状态中的客户邮箱或 ID - 重试策略：是，但如不可用则回退到基本信息 - 缓存：是，使用生存时间在新鲜度和性能之间取得平衡

Send reply

- 何时执行节点：批准后（人工或自动） - 重试策略：是，对于网络问题使用指数退避 - 不应缓存：每次发送都是唯一操作

Bug track

- 何时执行节点：当意图为"bug"时始终执行 - 重试策略：是，关键是不能丢失 bug 报告 - 返回：响应中包含工单 ID

Human review node

- 决策上下文：原始邮件、回复草稿、紧急程度、分类 - 期望的输入格式：批准布尔值加上可选的编辑回复 - 触发时机：高紧急程度、复杂问题或质量问题

Transient errors

添加重试策略以自动重试网络问题和速率限制。

    workflow.addNode(
      "searchDocumentation",
      searchDocumentation,
      {
        retryPolicy: { maxAttempts: 3, initialInterval: 1.0 },
      },
    );
    

LLM-recoverable

将错误存储在状态中并循环回退，这样 LLM 可以看到出了什么问题并重试：

    const executeTool: GraphNode<typeof State> = async (state, config) => {
      try {
        const result = await runTool(state.toolCall);
        return new Command({
          update: { toolResult: result },
          goto: "agent",
        });
      } catch (error) {
        // Let the LLM see what went wrong and try again
        return new Command({
          update: { toolResult: `Tool error: ${error}` },
          goto: "agent"
        });
      }
    }
    

User-fixable

在需要时暂停并收集用户信息（如账户 ID、订单号或澄清说明）：

    const lookupCustomerHistory: GraphNode<typeof State> = async (state, config) => {
      if (!state.customerId) {
        const userInput = interrupt({
          message: "Customer ID needed",
          request: "Please provide the customer's account ID to look up their subscription history",
        });
        return new Command({
          update: { customerId: userInput.customerId },
          goto: "lookupCustomerHistory",
        });
      }
      // Now proceed with the lookup
      const customerData = await fetchCustomerHistory(state.customerId);
      return new Command({
        update: { customerHistory: customerData },
        goto: "draftResponse",
      });
    }
    

Unexpected

让它们向上冒泡以便调试。不要捕获你无法处理的内容：

    const sendReply: GraphNode<typeof EmailAgentState> = async (state, config) => {
      try {
        await emailService.send(state.responseText);
      } catch (error) {
        throw error;  // Surface unexpected errors
      }
    }
    

Saga / compensation

重试耗尽后，运行一个恢复函数来更新状态并将流程路由到补偿分支。

Read and classify nodes

    const llm = new ChatAnthropic({ model: "claude-sonnet-4-6" });

    const readEmail: GraphNode<typeof EmailAgentState> = async (state, config) => {
      // Extract and parse email content
      // In production, this would connect to your email service
      console.log(`Processing email: ${state.emailContent}`);
      return {};
    }

    const classifyIntent: GraphNode<typeof EmailAgentState> = async (state, config) => {
      // Use LLM to classify email intent and urgency, then route accordingly

      // Create structured LLM that returns EmailClassification object
      const structuredLlm = llm.withStructuredOutput(EmailClassificationSchema);

      // Format the prompt on-demand, not stored in state
      const classificationPrompt = `
      Analyze this customer email and classify it:

      Email: ${state.emailContent}
      From: ${state.senderEmail}

      Provide classification including intent, urgency, topic, and summary.
      `;

      // Get structured response directly as object
      const classification = await structuredLlm.invoke(classificationPrompt);

      // Determine next node based on classification
      let nextNode: "searchDocumentation" | "humanReview" | "draftResponse" | "bugTracking";

      if (classification.intent === "billing" || classification.urgency === "critical") {
        nextNode = "humanReview";
      } else if (classification.intent === "question" || classification.intent === "feature") {
        nextNode = "searchDocumentation";
      } else if (classification.intent === "bug") {
        nextNode = "bugTracking";
      } else {
        nextNode = "draftResponse";
      }

      // Store classification as a single object in state
      return new Command({
        update: { classification },
        goto: nextNode,
      });
    }
    

Search and tracking nodes

    const searchDocumentation: GraphNode<typeof EmailAgentState> = async (state, config) => {
      // Search knowledge base for relevant information

      // Build search query from classification
      const classification = state.classification!;
      const query = `${classification.intent} ${classification.topic}`;

      let searchResults: string[];

      try {
        // Implement your search logic here
        // Store raw search results, not formatted text
        searchResults = [
          "Reset password via Settings > Security > Change Password",
          "Password must be at least 12 characters",
          "Include uppercase, lowercase, numbers, and symbols",
        ];
      } catch (error) {
        // For recoverable search errors, store error and continue
        searchResults = [`Search temporarily unavailable: ${error}`];
      }

      return new Command({
        update: { searchResults },  // Store raw results or error
        goto: "draftResponse",
      });
    }

    const bugTracking: GraphNode<typeof EmailAgentState> = async (state, config) => {
      // Create or update bug tracking ticket

      // Create ticket in your bug tracking system
      const ticketId = "BUG-12345";  // Would be created via API

      return new Command({
        update: { searchResults: [`Bug ticket ${ticketId} created`] },
        goto: "draftResponse",
      });
    }
    

Response nodes

    const draftResponse: GraphNode<typeof EmailAgentState> = async (state, config) => {
      // Generate response using context and route based on quality

      const classification = state.classification!;

      // Format context from raw state data on-demand
      const contextSections: string[] = [];

      if (state.searchResults) {
        // Format search results for the prompt
        const formattedDocs = state.searchResults.map(doc => `- ${doc}`).join("\n");
        contextSections.push(`Relevant documentation:\n${formattedDocs}`);
      }

      if (state.customerHistory) {
        // Format customer data for the prompt
        contextSections.push(`Customer tier: ${state.customerHistory.tier ?? "standard"}`);
      }

      // Build the prompt with formatted context
      const draftPrompt = `
      Draft a response to this customer email:
      ${state.emailContent}

      Email intent: ${classification.intent}
      Urgency level: ${classification.urgency}

      ${contextSections.join("\n\n")}

      Guidelines:
      - Be professional and helpful
      - Address their specific concern
      - Use the provided documentation when relevant
      `;

      const response = await llm.invoke([new HumanMessage(draftPrompt)]);

      // Determine if human review needed based on urgency and intent
      const needsReview = (
        classification.urgency === "high" ||
        classification.urgency === "critical" ||
        classification.intent === "complex"
      );

      // Route to appropriate next node
      const nextNode = needsReview ? "humanReview" : "sendReply";

      return new Command({
        update: { responseText: response.content.toString() },  // Store only the raw response
        goto: nextNode,
      });
    }

    const humanReview: GraphNode<typeof EmailAgentState> = async (state, config) => {
      // Pause for human review using interrupt and route based on decision
      const classification = state.classification!;

      // interrupt() must come first - any code before it will re-run on resume
      const humanDecision = interrupt({
        emailId: state.emailId,
        originalEmail: state.emailContent,
        draftResponse: state.responseText,
        urgency: classification.urgency,
        intent: classification.intent,
        action: "Please review and approve/edit this response",
      });

      // Now process the human's decision
      if (humanDecision.approved) {
        return new Command({
          update: { responseText: humanDecision.editedResponse || state.responseText },
          goto: "sendReply",
        });
      } else {
        // Rejection means human will handle directly
        return new Command({ update: {}, goto: END });
      }
    }

    const sendReply: GraphNode<typeof EmailAgentState> = async (state, config) => {
      // Send the email response
      // Integrate with email service
      console.log(`Sending reply: ${state.responseText!.substring(0, 100)}...`);
      return {};
    }
    

Graph compilation code

// Create the graph
const workflow = new StateGraph(EmailAgentState)
  // Add nodes with appropriate error handling
  .addNode("readEmail", readEmail)
  .addNode("classifyIntent", classifyIntent)
  // Add retry policy for nodes that might have transient failures
  .addNode(
    "searchDocumentation",
    searchDocumentation,
    { retryPolicy: { maxAttempts: 3 } },
  )
  .addNode("bugTracking", bugTracking)
  .addNode("draftResponse", draftResponse)
  .addNode("humanReview", humanReview)
  .addNode("sendReply", sendReply)
  // Add only the essential edges
  .addEdge(START, "readEmail")
  .addEdge("readEmail", "classifyIntent")
  .addEdge("sendReply", END);

// Compile with checkpointer for persistence
const memory = new MemorySaver();
const app = workflow.compile({ checkpointer: memory });

Testing the agent

// Test with an urgent billing issue
const initialState: EmailAgentStateType = {
  emailContent: "I was charged twice for my subscription! This is urgent!",
  senderEmail: "customer@example.com",
  emailId: "email_123"
};

// Run with a thread_id for persistence
const config = { configurable: { thread_id: "customer_123" } };
const result = await app.invoke(initialState, config);
// The graph will pause at human_review
console.log(`Draft ready for review: ${result.responseText?.substring(0, 100)}...`);

// When ready, provide human input to resume
const humanResponse = new Command({
  resume: {
    approved: true,
    editedResponse: "We sincerely apologize for the double charge. I've initiated an immediate refund...",
  }
});

// Resume execution
const finalResult = await app.invoke(humanResponse, config);
console.log("Email sent successfully!");

Node granularity trade-offs

您可能想知道：为什么不合并 Read Email 和 Classify Intent 到一个节点中？

或者为什么要将文档搜索与草稿回复分开？

答案涉及弹性和可观察性之间的权衡。

弹性考虑： LangGraph 的 持久化层 在节点边界创建检查点。当工作流在中断或失败后恢复时，它会从执行停止的节点开始重新启动。较小的节点意味着更频繁的检查点，这意味着如果出现问题，需要重复的工作更少。如果您将多个操作组合到一个大节点中，靠近末尾的故障意味着从该节点的开头重新执行所有内容。

为什么我们为邮件代理选择这种分解：

• 外部服务隔离： 文档搜索和缺陷跟踪是独立的节点，因为它们调用外部 API。如果搜索服务缓慢或失败，我们希望将其与 LLM 调用隔离开来。我们可以向这些特定节点添加重试策略，而不影响其他节点。
• 中间可见性： 将 Classify Intent 作为一个单独的节点，让我们能够在采取行动之前检查 LLM 的决定。这对于调试和监控很有价值——您可以准确看到代理何时以及为何路由到人工审核。
• 不同的失败模式： LLM 调用、数据库查询和电子邮件发送具有不同的重试策略。单独的节点让您能够独立配置这些。
• 可重用性和测试： 较小的节点更容易独立测试，并在其他工作流中重用。

另一种有效的方法：您可以将 Read Email 和 Classify Intent 合并到单个节点中。您将失去在分类之前检查原始电子邮件的能力，并且在该节点中的任何故障时都会重复两个操作。对于大多数应用程序来说，单独节点的可见性和调试好处值得这个权衡。

应用层关注点：第2步中的缓存讨论（是否缓存搜索结果）是一个应用层决策，而非 LangGraph 框架的功能。你根据具体需求在节点函数中实现缓存——LangGraph 不规定这一点。

性能考虑：更多节点并不意味着更慢的执行。LangGraph 默认在后台写入检查点（异步持久化模式），因此你的图会继续运行，无需等待检查点完成。这意味着你可以在最小性能影响下获得频繁的检查点。如有需要，你可以调整此行为——使用 "exit" 模式仅在完成时创建检查点，或使用 "sync" 模式阻塞执行直到每个检查点写入完成。