每天在飞书里总有一批工作像“数据搬运工”查多维表格里的状态帮业务同学把几十条记录汇总成计划表在群里回复“这个需求排到哪了”再把散落在各处的信息整合成一段结论。这些工作不复杂但非常消耗人。你可能会想能不能直接丢给大模型试过的人都知道把同样的问题发给豆包网页版得到的是一段流畅的通用回答但它不会打开你手里的真实表格也不会把结果发回群里。问题不在模型智力而在连接。大模型只会“说话”真正的工作发生在系统里。豆包、飞书、Agent 这三样东西放在一起解决的恰恰是“从会说话到会办事”这一段距离。这里的“豆包工作”我更愿意理解成一种工作形态以豆包大模型能力为底座通过 Agent 调度飞书业务数据和办公流程。它带来的变化不是多了一个问答入口而是把重复的人力操作变成一条可以被编排、被追踪、被重试的自动化链路。这也是它和普通聊天机器人的本质区别。我想先说清楚一个判断Agent 接上飞书价值不在闲聊而在“闭环”。一个用户发来消息Agent 能识别意图能去多维表格查数据能调用 API 完成任务还能把结果发回同一个群。这个感知、决策、执行、反馈的循环才算真正有用。如果你能把下面这条最小链路跑通就掌握了构建这类协作式 Agent 的基本方法。这篇博客会从核心概念、环境准备、流程拆解、代码实现、问题排查到工程建议逐步带你走完整个过程。文章里的示例以 Python 为主涉及飞书开放平台能力、豆包模型 API 和飞书多维表格既有能直接复制的代码也会解释每个设计选择背后的原因。1. 这篇文章真正要解决的问题很多人一开始会把“豆包 飞书”当成一个更聪明的聊天窗口来用。实际集成过一次就会发现真正的难点不在于模型会说话而在于三个问题。第一是身份问题。飞书里需要有一个人能看懂消息、能发消息、能查数据这个人对应的就是飞书自建应用里的机器人。如果没有这个身份模型能力再强也只是停留在网页问答它进不了群聊看不到内部数据也无法代表团队去执行操作。所以 Agent 化改造的第一步不是调模型 API而是先在飞书里建立一个属于应用的机器人身份并把消息收发的通道打通。第二是权限问题。机器人能读哪些可见范围能访问哪些多维表格能发送到哪些群聊都需要明确授权。技术链路通不通往往不取决于模型而取决于权限配置是否到位。很多人代码写得没错却因为应用没有发布版本、权限没有生效、表格没有加入可用范围在调试阶段浪费了大量时间。权限体系看似繁琐它其实是企业场景里保证安全的关键机制也是 Agent 能“放心做事”的前提。第三是事务问题。真实办公场景里数据往往是多个来源的。一个需求排期可能分布在三张多维表格里一个项目状态可能要拼外部的接口才能拿到。Agent 要处理的是这种“跨系统、带上下文”的任务而不是单轮闲聊。这要求开发者在设计阶段就规划好工具集。给 Agent 哪些工具、每个工具接收什么参数、返回什么结构都会直接影响最终效果。这篇文章想解决的核心痛点就是让一位对 Agent 开发感兴趣、但又不想从零造轮子的开发者能在飞书业务场景里快速搭建一个有生产价值的“数字同事”。读完你至少能回答四个问题飞书机器人和 Agent 之间是什么关系豆包模型能力怎么接到飞书事件链路中多维表格的数据怎么分页取出交给模型哪些环节最容易踩坑以及怎么排查。2. Agent 与飞书集成的核心概念2.1 豆包从对话模型到工具底座豆包是字节跳动推出的 AI 大模型产品系列面向开发者主要通过火山方舟平台提供模型调用能力。很多人的第一印象是“豆包是一个聊天工具”但在开发视角里它更重要的身份是 Agent 的决策引擎理解用户请求、拆解任务、决定调用哪些工具、解释工具返回的结果。模型本身不直接访问飞书数据也不直接操作业务系统它只是“大脑”真正执行动作的是你为它编写的工具函数。在工程上你其实不需要关心模型内部参数只需要按主流 chat completions 协议调用 API。这种兼容性的好处是接入成本低。你既可以直接写 HTTP 请求也可以用现成的模型 SDK。后面代码部分会演示最直接的 HTTP 调用方式方便你理解协议本身的交互流程。2.2 飞书开放平台机器人的身份与权限体系飞书开放平台允许开发者创建自建应用。一个自建应用并不只是一个“菜单入口”它同时提供四部分能力首先是机器人身份可以在群聊中收发消息其次是权限体系只授予应用需要的那部分数据访问能力然后是事件订阅把用户在群里的 消息实时推送给你的服务最后是开放 API包括多维表格、文档、云空间、日历、审批等大量业务接口。这几部分组合起来才构成 Agent 的“手”和“眼睛”。没有它们模型只是一个大脑看不到业务数据也无法影响真实世界。这里有一个容易混淆的点飞书机器人不是“接管一个飞书账号”。它出现在群里时是一个独立身份但这个身份背后是应用不占用真实员工账号也不会看到不该看的数据。它的权限完全由你配置可以在权限目录里最小化授权。2.3 Agent不是升级版聊天框Agent 目前没有统一的精确定义但在工程上它一般由四部分组成大模型负责理解和生成是“大脑”工具注册把真实的 API 封装成模型可以调用的一种函数描述任务规划让模型在复杂任务中把目标拆成多个子步骤记忆与上下文负责保存前面对话、业务数据、历史状态。为什么说“接上飞书后Agent 终于像个同事”因为同事之所以叫同事是因为他了解你的业务上下文能操作内部系统并且在固定渠道给你结果。之前的 Agent 更多停留在“很有知识的人”阶段但接上飞书的 Agent 第一次把身份、数据、工具、交付渠道全部打通了。它不再只给你建议而是直接给你结果。下表可以更直观地看出普通聊天机器人与接入飞书的 Agent 差异对比维度普通聊天机器人接入飞书的 Agent数据访问只能依赖训练数据可通过开放 API 读取多维表格等业务数据操作能力无可以调用工具完成查询、创建、更新等动作结果触达局限在聊天页面发送到飞书群聊可 相关人员可靠性生成结果不稳定有日志、可重试、可追踪业务身份无飞书内的机器人身份权限可控3. 环境准备与前置条件在写代码之前先把账号、环境和权限准备好。整个过程会用到两个平台账号火山方舟账号用于创建豆包模型推理接入点获取 API Key 和模型 ID飞书开放平台账号用于创建自建应用获取 App ID、App Secret并配置应用能力。如果你在团队里最好有飞书管理员权限或者让管理员协助创建应用并审核发布。很多权限校验问题其实是因为应用没有发布正式版本导致的。本文所有示例代码使用 Python 编写建议准备 Python 3.9 及以上版本、pip 包管理器、一个能运行 Python 的机器。本地开发即可不需要公网服务器前提是你使用飞书事件订阅的长连接模式。如果使用传统回调地址模式则需要准备一个可被飞书访问的公网 HTTPS 地址还要处理 URL 验证和加解密。对独立开发者来说长连接模式最省心它由飞书 SDK 主动建立连接事件会直接推送到本地进程本地调试体验很接近内网开发。开始编码前你需要在两个平台分别拿到四类信息# 火山方舟 ARK_API_KEYxxxx ARK_MODEL_IDxxxx # 飞书开放平台 FEISHU_APP_IDxxxx FEISHU_APP_SECRETxxxx这里的敏感信息要特别重视。App Secret 和 API Key 都属于核心凭证不要提交到 Git 仓库不要在网页代码里硬编码也不要出现在截图或日志中。建议放在本地环境变量或密钥管理服务中。后续文章示例代码里的os.getenv就是从环境变量读取这些值请先设置好再运行。4. 核心流程拆解从飞书机器人到 Agent 工作链路先描述整条链路用户在飞书群聊里 机器人 → 飞书事件订阅把消息推送到你的服务 → Agent 服务识别意图 → 需要查数据时调用多维表格 API → 把数据交给豆包模型生成回复 → 通过飞书 API 把回复发回群聊。整条链看起来不长但每一步都有独立的技术任务缺一环都不会有理想效果。4.1 在飞书开放平台创建自建应用登录飞书开放平台进入开发者后台创建企业自建应用。应用名称可以取“AI 工作助手”之类描述中说明用途。创建完成后你会在“凭证与基础信息”页面看到 App ID 和 App Secret。App ID 是应用的唯一标识App Secret 相当于应用的密码后面获取 tenant_access_token 时必须用到。4.2 开通机器人能力并配置权限在“添加应用能力”中开启“机器人”。然后进入“权限管理”按最小化原则开通权限。例如至少要包含与消息收发、文件读取相关的权限。如果 Agent 要访问多维表格就需要给对应应用开通多维表格读取权限并且把具体表格加入应用的可用范围。这一步是很多集成失败的高发区权限虽然加上了但没有创建版本并发布导致测试阶段调用 API 一直报权限错误。所以配置权限后一定要到“版本管理”里创建版本并发布到企业内部。发布后权限变更才真正生效API 调用才会返回正确结果。4.3 配置事件订阅在“事件订阅”中选择接收事件的方式。飞书支持回调地址和长连接两种方式。长连接模式适合本地开发和内网部署由 SDK 主动与飞书建立 WebSocket 连接事件直接推送到本地进程。回调地址模式需要公网可达且要处理好 URL 验证和加解密。订阅事件时至少要订阅“接收消息”事件。这样以后用户在群里 机器人你的服务就能收到消息。注意飞书群聊里的机器人通常需要被 才会触发推送这个设计是为了避免机器人收到群里所有消息。4.4 在火山方舟接入豆包模型在火山方舟控制台创建一个“推理接入点”选择豆包模型创建完成后会得到一个模型 ID。这个 ID 是调用 API 时的 model 参数。对 Agent 来说模型扮演的是“调度大脑”它会根据用户输入决定是否需要调用工具以及如何组织返回内容。为了让模型在飞书场景里表现稳定可以在系统提示词里明确告诉它你是一个飞书办公助手你的任务是帮助用户查询和分析业务数据。系统提示词不是摆设它会直接影响模型的回答风格和工具调用倾向。4.5 设计 Agent 的调度循环接好两边之后核心代码就是在飞书事件入口里实现一个调度循环接收用户消息把消息交给模型模型判断意图需要数据时调用已注册的工具把工具返回的数据拼回上下文让模型生成最终答复把答复发送回飞书群聊