> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 飞书

> 在飞书中与智能体服务里的智能体对话。

飞书渠道通过 WebSocket 长连接接入，无需公网回调地址，本地或内网部署也能直接使用。目前飞书渠道的实现支持：

* **交互式卡片确认**：智能体调用需要审批的工具时，在飞书里以卡片形式请求确认，点击按钮即可批准或拒绝；
* **流式回复**：智能体的回答在同一条消息内逐步更新，边生成边呈现；
* **多模态输入**：接收用户发来的图片、文件、语音等消息，交给智能体处理；
* **Markdown 富文本**：回复支持 Markdown 渲染，超长内容自动分段。

接入分三步：在[飞书开放平台](https://open.feishu.cn/)创建应用并拿到凭据，启动一个智能体服务承载渠道，最后在管理界面添加飞书渠道。

## 前置条件

飞书渠道依赖 `lark-oapi`，随 `channel` 可选依赖安装：

```bash 安装依赖 theme={null}
pip install "agentscope[channel]"
```

## 创建应用

在[飞书开放平台](https://open.feishu.cn/)完成机器人的创建与配置，全程约几分钟。

<Steps>
  <Step title="创建企业自建应用">
    进入开发者后台，创建一个"企业自建应用"，填写名称与图标。
  </Step>

  <Step title="记录 App ID 与 App Secret">
    在"凭证与基础信息"页，复制 **App ID** 与 **App Secret**，稍后填入渠道配置。App Secret 是机密，请妥善保管。
  </Step>

  <Step title="启用机器人能力">
    在"添加应用能力"中启用"机器人"，机器人才能收发消息。
  </Step>

  <Step title="配置事件订阅（长连接）">
    在"事件与回调"页，订阅方式选择 **长连接**，无需填写回调地址。订阅"接收消息" `im.message.receive_v1` 事件；卡片确认还需订阅卡片回传交互 `card.action.trigger`。
  </Step>

  <Step title="申请权限">
    在"权限管理"中申请消息相关权限：接收消息、以应用身份发送消息（单聊与群聊）。若需要在配置路由时列出机器人所在的群，再申请获取群列表的权限。具体权限项以[飞书官方文档](https://open.feishu.cn/document/)为准。
  </Step>

  <Step title="发布版本">
    创建并发布应用版本，使其在企业内可用。之后即可把机器人加入群聊，或直接与它私聊。
  </Step>
</Steps>

## 启动智能体服务

渠道运行在[智能体服务](/versions/2.0.6dev/zh/deploy/agent-service)之上。用 `create_app` 启动服务，并用 `channels` 参数声明允许接入的渠道类型。渠道依赖消息总线（`message_bus`），单机开发用 `InMemoryMessageBus` 即可，多进程或多节点部署再换成 `RedisMessageBus`。

```python 启动承载渠道的智能体服务 theme={null}
from agentscope.app import create_app
from agentscope.app.channel import FeishuChannel
from agentscope.app.message_bus import InMemoryMessageBus
from agentscope.app.storage import RedisStorage
from agentscope.app.workspace_manager import LocalWorkspaceManager

app = create_app(
    storage=RedisStorage(host="localhost", port=6379),
    # 单机开发用内存消息总线；多节点部署换成 RedisMessageBus
    message_bus=InMemoryMessageBus(),
    workspace_manager=LocalWorkspaceManager(basedir="./workspaces"),
    channels=[FeishuChannel],   # 本服务允许接入的渠道类型
)
# 用 uvicorn 启动后，渠道功能即可用
# uvicorn.run(app, host="0.0.0.0", port=8000)
```

## 添加渠道

在智能体服务的管理界面（参见示例前端 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui)）中，通过可视化表单添加渠道，无需手写配置。

<Steps>
  <Step title="新建渠道并选择飞书">
    在渠道管理页新建一个渠道，平台类型选择"飞书"。
  </Step>

  <Step title="填入凭据">
    把上一步拿到的 **App ID** 与 **App Secret** 填入凭据表单。
  </Step>

  <Step title="配置路由规则">
    选择消息交给哪个智能体、会话如何划分。路由规则的含义见[会话路由](/versions/2.0.6dev/zh/deploy/channel/routing)。
  </Step>

  <Step title="保存并启用">
    保存后启用渠道，服务立即建立与飞书的长连接，机器人上线。把它加入群聊或发起私聊即可开始对话。
  </Step>
</Steps>

<Note>
  管理界面的操作对应一组 `/channels` 接口，需要以编程方式批量创建渠道时可直接调用，字段见本章 [API](/versions/2.0.6dev/en/deploy/openapi.json) 部分。
</Note>

## 平台配置

飞书渠道有一个平台专属开关：

| 字段                  | 说明                          | 默认值     |
| ------------------- | --------------------------- | ------- |
| `only_at_reply`     | 群聊中是否仅在被 @ 时才回复。私聊不受影响，始终回复 | `true`  |
| `show_thinking`     | 是否把模型的思考过程一并展示在回复里          | `false` |
| `show_tool_process` | 是否把工具调用与结果一并展示在回复里          | `false` |

<Tip>
  群聊里如果希望机器人像成员一样随时参与讨论，把 `only_at_reply` 关掉；默认开启可以避免机器人在群里过于活跃。
</Tip>

## 验证与排查

* 在管理界面查看渠道状态，或调用 `GET /channels/{id}/status` 确认长连接已建立。
* 若机器人在群里不响应，先确认 `only_at_reply` 与 @ 行为是否符合预期，再检查消息接收权限是否已申请并随版本发布。
* 若机器人完全不上线，检查 App ID / App Secret 是否正确、事件订阅是否设为长连接方式。

## 延伸阅读

<CardGroup cols={2}>
  <Card title="会话路由" icon="route" href="/versions/2.0.6dev/zh/deploy/channel/routing" cta="查看详情" arrow>
    把不同的群路由到不同的智能体。
  </Card>

  <Card title="Discord" icon="discord" href="/versions/2.0.6dev/zh/deploy/channel/discord" cta="查看详情" arrow>
    用同一套流程接入 Discord。
  </Card>
</CardGroup>