1. 图 Agent（Graph Agent）

概述

图 Agent 是 Xyzen 中最强大的功能之一，它突破了传统单轮对话的局限， 允许你构建复杂的、多步骤的 AI 工作流。与简单的聊天 Assistant 不同， 图 Agent 采用 LangGraph 技术栈，能够处理：

核心能力

• 多节点编排：将复杂任务分解为多个独立的处理节点，每个节点专注于特定功能
• 条件分支控制：根据实时执行结果动态选择执行路径，支持 if-else 分支和动态路由
• 状态管理：在整个工作流中维护和传递执行上下文，节点间可以共享和修改状态
• 循环和递归：支持需要重复迭代的任务，如多轮对话、数据清理等
• 多轮推理：实现复杂的思维链（Chain of Thought），逐步推导出最终答案

核心概念

状态图（State Graph）

状态图是图 Agent 的核心架构。它用来定义工作流中所有数据的结构和流向。 简单来说，状态图就像是一个包含了所有变量的"上下文对象"， 工作流中的每个节点都可以读取这个状态，并根据需要修改它。

状态通常包含：

• 输入数据：用户的查询、上传的文件等初始信息
• 中间结果：各个节点的处理结果，用于后续节点参考
• 执行上下文：当前的执行步骤、错误信息、临时计算结果等
• 最终输出：工作流的最终结果，返回给用户

通过良好的状态设计，你可以确保工作流的各个部分能够有效地协作。

节点类型

节点是图 Agent 的基本执行单元。Xyzen 提供了多种预定义的节点类型，每种类型服务于不同的目的：

LLM 节点 - 调用大语言模型进行推理。这类节点可以：

• 分析用户的查询意图和复杂度
• 生成文本内容、代码、分析报告等
• 制定执行计划和策略
• 总结和综合多个源的信息

工具节点 - 执行外部工具和 MCP Server。典型用途包括：

• 调用数据库查询或搜索服务
• 执行计算密集的操作
• 与第三方 API 交互
• 文件处理和数据转换

路由节点 - 作为工作流的"决策中心"。路由节点：

• 根据条件判断工作流应该走哪个分支
• 支持多条件的复杂判断逻辑
• 避免不必要的计算成本

子 Agent 节点 - 调用其他已有的 Agent。这使你能够：

• 复用已有的 Agent，避免重复开发
• 构建分层的 Agent 架构
• 委派特定的专业任务给专门的 Agent

特殊节点 - START 和 END 节点标记工作流的入口和出口点。

边（Edges）

边定义了节点之间的连接关系和执行流向。在图 Agent 中，边有两种主要类型：

简单边 - 最直接的连接方式。当一个节点完成执行时，工作流无条件地流向下一个节点。 这种边适用于流程是固定的、无需根据前一个节点的结果进行判断的场景。

条件边 - 根据执行结果进行动态路由。条件边允许你定义一个判断条件， 根据状态的值决定工作流走哪条分支。例如，如果用户的查询被判定为"简单问题"， 则走快速回答路径；如果是"复杂问题"，则走深度分析路径。 这种灵活的路由机制使得工作流能够适应不同的输入场景。

构建图 Agent

构建一个有效的图 Agent 需要经历三个关键步骤。这个过程既是技术性的， 也是创意性的——你需要思考如何最优地分解问题。

第一步：定义状态模式

在开始构建图 Agent 前，你需要明确定义在整个工作流中会用到哪些数据。 状态模式就像是你的工作流的"蓝图"，明确指出工作流需要处理哪些类型的数据、 每个数据字段的含义是什么、这些数据如何在节点间流动。

良好的状态设计应该：

• 清晰完整：包含所有必需的数据，避免遗漏
• 避免冗余：不要存储可以由其他数据派生出来的信息
• 易于扩展：当工作流演进时，容易添加新的状态字段

例如，在一个文档分析工作流中，你的状态可能包括用户的查询、文档内容、分析结果和最终答案。这样，无论工作流有多复杂，每个节点都能获取它需要的信息。

第二步：创建节点

完成状态设计后，接下来创建节点。每个节点都是工作流中的一个处理单元，你需要为它定义：

节点的职责 - 清晰地描述这个节点做什么。是分析用户意图、搜索数据库、调用 API，还是生成报告。

节点的配置 - 取决于节点类型：

• LLM 节点需要选择模型、设置温度参数（控制创意度）、编写系统提示
• 工具节点需要指定调用哪个外部服务或 API
• 路由节点需要定义判断条件

节点的输入输出 - 明确指出节点从状态中读取哪些字段，以及修改或添加哪些字段。

第三步：连接节点

节点创建完成后，你需要通过边（Edges）将它们连接起来，形成完整的工作流。这是最关键的一步，因为：

执行顺序 - 边决定了工作流的执行顺序。你需要思考：哪个节点应该先执行？哪个节点的输出是另一个节点的输入？

条件分支 - 通过添加条件边，你可以根据节点的输出进行分支。例如，在分析用户查询后，可以根据复杂度判断是直接回答还是进行深度分析。

错误处理 - 你可以添加错误处理分支，当某个节点执行失败时，工作流转向错误处理节点。

在可视化编辑器中，连接节点就像在 Figma 中绘制连线一样直观——拖拽从一个节点到另一个节点，然后配置边的条件（如果是条件边）。

实战示例：科研论文分析工作流

我们来看一个完整的实际案例，了解如何将上述概念应用到真实场景中。

这个工作流展示了图 Agent 的几个关键特性：

提取节点 - 首先解析上传的论文文件，提取其中的文本内容。这个节点调用文本处理工具，输出清理后的论文文本。

分析节点 - 接收用户的问题和论文文本，使用 LLM 分析这个问题的复杂度。分析的结果（一个 0-10 的分数）被保存到状态中。

路由分支 - 这是工作流的核心决策点。根据分析得出的复杂度分数：

• 如果是简单问题（比如"这篇论文的作者是谁"），直接进入快速回答路径
• 如果是复杂问题（比如"这篇论文与之前的研究相比有哪些创新"），进入深度分析路径

并行处理 - 两个分支最终汇聚到综合节点，无论采用哪个路径，最后都要生成最终答案。

优势 - 这个设计既保证了简单问题的快速响应（降低成本），又能处理复杂问题（提升质量）。

执行图 Agent

图 Agent 构建完成后，你可以通过两种方式执行它，取决于你的应用场景：

流式执行（WebSocket） - 这是实时交互式应用的首选。当用户在前端提交查询时，后端通过 WebSocket 连接向前端实时推送工作流的执行进度。这样用户可以看到：

• 当前正在执行哪个节点
• 节点的中间输出（如思考过程、数据库查询结果等）
• 最终答案生成的过程

这种方式特别适合需要用户交互、需要中间确认的场景。例如，在执行某个危险操作前，可以暂停工作流，等待用户确认。

同步执行（REST API） - 当你的应用是后端服务，或者不需要实时反馈时，可以直接调用 REST API。工作流会在后端完整执行，最后返回结果。这种方式更简单，适合批量处理任务。

关键区别：

• 流式执行适合用户交互场景，提升用户体验
• 同步执行适合服务端场景，更容易集成

无论选择哪种方式，Xyzen 都会自动记录执行过程、性能指标和消费成本，帮助你监控和优化工作流。