> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Graph API 和 Functional API 之间选择

LangGraph 提供两种不同的 API 来构建智能体工作流：**Graph API** 和 **Functional API**。这两种 API 共享相同的底层运行时，并且可以在同一个应用程序中结合使用，但它们是为不同的用例和开发偏好而设计的。

本指南将帮助您根据具体需求理解何时使用每种 API。

## 快速决策指南

当您需要以下功能时，请使用 **Graph API**：

* **复杂工作流可视化**，用于调试和文档编写
* **显式状态管理**，在多个节点间共享数据
* **条件分支**，具有多个决策点
* **并行执行路径**，需要在后续合并
* **团队协作**，可视化表示有助于理解

当您希望实现以下目标时，请使用 **Functional API**：

* **对现有过程式代码的最小改动**
* **标准控制流**（if/else、循环、函数调用）
* **函数作用域状态**，无需显式状态管理
* **快速原型开发**，减少样板代码
* **线性工作流**，具有简单的分支逻辑

## 详细比较

### 何时使用 Graph API

[Graph API](/oss/javascript/langgraph/graph-api) 使用声明式方法，您定义节点、边和共享状态来创建可视化的图结构。

**1. 复杂的决策树和分支逻辑**

当您的工作流具有依赖于各种条件的多个决策点时，Graph API 使这些分支变得明确且易于可视化。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import {
  StateGraph,
  StateSchema,
  MessagesValue,
  START,
  END,
  type GraphNode,
  type ConditionalEdgeRouter,
} from "@langchain/langgraph";

// Graph API：决策路径的清晰可视化
const AgentState = new StateSchema({
  messages: MessagesValue,
  currentTool: z.string(),
  retryCount: z.number().default(0),
});

const shouldContinue: ConditionalEdgeRouter<typeof AgentState> = (state) => {
  if (state.retryCount > 3) {
    return END;
  } else if (state.currentTool === "search") {
    return "processSearch";
  } else {
    return "callLlm";
  }
};

const workflow = new StateGraph(AgentState)
  .addNode("callLlm", callLlmNode)
  .addNode("processSearch", searchNode)
  .addConditionalEdges("callLlm", shouldContinue);
```

**2. 跨多个组件的状态管理**

当您需要在工作流的不同部分之间共享和协调状态时，Graph API 的显式状态管理非常有益。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import { StateSchema, type GraphNode } from "@langchain/langgraph";

// 多个节点可以访问和修改共享状态
const WorkflowState = new StateSchema({
  userInput: z.string(),
  searchResults: z.array(z.string()).default([]),
  generatedResponse: z.string().optional(),
  validationStatus: z.string().optional(),
});

const searchNode: GraphNode<typeof WorkflowState> = async (state) => {
  // 访问共享状态
  const results = await search(state.userInput);
  return { searchResults: results };
};

const validationNode: GraphNode<typeof WorkflowState> = async (state) => {
  // 访问前一个节点的结果
  const isValid = await validate(state.generatedResponse);
  return { validationStatus: isValid ? "valid" : "invalid" };
};
```

**3. 带同步的并行处理**

当您需要并行运行多个操作然后合并其结果时，Graph API 可以自然地处理这一点。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { START } from "@langchain/langgraph";

// 并行处理多个数据源
workflow
  .addNode("fetchNews", fetchNews)
  .addNode("fetchWeather", fetchWeather)
  .addNode("fetchStocks", fetchStocks)
  .addNode("combineData", combineAllData)
  // 所有获取操作并行运行
  .addEdge(START, "fetchNews")
  .addEdge(START, "fetchWeather")
  .addEdge(START, "fetchStocks")
  // combine 等待所有并行操作完成
  .addEdge("fetchNews", "combineData")
  .addEdge("fetchWeather", "combineData")
  .addEdge("fetchStocks", "combineData");
```

**4. 团队开发和文档编写**

Graph API 的可视化特性使团队更容易理解、记录和维护复杂的工作流。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// 清晰的关注点分离 - 每个团队成员可以处理不同的节点
workflow
  .addNode("dataIngestion", dataTeamFunction)
  .addNode("mlProcessing", mlTeamFunction)
  .addNode("businessLogic", productTeamFunction)
  .addNode("outputFormatting", frontendTeamFunction);
```

### 何时使用 Functional API

[Functional API](/oss/javascript/langgraph/functional-api) 使用命令式方法，将 LangGraph 功能集成到标准的过程式代码中。

**1. 现有的过程式代码**

当您有使用标准控制流的现有代码，并希望以最小的重构添加 LangGraph 功能时。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { task, entrypoint } from "@langchain/langgraph";

// Functional API：对现有代码的最小改动
const processUserInput = task("processUserInput", async (userInput: string) => {
  // 进行最小改动的现有函数
  return { processed: userInput.toLowerCase().trim() };
});

const workflow = entrypoint({ checkpointer }, async (userInput: string) => {
  // 标准控制流
  const processed = await processUserInput(userInput);

  let response: string;
  if (processed.processed.includes("urgent")) {
    response = await handleUrgentRequest(processed);
  } else {
    response = await handleNormalRequest(processed);
  }

  return response;
});
```

**2. 具有简单逻辑的线性工作流**

当您的工作流主要是顺序执行，并具有直接的条件逻辑时。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { entrypoint, interrupt } from "@langchain/langgraph";

const essayWorkflow = entrypoint({ checkpointer }, async (topic: string) => {
  // 具有简单分支的线性流程
  let outline = await createOutline(topic);

  if (outline.points.length < 3) {
    outline = await expandOutline(outline);
  }

  const draft = await writeDraft(outline);

  // 人工审核检查点
  const feedback = interrupt({ draft, action: "Please review" });

  let finalEssay: string;
  if (feedback === "approve") {
    finalEssay = draft;
  } else {
    finalEssay = await reviseEssay(draft, feedback);
  }

  return { essay: finalEssay };
});
```

**3. 快速原型开发**

当您希望快速测试想法，而无需定义状态模式和图结构的开销时。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { entrypoint } from "@langchain/langgraph";

const quickPrototype = entrypoint(
  { checkpointer },
  async (data: Record<string, unknown>) => {
    // 快速迭代 - 无需状态模式
    const step1Result = await processStep1(data);
    const step2Result = await processStep2(step1Result);

    return { finalResult: step2Result };
  },
);
```

**4. 函数作用域的状态管理**

当您的状态自然地限定在单个函数内，不需要广泛共享时。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { task, entrypoint } from "@langchain/langgraph";

const analyzeDocument = task("analyzeDocument", async (document: string) => {
  // 函数内的本地状态管理
  const sections = extractSections(document);
  const summaries = await Promise.all(sections.map(summarize));
  const keyPoints = extractKeyPoints(summaries);

  return {
    sections: sections.length,
    summaries,
    keyPoints,
  };
});

const documentProcessor = entrypoint(
  { checkpointer },
  async (document: string) => {
    const analysis = await analyzeDocument(document);
    // 根据需要在函数间传递状态
    return await generateReport(analysis);
  },
);
```

## 结合使用两种 API

您可以在同一个应用程序中结合使用这两种 API。当系统的不同部分有不同需求时，这非常有用。

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import {
  StateGraph,
  StateSchema,
  entrypoint,
  type GraphNode,
} from "@langchain/langgraph";

// 为复杂的多智能体协调定义状态
const CoordinationState = new StateSchema({
  rawData: z.record(z.string(), z.unknown()),
  processedData: z.record(z.string(), z.unknown()).optional(),
});

// 使用 Functional API 进行简单的数据处理
const dataProcessor = entrypoint(
  {},
  async (rawData: Record<string, unknown>) => {
    const cleaned = await cleanData(rawData);
    const transformed = await transformData(cleaned);
    return transformed;
  },
);

// 在图中使用 Functional API 的结果
const orchestratorNode: GraphNode<typeof CoordinationState> = async (state) => {
  const processedData = await dataProcessor.invoke(state.rawData);
  return { processedData };
};

// 使用 Graph API 进行复杂的多智能体协调
const coordinationGraph = new StateGraph(CoordinationState)
  .addNode("orchestrator", orchestratorNode)
  .addNode("agentA", agentANode)
  .addNode("agentB", agentBNode);
```

## API 之间的迁移

### 从 Functional API 迁移到 Graph API

当您的 Functional 工作流变得复杂时，您可以迁移到 Graph API：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import * as z from "zod";
import { entrypoint } from "@langchain/langgraph";

// 之前：Functional API
const complexWorkflow = entrypoint(
  { checkpointer },
  async (inputData: Record<string, unknown>) => {
    const step1 = await processStep1(inputData);

    let result: unknown;
    if (step1.needsAnalysis) {
      const analysis = await analyzeData(step1);
      if (analysis.confidence > 0.8) {
        result = await highConfidencePath(analysis);
      } else {
        result = await lowConfidencePath(analysis);
      }
    } else {
      result = await simplePath(step1);
    }

    return result;
  },
);

// 之后：Graph API
import {
  StateGraph,
  StateSchema,
  type GraphNode,
  type ConditionalEdgeRouter,
} from "@langchain/langgraph";

const WorkflowState = new StateSchema({
  inputData: z.record(z.string(), z.unknown()),
  step1Result: z.record(z.string(), z.unknown()).optional(),
  analysis: z.record(z.string(), z.unknown()).optional(),
  finalResult: z.unknown().optional(),
});

const shouldAnalyze: ConditionalEdgeRouter<typeof WorkflowState> = (state) => {
  return state.step1Result?.needsAnalysis ? "analyze" : "simplePath";
};

const confidenceCheck: ConditionalEdgeRouter<typeof WorkflowState> = (
  state,
) => {
  return (state.analysis?.confidence as number) > 0.8
    ? "highConfidence"
    : "lowConfidence";
};

const workflow = new StateGraph(WorkflowState)
  .addNode("step1", processStep1Node)
  .addConditionalEdges("step1", shouldAnalyze)
  .addNode("analyze", analyzeDataNode)
  .addConditionalEdges("analyze", confidenceCheck);
// ... 添加剩余的节点和边
```

### 从 Graph API 迁移到 Functional API

当您的图对于简单的线性流程变得过于复杂时：

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { z } from "zod/v4";
import { StateGraph, StateSchema, entrypoint } from "@langchain/langgraph";

// 之前：过度设计的 Graph API
const SimpleState = new StateSchema({
  input: z.string(),
  step1: z.string().optional(),
  step2: z.string().optional(),
  result: z.string().optional(),
});

// 之后：简化的 Functional API
const simpleWorkflow = entrypoint(
  { checkpointer },
  async (inputData: string) => {
    const step1 = await processStep1(inputData);
    const step2 = await processStep2(step1);
    return await finalizeResult(step2);
  },
);
```

## 总结

当您需要显式控制工作流结构、复杂分支、并行处理或团队协作优势时，请选择 **Graph API**。

当您希望以最小的改动将 LangGraph 功能添加到现有代码、拥有简单的线性工作流或需要快速原型开发能力时，请选择 **Functional API**。

两种 API 都提供相同的核心 LangGraph 功能（持久化、流式处理、Human in the Loop、记忆），但将它们封装在不同的范式中，以适应不同的开发风格和用例。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP
    获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub
    上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langgraph/choosing-apis.mdx)
    或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>