掘金 人工智能 13小时前
Eino ADK:构建智能Excel处理助手Excel Agent
index_new5.html
../../../zaker_core/zaker_tpl_static/wap/tpl_guoji1.html

 

本文详细介绍了如何利用Eino ADK(Agent Development Kit)构建一个名为Excel Agent的强大多智能体系统。Excel Agent能理解用户指令、处理Excel表格,并通过自动规划、工具调用和结果校验来稳定完成数据处理任务。文章深入剖析了Excel Agent的完整架构,包括Planner、Executor、CodeAgent、WebSearchAgent、Replanner和ReportAgent等核心组件的功能。同时,阐述了Eino ADK的ChatModelAgent(基于ReAct模式)、Plan-Execute Agent框架、Workflow Agents(SequentialAgent、LoopAgent、ParallelAgent)以及Agent抽象和数据传递机制(History、共享Session),展示了如何通过这些核心设计特点构建高效、灵活的AI应用系统。文章还通过一个提取CSV文件第一列的实际案例,演示了Excel Agent的运行流程、输入输出以及关键步骤的日志输出。

💡 **Excel Agent 的核心功能与架构**:Excel Agent 是一个智能助手,能够理解用户指令,处理 Excel 文件,并通过自动规划、工具调用和结果校验来完成数据处理任务。其架构包含 Planner(规划)、Executor(执行)、CodeAgent(代码执行)、WebSearchAgent(网络搜索)、Replanner(重规划)和 ReportAgent(报告生成)等多个智能体协同工作,以实现复杂任务的分解与执行。

🛠️ **Eino ADK 的关键设计理念**:Eino ADK 是构建 Excel Agent 的基础,其核心设计包括:ChatModelAgent(基于ReAct模式实现“思考-行动-观察”的链式推理)、Plan-Execute Agent框架(通过Planner、Executor、Replanner实现任务的结构化规划、执行与动态调整)、Workflow Agents(提供SequentialAgent、LoopAgent、ParallelAgent等编排方式实现Agent的有序运行),以及History和共享Session机制(支持Agent间高效的数据传递与协作)。

🚀 **Agent 协作与数据传递**:Eino ADK 强调 Agent 间的协作,通过 History 机制记录和传递 Agent 间的交互历史,以及共享 Session 来实现跨 Agent 的状态管理和数据共享。这使得多 Agent 系统能够有效地共享信息,避免上下文混乱,并支持复杂的任务流转,例如将 Agent 视为工具进行显式调用(ToolCall)或将任务移交至子 Agent(Transfer)。

📈 **实际应用案例与运行流程**:文章通过一个提取CSV文件第一列的实际任务,详细展示了Excel Agent从接收用户指令到最终生成报告的完整运行流程。这包括Planner生成任务计划、Executor调用CodeAgent执行代码、CodeAgent利用PythonRunner运行并根据ReAct模式自动纠错,以及Replanner判断任务完成并由ReportAgent进行总结,直观呈现了Agent系统的强大能力和可控性。

本文将会向您介绍如何利用 Eino ADK (Agent Development Kit) 构建一个强大的多智能体系统。

以 Excel Agent 这个实际业务场景为基础,Excel Agent 是一个能够“听懂你的话、看懂你的表格、写出并执行代码”的智能助手。它把复杂的 Excel 处理工作拆解为清晰的步骤,通过自动规划、工具调用与结果校验,稳定完成各项Excel数据处理任务。

接下来我们将从 Excel Agent 的完整架构与功能出发,向您展示该 Agent 是如何通过 Eino ADK 逐步搭建的,进而深入浅出的理解 Eino ADK 的核心设计特点,助您快速上手 Eino ADK,向构建自定义智能体与 AI 应用系统更进一步。

本示例完整代码位于 Github,您可以随时浏览与下载。

Excel Agent 是什么?

Excel Agent 是一个“看得懂 Excel 的智能助手”,它先把问题拆解成步骤,再一步步执行并校验结果。它能理解用户问题与上传的文件内容,提出可行的解决方案,并选择合适的工具(系统命令、生成并运行 Python 代码、网络查询等等)完成任务。

Excel Agent 整体是基于 Eino ADK 实现的 Multi-Agent 系统,完整架构如下图所示:

Excel Agent 内部包含的几个 Agent 功能分别为:

Excel Agent 的典型使用场景

在真实业务里,你可以把 Excel Agent 当成一位“Excel 专家 + 自动化工程师”。当你交付一个原始表格和目标描述,它会给出方案并完成执行:

Excel Agent 的完整运行动线为:

核心收益

Excel Agent 既可以单独使用,也可以作为子 Agent,集成在一个复合的多专家系统中,由外部路由到此 Agent 上,解决 excel 领域相关的问题。

下面我们将逐步拆解 Excel Agent,深入了解 Eino ADK 的核心设计特点,以及如何利用这些特点构建高效、灵活的 AI 应用系统。

ChatModelAgent:与 LLM 交互的基石

ChatModelAgent是 Eino ADK 中的一个核心预构建的 Agent,内部使用了 ReAct 模式(一种让模型‘思考-行动-观察’的链式推理模式):

ChatModelAgent旨在让 ChatModel 进行显式的、一步一步的“思考”,结合思考过程驱动行动,观测历史思考过程与行动结果继续进行下一步的思考与行动,最终解决复杂问题:

在 Excel Agent 中,每个 Agent 的核心都是这样一个 ChatModelAgent,以 Executor 运行【读取用户输入表格的头信息】这个步骤为例 ,我们可以通过观察完整的运行过程来理解 ReAct 模式在 ChatModelAgent中的表现:

    Executor:经过判断,将任务转交给 CodeAgent 运行

    CodeAgent:接收到任务【读取用户输入表格的头信息】

    运行完成,将表格头信息返回给 Executor

Plan-Execute Agent:基于「规划-执行-反思」的多智能体协作框架

Plan-Execute Agent 是 Eino ADK 中一种基于「规划-执行-反思」范式的多智能体协作框架,旨在解决复杂任务的分步拆解、执行与动态调整问题。它通过 Planner(规划器)、**Executor(执行器)**和 Replanner(重规划器) 三个核心智能体的协同工作,实现任务的结构化规划、工具调用执行、进度评估与动态 replanning,最终达成用户目标:

// 完整代码: https://github.com/cloudwego/eino/blob/main/adk/prebuilt/planexecute/plan_execute.go// NewPlanner creates a new planner agent based on the provided configuration.func NewPlanner(_ context.Context, cfg *PlannerConfig) (adk.Agent, error)// NewExecutor creates a new executor agent.func NewExecutor(ctx context.Context, cfg *ExecutorConfig) (adk.Agent, error)// NewReplanner creates a new replanner agent.func NewReplanner(_ context.Context, cfg *ReplannerConfig) (adk.Agent, error)// New creates a new plan-execute-replan agent with the given configuration.func New(ctx context.Context, cfg *Config) (adk.Agent, error)

而 Excel Agent 的核心能力恰好为【解决用户在 excel 领域的问题】,与该智能体协作框架定位一致:

Planner 和 Replanner 会将用户模糊的指令拆解为清晰的、可执行的步骤清单,即包含多个步骤(Step)的计划(Plan),Eino ADK 为此提供了灵活的 Plan 接口定义,支持用户自定义 Plan 结构与细节:

type Plan interface {    // FirstStep returns the first step to be executed in the plan.    FirstStep() string    // Marshaler serializes the Plan into JSON.    // The resulting JSON can be used in prompt templates.    json.Marshaler    // Unmarshaler deserializes JSON content into the Plan.    // This processes output from structured chat models or tool calls into the Plan structure.    json.Unmarshaler}

默认情况下,框架会使用内置的 Plan 结构作为兜底配置,例如下面就是 Excel Agent 产生的一个完整运行计划:

### 任务计划- [x] 1. Read the contents of '模拟出题.csv' from the working directory into a pandas DataFrame.- [x] 2. Identify the question type (e.g., multiple-choice, short-answer) for each row in the DataFrame.- [x] 3. For non-short-answer questions, restructure the data to place question, answer, explanation, and options in the same row.- [x] 4. For short-answer questions, merge the answer content into the explanation column and ensure question and merged explanation are in the same row.- [x] 5. Verify that all processed rows have question, answer (where applicable), explanation, and options (where applicable) in a single row with consistent formatting.- [x] 6. Generate a cleaned report presenting the formatted questions with all relevant components (question, answer, explanation, options) in unified rows.

Workflow Agents:可控的多 Agent 运行流水线

Excel Agent 中,存在一些需要按照特定顺序运行 agent 的情况:

    顺序运行:先运行 Planner,再运行 Executor 和 Replanner;Planner 只运行一次。

    循环运行:Executor 和 Replanner 需要按需循环运行多次,每次循环运行都是先运行 Executor 后运行 Replanner

    顺序运行:Plan-Executor 整体运行完后,固定运行一次 ReportAgent 进行总结。

对于这些拥有固定执行流程的场景,Eino ADK 提供了三种流程编排方式,协助用户快速搭建可控的工作流:

import github.com/cloudwego/eino/adk// 依次执行 制定研究计划 -> 搜索资料 -> 撰写报告sequential := adk.NewSequentialAgent(ctx, &adk.SequentialAgentConfig{    Name: "research_pipeline",    SubAgents: []adk.Agent{        planAgent,    // 制定研究计划        searchAgent,  // 搜索资料        writeAgent,   // 撰写报告    },})

import github.com/cloudwego/eino/adk// 循环执行 5 次,每次顺序为:分析当前状态 -> 提出改进方案 -> 验证改进效果loop := adk.NewLoopAgent(ctx, &adk.LoopAgentConfig{    Name: "iterative_optimization",    SubAgents: []adk.Agent{        analyzeAgent,  // 分析当前状态        improveAgent,  // 提出改进方案        validateAgent, // 验证改进效果    },    MaxIterations: 5,})

import github.com/cloudwego/eino/adk// 并发执行 情感分析 + 关键词提取 + 内容摘要parallel := adk.NewParallelAgent(ctx, &adk.ParallelAgentConfig{    Name: "multi_analysis",    SubAgents: []adk.Agent{        sentimentAgent,  // 情感分析        keywordAgent,    // 关键词提取        summaryAgent,    // 内容摘要    },})

Agent 抽象:灵活定义 Agent 的基础

Eino ADK 的核心是一个简洁而强大的 Agent 接口,每个 Agent 都有明确的身份(Name)、清晰的职责(Description)和标准化的执行方式(Run),为 Agent 之间的发现与调用提供了基础。无论是简单的问答机器人,还是复杂的多步骤任务处理系统,都可以通过这个统一的接口加以实现。

type Agent interface {    Name(ctx context.Context) string    Description(ctx context.Context) string    Run(ctx context.Context, input *AgentInput, options ...AgentRunOption) *AsyncIterator[*AgentEvent]}
type AgentInput struct {    Messages        []Message    EnableStreaming bool}type Message = *schema.Message // *schema.Message 是模型输入输出的结构定义
type AgentEvent struct {    AgentName string    // 产生 Event 的 Agent 名称(框架自动填充)    RunPath []RunStep   // 到达当前 Agent 的完整运行轨迹(框架自动填充)    Output *AgentOutput // Agent 输出消息内容    Action *AgentAction // Agent 动作事件内容    Err error           // Agent 报错}type AgentOutput struct {    MessageOutput *MessageVariant // 模型消息输出内容    CustomizedOutput any          // 自定义输出内容}type MessageVariant struct {    IsStreaming bool            // 是否为流式输出        Message       Message        // 非流式消息输出    MessageStream MessageStream  // 流式消息输出    Role schema.RoleType         // 消息角色    ToolName string              // 工具名称}type AgentAction struct {    Exit bool                               // Agent 退出    Interrupted *InterruptInfo              // Agent 中断    TransferToAgent *TransferToAgentAction  // Agent 跳转    CustomizedAction any                    // 自定义 Agent 动作}

异步迭代器允许 Agent 在运行过程中的任意时刻向迭代器发送消息(Agent 调用模型结果、工具运行结果、中间状态等等),同时调用方以一种有序、阻塞的方式消费这一系列事件:

iter := myAgent.Run(ctx, "hello") // get AsyncIteratorfor {    event, ok := iter.Next()    if !ok {        break    }    // handle event}

Agent 协作:隐藏在 Agent 后的数据传递

Excel Agent 架构图中的节点代表每个具体的 Agent,边代表了数据流通与任务转移。在构建多 Agent 系统时,让不同 Agent 之间高效、准确地共享信息至关重要。

这些信息不仅包含 Agent 的输入输出,还有全局的、部分可见的种种额外信息,例如:

Eino ADK 包含两种基础的数据传递机制:

// Agent 内获取全部 SessionValuesfunc GetSessionValues(ctx context.Context) map[string]any// Agent 内指定 key 获取 SessionValues 中的值func GetSessionValue(ctx context.Context, key string) (any, bool)// Agent 内添加 SessionValuesfunc AddSessionValue(ctx context.Context, key string, value any)// Agent 内批量添加 SessionValuesfunc AddSessionValues(ctx context.Context, kvs map[string]any)// WithSessionValues 在 Agent 运行前由外部注入 SessionValuesfunc WithSessionValues(v map[string]any) AgentRunOption

除了完善的 Agent 间数据传递机制,Eino ADK 从实践出发,提供了多种 Agent 协作模式:

// 设置父子 Agent 关系func SetSubAgents(ctx context.Context, agent Agent, subAgents []Agent) (Agent, error)// 指定目标 Agent 名称,构造 Transfer Eventfunc NewTransferToAgentAction(destAgentName string) *AgentAction

// 将 Agent 转换为 Toolfunc NewAgentTool(_ context.Context, agent Agent, options ...AgentToolOption) tool.BaseTool

Excel Agent 示例运行

配置环境与输入输出路径

func main() {    // query := schema.UserMessage("统计附件文件中推荐的小说名称及推荐次数,并将结果写到文件中。凡是带有《》内容都是小说名称,形成表格,表头为小说名称和推荐次数,同名小说只列一行,推荐次数相加")    // query := schema.UserMessage("读取模拟出题.csv 中的内容,规范格式将题目、答案、解析、选项放在同一行,简答题只把答案写入解析即可")    query := schema.UserMessage("请帮我将 question.csv 表格中的第一列提取到一个新的 csv 中")}
% tree adk/multiagent/integration-excel-agent/playground/test_dataadk/multiagent/integration-excel-agent/playground/test_data├── questions.csv├── 推荐小说.txt└── 模拟出题.csv1 directory, 3 files

查看运行结果

Excel Agent 单次运行会在输出路径下创建一个新的工作目录,并在该目录下完成任务,运行时产生的中间产物与最终结果都会写到该目录下。

请帮我将 question.csv 表格中的第一列提取到一个新的 csv 中这个任务为例,运行完成后在工作目录下包含的内容有:

    原始输入:从输入路径获取到的 question.csv

    Planner / Replanner 给出的运行计划:plan.md

### 任务计划- [x] 1. {"desc":"Read the 'questions.csv' file into a pandas DataFrame."}- [x] 2. Save the extracted first column to a new CSV file.
    Executor 中的 CodeAgent 书写的代码:$uuid.py
import pandas as pddf = pd.read_csv('questions.csv')first_column = df.iloc[:, 0]first_column.to_csv('extracted_first_column.csv', index=False)
    运行中间产物:extracted_first_column.csvfirst_column.csv
typemultiple-choice...short-answer
    最终报告:final_report.json
{  "is_success": true,  "result": "Successfully extracted the first column from questions.csv and saved it to first_column.csv.",  "files": [    {      "path": "/User/user/go/src/github.com/cloudwego/eino-examples/adk/multiagent/integration-excel-agent/playground/00f118af-4bd8-42f7-8d11-71f2801218bd/first_column.csv",      "desc": "A CSV file containing only the first column data from the original questions.csv."    }  ]}

运行过程输出

Excel Agent 会将每个步骤的运行结果输出到日志中。下面仍以请帮我将 question.csv 表格中的第一列提取到一个新的 csv 中这个任务为例,向您展示 Excel Agent 在运行过程中的几个关键步骤及其输出,并通过对步骤的解释,直观地呈现 Agent 的运行流程及其强大能力。:

name: Planneranswer: {    "steps": [        {            "index": 1,            "desc": "Read the 'questions.csv' file into a pandas DataFrame."        },        {            "index": 2,            "desc": "Extract the first column from the DataFrame."        },        {            "index": 3,            "desc": "Save the extracted first column to a new CSV file."        }    ]}
name: Executortool name: CodeAgentarguments: {"request":"Read the 'questions.csv' file into a pandas DataFrame using pandas. Use the pandas.read_csv function and store the result in a variable named df."}
# CodeAgent 使用 PythonRunner 工具运行代码name: Executortool name: PythonRunnerarguments: {"code":"```python\nfirst_column = df.iloc[:, 0]\n```"}# PythonRunner 代码运行报错name: Executortool response: Traceback (most recent call last):  File "/User/user/go/src/github.com/cloudwego/eino-examples/adk/multiagent/integration-excel-agent/playground/00f118af-4bd8-42f7-8d11-71f2801218bd/00f118af-4bd8-42f7-8d11-71f2801218bd.py", line 1, in <module>    first_column = df.iloc[:, 0]                   ^^NameError: name 'df' is not defined# ReAct 模式自动纠错,修正无法运行的代码name: Executoranswer: The error occurs because the DataFrame `df` is not defined. We need to first load the data from the existing CSV file `questions.csv` into `df`. Here's the corrected code:tool name: PythonRunnerarguments: {"code":"```python\nimport pandas as pd\ndf = pd.read_csv('questions.csv')\nfirst_column = df.iloc[:, 0]\nprint(first_column.head())  # Verify the result\n```"}# 代码运行成功,返回运行结果name: Executorpath: [{SequentialAgent} {plan_execute_replan} {Planner} {execute_replan} {Executor}]tool response: 0    multiple-choice1    multiple-choice2    multiple-choice3    multiple-choice4    multiple-choiceName: type, dtype: object
name: Replanneranswer: {    "is_success": true,    "result": "已成功将'questions.csv'表格中的第一列提取到新的CSV文件'extracted_first_column.csv'中。",    "files": [        {            "desc": "包含原表格第一列数据的新CSV文件",            "path": "extracted_first_column.csv"        }    ]}
name: Reporttool name: SubmitResultarguments: {    "is_success": true,    "result": "Successfully extracted the first column from questions.csv and saved it to first_column.csv.",    "files": [        {            "path": "/User/user/go/src/github.com/cloudwego/eino-examples/adk/multiagent/integration-excel-agent/playground/00f118af-4bd8-42f7-8d11-71f2801218bd/first_column.csv",            "desc": "A CSV file containing only the first column data from the original questions.csv."        }    ]}

总结

Excel Agent 所呈现的并非“单一智能体”的技巧,而是一套以 Eino ADK 为底座的 Multi-Agent 系统工程化方法论:

💡 立即开始你的智能体开发之旅

Eino ADK,让智能体开发变得简单而强大!

参考资料

[1] ReAct: react-lm.github.io/

[2] Eino 示例代码: github.com/cloudwego/e…

[3] Eino ADK 文档: www.cloudwego.io/zh/docs/ein…

[4] Eino ADK 源码: github.com/cloudwego/e…

[5] Eino ADK Examples: github.com/cloudwego/e…

Fish AI Reader

Fish AI Reader

AI辅助创作,多种专业模板,深度分析,高质量内容生成。从观点提取到深度思考,FishAI为您提供全方位的创作支持。新版本引入自定义参数,让您的创作更加个性化和精准。

FishAI

FishAI

鱼阅,AI 时代的下一个智能信息助手,助你摆脱信息焦虑

联系邮箱 441953276@qq.com

相关标签

Eino ADK Multi-Agent System Excel Agent AI Agent Development LLM ReAct Workflow Automation Data Processing
相关文章