AutoGPT Platform Airtable Bases 模块指南：Create Base 与 List Bases Block 全解析

在 AutoGPT Platform 的可视化 Agent 编排体系中，Airtable 集成模块负责将外部 Airtable 数据接入自动化工作流。Bases 是 Airtable 中的顶层容器——所有的表（Table）、记录（Record）与数据都挂在某个 Base 之下。本指南基于仓库文档 docs/integrations/block-integrations/airtable/bases.md，结合平台 Block 的源码实现，系统讲解「Airtable Create Base」（创建/查找 Base）与「Airtable List Bases」（列出 Base）两个 Block 的能力边界、输入输出契约与底层调用链，帮助你掌握在 AutoGPT 工作流中编程化搭建 Airtable 数据结构的完整方法。

---

一、模块定位：Bases 在 Airtable 集成中的位置

在 Airtable 的数据模型里，Base（库）是最顶层的容器，向下包含 Table（表）与 Record（记录）。AutoGPT Platform 的 Airtable 集成层围绕这一模型拆分为四类 Block 文档：

• bases.md（本文主体）：Base 的创建与枚举；
• schema.md：表结构（字段）管理；
• records.md：记录级增删改查；
• triggers.md：基于 Airtable Webhook 的触发能力。

对应到代码仓库，四个文档分别由 autogpt_platform/backend/backend/blocks/airtable/ 目录下的 bases.py、schema.py、records.py、triggers.py 实现。其中 Base 管理相关的两个 Block 定义于 bases.py，并且通过同名文件被平台按块（Block）注册到可视化编辑器中，供拖拽编排使用。

两个 Base Block 属于 BlockCategory.DATA 数据类目：

Block 类名	文档名称	实现 Block ID
AirtableCreateBaseBlock	Airtable Create Base	f59b88a8-54ce-4676-a508-fd614b4e8dce
AirtableListBasesBlock	Airtable List Bases	4bd8d466-ed5d-4e44-8083-97f25a8044e7

说明：Block ID 是平台上每个块实例的唯一标识，可在编辑器内定位该块的定义与持久化配置。

---

二、Airtable Create Base：创建或查找一个 Base

2.1 能力说明（What it is）

Airtable Create Base 的作用是在指定 Airtable workspace（工作区）中创建一个新 Base，或者查找同名的既有 Base。创建时，你可以选择性地传入初始表（Table）及其字段（Field）定义，一次性完成 Base 级 Schema 初始化，无需创建后再逐表配置。

2.2 工作原理（How it works）

从源码实现看，该 Block 的完整运行逻辑位于 AirtableCreateBaseBlock.run，核心分两步：

1. 查重（可选）：当 find_existing 为 true（代码中默认值即为 True，见 bases.py 输入定义）时，Block 会先调用 list_bases() 拉取当前账号可见的全部 Base，并逐个按 name 与目标名称比对。由于 Airtable API 本身不提供按名称搜索的接口（源码注释明确说明 Airtable API doesn't have a direct search），因此查重只能通过「先全量枚举再过滤」实现：
   • 若命中同名 Base：直接输出该 Base 的 id，置 was_created=False，随后尝试通过 get_base_tables() 读取该 Base 的表结构并逐个输出；若读取失败则兜底输出空表列表（tables: []）后结束；
   • 若未命中：继续进入创建分支。
2. 创建（否则新建）：调用底层 create_base()，向 Airtable Meta API 发送创建请求，成功后输出新 Base 的 id，置 was_created=True，并输出返回的表结构。

底层三个 API 函数的实现均位于 _api.py：

• create_base()：POST https://api.airtable.com/v0/meta/bases，请求体携带 name、workspaceId，以及可选的 tables 数组；
• list_bases()：GET https://api.airtable.com/v0/meta/bases，支持透传 offset 分页参数；
• get_base_tables()：GET https://api.airtable.com/v0/meta/bases/{base_id}/tables，返回含完整字段定义的表格 Schema 列表。

在创建分支中传入的 tables 会经过 SDK 的 _convert_bools() 递归处理（把字符串形式的 "true"/"false" 转换为真实布尔值），确保与 Airtable API 的 JSON 契约一致。

2.3 输入参数（Inputs）

Input	描述	类型	是否必填
credentials	Airtable API 凭据（由连接配置自动注入）	CredentialsMetaInput	是
workspace_id	将创建 Base 的目标工作区 ID	str	是
name	新 Base 的名称	str	是
find_existing	若为 true，遇到同名 Base 时返回既有 Base 而非创建重复项	bool	否（代码默认 True）
tables	要随 Base 一起创建的表对象数组，至少需指定一张表及其字段；每个表应包含 name 与 fields 属性	List[Dict[str, Any]]	否

关于 tables 的结构，代码中预置了合理的默认值（bases.py L39-L55）：当不显式传参时，会自动创建一张名为 Default table 的默认表，其中包含一个 ID 字段，类型为 number，precision（小数位精度）为 0，描述为「自增 ID 字段」。参考的 JSON 结构如下：

{
  "name": "Default table",
  "description": "Default table",
  "fields": [
    {
      "name": "ID",
      "type": "number",
      "description": "Auto-incrementing ID field",
      "options": { "precision": 0 }
    }
  ]
}

每个 field 中 type 取值必须落在 Airtable 支持的字段类型集合内。该枚举完整定义于 _api.py 的 TableFieldType，包括但不限于：singleLineText（单行文本）、multilineText、email、url、phoneNumber、number、percent、currency、singleSelect、multipleSelects、multipleRecordLinks、date、dateTime、checkbox、formula、rollup、lookup、autoNumber、rating、richText、button、aiText 等。若传入非法类型，create_table / create_field 等 Schema 层函数会通过断言直接报错，提示合法类型集合，这是 Schema 写入前的一道关键校验。

2.4 输出参数（Outputs）

Output	描述	类型
base_id	创建或找到的 Base 的 ID	str
tables	表对象数组	List[Dict[str, Any]]
table	单个表对象（供后续流程逐表取用）	Dict[str, Any]
was_created	若新建了 Base 为 True；若命中既有 Base 则为 False	bool
error	操作失败时的错误信息	str

值得注意的是，输出 tables 的同时会以 yield 的方式逐张表输出 table（bases.py L112-L114），这样的流式输出设计使得下游 Block 无需遍历数组即可直接消费单张表对象，非常适合「创建 Base 后立刻对每张表做初始化」的链路编排。

2.5 典型应用场景

• 项目启动初始化（Project Setup）：每当项目启动时自动以预设的表结构创建新 Base，避免人工重复搭建；
• 模板化部署（Template Deployment）：将同一套标准 Base 模板批量部署到多个团队或客户的工作区；
• 多租户应用（Multi-Tenant Apps）：以程序化方式为每个客户/每个项目创建相互隔离的独立 Base。

---

三、Airtable List Bases：枚举当前账号可见的全部 Base

3.1 能力说明（What it is）

Airtable List Bases 用于列出与当前连接账号关联的所有 Base。每次调用返回每个 Base 的基础信息（包括 ID、名称及权限级别等），用于工作流的发现、审计与批量操作前置步骤。

3.2 工作原理（How it works）

该 Block 的实现位于 AirtableListBasesBlock，逻辑非常直接：把输入中的 offset（若非空）透传给底层 list_bases()，由它向 GET https://api.airtable.com/v0/meta/bases 发起请求，随后：

1. yield "bases" 输出本页 Base 对象数组；
2. yield "offset" 输出下一页游标（当没有更多数据时为 null/None）。

由于 Airtable 的 Meta API 对列表接口返回结果做了分页限制（单次调用可能无法返回全部 Base），文档明确建议：当输出中的 offset 非空时，应将其作为下一次调用的 offset 输入继续翻页，直到 offset 为空表示取完所有 Base。这与 Create Base 内部查重逻辑共用同一套分页枚举机制。

3.3 输入参数（Inputs）

Input	描述	类型	是否必填
credentials	Airtable API 凭据（由连接配置自动注入）	CredentialsMetaInput	是
trigger	触发 Block 运行，具体取值被忽略	str	否（默认 "manual"）
offset	上一次请求返回的分页游标	str	否（默认 ""）

trigger 输入的存在是为了让「主动拉取型」Block 能够接入上游触发事件（如调度器、消息队列），其值不会被真正使用——从 代码注释 中的 "Trigger the block to run - value is ignored" 可见该字段仅承担触发职责。而在代码层面，空的 offset 会被规范化为 None 后跳过（if input_data.offset else None），保证不向 API 发送多余的查询参数。

3.4 输出参数（Outputs）

Output	描述	类型
bases	Base 对象数组	List[Dict[str, Any]]
offset	下一页游标（无更多 Base 时为 null）	str
error	操作失败时的错误信息	str

3.5 典型应用场景

• Base 发现（Base Discovery）：动态获取用户可访问的 Base 列表，用于构建动态下拉选择框或导航菜单；
• 资产盘点（Inventory Management）：遍历整个组织/工作区的全部 Base，用于审计与文档化记录；
• 跨 Base 操作（Cross-Base Operations）：先枚举所有 Base，再对它们逐一执行批量数据处理，构成「枚举 → 遍历 → 处理」的数据管道。

---

四、认证方式与配置前提

两个 Base Block 都需要有效的 Airtable 凭据。在平台侧，Airtable Provider 由 _config.py 统一配置，核心约定包括：

• Provider 名称：airtable，描述为 "Bases, tables, and records"；
• API Key 认证：环境变量 AIRTABLE_API_KEY（即 Airtable Personal Access Token），用于输入 credentials 的 API Key 类型凭据；
• OAuth 2.0 认证（备选）：通过 AirtableOAuthHandler 支持，服务端需配置 AIRTABLE_CLIENT_ID 与 AIRTABLE_CLIENT_SECRET，所需 scopes 覆盖 data.records:read、data.records:write、schema.bases:read、schema.bases:write、webhook:manage 等，schema.bases:write 正是 Create Base 写入所必需的权限项；
• 成本模型：每个 Block 每次运行的基础成本为 1（BlockCostType.RUN），即每执行一次 Base 相关调用计 1 点运行成本。

在仓库的集成测试 _api_test.py 中可以看到端到端验证方式：测试通过环境变量 AIRTABLE_API_KEY 构造 APIKeyCredentials（provider="airtable"），随后依次执行 create_base → 断言返回 id → list_bases → 断言新 Base 名称出现在结果中 → 再基于 base_id 做表级增改。该测试在没有配置 API Key 时会自动 pytest.skip 跳过，说明运行前提是平台环境具备真实的 Airtable 凭据与目标工作区（测试硬编码使用工作区 wsphuHmfllg7V3Brd 作为演示目标）。

---

五、在 AutoGPT 工作流中编排：实战模式

结合 Create Base 的「流式输出 table」与 List Bases 的「offset 翻页」设计，可以归纳出两类常见的编排模式：

模式 A：幂等初始化（创建 + 查重）

将 Airtable Create Base 作为工作流入口之后，始终开启 find_existing=True，并依据 was_created 分支处理：False 表示复用既有 Base（base_id 为已有库），True 表示新库刚创建完成。这种「查找优先、创建兜底」的语义天然满足幂等性要求——无论工作流被触发多少次，都不会在工作区里堆积同名重复 Base。

模式 B：全量枚举与批量处理

将 Airtable List Bases 的输出 bases 接到下游处理节点，同时把 offset 反馈回自身输入形成翻页循环，直到 offset 为 null，即可保证枚举覆盖当前账号的全部 Base，为跨库数据同步、归档或报表生成提供完整输入集合。

实际使用时，请确保工作流图已正确挂载 Airtable 凭据节点，并留意 Airtable 侧对 workspace 数量、Base 数量以及 Meta API 调用频率的配额限制（不同订阅套餐差异较大），合理设置触发节流，避免超限报错。

---

六、关键参考路径速查

目的	仓库路径
Base Block 官方文档（本文源头）	docs/integrations/block-integrations/airtable/bases.md
记录/表结构/触发相关文档	records.md、schema.md、triggers.md
Create Base / List Bases Block 实现	autogpt_platform/backend/backend/blocks/airtable/bases.py
底层 Airtable API 封装（Base/Tables/Records）	autogpt_platform/backend/backend/blocks/airtable/_api.py
Provider 认证与成本配置	autogpt_platform/backend/backend/blocks/airtable/_config.py
Airtable 集成集成测试（含 Key 校验模式）	autogpt_platform/backend/backend/blocks/airtable/_api_test.py
Block SDK 通用编写指南	docs/platform/block-sdk-guide.md
Agent 块体系与可视化编排说明	docs/platform/agent-blocks.md

以上路径均可在本仓库内直接查看，作为进一步把 Base 级能力与 Record、Schema 类 Block 组合成完整数据工作流的切入点。