P7 · 如何统一管理模型、工具和外部资源？ - Resource & Integration
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何将模型、工具、知识资源、外部 API 与数据源抽象为可注册、发现、配置、授权、调用、计量、审计和安全复用的平台资源，同时避免将凭据、权限和运行时状态错误地耦合到 Agent 定义？
专题导读
本篇属 Technical Architecture。P7 研究 Resource & Integration：平台如何把异构外部能力转换为具有统一管理语义、但保留各自调用特征的资源。它承接 P3 的不可变 Agent Version、P4 的开发依赖声明、P5 的部署运行管理和 P6 的工作流调度；不重复研究 AI 模型推理细节（01 AI）、单个 Agent 如何调用工具（02 Agent）或 Agent System 内部工具执行机制（03 · Agent System）。
本文从资源模型、连接器、授权凭据、调用路径、数据治理、可靠性和平台运营等方面建立技术框架。研究报告 Studio 作为贯穿案例。文中接口、数据表、指标和测试均为参考设计或待验证方案，不是已部署的产品能力；标准与厂商文档在附录列出核验入口，版本敏感的细节应在实施时重新核查。
研究结论
- 资源不是凭据，也不是一次调用。 Resource Definition 描述可提供的能力；Connection 代表某个租户或工作空间对外部服务的配置与连接；Credential 是受保护的授权材料；Binding 将资源的使用权授予 Agent/Workflow；Invocation 记录一次调用。
- 统一的是治理与生命周期，不是抹平差异。 模型推理、检索、数据库查询、网页浏览、文件操作和外部业务写入在接口、成本、时延、副作用与权限上均有差异；应使用类型化适配器，而非单一万能
execute()语义。 - 资源访问必须在运行时重新授权。 构建期校验和 Agent Version 中的资源引用不构成永久授权；每次执行仍需检查租户、主体、操作、环境、配额与策略。
- 连接与密钥应解耦。 资源清单可以共享，连接配置可以按工作空间管理，密钥只由专用密钥管理机制保存并按需注入，禁止进入 Manifest、日志和产物。
- 外部调用要区分只读与有副作用操作。 重试、缓存、审批、幂等和补偿策略必须基于资源操作语义设计；不能将所有 API 调用视为可安全重试。
- 平台需要可追溯的依赖解析。 一次 Run 应记录实际使用的模型路由、连接器版本、资源绑定、授权决策和关键外部结果引用，以支持诊断、成本归因与复现分析。
- MVP 从有限资源目录与明确的安全边界开始。 优先支持少量模型、只读检索与文件存储，随后按真实需求扩展外部写入、组织级连接、多租户和插件生态。
一、概念定义与研究边界
1.1 平台资源的定义
在 Agent Platform 中，**资源（Resource）**是能够被 Agent、Workflow 或平台服务引用和使用的外部或共享能力。资源可能由平台内部实现，也可能通过外部服务提供。它既可能是可调用能力（模型、工具、API），也可能是可访问的数据资产（知识库、文件集合、数据库、索引）。
**集成（Integration）**是将这些能力接入平台并持续管理其配置、认证、通信、错误与生命周期的过程。**连接器（Connector）**是集成的一种软件实现形态。**工具（Tool）**则是暴露给 Agent 的可调用操作接口：一个连接器可暴露多个工具，一个工具也可能由平台内部服务实现。
例如“搜索公司知识库”是工具能力；具体检索索引是资源；某个团队的数据库连接是 Connection；执行者是否有权查询该索引是授权问题；检索请求及结果属于 Invocation 与数据访问记录。
1.2 与相邻专题的分工
| 专题 | 主要责任 | P7 不重复的内容 |
|---|---|---|
| 01 AI / E1 - E8 | 模型 API、路由、推理优化 | 模型算法与推理参数基础 |
| 02 Agent / A6 - A8 | 单 Agent 使用知识、工具与 Skill | Agent 内部能力设计 |
| 03 Agent System / L3 - L4 - L5 | 系统内部模型服务、工具执行和编排 | 系统执行引擎实现 |
| P3 Agent Registry | 定义、版本与依赖引用 | 资源连接的运行时授权 |
| P4 Development Services | 编辑资源声明、开发期校验 | 共享连接及凭据生命周期 |
| P5 Runtime Management | 执行环境、部署与实例 | 资源目录及调用适配 |
| P6 Workflow Management | 工作流资产、触发与调度 | 外部能力统一接入 |
| P8 Platform API & SDK | 平台对外接口 | 平台向外部供应商的集成 |
| P9 Extensibility & Ecosystem | 插件协议、扩展点与生态 | 具体资源连接治理 |
| P10 Platform Data & Assets | 平台数据与产物的资产生命周期 | 资源调用与外部连接 |
| P11 - P12 | 租户隔离、权限和治理框架 | 具体资源授权执行与计量 |
关键边界：P7 是平台的资源控制与集成服务，不是所有第三方功能的业务实现。P9 研究“平台允许怎样扩展”，P7 研究“已经接入的资源怎样安全可用”。
二、资源分类与能力差异
| 类型 | 典型资源 | 主要操作 | 特殊约束 |
|---|---|---|---|
| 模型资源 | LLM、Embedding、语音、图像模型 | 推理、嵌入、生成 | token/算力成本、上下文、区域、速率 |
| 工具资源 | 搜索、浏览器、代码执行、文件处理 | 读取、计算、操作 | 执行隔离、输入校验、副作用 |
| 知识资源 | 文档集合、索引、检索服务 | 检索、读取、更新 | ACL、文档版本、引用来源 |
| 数据源 | SQL、对象存储、数据仓库 | 查询、写入、同步 | 行列权限、事务、敏感数据 |
| 外部业务服务 | 邮件、日历、工单、CRM | 读取、创建、修改 | 用户授权、审批、幂等 |
| 平台内部资源 | 模板、Skill、Prompt、文件产物 | 解析、读取、引用 | 版本与租户边界 |
| 事件资源 | Webhook、消息主题、事件流 | 订阅、发布、确认 | 重放、去重、顺序、签名 |
“模型”与“工具”不是天然互斥的分类：从 Agent 的视角，模型调用也可能通过统一调用网关；但平台仍应保留模型特有的参数、计费、数据政策与观测字段。
2.1 资源分级
可按影响程度定义参考分级：R0 公共只读；R1 租户内只读；R2 受控写入；R3 高风险外部操作（如发送邮件、支付、删除）。分级仅是平台设计示例，实际风险需结合组织政策、数据敏感度、作用域及用户授权确定。R2/R3 可以引入人工审批、双重确认或更严格的限额；不能只靠“模型会谨慎”作为安全控制。
三、核心对象模型
3.1 建议区分的对象
| 对象 | 身份与含义 | 生命周期要点 |
|---|---|---|
| Resource Definition | 资源的稳定标识、类型、能力与 Schema | 注册、校验、更新、弃用 |
| Resource Version | 不可变能力契约及适配器版本 | 发布、兼容性、撤销 |
| Connector | 实现调用协议的代码/服务 | 安装、升级、禁用 |
| Connection | 某个主体或空间的具体连接配置 | 创建、验证、失效、轮换 |
| Credential Reference | 指向密钥管理系统的引用 | 授权、轮换、撤销 |
| Resource Binding | 将 Agent/Workflow 与资源和作用域关联 | 授予、变更、撤销 |
| Policy Decision | 一次使用许可与限制的判定 | 审计、过期、重新评估 |
| Invocation | 一次具体资源操作 | 请求、执行、结果、失败 |
| Usage Record | 用量、成本和配额记录 | 汇总、归因、对账 |
Resource Definition 不等于 Connection：多个 Workspace 可以引用同一公开定义，但使用不同连接和授权。Binding 不应包含明文凭据。Invocation 应引用 Run、Step Run 或人工操作上下文，便于追踪来源。
3.2 关系示意
flowchart LR
RD[Resource Definition] --> RV[Resource Version]
RV --> CN[Connector Adapter]
WS[Workspace / Tenant] --> CO[Connection]
CO --> CR[Credential Reference]
AG[Agent Version / Workflow Version] --> BD[Resource Binding]
BD --> RV
BD --> CO
RUN[Run / Step Run] --> INV[Invocation]
INV --> PD[Policy Decision]
INV --> CN
INV --> US[Usage Record]
PD --> BD这是逻辑模型。实际部署中 Resource Registry、Connection Service、Secrets Manager、Policy Engine 与 Invocation Gateway 可以合并在模块化单体中，亦可按规模拆分。
3.3 参考资源声明
{
"resource_id": "resource.web_search",
"version": "1.2.0",
"kind": "tool",
"operations": [
{
"name": "search",
"input_schema_ref": "schemas/search-input-v2.json",
"side_effect": "read_only",
"timeout_ms": 15000,
"retry_policy": "bounded_read_retry"
}
],
"connector": {"type": "http_adapter", "adapter_version": "2.1.0"},
"required_scopes": ["search:read"],
"data_classification": "external_request"
}以上是教学用 Manifest，不是行业统一 Schema。read_only 应描述业务语义，不能由 HTTP GET/POST 方法机械推断。
四、总体技术架构
flowchart TB
UI[Builder / Studio / SDK] --> API[Platform API]
API --> REG[Resource Catalog & Registry]
API --> CON[Connection Management]
CP[Control Plane] --> BIND[Binding & Authorization]
CP --> RUN[Run Admission]
RUN --> EP[Execution Plane / Worker]
EP --> GW[Resource Invocation Gateway]
GW --> PDP[Policy Decision / Quota]
GW --> SEC[Secrets Broker]
GW --> ADP[Typed Adapters]
ADP --> MOD[Model Providers]
ADP --> TOOL[Tools / External APIs]
ADP --> DATA[Knowledge / Data Sources]
GW --> OBS[Trace / Usage / Audit]
REG --> BIND
CON --> SEC4.1 组件职责
Resource Catalog / Registry：维护资源标识、能力描述、Schema、版本、状态、标签、所有者与可发现范围。Catalog 面向检索发现，Registry 面向可信定义与版本管理，两者可由同一服务承担。
Connection Management：管理供应商端点、区域、认证方式、健康状态、工作空间绑定与凭据引用。它负责连接的可用性，不代表连接使用者拥有全部操作权限。
Binding & Authorization：将资源能力与 Agent Version、Workflow Version、Workspace 或特定 Run 绑定，定义允许的操作、环境和数据范围。发布时校验声明，运行时再次授权。
Invocation Gateway：统一执行请求准入、调用追踪、超时、速率限制、计量和错误映射；通过类型化 Adapter 处理各类供应商协议。不是所有请求都必须通过一个中心化网络代理：在高吞吐或严格隔离场景中，可使用 SDK/Sidecar/本地 Adapter，但必须保留等价治理控制。
Secrets Broker：在受授权且受约束的执行环境中提供短期凭据或代理签名调用；应支持撤销与轮换。避免把供应商 API Key 复制到 Agent Prompt、版本定义或浏览器。
Usage & Audit：记录资源调用的主体、用途、资源版本、耗时、结果状态、成本和授权决策。日志应脱敏；并非所有请求/响应内容都可以长期保存。
五、资源接入与注册流程
- 能力建模：确定资源类型、操作、Schema、输入输出、读写副作用、错误类型和成本模型。
- 适配器开发：实现认证、协议转换、分页、超时、限流、错误映射及响应标准化。
- 安全审查：确认数据传输目的地、请求范围、权限、密钥注入和网络访问规则。
- 契约测试：验证 Schema、错误码、版本兼容性与异常路径。
- 发布资源版本：登记可用能力及适配器版本；明确弃用策略。
- 创建连接：在租户或工作空间作用域配置端点、OAuth 授权或密钥引用。
- 授权绑定：按 Agent/Workflow、操作及环境设置使用范围。
- 运行时调用：检查策略、解析连接、获取受限凭据、执行、计量、审计。
- 持续运营：监控连接健康、配额、供应商变更和授权撤销。
5.1 连接状态机
DRAFT → VALIDATING → ACTIVE → DEGRADED
↘ INVALID
ACTIVE → REAUTH_REQUIRED → ACTIVE
ACTIVE → DISABLED → DELETED状态为建议示例。DEGRADED 可能代表速率限制、部分操作失败或供应商故障；REAUTH_REQUIRED 通常表示 OAuth 授权过期或被撤销。不要将“健康探测通过”误当成所有操作均有权限。
六、资源解析、版本与依赖锁定
Agent Version 可以引用 resource_id + version_constraint，但运行前还需要解析具体资源版本、连接、授权主体和策略。对于可复现性要求较高的任务，建议生成 Resolved Resource Snapshot，包含：资源版本、适配器版本、连接标识（非密钥）、允许操作、模型路由策略版本、策略版本和解析时间。
{
"run_id": "run_123",
"resource_snapshot": [
{
"resource_id": "resource.web_search",
"resource_version": "1.2.0",
"connection_id": "conn_ws_04",
"allowed_operations": ["search"],
"adapter_version": "2.1.0"
}
],
"policy_version": "policy_2026_10"
}注意：即使版本、配置与提示词完全固定，外部搜索结果、远程数据库、供应商模型和实时 API 仍可能发生变化。依赖可追溯不等于执行结果严格可复现。若需重放，应保存合法、必要、脱敏的响应快照或可验证的结果摘要，并遵守数据保留政策。
七、模型资源集成
7.1 模型目录与供应商适配
模型资源应记录能力（文本、图像、语音、Embedding）、上下文或输入限制、结构化输出支持、工具调用能力、地区、数据处理约束、价格来源与更新日期。能力描述是运行时路由的依据，但不能仅依赖供应商的营销标签；关键能力应有实测或契约验证。
典型路径：Agent/Workflow 声明模型需求 → Control Plane 校验模型策略 → Model Gateway 选择供应商及模型 → 适配器构造请求 → 返回输出、用量与错误 → 记录 Run 级用量。
7.2 路由与回退
路由可以基于能力、预算、区域、延迟、可用性和租户策略。回退时需检查目标模型是否支持相同输入结构、工具调用、上下文长度和数据区域要求。自动切换模型可能改变行为和输出质量，应记录实际模型 ID，必要时禁止静默回退。
模型提供方返回的 token 统计、计费单位和缓存语义可能不同。平台可建立统一计量字段，但必须保留原始供应商计量与换算依据，避免把估算成本误报为最终账单。
八、工具、API 与外部服务集成
8.1 工具契约
工具注册应至少包含名称、用途、输入 Schema、输出 Schema、错误类型、权限作用域、超时、重试策略、副作用等级和数据处理要求。描述文本用于帮助 Agent 选择工具，但不能替代平台侧的 Schema 校验与授权。
8.2 只读与写入操作
| 操作 | 例子 | 主要控制 |
|---|---|---|
| 只读查询 | 搜索文档、查询公开资料 | 访问范围、速率限制、脱敏 |
| 受控修改 | 更新工单、写入数据库 | 用户授权、幂等键、变更审计 |
| 外部发送 | 发送邮件、发布内容 | 审批、收件对象校验、去重 |
| 高风险操作 | 删除资产、资金类操作 | 明确授权、额外确认、强审计 |
即使是只读工具，也可能泄露查询内容、产生费用或触发外部服务记录；“只读”不等于“无风险”。
8.3 超时与重试
必须区分连接失败、超时、供应商限流、认证失效、输入无效和业务拒绝。对可重试错误采用有上限的指数退避与随机抖动；对非幂等写入，先检查供应商是否支持幂等键、状态查询或补偿操作。超时之后结果可能处于未知状态，不得自动认定未执行。
8.4 协议适配与 MCP
Model Context Protocol（MCP）可作为工具与资源接入的协议选择之一，但不能替代平台的租户授权、凭据治理、执行隔离与审计。平台应在接入 MCP Server 或其他远程工具服务时，核验服务身份、工具清单变更、操作作用域、网络访问范围及数据外传风险。不同协议的授权模型与安全特性应按其官方规范版本评估。
九、知识库、数据库与文件资源
9.1 知识资源的访问边界
Knowledge Resource 可以表示文档集合、索引、检索配置或知识服务。平台需区分知识资产所有者、索引维护者、查询者及 Agent 执行主体。检索时应将 ACL 约束下推到实际数据检索层，而不是检索完成后仅在 UI 隐藏敏感结果。
9.2 数据源连接
数据库连接应尽量使用最小权限账号、只读视图或限定的查询模板。允许模型自由生成 SQL 时，应增加语句类型约束、执行超时、行数限制、敏感字段控制和审计；不应将模型生成的 SQL 直接作为可信输入。
9.3 文件与对象存储
文件访问应通过对象 ID、租户归属、权限与短期访问凭据控制。外部导入文件需验证类型、大小、来源和内容处理风险。Agent 生成的 Artifact 归 P10 管理资产生命周期，P7 负责资源接入与调用路径；两者通过资源引用和授权契约连接。
十、认证、授权与密钥治理
10.1 身份层次
一次资源调用至少涉及四类身份：发起操作的用户、Agent/Workflow 的逻辑身份、执行任务的运行时服务身份、连接到外部供应商的授权身份。四者不能简单合并成“平台管理员账号”。
10.2 授权判定
建议判定输入包括：tenant_id、workspace_id、user_id/service_principal、agent_version、run_id、resource_id、operation、environment、data_scope。授权结果可包含允许/拒绝、最大用量、审批要求、输出脱敏和审计级别。
授权策略既可以由 P12 统一制定，也需要在 P7 的资源调用路径强制执行。构建期、发布期与运行期校验各有作用，不能互相替代。
10.3 凭据处理
- 密钥存入 Secrets Manager 或等价安全存储，数据库仅保存引用和必要元数据。
- 优先使用短期、可撤销、最小权限凭据；按供应商能力采用 OAuth 或服务身份。
- 不将凭据注入 Prompt、日志、Trace、错误消息或导出的 Manifest。
- 支持轮换、撤销、连接失效通知与审计。
- 对第三方工具采取网络出口控制，防止通过非授权地址转发敏感数据。
10.4 Prompt Injection 与不可信资源
工具输出、网页内容和检索文档应视为不可信数据，不能将其中的“系统指令”“授权要求”提升为平台控制指令。对于高风险工具操作，应在模型输出之外设置确定性的权限与审批检查。这里的隔离与策略执行应与 03 Agent System / H2 Security、H12 Policy & Governance 协同。
十一、资源调用执行链路
sequenceDiagram
participant U as User/Studio
participant CP as Control Plane
participant W as Worker
participant G as Invocation Gateway
participant A as Auth/Policy
participant S as Secrets Broker
participant X as External Provider
participant O as Audit/Usage
U->>CP: Start Run (Agent Version)
CP->>CP: Resolve resource bindings
CP->>W: Dispatch Run + resource snapshot
W->>G: Invoke resource operation
G->>A: Authorize subject + operation + scope
A-->>G: Permit / Deny / Require approval
G->>S: Request scoped credential
S-->>G: Short-lived access or signed request
G->>X: Execute provider request
X-->>G: Response / error / usage
G->>O: Emit trace + usage + audit metadata
G-->>W: Typed result
W-->>CP: Step outcome / artifact reference该流程是参考时序。审批需要独立的持久化等待与恢复流程，不能在网关中无限期阻塞连接。平台可以通过侧车或 Worker 内 SDK 执行相同职责，核心是授权、计量和审计控制不可绕过。
十二、可靠性、性能与成本治理
12.1 可靠性策略
| 风险 | 平台控制 | 验证重点 |
|---|---|---|
| 供应商限流 | 配额、队列、退避、熔断 | 不发生无限重试 |
| 网络超时 | 截止时间、未知结果处理 | 写入不会无条件重放 |
| 凭据撤销 | 连接状态更新、重新授权 | 已撤销权限不能继续使用 |
| 连接器升级 | 版本固定、兼容测试、回滚 | 老 Run 依赖可追溯 |
| 数据源越权 | 查询级 ACL、租户隔离 | 跨租户数据不可读 |
| 外部输出污染 | 输入净化、内容边界、策略 | 不可信文本不能提权 |
| 资源不可用 | 降级、人工介入、错误分类 | 失败原因可诊断 |
12.2 资源配额
配额应支持至少按租户、工作空间、Agent、资源类型和时间窗口聚合。区分“调用次数”“并发”“token”“计算时间”“数据传输”“供应商费用”等不同维度。预算是控制策略，不等于财务结算；供应商账单可能延迟，平台需要对估算与最终对账结果分别标识。
12.3 性能设计
资源目录与非敏感元数据可缓存；授权结果、连接状态和密钥不应无限期缓存。批量请求、连接池、流式响应、并发限制与熔断可降低延迟或成本，但需权衡数据隔离、供应商限制与错误放大。缓存检索结果时必须将租户、ACL 与数据版本纳入缓存键或等价隔离机制。
十三、参考 API、数据模型与事件契约
13.1 参考 API
POST /v1/resources
GET /v1/resources?kind=tool
GET /v1/resources/{resource_id}/versions
POST /v1/workspaces/{workspace_id}/connections
POST /v1/connections/{connection_id}:validate
POST /v1/agents/{agent_id}/resource-bindings
GET /v1/runs/{run_id}/resource-usage
POST /v1/connections/{connection_id}:revoke这些路径是示例，不代表任何既有厂商 API。写入请求应包含幂等策略与明确的权限检查。
13.2 参考关系模型
CREATE TABLE resource_definitions (
resource_id TEXT PRIMARY KEY,
kind TEXT NOT NULL,
owner_tenant_id TEXT,
status TEXT NOT NULL
);
CREATE TABLE resource_versions (
resource_id TEXT NOT NULL,
version TEXT NOT NULL,
manifest_json JSONB NOT NULL,
manifest_digest TEXT NOT NULL,
PRIMARY KEY (resource_id, version)
);
CREATE TABLE connections (
connection_id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
workspace_id TEXT NOT NULL,
resource_id TEXT NOT NULL,
credential_ref TEXT NOT NULL,
status TEXT NOT NULL
);
CREATE TABLE resource_bindings (
binding_id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
agent_version_id TEXT,
workflow_version_id TEXT,
resource_id TEXT NOT NULL,
resource_version TEXT NOT NULL,
connection_id TEXT NOT NULL,
allowed_operations JSONB NOT NULL
);
CREATE TABLE resource_invocations (
invocation_id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
run_id TEXT NOT NULL,
binding_id TEXT NOT NULL,
operation TEXT NOT NULL,
status TEXT NOT NULL,
duration_ms INTEGER,
estimated_cost NUMERIC(18,6),
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);实现注意：这仅展示对象边界，未包含完整外键、唯一性、索引、审计、行级安全、加密与迁移方案。生产系统还应根据租户隔离策略设置复合键/约束，防止跨租户引用。credential_ref 不是密钥明文。
13.3 参考事件
{
"event_type": "resource.invocation.completed",
"event_id": "evt_001",
"tenant_id": "tenant_a",
"run_id": "run_123",
"invocation_id": "inv_456",
"resource_id": "resource.web_search",
"operation": "search",
"status": "succeeded",
"duration_ms": 812,
"usage": {"request_count": 1},
"timestamp": "2026-10-31T00:00:00Z"
}事件消费者应具备去重与乱序容忍能力；避免把敏感请求正文、完整响应和密钥放入通用事件总线。
十四、贯穿案例：技术研究报告 Studio
14.1 资源需求
Studio 的研究任务可能需要：模型服务（选题、分析、写作）、网页检索、团队知识库、文档解析、文件存储，以及可选的邮件/发布服务。每项资源分别声明访问范围和调用语义；不能让所有 Agent 共用一个拥有全部权限的连接。
| 角色/环节 | 所需资源 | 建议权限 |
|---|---|---|
| 选题 Agent | 模型、公开搜索 | 只读 |
| 深度调研 Agent | 模型、搜索、文档读取 | 只读与有限文件写入 |
| 分析 Agent | 模型、已授权资料 | 只读 |
| 审核 Agent | 模型、报告草稿 | 只读、写审核意见 |
| 写作 Agent | 模型、项目文件存储 | 项目内产物写入 |
| 发布步骤 | CMS/邮件等外部服务 | 独立审批与授权 |
14.2 一个完整调用示例
用户启动研究任务后，Control Plane 固定 Workflow Version 和 Agent Version，解析该 Workspace 可用的搜索连接与模型策略。Worker 在调研节点请求搜索工具；Invocation Gateway 验证资源绑定、调用范围和配额，随后使用工作空间授权的连接执行请求，返回标准化结果并记录引用与用量。研究结果写入项目产物存储，后续分析节点只能读取获授权的项目资料。若最后一步需要向外部发布，平台创建审批请求，审批通过后才允许写入外部系统。
14.3 分阶段实施
阶段 A：最小闭环。支持模型、公开检索、文件存储三类资源；实现 Resource Definition、Connection、Binding、Invocation 与基础审计；密钥不入数据库明文。
阶段 B：团队协作。增加 Workspace 级连接管理、权限作用域、资源配额、依赖版本快照、连接健康与告警。
阶段 C：平台化运营。增加 OAuth 连接、第三方写入审批、连接器版本治理、跨租户隔离、计费对账和插件生态集成。
不要把这些阶段理解为必须依次部署的固定架构。若初始业务包含敏感数据或高风险写操作，应从第一天就实现对应的权限与审批控制。
十五、工程验证与验收设计
以下均为待执行测试。建议采用假供应商（Fake Provider）、受控测试租户、模拟密钥轮换与故障注入，避免直接在生产账号中测试高风险写操作。
| ID | 测试场景 | 预期验收条件 |
|---|---|---|
| T01 | 注册合法资源定义 | Schema 校验通过并记录版本 |
| T02 | 注册非法操作 Schema | 拒绝并返回可诊断错误 |
| T03 | 资源版本更新 | 已发布版本不被原地修改 |
| T04 | 工作空间创建连接 | 仅保存凭据引用，不暴露密钥 |
| T05 | 连接验证失败 | 正确标记状态与错误类别 |
| T06 | 无授权 Agent 调用 | 网关拒绝且记录审计 |
| T07 | 跨租户引用连接 | 拒绝且无数据泄露 |
| T08 | 只读工具正常调用 | 结果与用量可关联 Run |
| T09 | 外部写入未审批 | 操作不被实际执行 |
| T10 | 供应商限流 | 有界退避并记录原因 |
| T11 | 写入调用超时 | 标记未知结果，不盲目重试 |
| T12 | 密钥轮换 | 旧凭据撤销，新凭据按策略生效 |
| T13 | OAuth 授权撤销 | 后续调用被拒绝 |
| T14 | 资源配额耗尽 | 拒绝新调用，已有记录可查询 |
| T15 | 连接器版本升级 | 契约兼容或明确拒绝 |
| T16 | 工具输出注入指令 | 不提升为系统授权指令 |
| T17 | 检索 ACL 限制 | 不返回无权访问的文档 |
| T18 | 模型路由回退 | 实际模型被记录且策略合规 |
| T19 | 审计脱敏 | 日志不包含凭据和敏感正文 |
| T20 | 重复事件 | 用量不会无故重复累计 |
| T21 | 资源删除与历史 Run | 历史引用仍可审计，遵守保留策略 |
| T22 | 多连接同一资源 | 作用域与计量相互隔离 |
| T23 | 外部服务故障 | 降级或失败可诊断，无无限循环 |
| T24 | 并发高负载 | 配额和并发限制实际生效 |
建议补充非功能指标：授权拒绝正确率、跨租户泄露事件数、连接健康检测延迟、调用成功率、P95 调用延迟、供应商成本差异、凭据轮换恢复时间。指标阈值应由业务 SLO 与供应商 SLA 决定，不应在缺乏负载基线时随意规定。
十六、常见误区与架构决策
误区一：统一资源网关意味着所有外部能力都有相同语义。 实际上，统一治理与观测即可；模型流式输出、数据库事务和异步邮件发送需要各自的适配器与错误模型。
误区二：Agent Manifest 中引用资源就意味着已获授权。 Manifest 是能力声明，运行期仍必须检查主体、租户、操作和数据范围。
误区三：保存 API Key 即完成集成。 集成还包括授权撤销、版本兼容、速率限制、审计、数据合规与故障处理。
误区四：只读操作无需治理。 搜索查询、数据库读取和外部检索可能泄露信息、产生成本或越过 ACL。
误区五：重试总能提升成功率。 对非幂等写入，超时后重试可能导致重复副作用。
误区六：模型生成的工具调用是可信命令。 平台必须在执行前完成确定性的 Schema、权限和策略校验。
16.1 关键架构决策记录（ADR）建议
每项重要决策应记录：业务约束、候选方案、选择理由、放弃方案、风险、迁移成本和验证方法。优先记录以下 ADR：资源目录与 Agent Registry 是否合并；网关集中式还是 Worker 侧适配；密钥管理方式；模型路由与回退策略；多租户连接隔离；高风险写入审批；资源调用审计与数据保留。
十七、专题总结与后续衔接
P7 的核心成果是一套资源治理与调用契约：平台能够知道有哪些资源、由谁提供、谁有权使用、如何调用、调用了什么、产生多少成本、发生错误后如何处理。它将 P3/P4 中的依赖声明连接到 P5/P6 的实际执行过程，同时向 P8 的 API/SDK、P9 的插件扩展、P10 的资产管理以及 P11/P12 的租户治理提供基础。
后续 P8 应重点研究平台如何向外提供统一 API 与 SDK，不能把 P7 的“平台接入外部资源”与 P8 的“外部开发者接入平台”混为一谈。
附录 A：参考文献与原始资料
以下优先列出标准、协议和官方文档入口。部分链接是持续更新的官方文档，而非固定出版版本；在正式工程实施前应核验对应版本、适用日期与供应商约束。
- Model Context Protocol，官方规范与文档：<modelcontextprotocol.io/specification>。用于研究工具与资源互操作协议；不代表平台安全治理已由协议自动实现。
- OAuth 2.0 Authorization Framework，RFC 6749：<www.rfc-editor.org/rfc/rfc6749>。用于外部授权与访问令牌基础。
- OAuth 2.0 Security Best Current Practice，RFC 9700：<www.rfc-editor.org/rfc/rfc9700>。用于 OAuth 安全实践。
- HTTP Semantics，RFC 9110：<www.rfc-editor.org/rfc/rfc9110>。用于 HTTP 方法语义、状态码与幂等性背景。
- OpenAPI Specification：<spec.openapis.org/oas/latest.html>。用于 REST API 契约描述。
- JSON Schema 官方规范：<json-schema.org/specification>。用于工具输入输出与资源 Manifest 校验。
- OpenTelemetry 官方文档：<opentelemetry.io/docs>。用于跨服务追踪、指标与日志语义。
- OWASP Top 10 for LLM Applications 项目：<genai.owasp.org>。用于检索内容与工具输出的提示注入风险研究。
- NIST AI Risk Management Framework：<www.nist.gov/itl/ai-risk-management-framework>。用于风险识别、治理和控制设计。
- PostgreSQL 官方文档：<www.postgresql.org/docs>。用于参考关系模型、事务和行级安全的实现核验。
- HashiCorp Vault 官方文档：<developer.hashicorp.com/vault/docs>。作为凭据管理的一种实现参考，非唯一方案。
- Kubernetes Secrets 官方文档：<kubernetes.io/docs/concepts/configuration/secret>。用于理解容器环境中的敏感配置管理及其局限。
引用边界：本篇对象模型、资源分级、参考 API、SQL、状态机和分阶段路线均为本文综合设计建议，不应被误写为上述标准的强制要求。文中没有对各供应商最新功能、价格或服务级别作实时核验。
附录 B：研究证据、验证声明与适用边界
| 内容 | 证据属性 | 当前状态 |
|---|---|---|
| OAuth、HTTP、JSON Schema、OpenAPI 等协议背景 | 可通过规范核验 | 提供官方核验入口；本文未逐条执行兼容测试 |
| Resource / Connection / Binding / Invocation 对象划分 | 工程抽象与设计建议 | 未经真实业务验证 |
| Invocation Gateway 与 Secrets Broker 架构 | 参考实现方案 | 未部署、未测性能 |
| 多租户资源隔离与 ACL 设计 | 安全架构建议 | 未开展渗透或隔离测试 |
| Studio 资源矩阵和开发路线 | 场景化推演 | 需要根据实际代码和需求校准 |
| 24 项测试 | 待执行验收计划 | 未运行；不得表述为通过 |
| 模型回退、供应商计费与连接健康 | 需依赖具体供应商验证 | 未核验实时价格、接口能力或 SLA |
适用范围：适用于需要统一接入模型、工具、知识、数据和第三方服务的 Agent Platform，尤其适用于多 Agent Studio、团队协作平台及面向开发者的可扩展系统。小型单用途 Agent 应用可以简化 Catalog、网关与连接服务的物理实现，但仍需保留必要的授权、密钥和错误处理机制。对于金融、医疗、政府等高敏感领域，还应增加行业合规、数据驻留、审计与审批要求。
最终自检：本文使用 v1.3 正式专题名称与编号；明确与 P3 - P4 - P5 - P6 - P7 - P8 - P9 - P10 - P11 - P12 的边界；提供对象、架构、调用链、API、SQL、Studio 案例、测试与证据声明；所有示例均标识为参考设计，未声称完成真实测试。