豆包工作这类 Agent 产品的出现正在把办公软件从一个“工具型平台”变成“智能执行平台”。本文会从字节跳动发布豆包工作、并与飞书深度打通这一产品动态出发拆解 AI Agent 在办公协作场景中的技术定位然后落到工程实践如何基于飞书开放能力自己搭建一个能接受指令、读取数据、写回结果的 Agent 工作流。文章包含完整的环境准备、Python 代码示例、飞书机器人接入、多维表格操作、MCP/Skill 概念辨析、常见问题排查和工程建议。无论你是技术负责人、后端开发还是刚接触 Agent 的入门学习者都可以从这篇文章找到可直接迁移的思路。1. 为什么“豆包工作”值得关注Agent 与办公协作的碰撞1.1 从大模型到工作场景的距离过去两年大模型的能力已经有目共睹能写文案、能总结文档、能生成 SQL。但真正把大模型放到业务中我们会发现一个很现实的问题模型只是能“理解”和“生成内容”它不会主动打开飞书文档不会把结论写进多维表格也不会在消息群里回复你“任务已完成”。这就是 LLM 和 Agent 的最大区别。大模型是“大脑”能思考Agent 是“大脑 手和脚”能根据目标规划步骤并且调用外部工具完成实际操作。字节跳动推出的“豆包工作”Agent 产品正是把豆包大模型的“大脑”和飞书的“手和脚”结合起来。它的核心价值不是多了一个聊天入口而是让自然语言指令可以直接联动工作流。如果你打开最新热词你会发现“飞书多维表格”“Agent 开发”“豆包工作”这些词高频出现。因为大家已经意识到未来的办公自动化不再只是管理员配置几个自动化机器人而是业务人员用一句话就能驱动一堆工具协同完成工作。1.2 豆包工作是什么适合谁从公开信息和产品形态来看豆包工作是字节跳动基于豆包大模型能力推出的 Agent 产品方向是工作协作场景。它与飞书深度打通意味着用户可以在飞书中通过自然语言完成诸如总结某个群聊中的关键决策读取多维表格中的任务数据并给出分析自动生成会议纪要并同步到文档根据日历安排创建待办事项在文档中自定义生成内容并同步给团队成员。这适合谁如果你是普通办公用户它能降低使用复杂办公功能的门槛如果你是开发者更值得关注的是它背后的 Agent 产品设计思路一个 Agent 应该怎么理解用户意图、拆解任务、调用工具、反馈结果。1.3 与飞书深度打通意味着什么飞书本身就是非常完整的办公协作平台拥有消息、文档、多维表格、日历、会议、审批等多维能力。豆包工作与飞书深度打通不是简单地在飞书里加一个 AI 对话框而是让 Agent 可以理解飞书中的结构化数据并反向写入。换句话说飞书提供的不是“一个入口”而是“一套执行环境”。对开发者来说这是很好的产品样板Agent 真正有价值的场景往往不是纯粹的聊天而是它能否像人一样操作企业内部的数字化工具。想要做到这一点Agent 必须能接入开放平台的 API有能力读写业务数据。所以本文后半部分会手把手带大家搭建一个“仿豆包工作思路”的 Agent 工程让大模型通过飞书机器人接收任务再调用多维表格 API 读写数据最终把执行结果回到消息场景。2. Agent 产品核心概念拆解2.1 什么是 AI AgentAI Agent智能体可以理解为一种能够“自主完成目标”的智能程序。它不只是回答一个问题而是会围绕目标进行任务拆解、工具调用和结果校验。一个完整的 Agent 通常包含以下几个要素感知接收用户输入、环境信息或系统状态决策由大模型驱动生成行动计划和拆分步骤行动通过工具调用更改外部状态例如调用 API、操作数据库反馈把执行结果返回给用户或继续优化下一步。举个例子当你对 Agent 说“帮我整理多维表格里所有未完成任务并按优先级发到群里”Agent 的决策链路大致是提取用户意图整理未完成任务确定数据源定位多维表格定义筛选条件根据状态字段筛选未完成调用飞书 API 读取数据对结果进行排序和摘要将最终消息发送到指定群。可见Agent 的价值在于“复用已有工具系统”而大模型只负责其中最关键的决策和生成部分。2.2 Agent 的核心模块无论产品如何包装一个 Agent 系统在工程上基本会包含下面几个模块模块作用常见实现输入解析识别用户意图并提取关键参数LLM Function Calling任务规划拆解复杂任务为子步骤ReAct、Plan-and-Execute工具调用执行外部动作读取/写入数据Function Call、MCP、HTTP API状态记忆保存上下文与多轮执行状态Memory、向量数据库、多维表格结果反馈将执行结果输出给用户消息卡片、文本、文档安全控制校验用户权限、执行边界RBAC、审批流、限流实际做 Agent 产品时“状态记忆”和“安全控制”往往比“大模型提示词”更关键。很多 Agent 在上线初期表现不错但一旦用户多、任务长就会出现上下文丢失、工具调用权限混乱、错误执行等问题。2.3 Agent 与单纯聊天机器人的区别最早的飞书机器人也好微信机器人也好本质是“关键词应答”用户输入某个命令机器人执行固定逻辑。这种方式没有智能决策只能处理定义好的分支。而 Agent 形态的机器人不同它的区别在于能理解非结构化指令不需要用户严格按命令格式输入能动态选择工具而不是把每种场景写死在代码里能拆解复杂任务而不是只处理单轮问答能处理失败和异常例如调用 API 失败后调整策略。所以在设计 Agent 时最忌讳的思路是“把所有业务逻辑都塞进提示词”。更合理的方式是让大模型负责“调度”让飞书 API 负责“执行”让多维表格负责“状态”。3. 飞书为什么适合做 Agent 的“操作台”3.1 飞书开放能力的整体框架飞书开放平台是飞书面向开发者提供的接口体系覆盖了企业协作的核心对象。从 Agent 集成的角度看最常用的是四类能力机器人通过 Webhook 或事件订阅接收消息也可以主动发送消息文档创建、读取、编辑云文档多维表格以 API 方式读写表格数据通讯录与权限识别用户身份、校验组织架构权限。这种能力矩阵正好对应 Agent 的“感知 - 决策 - 行动 - 反馈”链路感知用户发送消息触发机器人事件 决策大模型理解用户意图规划步骤 行动调用多维表格 API、文档 API 等完成数据操作 反馈机器人将结果回复给用户/群聊3.2 飞书机器人与事件订阅在飞书中机器人是用户和 Agent 之间最常用的交互入口。一般有两种交互模式Webhook 模式外部系统通过 Webhook 地址主动推送消息到群里事件订阅模式飞书平台在用户发消息、群活跃时把事件推送给你配置的回调地址。对 Agent 来说事件订阅模式更合适因为它是双向交互用户发消息触发事件Agent 处理后通过 API 回复。Webhook 模式更适合单向通知例如 CI/CD 构建结束后推送给飞书群。首次接入时推荐使用“长连接”模式不是必须公网 IP。其中飞书在开发阶段也支持通过回调地址调试但如果你本地没有公网服务建议先用长连接方式避免在内网穿透上花太多时间。现代飞书开放平台对长连接模式的兼容度更高开发调试也更简单。3.3 多维表格Agent 的“记忆”与“数据库”多维表格Bitable是飞书里非常重要的结构化数据能力。它介于 Excel 和数据库之间对业务人员友好又提供完整的 API 操作能力。对 Agent 来说多维表格的定位非常独特可以保存任务的中间状态作为 Agent 的记忆可以记录 Agent 执行过的工具调用日志可以维护权限范围内的业务数据让 Agent 基于结构化字段做筛选、更新、统计。例如你可以创建一张“任务记录”多维表格字段包含任务标题、负责人、状态、优先级、截止日期。Agent 接到用户“帮我找出高优先级且未完成的任务”指令时实际就是调用list recordsAPI 读取数据在代码或大模型中完成筛选使用消息卡片返回结果。所以不要只把多维表格当成“Excel 的替代品”在 Agent 系统中它是低成本、高易用性的业务数据库。4. 环境准备与前置条件4.1 注册飞书企业自建应用要开发一个能操作飞书数据的 Agent我们首先要创建一个飞书应用。进入飞书开放平台选择“开发者后台”创建企业自建应用。这里要注意自建应用默认只有应用自身权限对外部 API 的调用需要单独申请权限应用凭证App ID 和 App Secret是后续调用 API 的身份证建议把应用设置为“测试企业”或“可用成员范围”受限避免开发阶段影响全公司。创建完成后你可以在“凭证与基础信息”页面看到App ID: cli_xxxxxxxxxxxxxxxx App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4.2 获取凭证与权限接下来我们需要在“权限管理”页面开通以下权限contact:user.base:readonly读取用户基础信息如果需要识别成员im:message:send_as_bot以机器人身份发送消息bitable:app读写多维表格数据docx:document读写文档按需开通。不同版本的飞书后台可能权限名称略有差异开通时以控制台展示为准。权限开通后并不立即生效。其中部分接口需要发布应用版本由管理员审核后才生效开发阶段可以用“测试企业”下直接生效的配置。4.3 本地开发环境下面是用 Python 做示例版本建议 Python 3.9另外需要准备requests库pip install requests项目目录可以参考agent-feishu-demo/ ├── main.py # 入口接收指令并分发 ├── client.py # 飞书 API 封装 ├── agent.py # Agent 调度逻辑 ├── bitable.py # 多维表格操作 ├── config.py # 配置App ID / Secret 等 └── requirements.txt版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。5. 实战搭建一个可运行的 Agent 工作流这一节我们做一个能跑通全流程的示例。目标场景是用户在飞书群里对机器人说“把多维表格中所有未完成任务统计给我”Agent 接收到消息后调用多维表格 API 筛选数据并向群里返回结果。为了降低复杂度我们先不接大模型而是用规则映射实现一个“最小 Agent 调度器”。这样方便理解Agent 工程骨架后续再替换成大模型决策也更容易。5.1 飞书 API 客户端封装首先封装飞书 API 的基础请求逻辑。# 文件路径agent-feishu-demo/client.py import requests class FeishuClient: def __init__(self, app_id: str, app_secret: str): self.app_id app_id self.app_secret app_secret self.tenant_access_token None def _get_token(self) - str: url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal payload { app_id: self.app_id, app_secret: self.app_secret, } resp requests.post(url, jsonpayload, timeout10) data resp.json() if data.get(code) ! 0: raise RuntimeError(f获取 token 失败: {data}) return data[tenant_access_token] def get_token(self) - str: if not self.tenant_access_token: self.tenant_access_token self._get_token() return self.tenant_access_token def request(self, method: str, path: str, **kwargs): url fhttps://open.feishu.cn/open-apis{path} headers kwargs.pop(headers, {}) headers[Authorization] fBearer {self.get_token()} return requests.request(method, url, headersheaders, timeout15, **kwargs)这里关键是tenant_access_token。飞书 API 使用应用身份调用时需要先通过 App ID 和 App Secret 换取租户访问令牌。为了避免每次请求都换取我们在客户端内存中缓存了 token。需要注意真实生产环境要考虑 token 过期时间通常是 2 小时缓存时最好记录过期时间而不是永远缓存。这里为了示例简洁只做内存缓存。5.2 Agent 调度器Agent 调度器的职责是根据用户输入决定调用哪一个工具。# 文件路径agent-feishu-demo/agent.py import re class Agent: def __init__(self, tool_map: dict): self.tool_map tool_map def dispatch(self, text: str) - str: # 这是一个极简的意图识别实际项目可替换为大模型 Function Calling if 未完成任务 in text or 统计任务 in text: tool_name query_unfinished_tasks elif 创建任务 in text or 添加任务 in text: tool_name create_task else: return 抱歉我还没有学会这个操作。 if tool_name not in self.tool_map: return 没有找到对应工具。 tool self.tool_map[tool_name] try: return tool() except Exception as e: return f工具执行失败{e}实际项目中dispatch方法应该由大模型担任。你可以通过 Function Calling 把工具列表传给模型模型根据用户描述自动选择工具和参数。这里用规则匹配是为了先跑通工程流程。5.3 读取多维表格数据接下来封装多维表格操作。你需要提前创建一个多维表格并从 URL 中获取app_token和table_id。例如多维表格 URL 为https://xxx.feishu.cn/base/{app_token}?table{table_id}那么代码可以这样写# 文件路径agent-feishu-demo/bitable.py import json class BitableClient: def __init__(self, client, app_token: str, table_id: str): self.client client self.app_token app_token self.table_id table_id def list_records(self, page_size: int 100) - list: path f/bitable/v1/apps/{self.app_token}/tables/{self.table_id}/records params {page_size: page_size} resp self.client.request(GET, path, paramsparams) data resp.json() if data.get(code) ! 0: raise RuntimeError(f读取多维表格失败: {data}) return data[data][items]这里需要区分“table_id”是多维表格中具体数据表的 ID不是“多维表格的 app_token”。一个多维表格可以包含多张数据表所以两者不能混淆。5.4 编写主流程现在把各模块串起来# 文件路径agent-feishu-demo/main.py from client import FeishuClient from bitable import BitableClient from agent import Agent APP_ID cli_xxxxxxxxxxxxxxxx APP_SECRET xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx APP_TOKEN bascnxxxxxxxxxxxxxxxx TABLE_ID tblxxxxxxxxxxxxxxxx client FeishuClient(APP_ID, APP_SECRET) bitable BitableClient(client, APP_TOKEN, TABLE_ID) def query_unfinished_tasks() - str: records bitable.list_records() unfinished [] for record in records: fields record.get(fields, {}) # 假设多维表格里字段名为“状态”状态值为“未开始”或“已完成” if fields.get(状态) ! 已完成: title fields.get(任务名称, 未命名任务) unfinished.append(title) if not unfinished: return 恭喜暂无未完成任务。 return 未完成任务如下\n \n.join(f- {item} for item in unfinished) def create_task() - str: # 示例中的创建任务函数后续可扩展为写入多维表格 return 创建任务功能正在开发中。 if __name__ __main__: agent Agent({ query_unfinished_tasks: query_unfinished_tasks, create_task: create_task, }) # 模拟用户输入 user_input 帮我统计未完成任务 print(agent.dispatch(user_input))这段代码虽然还没有真实接入飞书消息事件但已经跑通了“用户输入 - Agent 调度 - 工具调用 - 结果返回”的最小闭环。你可以先用命令行测试python main.py预期输出类似未完成任务如下 - 设计评审文档 - 性能压测报告 - 客户演示材料5.5 接入飞书机器人消息要把命令行的 Agent 变成真正可用的飞书机器人还需要两步创建机器人并开启事件订阅接收用户消息解析 text 内容后调用agent.dispatch再把结果通过机器人 API 回复。发送消息的 API 是# 在 client.py 中添加方法 def send_message(self, receive_id: str, text: str): path /im/v1/messages payload { receive_id_type: open_id, msg_type: text, receive_id: receive_id, content: f{{text: {text}}}, } resp self.request(POST, path, jsonpayload) return resp.json()说明content字段是 JSON 字符串而不是 Python 字典。这是飞书消息 API 的一个常见坑点很多新手在这里会调不通。当你配置好事件订阅用户发消息事件会推送到你的服务或长连接回调中。你只需要req_body request.json() event req_body[event] message event[message] text message[content] # 这里也是 JSON 字符串 user_open_id event[sender][sender_id][open_id] # 解析消息 text json.loads(text).get(text, ) # 调度 Agent result agent.dispatch(text) # 回复用户 feishu_client.send_message(user_open_id, result)到这里一个最简单的“飞书消息 - Agent - 工具调用 - 回复消息”闭环就完成了。6. 进阶让 Agent 写回多维表格6.1 创建记录接口Agent 的一个关键优势是不仅能读还能写。例如用户说“创建任务6 月 30 日前完成新版首页设计”我们需要创建一条多维表格记录。飞书多维表格创建记录的接口POST /bitable/v1/apps/{app_token}/tables/{table_id}/records请求体示例{ fields: { 任务名称: 新版首页设计, 负责人: 张三, 状态: 未开始, 截止日期: 1719676800000 } }注意多维表格中的日期字段如果字段类型是“日期”API 一般要求传入毫秒级时间戳而不是字符串。这一点很容易踩坑。6.2 在 BitableClient 中添加创建方法def create_record(self, fields: dict) - dict: path f/bitable/v1/apps/{self.app_token}/tables/{self.table_id}/records payload {fields: fields} resp self.client.request(POST, path, jsonpayload) data resp.json() if data.get(code) ! 0: raise RuntimeError(f创建记录失败: {data}) return data[data][record]6.3 完善 Agent 工具现在我们可以在create_task函数里真正写入数据def create_task(text: str) - str: # 正常场景应由大模型从用户输入中提取结构化字段 # 这里先用简单规则模拟 fields { 任务名称: text.replace(创建任务, ), 状态: 未开始, } try: record bitable.create_record(fields) record_id record.get(record_id, ) return f任务已创建记录 ID{record_id} except Exception as e: return f创建任务失败{e}到这里Agent 已经有能力把用户指令转化为多维表格数据。如果结合大模型做字段抽取就可以实现更自然的交互。6.4 让 Agent 形成工作闭环如果继续扩展还可以做这样的事根据截止日期自动提醒未完成任务每当多维表格状态更新时自动通知群里的负责人把每周统计结果定时发送到管理群。这些都不需要改 Agent 核心结构只要新增工具函数注册到tool_map即可。这也体现了 Agent 架构的扩展性核心调度逻辑保持稳定工具层可以持续增加。7. 引入 MCP 与 SkillAgent 能力扩展思路7.1 MCP 解决什么问题在 Agent 开发里MCPModel Context Protocol模型上下文协议经常和“工具调用”一起出现。如果把工具调用比作“每个服务自己定义的接口”那么 MCP 就是“统一对接标准”。举例来说飞书提供一个 MCP ServerAgent 不用去关心每个 API 的鉴权方式、参数结构而是通过协议标准去发现和调用可用的飞书工具。这对企业来说非常友好开发一次 Agent就能在多个支持 MCP 的客户端里复用同样的飞书能力。不过MCP 并不等于 Agent。MCP 更偏向“连接层”它解决的是 Agent 如何发现和调用工具的问题Agent 本身依然需要意图理解、任务规划、结果反馈这些能力。7.2 Skill 与 MCP 的区别Skill 通常指“某一类任务的能力包”。例如“会议纪要 Skill”可能包含读取会议录音转写结果调用大模型生成结构化纪要写入飞书文档发送通知给参会人。而 MCP 解决的是“这个 Skill 如何调用外部系统”的协议问题。你可以理解成Skill 是“做什么”的抽象MCP 是“怎么连接”的标准。在工程落地时我们一般先编排 Skill再把 Skill 内部依赖的外部系统通过 MCP 或 API Client 接入。你不需要在所有项目里都引入 MCP如果企业已有规范化的 API 层直接封装成工具函数也可以。7.3 多 Agent 协作的编排思路豆包工作这样的产品后续大概率会支持多 Agent 协作一个 Agent 负责理解需求一个 Agent 负责操作文档另一个 Agent 负责数据分析。多 Agent 协作时最重要的是明确“通信机制”和“共享状态”。最简单的落地方式就是共用一张多维表格每个 Agent 有独立的agent_id任务表记录任务状态、负责人 Agent、输入输出高优先级 Agent 只读任务表中分配给自己的记录。这样设计的好处是Agent 之间不直接互相调用而是通过数据表解耦。即使某个 Agent 崩溃其他 Agent 依然可以根据任务状态继续工作。8. 常见问题与排查思路在开发飞书 Agent 的过程中最容易遇到的几个问题如下。问题现象常见原因解决思路获取 token 失败返回 10003App ID 不存在或 App Secret 错误检查应用凭证是否正确API 返回权限不足错误未在权限管理开通对应 API 权限开通权限后重新发布应用版本发送消息报 invalid content消息 content 不是合法的 JSON 字符串用json.dumps({text: text})而不是原始 dict多维表格读取不到数据app_token 或 table_id 错误从 URL 中复制正确的两个 ID长连接接不到事件事件订阅没添加“接收消息”事件在事件配置中添加im.message.receive_v1Agent 回复太慢每次请求都重新获取 token缓存 tenant_access_token 并处理过期时间日期字段写不进去传入了字符串日期而不是时间戳转换为毫秒级时间戳8.1 消息解析的坑很多同学在飞书机器人事件回调里解析消息时会遇到下面的问题message event[message] content message[content] # content 实际是字符串类似 {text:你好}表面上看是 dict其实是 JSON 字符串。必须用json.loads(content)解析。同理发送消息时content字段也必须先序列化成 JSON 字符串否则飞书 API 会报错。8.2 权限生效延迟飞书后台开通权限后并不是马上生效。自建应用需要创建版本并发布由管理员审批后新权限才会生效。在开发阶段建议使用“测试企业”或配置应用可用范围为测试成员避免频繁走发布流程。这里也需要强调涉及读取通讯录、消息内容、业务数据时应该遵守最小权限原则。只申请当前功能必需的权限不要一次性开通所有只读、写权限更不要把 App Secret 放到前端代码或公开仓库中。8.3 调试建议推荐先使用飞书开放平台的“API 调试台”验证单接口再把调试通过的参数复制到代码中。这样可以快速定位问题究竟是参数错误、权限不足还是代码逻辑问题。9. 工程落地中的最佳实践9.1 权限与安全边界Agent 的能力越大权限风险越大。如果一个 Agent 能被群里任意成员触发还能写多维表格那权限控制必须仔细设计。几个建议为 Agent 使用独立的自建应用不与公司其他应用共用一个凭证在应用配置中限制可用成员范围对敏感操作删除数据、批量更新、调用审批增加二次确认在 Agent 层记录操作人和操作内容方便审计。9.2 异常处理与重试策略Agent 调用 API 时网络抖动、频率限制、数据校验失败都是常态。不要假设一次调用必然成功。建议封装统一的调用函数对 429 限流错误做指数退避重试对 4xx 参数错误直接返回失败原因不重试对 5xx 服务端错误可重试 2 到 3 次记录失败日志并给用户明确反馈。9.3 可观测性与日志Agent 的决策链路比普通接口更长出现问题往往难以定位。建议记录以下关键链路信息request_id: user_open_id: user_input: selected_tool: tool_params: tool_result: error_message: duration_ms:日志中不要记录敏感信息例如 App Secret、用户详细消息内容等。如果必须记录建议脱敏。9.4 把 Agent 当调度器而不是执行器最后一条工程建议是不要在 Agent 内部写太多复杂业务代码。一个成熟的架构应该是Agent负责语义理解、任务规划、结果组装工具层负责调用飞书 API、数据库、业务系统数据层负责记录任务状态、Agent 记忆、执行日志。这样拆分之后大模型的升级、工具的替换、业务逻辑的调整可以互不影响。豆包工作与飞书深度打通本质上也是在做同一件事让大模型负责“调度”让飞书负责“执行”让数据在各模块之间有序流动。9.5 注意生产环境的变更规范如果你的 Agent 接入了生产环境的多维表格并且具备写入、删除、批量更新能力建议先在小范围测试确认数据模型和流程没有问题后再扩大可用范围。涉及生产数据的变更操作优先使用“模拟数据”或“测试表格”验证并为多维表格定期备份数据。10. 小结与进一步学习方向从豆包工作与飞书深度打通这个产品事件我们能看到 Agent 在办公协作场景中的落地路径越来越清晰。Agent 的真正价值不取决于模型多强大而取决于它能否安全、准确地调用真实业务工具。本文以飞书开放平台为例完整搭建了一个最小 Agent 工作流从飞书应用创建、API 封装、Agent 调度器设计到多维表格数据读写和机器人消息接入。核心思路可以概括成一句话让大模型负责决策让 API 负责执行让结构化数据表负责记忆。如果你想继续深入建议按下面几个方向学习飞书开放平台更多 API文档、日历、审批、云盘能力Function Calling 和提示词工程把规则匹配的调度器替换成大模型决策MCP 协议统一不同业务系统的工具接入标准多 Agent 协作框架用多维表格作为共享状态实现多个 Agent 的异步协作Agent 安全权限模型、操作审计、敏感动作二次确认。办公协作是 Agent 落地最快、最高频的场景之一。与其等待别人的产品完善不如现在就从飞书开放平台开始搭建一个属于你自己的智能工作助手。以后遇到重复性协作任务比如统计任务、整理文档、同步信息都可以交给 Agent 去跑。如果这篇教程对你有帮助欢迎收藏备用后续可以继续拆解更多 Agent 实战细节。
豆包工作这类 Agent 产品的出现正在把办公软件从一个“工具型平台”变成“智能执行平台”。本文会从字节跳动发布豆包工作、并与飞书深度打通这一产品动态出发拆解 AI Agent 在办公协作场景中的技术定位然后落到工程实践如何基于飞书开放能力自己搭建一个能接受指令、读取数据、写回结果的 Agent 工作流。文章包含完整的环境准备、Python 代码示例、飞书机器人接入、多维表格操作、MCP/Skill 概念辨析、常见问题排查和工程建议。无论你是技术负责人、后端开发还是刚接触 Agent 的入门学习者都可以从这篇文章找到可直接迁移的思路。1. 为什么“豆包工作”值得关注Agent 与办公协作的碰撞1.1 从大模型到工作场景的距离过去两年大模型的能力已经有目共睹能写文案、能总结文档、能生成 SQL。但真正把大模型放到业务中我们会发现一个很现实的问题模型只是能“理解”和“生成内容”它不会主动打开飞书文档不会把结论写进多维表格也不会在消息群里回复你“任务已完成”。这就是 LLM 和 Agent 的最大区别。大模型是“大脑”能思考Agent 是“大脑 手和脚”能根据目标规划步骤并且调用外部工具完成实际操作。字节跳动推出的“豆包工作”Agent 产品正是把豆包大模型的“大脑”和飞书的“手和脚”结合起来。它的核心价值不是多了一个聊天入口而是让自然语言指令可以直接联动工作流。如果你打开最新热词你会发现“飞书多维表格”“Agent 开发”“豆包工作”这些词高频出现。因为大家已经意识到未来的办公自动化不再只是管理员配置几个自动化机器人而是业务人员用一句话就能驱动一堆工具协同完成工作。1.2 豆包工作是什么适合谁从公开信息和产品形态来看豆包工作是字节跳动基于豆包大模型能力推出的 Agent 产品方向是工作协作场景。它与飞书深度打通意味着用户可以在飞书中通过自然语言完成诸如总结某个群聊中的关键决策读取多维表格中的任务数据并给出分析自动生成会议纪要并同步到文档根据日历安排创建待办事项在文档中自定义生成内容并同步给团队成员。这适合谁如果你是普通办公用户它能降低使用复杂办公功能的门槛如果你是开发者更值得关注的是它背后的 Agent 产品设计思路一个 Agent 应该怎么理解用户意图、拆解任务、调用工具、反馈结果。1.3 与飞书深度打通意味着什么飞书本身就是非常完整的办公协作平台拥有消息、文档、多维表格、日历、会议、审批等多维能力。豆包工作与飞书深度打通不是简单地在飞书里加一个 AI 对话框而是让 Agent 可以理解飞书中的结构化数据并反向写入。换句话说飞书提供的不是“一个入口”而是“一套执行环境”。对开发者来说这是很好的产品样板Agent 真正有价值的场景往往不是纯粹的聊天而是它能否像人一样操作企业内部的数字化工具。想要做到这一点Agent 必须能接入开放平台的 API有能力读写业务数据。所以本文后半部分会手把手带大家搭建一个“仿豆包工作思路”的 Agent 工程让大模型通过飞书机器人接收任务再调用多维表格 API 读写数据最终把执行结果回到消息场景。2. Agent 产品核心概念拆解2.1 什么是 AI AgentAI Agent智能体可以理解为一种能够“自主完成目标”的智能程序。它不只是回答一个问题而是会围绕目标进行任务拆解、工具调用和结果校验。一个完整的 Agent 通常包含以下几个要素感知接收用户输入、环境信息或系统状态决策由大模型驱动生成行动计划和拆分步骤行动通过工具调用更改外部状态例如调用 API、操作数据库反馈把执行结果返回给用户或继续优化下一步。举个例子当你对 Agent 说“帮我整理多维表格里所有未完成任务并按优先级发到群里”Agent 的决策链路大致是提取用户意图整理未完成任务确定数据源定位多维表格定义筛选条件根据状态字段筛选未完成调用飞书 API 读取数据对结果进行排序和摘要将最终消息发送到指定群。可见Agent 的价值在于“复用已有工具系统”而大模型只负责其中最关键的决策和生成部分。2.2 Agent 的核心模块无论产品如何包装一个 Agent 系统在工程上基本会包含下面几个模块模块作用常见实现输入解析识别用户意图并提取关键参数LLM Function Calling任务规划拆解复杂任务为子步骤ReAct、Plan-and-Execute工具调用执行外部动作读取/写入数据Function Call、MCP、HTTP API状态记忆保存上下文与多轮执行状态Memory、向量数据库、多维表格结果反馈将执行结果输出给用户消息卡片、文本、文档安全控制校验用户权限、执行边界RBAC、审批流、限流实际做 Agent 产品时“状态记忆”和“安全控制”往往比“大模型提示词”更关键。很多 Agent 在上线初期表现不错但一旦用户多、任务长就会出现上下文丢失、工具调用权限混乱、错误执行等问题。2.3 Agent 与单纯聊天机器人的区别最早的飞书机器人也好微信机器人也好本质是“关键词应答”用户输入某个命令机器人执行固定逻辑。这种方式没有智能决策只能处理定义好的分支。而 Agent 形态的机器人不同它的区别在于能理解非结构化指令不需要用户严格按命令格式输入能动态选择工具而不是把每种场景写死在代码里能拆解复杂任务而不是只处理单轮问答能处理失败和异常例如调用 API 失败后调整策略。所以在设计 Agent 时最忌讳的思路是“把所有业务逻辑都塞进提示词”。更合理的方式是让大模型负责“调度”让飞书 API 负责“执行”让多维表格负责“状态”。3. 飞书为什么适合做 Agent 的“操作台”3.1 飞书开放能力的整体框架飞书开放平台是飞书面向开发者提供的接口体系覆盖了企业协作的核心对象。从 Agent 集成的角度看最常用的是四类能力机器人通过 Webhook 或事件订阅接收消息也可以主动发送消息文档创建、读取、编辑云文档多维表格以 API 方式读写表格数据通讯录与权限识别用户身份、校验组织架构权限。这种能力矩阵正好对应 Agent 的“感知 - 决策 - 行动 - 反馈”链路感知用户发送消息触发机器人事件 决策大模型理解用户意图规划步骤 行动调用多维表格 API、文档 API 等完成数据操作 反馈机器人将结果回复给用户/群聊3.2 飞书机器人与事件订阅在飞书中机器人是用户和 Agent 之间最常用的交互入口。一般有两种交互模式Webhook 模式外部系统通过 Webhook 地址主动推送消息到群里事件订阅模式飞书平台在用户发消息、群活跃时把事件推送给你配置的回调地址。对 Agent 来说事件订阅模式更合适因为它是双向交互用户发消息触发事件Agent 处理后通过 API 回复。Webhook 模式更适合单向通知例如 CI/CD 构建结束后推送给飞书群。首次接入时推荐使用“长连接”模式不是必须公网 IP。其中飞书在开发阶段也支持通过回调地址调试但如果你本地没有公网服务建议先用长连接方式避免在内网穿透上花太多时间。现代飞书开放平台对长连接模式的兼容度更高开发调试也更简单。3.3 多维表格Agent 的“记忆”与“数据库”多维表格Bitable是飞书里非常重要的结构化数据能力。它介于 Excel 和数据库之间对业务人员友好又提供完整的 API 操作能力。对 Agent 来说多维表格的定位非常独特可以保存任务的中间状态作为 Agent 的记忆可以记录 Agent 执行过的工具调用日志可以维护权限范围内的业务数据让 Agent 基于结构化字段做筛选、更新、统计。例如你可以创建一张“任务记录”多维表格字段包含任务标题、负责人、状态、优先级、截止日期。Agent 接到用户“帮我找出高优先级且未完成的任务”指令时实际就是调用list recordsAPI 读取数据在代码或大模型中完成筛选使用消息卡片返回结果。所以不要只把多维表格当成“Excel 的替代品”在 Agent 系统中它是低成本、高易用性的业务数据库。4. 环境准备与前置条件4.1 注册飞书企业自建应用要开发一个能操作飞书数据的 Agent我们首先要创建一个飞书应用。进入飞书开放平台选择“开发者后台”创建企业自建应用。这里要注意自建应用默认只有应用自身权限对外部 API 的调用需要单独申请权限应用凭证App ID 和 App Secret是后续调用 API 的身份证建议把应用设置为“测试企业”或“可用成员范围”受限避免开发阶段影响全公司。创建完成后你可以在“凭证与基础信息”页面看到App ID: cli_xxxxxxxxxxxxxxxx App Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4.2 获取凭证与权限接下来我们需要在“权限管理”页面开通以下权限contact:user.base:readonly读取用户基础信息如果需要识别成员im:message:send_as_bot以机器人身份发送消息bitable:app读写多维表格数据docx:document读写文档按需开通。不同版本的飞书后台可能权限名称略有差异开通时以控制台展示为准。权限开通后并不立即生效。其中部分接口需要发布应用版本由管理员审核后才生效开发阶段可以用“测试企业”下直接生效的配置。4.3 本地开发环境下面是用 Python 做示例版本建议 Python 3.9另外需要准备requests库pip install requests项目目录可以参考agent-feishu-demo/ ├── main.py # 入口接收指令并分发 ├── client.py # 飞书 API 封装 ├── agent.py # Agent 调度逻辑 ├── bitable.py # 多维表格操作 ├── config.py # 配置App ID / Secret 等 └── requirements.txt版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。5. 实战搭建一个可运行的 Agent 工作流这一节我们做一个能跑通全流程的示例。目标场景是用户在飞书群里对机器人说“把多维表格中所有未完成任务统计给我”Agent 接收到消息后调用多维表格 API 筛选数据并向群里返回结果。为了降低复杂度我们先不接大模型而是用规则映射实现一个“最小 Agent 调度器”。这样方便理解Agent 工程骨架后续再替换成大模型决策也更容易。5.1 飞书 API 客户端封装首先封装飞书 API 的基础请求逻辑。# 文件路径agent-feishu-demo/client.py import requests class FeishuClient: def __init__(self, app_id: str, app_secret: str): self.app_id app_id self.app_secret app_secret self.tenant_access_token None def _get_token(self) - str: url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal payload { app_id: self.app_id, app_secret: self.app_secret, } resp requests.post(url, jsonpayload, timeout10) data resp.json() if data.get(code) ! 0: raise RuntimeError(f获取 token 失败: {data}) return data[tenant_access_token] def get_token(self) - str: if not self.tenant_access_token: self.tenant_access_token self._get_token() return self.tenant_access_token def request(self, method: str, path: str, **kwargs): url fhttps://open.feishu.cn/open-apis{path} headers kwargs.pop(headers, {}) headers[Authorization] fBearer {self.get_token()} return requests.request(method, url, headersheaders, timeout15, **kwargs)这里关键是tenant_access_token。飞书 API 使用应用身份调用时需要先通过 App ID 和 App Secret 换取租户访问令牌。为了避免每次请求都换取我们在客户端内存中缓存了 token。需要注意真实生产环境要考虑 token 过期时间通常是 2 小时缓存时最好记录过期时间而不是永远缓存。这里为了示例简洁只做内存缓存。5.2 Agent 调度器Agent 调度器的职责是根据用户输入决定调用哪一个工具。# 文件路径agent-feishu-demo/agent.py import re class Agent: def __init__(self, tool_map: dict): self.tool_map tool_map def dispatch(self, text: str) - str: # 这是一个极简的意图识别实际项目可替换为大模型 Function Calling if 未完成任务 in text or 统计任务 in text: tool_name query_unfinished_tasks elif 创建任务 in text or 添加任务 in text: tool_name create_task else: return 抱歉我还没有学会这个操作。 if tool_name not in self.tool_map: return 没有找到对应工具。 tool self.tool_map[tool_name] try: return tool() except Exception as e: return f工具执行失败{e}实际项目中dispatch方法应该由大模型担任。你可以通过 Function Calling 把工具列表传给模型模型根据用户描述自动选择工具和参数。这里用规则匹配是为了先跑通工程流程。5.3 读取多维表格数据接下来封装多维表格操作。你需要提前创建一个多维表格并从 URL 中获取app_token和table_id。例如多维表格 URL 为https://xxx.feishu.cn/base/{app_token}?table{table_id}那么代码可以这样写# 文件路径agent-feishu-demo/bitable.py import json class BitableClient: def __init__(self, client, app_token: str, table_id: str): self.client client self.app_token app_token self.table_id table_id def list_records(self, page_size: int 100) - list: path f/bitable/v1/apps/{self.app_token}/tables/{self.table_id}/records params {page_size: page_size} resp self.client.request(GET, path, paramsparams) data resp.json() if data.get(code) ! 0: raise RuntimeError(f读取多维表格失败: {data}) return data[data][items]这里需要区分“table_id”是多维表格中具体数据表的 ID不是“多维表格的 app_token”。一个多维表格可以包含多张数据表所以两者不能混淆。5.4 编写主流程现在把各模块串起来# 文件路径agent-feishu-demo/main.py from client import FeishuClient from bitable import BitableClient from agent import Agent APP_ID cli_xxxxxxxxxxxxxxxx APP_SECRET xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx APP_TOKEN bascnxxxxxxxxxxxxxxxx TABLE_ID tblxxxxxxxxxxxxxxxx client FeishuClient(APP_ID, APP_SECRET) bitable BitableClient(client, APP_TOKEN, TABLE_ID) def query_unfinished_tasks() - str: records bitable.list_records() unfinished [] for record in records: fields record.get(fields, {}) # 假设多维表格里字段名为“状态”状态值为“未开始”或“已完成” if fields.get(状态) ! 已完成: title fields.get(任务名称, 未命名任务) unfinished.append(title) if not unfinished: return 恭喜暂无未完成任务。 return 未完成任务如下\n \n.join(f- {item} for item in unfinished) def create_task() - str: # 示例中的创建任务函数后续可扩展为写入多维表格 return 创建任务功能正在开发中。 if __name__ __main__: agent Agent({ query_unfinished_tasks: query_unfinished_tasks, create_task: create_task, }) # 模拟用户输入 user_input 帮我统计未完成任务 print(agent.dispatch(user_input))这段代码虽然还没有真实接入飞书消息事件但已经跑通了“用户输入 - Agent 调度 - 工具调用 - 结果返回”的最小闭环。你可以先用命令行测试python main.py预期输出类似未完成任务如下 - 设计评审文档 - 性能压测报告 - 客户演示材料5.5 接入飞书机器人消息要把命令行的 Agent 变成真正可用的飞书机器人还需要两步创建机器人并开启事件订阅接收用户消息解析 text 内容后调用agent.dispatch再把结果通过机器人 API 回复。发送消息的 API 是# 在 client.py 中添加方法 def send_message(self, receive_id: str, text: str): path /im/v1/messages payload { receive_id_type: open_id, msg_type: text, receive_id: receive_id, content: f{{text: {text}}}, } resp self.request(POST, path, jsonpayload) return resp.json()说明content字段是 JSON 字符串而不是 Python 字典。这是飞书消息 API 的一个常见坑点很多新手在这里会调不通。当你配置好事件订阅用户发消息事件会推送到你的服务或长连接回调中。你只需要req_body request.json() event req_body[event] message event[message] text message[content] # 这里也是 JSON 字符串 user_open_id event[sender][sender_id][open_id] # 解析消息 text json.loads(text).get(text, ) # 调度 Agent result agent.dispatch(text) # 回复用户 feishu_client.send_message(user_open_id, result)到这里一个最简单的“飞书消息 - Agent - 工具调用 - 回复消息”闭环就完成了。6. 进阶让 Agent 写回多维表格6.1 创建记录接口Agent 的一个关键优势是不仅能读还能写。例如用户说“创建任务6 月 30 日前完成新版首页设计”我们需要创建一条多维表格记录。飞书多维表格创建记录的接口POST /bitable/v1/apps/{app_token}/tables/{table_id}/records请求体示例{ fields: { 任务名称: 新版首页设计, 负责人: 张三, 状态: 未开始, 截止日期: 1719676800000 } }注意多维表格中的日期字段如果字段类型是“日期”API 一般要求传入毫秒级时间戳而不是字符串。这一点很容易踩坑。6.2 在 BitableClient 中添加创建方法def create_record(self, fields: dict) - dict: path f/bitable/v1/apps/{self.app_token}/tables/{self.table_id}/records payload {fields: fields} resp self.client.request(POST, path, jsonpayload) data resp.json() if data.get(code) ! 0: raise RuntimeError(f创建记录失败: {data}) return data[data][record]6.3 完善 Agent 工具现在我们可以在create_task函数里真正写入数据def create_task(text: str) - str: # 正常场景应由大模型从用户输入中提取结构化字段 # 这里先用简单规则模拟 fields { 任务名称: text.replace(创建任务, ), 状态: 未开始, } try: record bitable.create_record(fields) record_id record.get(record_id, ) return f任务已创建记录 ID{record_id} except Exception as e: return f创建任务失败{e}到这里Agent 已经有能力把用户指令转化为多维表格数据。如果结合大模型做字段抽取就可以实现更自然的交互。6.4 让 Agent 形成工作闭环如果继续扩展还可以做这样的事根据截止日期自动提醒未完成任务每当多维表格状态更新时自动通知群里的负责人把每周统计结果定时发送到管理群。这些都不需要改 Agent 核心结构只要新增工具函数注册到tool_map即可。这也体现了 Agent 架构的扩展性核心调度逻辑保持稳定工具层可以持续增加。7. 引入 MCP 与 SkillAgent 能力扩展思路7.1 MCP 解决什么问题在 Agent 开发里MCPModel Context Protocol模型上下文协议经常和“工具调用”一起出现。如果把工具调用比作“每个服务自己定义的接口”那么 MCP 就是“统一对接标准”。举例来说飞书提供一个 MCP ServerAgent 不用去关心每个 API 的鉴权方式、参数结构而是通过协议标准去发现和调用可用的飞书工具。这对企业来说非常友好开发一次 Agent就能在多个支持 MCP 的客户端里复用同样的飞书能力。不过MCP 并不等于 Agent。MCP 更偏向“连接层”它解决的是 Agent 如何发现和调用工具的问题Agent 本身依然需要意图理解、任务规划、结果反馈这些能力。7.2 Skill 与 MCP 的区别Skill 通常指“某一类任务的能力包”。例如“会议纪要 Skill”可能包含读取会议录音转写结果调用大模型生成结构化纪要写入飞书文档发送通知给参会人。而 MCP 解决的是“这个 Skill 如何调用外部系统”的协议问题。你可以理解成Skill 是“做什么”的抽象MCP 是“怎么连接”的标准。在工程落地时我们一般先编排 Skill再把 Skill 内部依赖的外部系统通过 MCP 或 API Client 接入。你不需要在所有项目里都引入 MCP如果企业已有规范化的 API 层直接封装成工具函数也可以。7.3 多 Agent 协作的编排思路豆包工作这样的产品后续大概率会支持多 Agent 协作一个 Agent 负责理解需求一个 Agent 负责操作文档另一个 Agent 负责数据分析。多 Agent 协作时最重要的是明确“通信机制”和“共享状态”。最简单的落地方式就是共用一张多维表格每个 Agent 有独立的agent_id任务表记录任务状态、负责人 Agent、输入输出高优先级 Agent 只读任务表中分配给自己的记录。这样设计的好处是Agent 之间不直接互相调用而是通过数据表解耦。即使某个 Agent 崩溃其他 Agent 依然可以根据任务状态继续工作。8. 常见问题与排查思路在开发飞书 Agent 的过程中最容易遇到的几个问题如下。问题现象常见原因解决思路获取 token 失败返回 10003App ID 不存在或 App Secret 错误检查应用凭证是否正确API 返回权限不足错误未在权限管理开通对应 API 权限开通权限后重新发布应用版本发送消息报 invalid content消息 content 不是合法的 JSON 字符串用json.dumps({text: text})而不是原始 dict多维表格读取不到数据app_token 或 table_id 错误从 URL 中复制正确的两个 ID长连接接不到事件事件订阅没添加“接收消息”事件在事件配置中添加im.message.receive_v1Agent 回复太慢每次请求都重新获取 token缓存 tenant_access_token 并处理过期时间日期字段写不进去传入了字符串日期而不是时间戳转换为毫秒级时间戳8.1 消息解析的坑很多同学在飞书机器人事件回调里解析消息时会遇到下面的问题message event[message] content message[content] # content 实际是字符串类似 {text:你好}表面上看是 dict其实是 JSON 字符串。必须用json.loads(content)解析。同理发送消息时content字段也必须先序列化成 JSON 字符串否则飞书 API 会报错。8.2 权限生效延迟飞书后台开通权限后并不是马上生效。自建应用需要创建版本并发布由管理员审批后新权限才会生效。在开发阶段建议使用“测试企业”或配置应用可用范围为测试成员避免频繁走发布流程。这里也需要强调涉及读取通讯录、消息内容、业务数据时应该遵守最小权限原则。只申请当前功能必需的权限不要一次性开通所有只读、写权限更不要把 App Secret 放到前端代码或公开仓库中。8.3 调试建议推荐先使用飞书开放平台的“API 调试台”验证单接口再把调试通过的参数复制到代码中。这样可以快速定位问题究竟是参数错误、权限不足还是代码逻辑问题。9. 工程落地中的最佳实践9.1 权限与安全边界Agent 的能力越大权限风险越大。如果一个 Agent 能被群里任意成员触发还能写多维表格那权限控制必须仔细设计。几个建议为 Agent 使用独立的自建应用不与公司其他应用共用一个凭证在应用配置中限制可用成员范围对敏感操作删除数据、批量更新、调用审批增加二次确认在 Agent 层记录操作人和操作内容方便审计。9.2 异常处理与重试策略Agent 调用 API 时网络抖动、频率限制、数据校验失败都是常态。不要假设一次调用必然成功。建议封装统一的调用函数对 429 限流错误做指数退避重试对 4xx 参数错误直接返回失败原因不重试对 5xx 服务端错误可重试 2 到 3 次记录失败日志并给用户明确反馈。9.3 可观测性与日志Agent 的决策链路比普通接口更长出现问题往往难以定位。建议记录以下关键链路信息request_id: user_open_id: user_input: selected_tool: tool_params: tool_result: error_message: duration_ms:日志中不要记录敏感信息例如 App Secret、用户详细消息内容等。如果必须记录建议脱敏。9.4 把 Agent 当调度器而不是执行器最后一条工程建议是不要在 Agent 内部写太多复杂业务代码。一个成熟的架构应该是Agent负责语义理解、任务规划、结果组装工具层负责调用飞书 API、数据库、业务系统数据层负责记录任务状态、Agent 记忆、执行日志。这样拆分之后大模型的升级、工具的替换、业务逻辑的调整可以互不影响。豆包工作与飞书深度打通本质上也是在做同一件事让大模型负责“调度”让飞书负责“执行”让数据在各模块之间有序流动。9.5 注意生产环境的变更规范如果你的 Agent 接入了生产环境的多维表格并且具备写入、删除、批量更新能力建议先在小范围测试确认数据模型和流程没有问题后再扩大可用范围。涉及生产数据的变更操作优先使用“模拟数据”或“测试表格”验证并为多维表格定期备份数据。10. 小结与进一步学习方向从豆包工作与飞书深度打通这个产品事件我们能看到 Agent 在办公协作场景中的落地路径越来越清晰。Agent 的真正价值不取决于模型多强大而取决于它能否安全、准确地调用真实业务工具。本文以飞书开放平台为例完整搭建了一个最小 Agent 工作流从飞书应用创建、API 封装、Agent 调度器设计到多维表格数据读写和机器人消息接入。核心思路可以概括成一句话让大模型负责决策让 API 负责执行让结构化数据表负责记忆。如果你想继续深入建议按下面几个方向学习飞书开放平台更多 API文档、日历、审批、云盘能力Function Calling 和提示词工程把规则匹配的调度器替换成大模型决策MCP 协议统一不同业务系统的工具接入标准多 Agent 协作框架用多维表格作为共享状态实现多个 Agent 的异步协作Agent 安全权限模型、操作审计、敏感动作二次确认。办公协作是 Agent 落地最快、最高频的场景之一。与其等待别人的产品完善不如现在就从飞书开放平台开始搭建一个属于你自己的智能工作助手。以后遇到重复性协作任务比如统计任务、整理文档、同步信息都可以交给 Agent 去跑。如果这篇教程对你有帮助欢迎收藏备用后续可以继续拆解更多 Agent 实战细节。
