用OpenAPI Spec实现通用SaaS连接器架构

大多数 SaaS 集成都是一个一个单独构建的。Slack 连接器、Stripe 连接器、HubSpot 连接器——每一个都需要数周的定制代码、OAuth 流程和 webhook 处理。

我们采用了一种不同的方式：一个统一的 OpenAPI 连接器，让 AI Agent 能够通过规范文件与任何 SaaS 对话。

我们的平台（S.C.A.L.A.）服务于 20 个不同的行业——餐厅、酒店、物业管理、零售等。每个垂直领域需要不同的集成：

• 餐厅需要 POS 系统 + 预订系统
• 酒店需要 PMS 系统 + 渠道管理器
• 零售需要库存管理 + 电商平台

对于一个自力更生的团队来说，构建 50+ 个定制集成是不现实的。

User prompt → AI Agent → Tool Dispatcher → OpenAPI Connector → External SaaS
                                    ↓
                            spec_url or spec_json
                            auth_type (api_key | bearer | basic | oauth2)
                            encrypted credentials (AES-256)

步骤 1：导入任意 OpenAPI 规范

用户粘贴规范 URL 或上传 JSON 文件。我们对其进行验证，提取端点，并存储 schema：

const createConnectorSchema = z.object({
  name: z.string().min(1).max(200),
  spec_url: z.string().url().max(2048).optional(),
  spec_json: z.record(z.string(), z.unknown()).optional(),
  auth_type: z.enum(['none', 'api_key', 'bearer', 'basic', 'oauth2']),
  auth_config: z.object({
    api_key: z.string().max(500).optional(),
    api_key_header: z.string().max(100).optional(),
    bearer_token: z.string().max(2000).optional(),
    // ... other auth types
  }).optional(),
});

步骤 2：AI Agent 发现可用操作

当用户说"查看我的库存水平"时，Agent 会：

• 查看所有已连接的 OpenAPI 规范
• 将意图匹配到可用端点（语义搜索）
• 使用正确的参数构建 API 调用
• 通过受 SSRF 保护的 fetch 执行

步骤 3：凭证永不离开保险库

所有密钥均使用 AES-256 静态加密。连接器仅在调用时解密，在内存中处理，从不记录日志：

import { encryptSecret, decryptSecret } from '../lib/encryption.js';

// Store encrypted
const encrypted = encryptSecret(rawApiKey);

// Decrypt only when calling
const key = decryptSecret(encrypted);

安全：SSRF 防护

通用连接器最大的风险是 SSRF——恶意规范可能指向内部服务。我们在获取前验证每个 URL：

import { validateUrlSSRF, safeFetch } from '../lib/ssrf.js';

// Blocks: localhost, 169.254.x.x, 10.x.x.x, internal DNS
const validated = validateUrlSSRF(targetUrl);
const response = await safeFetch(validated, { timeout: 15_000 });

每个连接器都有独立的速率限制桶。我们在全局 IP 限流器之上使用按密钥的进程内限流（1000 req/min）：

API Key → SHA-256 hash → lookup in api_keys table → scope check → rate limit bucket → execute

通过这种模式，添加一个新的 SaaS 集成只需几分钟，而不是几周：

• 用户粘贴 OpenAPI 规范 URL
• 设置 auth 类型 + 凭证
• AI Agent 立即知道如何使用每个端点

我们已经看到用户通过同一个通用连接器连接了从 Shopify 到自定义 ERP 的各种系统。

OpenAPI 规范不一致——许多存在类型错误、必填字段缺失或认证文档不完整。构建防御性解析。

AI 需要精选端点——向 Agent 展示大型 API 的全部 200 个端点是噪音。让用户固定他们实际需要的 5-10 个。

主动超时——外部 API 较慢。15 秒硬超时防止一个坏调用阻塞 Agent 循环。

记录除密钥外的所有内容——当调试"为什么 Agent 没有正确调用 Shopify？"时，你需要完整的请求链但不包含凭证。

S.C.A.L.A. 是一个具有 20 个行业特定 Agent 的 Agentic AI 平台。OpenAPI 连接器可在 Scale 计划中使用。

网站：get-scala.com

开源 WhatsApp Agent：SARA on GitHub

开源房地产可行性 Agent：LandIQ on GitHub

API 文档和沙盒可在 get-scala.com/api-docs 获取。

为真实企业构建 AI Agent，而非 Demo。关注以获取更多来自一线的实战经验。