Nango: AI Agent 时代的代码优先集成平台 —— 兼与 Composio 的异同与互补

随着生成式 AI 的爆发，如何让 AI Agent 真正"动手"操作外部世界，已经成为大模型应用落地的核心瓶颈。当你需要让 Agent 发一条 Pin、建一个 Jira 工单、或者同步一批 Salesforce CRM 数据时，你很快会撞上同一堵墙：OAuth 2.0 授权、Token 自动刷新、API 限流、指数退避重试、复杂分页……每对接一个平台，都需要把这些脏活累活重写一遍。

在这样的背景下，AI Agent集成中间层成为了当今基础设施里最拥挤、也最关键的赛道之一。在这条赛道上，Nango 和 Composio 是两个最常被开发者放在一起比较的明星项目。

本文将为您完整介绍 Nango 的核心架构与使用方法，系统对比它与 Composio 的相同点与差异性，并给出一个将两者结合互补的实战分层架构，帮助您的 AI Agent 既拥有“广度”又拥有“深度”。

一、Nango 是什么：以代码为中心的集成运行时

Nango 是一个开源的 API 集成平台，其核心理念是**“集成即代码”（Integrations as Code）**：开发者（或你的 Coding Agent，如 Claude Code）用 TypeScript 编写集成逻辑，而 Nango 生产级运行时负责托管认证、逻辑执行、自动重试、动态扩缩容和端到端的可观测性。它目前已覆盖 800 多个主流 API，提供 5000 多个可复用的集成模板。

要理解 Nango 的工作原理，需要抓住它的四个核心原语。

1. 托管认证 (Auth)

这是 Nango 最广为人知的能力。它完全托管了 OAuth 2.0、OAuth 1.0a、API Key 和 Basic Auth 的生命周期——包括授权重定向、凭证加密存储、Token 自动刷新以及失效校验。你只需在产品前端嵌入其白标（White-labeled）的 Connect UI 按钮，用户点击授权后，Nango 就会在后台处理剩下的一切。

[!IMPORTANT] Nango 的商业承诺：其托管认证功能（Auth）是永久免费的，无论你使用的是云版本（Cloud）还是本地自托管（Self-hosted）。许多团队甚至仅把 Nango 当作安全的“凭证管理器”来使用。

2. 认证代理 (Proxy)

用户授权成功后，最直接的发起 API 请求方式就是通过 Nango 认证代理。Proxy 会自动解析目标平台、自动在 Header 中注入有效凭证、并自动处理重试与限流：

import { Nango } from '@nangohq/node';
const nango = new Nango({ secretKey: process.env.NANGO_SECRET_KEY });

const res = await nango.post({
  endpoint: '/v5/pins',
  providerConfigKey: 'pinterest',
  connectionId: 'main-account',
  data: { 
    board_id: '12345', 
    media_source: { source_type: 'image_url', url: 'https://example.com/cover.jpg' } 
  }
});

providerConfigKey：标识“哪套应用配置”（如你在 Pinterest Developer 注册的 Client ID 和 Secret）。
connectionId：标识“哪位用户的授权账号”。这个两级模型天然支持多租户系统，隔离性极强。

3. 集成函数 (Functions: Actions, Syncs, Webhooks)

对于比单次 API 代理更复杂的业务逻辑，Nango 在其运行时中提供了三类可部署的 TypeScript 函数：

Action：按需执行的写操作（如“发帖并获取 ID”）。
Sync：持续的、增量的数据同步（如“每隔1小时拉取最新 CRM 数据同步到向量数据库”）。
Webhook：处理目标平台发出的回调事件。

Nango 所有的 5000+ 预置模板全部开源。你可以随时 Fork 任何一个模板并根据业务微调，代码提交到你自己的 Git 仓库中，可读、可审查、可本地测试。Nango 还提供了面向 Claude Code, Cursor 等 18+ 种 Coding Agent 的 Builder Skill，允许 AI 自动查阅文档、编写集成函数并根据真实报错自主修复。

4. MCP Server 规范集成

Nango 内置了 MCP Server（Model Context Protocol）端点。你可以将自己编写并部署的 TypeScript Actions 自动转化为带 Schema 定义的 MCP Tools，直接暴露给 Claude Desktop、Claude Code 或 OpenAI Agents SDK。AI 可以通过以下三个 Header 进行鉴权并调用：

X-Nango-Secret-Key: <your-secret-key>
X-Nango-Provider-Config-Key: pinterest
X-Nango-Connection-Id: user-123

二、Composio 是什么：开箱即用的工具网关

与 Nango 强调“编写代码”不同，Composio 的定位是**“AI Agent 的工具网关”（Tool Gateway for Agents）**。

Composio 拥有一个非常庞大的托管工具目录，内置了约 1000 个平台的开箱即用工具。它同样托管了 OAuth 生命周期，但对开发者屏蔽了具体的 API 拼装细节。如果你需要 Agent 连接 GitHub、Slack，你不需要写任何一行 TypeScript 代码，只需在 Composio 后台点击授权，Agent 即可通过统一的 MCP 协议或 OpenAPI Schema 自动获取该平台的一整套 Tool 调用列表。

然而，Composio 的边界也十分明显：其工具实现细节是闭源且封装好的，你无法精细修改其逻辑；此外，它的能力仅局限于 Tool Calls（问答交互中的单次函数调用），不提供持续的数据双向同步、复杂的 Webhook 监听事件处理。

三、Nango 与 Composio 的相同点：同一个赛道的两套解法

两者的底层逻辑和解决的痛点在表层非常相似：

痛点一致：都致力于解决 AI Agent 调用外部 API 时繁琐的身份验证、Token 刷新和接口格式化问题。
协议标准：都完美适配了 Model Context Protocol (MCP)，将底层 API 转换为大模型易于理解的 Tools。
租户隔离：都支持多租户（Multi-tenancy），允许你产品的最终用户授权各自的 SaaS 凭证。
API 天花板：两者的调用上限都依赖于目标平台的官方 API。如果目标平台没有提供公开 API，两家都无能为力。

四、Nango 与 Composio 的核心差异对比

两者的本质分野在于设计哲学：Composio 给你的是一个拿来即用的工具目录，而 Nango 给你的是一个高自由度的代码运行时。

维度	Composio	Nango
核心定位	托管工具网关（开箱即用，1000+ 平台）	代码优先集成运行时（“集成即代码”）
代码控制力	闭源封装，无法查看/修改工具的内部实现	1000% 开源，可随时 Fork、定制或自建
功能范畴	局限于单次 Tool Calls (写操作为主)	Tool Calls + 数据同步 (Sync) + Webhook
定制上限	低。遇不支持的参数只能等待官方排期更新	极高。自行编写 TypeScript 函数即可上线
商业授权	闭源 SaaS 服务	核心认证部分永久免费，运行时采用 Elastic 协议
典型画像	快速验证想法、需要主流平台标准工具的团队	将 Agent 集成作为核心资产，要求严密审计与可控性

五、强强联手：Nango 与 Composio 互补架构设计

在构建复杂的企业级 AI Agent集成 系统时，我们完全不需要在两者之间做出非此即备的妥协，而是可以将它们进行分层架构设计（Layered Architecture）：

Composio 作为“广度层”：负责主流平台的标准操作。如 GitHub 提 PR、Slack 发送标准通知。开箱即用，省去编写代码的成本。
Nango 作为“深度层”：负责处理客制化强、逻辑复杂的特殊平台，或者需要持续进行 RAG 知识库增量同步（Sync）的底层管道。

混合集成路由拓扑图

graph TD
    Orchestrator[AI Agent 编排层 Orchestrator] --> Router{多通道集成路由器}
    
    Router -- 主流标准工具 --> Composio[Composio 广度层]
    Router -- 深度定制/Sync/Webhook --> Nango[Nango 深度层]
    
    Composio --> Slack[Slack API]
    Composio --> GitHub[GitHub API]
    
    Nango --> CustomCRM[企业定制 CRM]
    Nango --> SyncDB[(知识库增量同步)]
    
    classDef default fill:#1e1b4b,stroke:#818cf8,color:#fff;
    classDef highlight fill:#312e81,stroke:#a78bfa,color:#fff;
    class Orchestrator,Router highlight;

工程落地三项准则

准则一：显式配置路由表。不要让 Agent 靠语义来盲猜该去哪里调用，应当在编排层显式声明渠道：

{
  "connectors": {
    "slack": { "via": "composio" },
    "pinterest": { "via": "nango", "providerConfigKey": "pin-prod", "connectionId": "user-99" }
  }
}

准则二：单一职责划分。一个第三方平台仅选择一条调用通道，严禁混合暴露，否则会引起凭证冲突与 Token 刷新的覆盖问题。
准则三：监控日志收拢。由于存在双通道，应在你的应用后端（Orchestrator）做统一的调用日志拦截与审计，避免在 Composio 和 Nango 的控制台之间来回切换排查问题。

六、结语：买现成的，还是造可控的？

Composio 与 Nango 的抉择，实际上是软件工程中经典“Buy vs Build”（买现成还是自建）命题在 AI Agent 时代的重演。Composio 将“开箱即用”做到了极致，让个人与中小团队能以最快速度组装出具备千种工具的 Agent；而 Nango 则坚守软件工程的控制底线——当集成代码本身就是产品护城河时，它必须能被审查、修改、并稳健地自托管运行。

将 Composio 的“广度优势”与 Nango 的“深度控制”有机结合，才是构建下一代高可用、高扩展性 AI Agent集成 栈的最优解。