# 自定义智能体接口概述

自定义智能体 OpenAPI 让你以编程方式与一个已发布的智能体交互：独立对话提问、多轮对话交互、管理会话、上传输入附件、下载智能体产出的文件，并校验智能体对当前用户的可见性。

## 典型场景

| 场景 | 调用顺序 |
|------|---------|
| 代用户向智能体提问，轮询拿结果 | 发起对话 → 获取对话结果 |
| 代用户向智能体提问，通过流式输出拿结果 | 发起对话（等待流式输出结果） |
| 提问时带上会话信息，通过多轮对话和智能体进行交互 | 发起对话（带上会话 ID） |
| 提问时带上用户的图片 / 文件 / 飞书云文档作为上下文 | 上传附件 → 发起对话 |
| 拉取智能体生成的图片、文件、飞书文档等产物 | 获取对话结果（拿 `agent_artifact_id`）→ 下载产物 |
| 校验当前用户在**指定渠道**(如web_sdk)下对智能体的可见性 | 校验可见性 |
| 创建一个空白会话，用于后续的多轮对话 | 创建会话 |
| 通过会话ID查询指定会话信息 | 查询指定会话信息 |
| 查询智能体当前的会话列表 | 查询会话列表 |
| 将之前的某一次会话删除 | 删除会话 |

## 前提条件

| 前提 | 说明 |
|------|------|
| 获取智能体AgentID | 通过智能体开发后台进入智能体，**通过浏览器地址栏中获取**。如https://xxx.feishu.cn/ai/custom_agent/agent_4k6wf15ngw7wu/builder/persona，AgentID是agent_4k6wf15ngw7wu |
| 智能体已开启 OpenAPI 渠道 | 由智能体管理员在**Aily后台-智能体详情-渠道管理**中开启 |
| 持有有效的 `user_access_token` 或 `tenant_access_token`| 通过请求头 `Authorization: Bearer <UAT>` 或 `Authorization: Bearer <TAT>` 传入 |
| 调用方与智能体同租户 | 仅能访问本租户内的智能体 |

## 接入流程

1. 智能体管理员开启 OpenAPI 渠道，并确认用户或调用的应用在可访问范围内
2. 应用在飞书开放平台申请所需权限（见“认证与权限”）
3. 携带 Authorization: Bearer <user_access_token> 或 Authorization: Bearer <tenant_access_token> 发起调用：
     1.  (可选)上传附件 —— 上传输入附件，拿到 agent_attachment_id
     2. 发起对话 —— 流式输出结果或拿到 agent_chat_id（异步）
     3. (可选) 轮询获取对话结果 —— 直到 status 进入终态（Completed / Failed）
     4. (如有产物)下载产物 —— 用获取对话结果返回的 agent_artifact_id 下载
     5. 会话管理 —— 支持会话的创建、删除、查询（指定会话和会话列表。）。

### 开启 OpenAPI渠道

**操作路径**：智能体编辑页 → 右上角「使用渠道」→ 打开**Open API 渠道**开关

![screenshot-20260701-165805.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/8036fdb366833b108c5d150192a8fb49_DAa2ALA6HU.png?lazyload=true&width=3840&height=1942)
![20260701-165830.jpeg](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/de8e2ea42d6715a6f00c9070a97c867a_mqjP2JZ3z7.jpeg?lazyload=true&width=3840&height=1934)

## 资源介绍

| 资源 | 说明 |
|------|------|
| **agent（智能体）** | 路径参数 `agent_id`，所有接口都挂在某个智能体下 |
| **session（会话）** | `agent_chat_session_id` 唯一标识 `用户→智能体` 多对话交互；一个会话可以对应多个对话轮次 |
| **chat（对话轮次）** | `agent_chat_id` 唯一标识一轮 `用户→智能体` 交互 |
| **attachment（输入附件）** | `agent_attachment_id`，调用方**上传**的输入资源（图片 / 文件 / 飞书云文档 / 多维表格），归属上传者，仅本人可引用 |
| **artifact（产物）** | `agent_artifact_id`，智能体**产出**的文件（如生成的图片、文件、飞书文档），区别于输入附件，有独立的下载接口 |

## 方法列表

资源 | API接口 | 所需权限 | 说明
---|---|---|---
session | <a href="https://open.larkoffice.com/document//uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_chat_session/create"/>创建会话 | 创建会话(aily:agent_chat:write) | 创建会话
session | <a href="https://open.larkoffice.com/document//uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_chat_session/create"/>删除会话 | 删除会话(aily:agent_chat:write) | 删除会话
session | <a href="https://open.larkoffice.com/document//uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_chat_session/create"/>查询指定会话信息 | 查询指定会话信息(aily:agent_chat:write) | 查询指定会话信息
session | <a href="https://open.larkoffice.com/document//uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_chat_session/create"/>查询会话列表 | 查询会话列表(aily:agent_chat:write) | 查询会话列表
chat | <a href="https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_chat/create"/>发起对话 | 发起对话(aily:agent_chat:write) | 发起一轮对话（流式输出或异步）
chat | <a href="https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_chat/get"/>获取对话结果 | 获取对话结果(aily:agent_chat:read) | 获取对话结果（状态与回复内容，轮询）
attachment | <a href="https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_attachment/create"/>上传附件 | 上传附件(aily:agent_attachment:write) | 上传附件
artifact | <a href="https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_artifact/get"/>下载智能体产物 | 下载智能体产物(aily:agent_artifact:read) | 获取智能体产物的下载 URL
agent | <a href="https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/aily-v1/agent-agent_visibility/check"/>校验可见性 | 校验可见性(aily:agent_visibility:read) | 校验当前用户在**指定渠道**（<code>channel_type</code>）下对智能体的可见性

## 错误码

| code | HTTP | 含义 |
|------|------|------|
| 10002 | 404 | chat 不存在 |
| 10006 | 403 | 智能体未开启 OpenAPI 渠道 |
| 10007 | 403 | 无权访问该智能体（非本租户）；或引用 / 操作了不属于你的附件 |
| 10008 | 403 | 当前租户未开通 OpenAPI 访问 |
| 10009 | 403 | 智能体未开启对应身份类型 |
| 10010 | 403 | 应用身份调用不在可调用范围内 |
| 10011 | 403 | 用户身份调用不在可见用范围内 |
| 50001 | 500 | 内部错误，联系技术支持 |