neon-postgres-agent-platforms

Neon AI Agent Program

**neon-postgres** 的配套内容（请先安装）。此技能涵盖 Neon Agent Program 的舰队规模控制平面：双组织布局、项目转移、按租户配置、复合检查点、用量、商业条款，以及何时通过 @neon/tools 向 Agent 提供 Management API 访问权限。

有关连接字符串、驱动程序、ORM、分支教程、应用中的 Auth、Data API 和 Neon 托管的 MCP，请使用 **neon-postgres** 和 Neon 文档。

范围

一般 Neon 用法请使用 **neon-postgres**。当问题涉及以下内容时，请使用此技能：

• 双组织的成本与 API 密钥（个人、组织、项目范围）
• 用于控制平面的 @neon/sdk，与用于面向 Agent 提供 Management API 访问权限的 @neon/tools
• 按租户配置和转移项目
• 全舰队快照／恢复编排与维护
• 复合检查点
• 面向计量型舰队的用量轮询
• Agent Plan 商业条款（附链接，不编造数字）
• 合作伙伴支持渠道

安装技能

npx skills add neondatabase/agent-skills -s neon-postgres

助手：安装后可以执行的操作

加载 **neon-postgres** 和此技能后，你便掌握了足够的上下文来处理平台级 Neon 工作：双组织布局、为新租户配置项目、复合检查点、组织级用量轮询，以及转移／升级流程——无需用户粘贴冗长的文档。

可运行示例的位置： TypeScript 示例可从此技能的 scripts/ 目录运行（package.json、npm run …）。**references/** 目录中有与可运行示例配套的 Markdown 指南； MANAGEMENT_API_SAMPLES.md 是脚本目录和环境变量映射表。面向用户的快速入门位于根目录的 README。

SDK 与 Agent 工具

你的控制平面应调用 @neon/sdk。此仓库中的示例脚本就是这样做的。

Neon MCP 服务 是面向 Agent 的自定义层：基于 @neon/sdk 编写的 MCP 工具处理程序。

如果你想让平台上的 Agent 直接管理 Neon，而无需编写这些处理程序，请使用 @neon/tools。它会将选定的 SDK 方法生成为包装器，并发布为 Agent 工具，同时提供适用于 MCP、Eve 和 Mastra 的适配器。

这些公开的客户端方法不是工具：projects.create、branches.create、operations.waitFor、postgres.roles.password 和 storage.objects.get。对于需要附加计算资源并返回连接字符串的创建操作，请使用 projects.createAndConnect 和 branches.createWithCompute。写入工具本身已经会等待操作完成。生成的架构是严格的：新增的 API 字段会被拒绝，除非你升级 @neon/tools，或者直接调用 @neon/sdk。

选择器是 SDK 路径（projects.list）。调用 publishedId 可获取面向模型的 ID（projects.list → list_projects）。toolIds 会列出所有选择器。MCP 2.x 使用 @neon/tools/mcp；MCP 1.x 使用 @neon/tools/mcp-v1。

import { McpServer } from "@modelcontextprotocol/server";
import { createNeonTools } from "@neon/tools";
import { registerNeonTools } from "@neon/tools/mcp";

const apiKey = process.env.NEON_API_KEY;
if (!apiKey) throw new Error("NEON_API_KEY is required");

const tools = createNeonTools({
  apiKey,
  tools: [
    "projects.list",
    "projects.createAndConnect",
    "branches.createWithCompute",
  ] as const,
});

const server = new McpServer({ name: "neon", version: "1.0.0" });
registerNeonTools(server, tools);

apiKey 接受一个函数，因此可以在每次请求时刷新短期令牌。已对客户端完成身份验证的远程 MCP 服务可以在构造时省略 apiKey；此时 registerNeonTools 会发送 authInfo.token。

MCP 注释仅供参考。使用 @neon/tools/mcp 的宿主必须读取 MCP _meta 中的 neon/requiresApproval，并在执行前实施自己的审批策略。Eve 和 Mastra 适配器会将此标记分别映射到 Eve 的 approval 钩子和 Mastra 的 requireApproval。所有非读取操作都标记为需要审批；会返回连接凭据的读取操作也同样如此。

仅选择每个 Agent 所需的方法。对于受租户范围限制的 Agent，注入路径 project_id，这样模型就无法在接受该路径参数的工具中选择其他项目：

const tools = createNeonTools({
  apiKey,
  tools: ["projects.get", "branches.createWithCompute"] as const,
  inject: {
    projectId: tenantProjectId,
    omitFromSchema: true,
  },
});

inject.projectId 仅会填充 URL 路径中的 project_id。它不会隐藏具有该名称的查询或正文参数，也不会限制没有项目路径的工具（例如 projects.list）。如果 Agent 不应看到组织中的其他内容，请同时使用项目范围的 API 密钥。

完整 API：@neon/tools README。

注意事项

Agent 经常会弄错的一些不明显的事实：

• 检查点是复合记录。 租户检查点包含源代码修订版本 + Neon 快照/分支 + 密钥/环境变量版本 + 部署 URL + Agent 元数据。不要把“检查点”等同于单独的“Neon 分支”。请参阅复合检查点文档。
• 跨组织转移需要个人 API 密钥（组织密钥仅在一个组织内有效）。在 Neon 中集成了 GitHub 或 Vercel 的项目无法转移；API 会返回 422（转移项目）。
• 完成快照恢复后，活动分支 ID 会发生变化。重新连接前，请轮询操作，直至完成。删除孤立的 (old) 分支，以避免产生存储费用。
• 与账单对齐的用量： 优先使用 GET /api/v2/consumption_history/v2/projects，而非旧版用量端点。旧版账户级端点已停用；请使用 v2 按项目的端点（旧版用量指南）。
• v2 metrics 参数的取值（适用于实现者）：compute_unit_seconds、root_branch_bytes_month、child_branch_bytes_month、instant_restore_bytes_month、snapshot_storage_bytes_month、public_network_transfer_bytes、private_network_transfer_bytes、extra_branches_month（用量指标）。
• Agent Plan 不提供快照计划。 合作伙伴需通过快照 API 和自己的调度器实现此功能。
• 费率和上限： 切勿臆造金额或限制。请以 neon.com 上的实时文档为准。

Agent Plan 与两个组织

合作伙伴会运营两个 Neon 组织：

组织	角色
赞助免费组织	免费层级终端用户（遵守计划规则）
付费组织	付费客户（按 Agent Plan 计量）

要点：

• 费率、抵扣额度和项目上限只能以实时的 Agent Plan 和 neon.com/agents 为准。切勿臆造数字。
• 组织 API 密钥： 用于在一个组织内执行自动化操作（创建项目、设置配额）。
• 个人 API 密钥： 客户更改层级时，将项目转移到其他组织需要此密钥；随后需 PATCH 配额以匹配新层级。
• 项目范围的 API 密钥： 提供成员级访问权限，且仅限访问一个项目，权限范围比组织密钥更窄，适用于每个租户的运行时，或不得操作组织其余部分的自动化任务。无法在整个组织内创建新项目；如果项目被转移出该组织，此密钥将失效。

链接： Agent Plan · AI Agent · 项目转移 · AI Agent 集成

HIPAA

• Agent Plan 包含 HIPAA，且不收取额外费用。 合作伙伴仍须遵循 Neon 发布的 HIPAA 计划（工作流、协议和配置）。
• 如需获取访问权限或启动相关流程，请联系您的Neon 主要联系人。
• 此技能不构成法律建议。

链接：Neon 上的 HIPAA

Fleet 形态：每个租户一个项目

• 每个租户一个项目是 Neon 文档中介绍的 Fleet 模式：你为每个租户（终端用户、客户的应用或Agent 工作负载）配置一个专属的 Neon 项目。该项目是分支、数据库、角色和计算资源的隔离边界，而不是一个仅按架构分区的共享 Postgres 集群。
• 隔离和计费：单独的项目可让不同租户之间实现完整的数据和资源隔离，让项目级别的用量限制和计费更直接明了（与本技能其他部分介绍的 Agent Plan 计量方式一致），也符合 Neon 管理 API 和控制台的结构（按项目调用创建、配额和生命周期接口）。

预发布和生产环境

• 对于每个租户项目，应将预发布与生产环境（以及临时预览环境）视为该项目内部由分支和快照驱动的生命周期流程——使用下文的快照和数据库版本控制以及沙盒和预览数据库进行 Fleet 编排，默认不另建项目。
• Agent 和应用构建者：将你们平台的环境（例如托管构建器或控制平面的方式）与各租户的预发布和生产分支区分开来，避免在台账和自动化流程中混淆“我们的生产服务”和“租户的生产分支”。
• 一些嵌入式产品也会将终端客户的生产和开发 Neon 资产拆分到不同组织中，以明确信任、密钥和计费边界；如果适用，请接着阅读超越分支的隔离（项目和组织的特殊情况）。

链接： AI Agent 集成指南

超越分支的隔离（项目和组织层面的边界情况）

当租户范围或信任要求超出 Fleet 模式下以分支和快照优先的暂存与生产环境时，请使用项目级或组织级拆分。嵌入式产品可能会在不同 Neon 组织中隔离终端客户的生产与开发数据库，而不仅仅是使用分支——这样可以更严格地划分计费、组织 API 密钥和控制台边界，同时仍可在每个组织内部管理分支。

项目级隔离（每个租户或工作负载使用多个项目）：

• 如果连接字符串或角色遭到泄露，可进一步限制影响范围——一次泄露不应波及无关工作负载。
• 运营生命周期不同（例如，一次性分析或迁移沙盒与生产数据），避免自动化流程或所有权在同一个 Postgres 中发生冲突。
• 团队或自动化流程不同，且迁移或管理权限存在冲突。
• 更严格的合规或数据混合规则，要求单个数据库不得承载混合工作负载。

每增加一个项目都会扩大 Fleet 的管理范围：更多 API 密钥、更多用量记录、更多维护工作和更高的运营成本——除非明确符合上述边界情况，否则应默认采用每个租户一个项目。

组织级隔离（超出赞助免费与付费的区分）：

• Agent Plan and two organizations 中的双组织布局用于商业拆分（免费层用户与付费客户）。这种模式可以与嵌入式产品拆分叠加：例如，按终端客户区分生产组织与开发组织，确保游乐场数据库不会与已上线的生产环境共享组织范围。请清楚记录内部映射，标明每个组织所属的环境和层级。
• 此外，合作伙伴有时需要额外的 Neon 组织或账户来满足签约要求（企业客户要求“仅使用其自己的组织”）、经销商或 MSP 模式，或地域与法律方面的隔离——产品默认值和限制请以实时文档为准；不要自行编造上限。
• 组织 API 密钥的范围仅限单个组织。跨组织迁移需要使用个人 API 密钥并转移项目，具体见 Gotchas——不要假设组织密钥可以跨组织操作。项目范围的密钥限制更多，仅适用于单个项目（API 密钥）。

嵌入式产品的安全实践：

• 为每项平台服务（控制平面、租户运行时、计费或用量任务）分配遵循最小权限原则的密钥；不要在错误的层级将生产密钥用于沙盒。
• 当终端客户的生产与开发环境位于不同 Neon 组织时，应按组织限定自动化流程（通常每个组织使用一个组织 API 密钥），并将 org_id 与 project_id / branch_id 一同持久化，确保任务和恢复操作指向正确的环境。
• 确保你的台账（project_id、branch_id、组织、检查点元数据）与所选隔离层级保持一致，以便恢复、转移和审计始终一致。

快照和数据库版本控制

关于快照语义、活动分支模式和恢复教程，请参阅 **neon-postgres** 和 AI 数据库版本控制。 此处重点关注租户群组：

• 在账本中按租户持久保存快照和分支 ID。通过 复合检查点 将每项与非 Neon 状态关联起来。
• 完成恢复后，分支 ID 会变化，孤立的 (old) 分支会不断累积。请自动清理并更新已存储的 ID。
• 重新连接租户应用前，先轮询操作直至完成。
• 产品语义（各层级的快照数量、Beta 定价日期）可能会变化。 请查阅 Agent Plan 文档确认。

典型的平台级检查点触发时机：

• 为租户升级生成的架构更改前
• 会修改租户数据库的 Agent 运行开始或结束时
• 执行破坏性迁移或面向客户的恢复操作前

链接： AI 数据库版本控制 · 备份和恢复 · 快照即检查点演示

沙盒和预览数据库

当合作伙伴需要为生成的应用创建按租户划分的预览或沙盒数据库时，请使用此方案。（单个应用的“如何创建分支？”问题请参阅 **neon-postgres**。）

• 通过 Management API 创建预览时，按客户 / Agent 运行跟踪 project_id / branch_id。
• 分支和存储数量会随群组规模增长。请监控上限并清理闲置的预览。
• 为预览计算资源设置较短的 suspend_timeout_seconds，以降低成本。
• 通过复合检查点，将分支 / 快照生命周期与密钥轮换及部署 URL 配合起来。

链接： AI Agent 集成指南

成本、用量和权益

• 切勿臆造价格、配额或限制。请查阅 Agent Plan 和 用量指标确认。
• 使用 GET /api/v2/consumption_history/v2/projects 获取与计费相符的字段。 旧版端点有所不同。旧版账户级端点已停用； 请改用 v2 按项目划分的指标 （旧版指南）。
• V2 metrics 查询字符串必须为以下值：compute_unit_seconds、 root_branch_bytes_month、child_branch_bytes_month、 instant_restore_bytes_month、snapshot_storage_bytes_month、 public_network_transfer_bytes、private_network_transfer_bytes、 extra_branches_month。
• 大约每 15 分钟轮询一次用量。轮询不会唤醒已暂停的计算资源。
• 从 scripts/ 运行 auth-users.ts meta，获取路由映射（Neon Auth REST、Postgres 角色和用量 API）。

链接： Agent Plan · 用量指标 · 用量限制 · 成本优化 · 计划

组织和项目限额提升

• 当前默认值和上限请查阅 Agent Plan 和 AI Agent 集成。 切勿臆造限制。
• 如需申请提高项目限额，请发送邮件至 [email protected]，提供组织 ID、增长背景 和时间安排。如有共享 Slack，也请在那里说明。

联合营销

• 联合营销是 Agent Plan 包含的权益。
• 可提供：联合博客文章、社交媒体推广、黑客马拉松赞助、案例研究、落地页展示。
• 请通过共享 Slack 或联系 Neon 代表，说明你正在构建的内容。

链接：Agent Plan

支持

• **共享 Slack 频道：**技术问题和紧急事项的最快处理途径。
• **Neon 代表：**账户级请求、自定义配置、升级处理。
• **提高限额：**发送电子邮件至 [email protected]，并提供组织 ID、业务增长背景 和时间安排。
• **账单：**通过 Slack 或 Neon 代表提出。可在 Neon Console 的 Billing 中查看额度余额和 发票。
• 社区：Neon Discord · 文档 · API 参考

仓库示例

来自 neondatabase/neon-for-agent-platforms 的可运行 Management API 自动化示例。

• 快速入门： README
• 脚本目录： MANAGEMENT_API_SAMPLES.md
• 复合检查点： COMPOUND_CHECKPOINTS_FOR_AGENT_PLATFORMS.md
• 检查点编排： CHECKPOINT_ORCHESTRATION_PATTERN.md
• 文档索引： SCRIPT-OVERVIEW.md

这些脚本仅使用 @neon/sdk。共享的 utils.ts 会构建客户端并解析默认分支；SDK 会为你轮询异步操作（就绪状态）。有关面向 Agent 的 Management API 工具，请参阅上文的 SDK vs agent tools。如需从应用代码访问 SQL（驱动程序、连接池、ORM），请使用 **neon-postgres**。