手搓生产级 AI Agent 系统（16）：Agent Registry 与 Capability Marketplace——让 Tool、Skill、MCP 和 Agent 可以被发现、授权与复用

文章摘要

前十五篇已经把生产级 Agent 从单体运行扩展到了 Planner、Tool Calling、Memory、Checkpoint、Human-in-the-Loop、多 Agent 协作、安全沙箱、评测发布和 Control Plane。系统现在已经能“管住 Agent”，但随着 Agent、Tool、Skill、MCP Server 和 Workflow 数量增长，新的问题开始出现：能力散落在代码、Prompt、YAML、MCP 配置和各个团队仓库里，Agent 不知道公司到底有哪些能力，平台不知道谁在用某个 Tool，也无法在一个高风险能力出问题时快速查清影响面并完成下线。

本篇继续建设 Agent Control Plane 的下一层：Registry + Capability Marketplace。目标不是做一个漂亮的“Agent 商店”，而是先建立一套统一能力目录，把 REST Tool、MCP Tool、Skill、Sub-Agent、Workflow 都抽象为可发现、可授权、可版本、可观测、可废弃的 Capability；再通过 Discovery Policy、语义搜索、Risk Gate、Credential Broker 和 Invocation Ledger，让模型只看到当前任务真正有权使用的一小部分能力。最后在这些基础上，才加入评分、推荐、模板和跨团队复用。

这一步的价值很实际：当公司从 10 个 Tool 增长到 500 个 Capability 后，Agent 不再需要把所有 Schema 塞进 Prompt；当某个 MCP Server 紧急下线时，平台能在几分钟内知道哪些 Agent、Workflow 和租户受影响；当团队重复造同一个 Tool 时，Registry 能把已有实现直接暴露出来；当高风险 Tool 被发现时，系统在 Discovery 阶段就能隐藏，而不是让模型看见以后靠 Prompt 自律。

为什么第 16 篇开始讨论“能力目录”

Agent 数量少的时候，架构很简单：

Agent
├─ Tool A
├─ Tool B
└─ Tool C

Tool 写在代码里。

半年以后经常变成：

25 个 Agent
18 个 Skill
60 个 REST Tool
14 个 MCP Server
9 个 Workflow
5 个模型 Provider

这时问题变成：

谁拥有这些能力？
哪个还在生产？
哪个已经 Deprecated？
谁有权限？
哪个最稳定？
哪个最便宜？
哪些 Agent 正在使用？

如果答案只能靠：

grep -R "tool_name" .

说明平台还没有真正形成能力层。

Registry 不是一个 Tool List

MCP 可以返回 tools/list。

Spring Bean 也能列出 Tool。

这些都只是：

当前进程能看到的工具

Registry 要回答的是组织级问题：

整个组织有什么能力？

所以我会统一抽象：

public enum CapabilityType {
    REST_TOOL,
    MCP_TOOL,
    SKILL,
    SUB_AGENT,
    WORKFLOW,
    DATA_SOURCE
}

这里刻意把 Skill 和 Agent 也放进来。

因为从调用方角度看，它们都是：

可复用能力

Capability 的最小 Contract

public record CapabilityManifest(
        String capabilityId,
        String displayName,
        CapabilityType type,
        String version,
        CapabilityStatus status,
        RiskLevel riskLevel,
        String ownerTeam,
        String description,
        String inputSchemaRef,
        String outputSchemaRef,
        Set requiredScopes,
        boolean approvalRequired,
        InvocationLimits limits,
        String providerBinding,
        String schemaHash) {
}

状态：

public enum CapabilityStatus {
    DRAFT,
    REVIEW,
    PRODUCTION,
    DEPRECATED,
    DISABLED
}

不要只有：

enabled=true/false

因为生产能力需要生命周期。

为什么 Tool、Skill、Agent 要统一

例如用户说：

帮我评估这份合同风险。

平台可能有三种实现：

contract-risk MCP Tool
legal-review Skill
legal-agent Sub-Agent

如果每种能力都由不同系统发现，上层 Router 会越来越复杂。

统一成：

Capability

以后，Discovery 只负责回答：

哪些能力可以帮助完成这个任务？

具体调用协议由 Adapter 处理。

Adapter 层

public interface CapabilityAdapter {

    boolean supports(
            CapabilityType type);

    InvocationResult invoke(
            CapabilityManifest capability,
            InvocationContext context,
            JsonNode arguments);
}

实现：

RestToolAdapter
McpToolAdapter
SkillAdapter
SubAgentAdapter
WorkflowAdapter

Agent 不需要知道某个能力背后是 HTTP、MCP 还是另一个 Agent。

它只需要一个稳定 Contract。

Discovery 和 Invocation 必须拆开

这是第一个关键安全边界。

一个主体可能：

可以知道某个能力存在

但不能调用。

另一个场景更严格：

连能力名称都不应该看到

例如 HR Agent 不应该发现：

production.database.delete

所以 Policy 至少有两个动作：

public interface CapabilityPolicy {

    boolean canDiscover(
            AccessContext access,
            CapabilityManifest capability);

    InvocationDecision canInvoke(
            AccessContext access,
            CapabilityManifest capability,
            InvocationRequest request);
}

为什么 Policy 必须在搜索之前

如果 Registry 里有 1000 个能力，最自然的实现是：

Embedding Search
→ Top 10
→ 权限过滤

这个顺序有问题。

因为搜索结果本身就可能泄露未授权能力。

正确顺序：

权限粗过滤
↓
语义搜索
↓
风险过滤
↓
任务上下文过滤
↓
Top K

即：

Policy Before Ranking

这应该成为 Agent Registry 的默认规则。

Capability Discovery Request

public record CapabilityDiscoveryRequest(
        String agentId,
        String tenantId,
        String subjectId,
        String purpose,
        String taskDescription,
        Set allowedTypes,
        RiskLevel maximumRisk,
        int limit) {
}

返回：

public record CapabilityCandidate(
        String capabilityId,
        String version,
        String description,
        RiskLevel risk,
        boolean approvalRequired,
        double relevanceScore,
        CapabilityHealth health) {
}

这里不返回 Secret。

也不一定立即返回完整 Tool Schema。

为什么要延迟加载 Tool Schema

假设企业有：

800 个 Capability

每个 Tool Schema 平均：

500 Token

如果一次性塞给模型：

40 万 Token

完全不可接受。

更合理的流程：

Intent
↓
Capability Discovery
↓
得到 5—10 个候选
↓
Materialize Tool Schema
↓
LLM 选择
↓
Invoke

也就是：

先发现能力
再加载协议

这和数据库查询优化非常像。

语义检索不是唯一评分

Discovery 可以组合：

Semantic Similarity
Keyword
Agent Affinity
Reliability
Latency
Cost

例如：

score = (
    semantic * 0.40
    + keyword * 0.20
    + agent_affinity * 0.15
    + reliability * 0.10
    + latency_score * 0.05
    + cost_score * 0.10
)

但这里有两个东西永远不应该进入加权平均：

Permission
Hard Risk Gate

没有权限就是 0。

Critical 且不满足审批就是 0。

不能因为语义相关度很高就突破权限。

Capability 的 Description 要像 API 文档，而不是营销文案

差的描述：

一个智能、强大、灵活的客户管理工具，
帮助 Agent 高效完成复杂工作。

模型完全不知道该什么时候用。

好的：

读取指定客户的 CRM 基本信息、
当前销售阶段和最近 20 条跟进记录。
只读，不修改 CRM。

再好的：

Use when the task requires current CRM status.
Do not use for contract, payment or support data.
Read-only.

Description 本身也是 Agent 选择质量的一部分。

Registry 要保存 Schema Hash

Tool 参数改一个字段就可能让旧 Agent 失败。

所以 Manifest 至少保存：

Version
Schema Hash
Compatibility

例如：

public enum CompatibilityLevel {
    BACKWARD_COMPATIBLE,
    BREAKING
}

升级：

v3 → v4

如果是 Breaking：

旧 v3 保留一段兼容期

而不是原地覆盖。

MCP Server 只是 Provider Binding

例如：

capability:
cloudrun.service.read

背后可能绑定：

google-managed-mcp

另一个环境绑定：

internal-cloudrun-proxy

所以：

Capability

和：

Provider

分开。

public record CapabilityProviderBinding(
        String bindingId,
        String capabilityId,
        String providerType,
        String endpointRef,
        String version,
        String region,
        int priority,
        BindingStatus status) {
}

这样同一个业务能力可以做多 Provider 容灾。

Agent 身份与用户身份都要带到 Invocation

不能只记录：

agent_id

因为 Agent 通常代表用户执行。

Invocation Context：

public record InvocationContext(
        String runId,
        String stepId,
        String agentId,
        String subjectId,
        String tenantId,
        String purpose,
        String approvalId,
        Set grantedScopes) {
}

最后审计能回答：

哪个用户
通过哪个 Agent
为了什么任务
调用了哪个能力

Credential Broker

Registry 不保存长期 Credential。

真正调用时：

Capability Resolver
↓
Policy
↓
Credential Broker
↓
短期 Token
↓
Adapter

public interface CredentialBroker {

    TemporaryCredential issue(
            InvocationContext context,
            CapabilityManifest capability,
            Duration ttl);
}

高风险 Capability：

TTL 可能只有 1—5 分钟

调用结束即失效。

Invocation Decision

不要只有：

ALLOW
DENY

生产 Agent 需要第三类：

ALLOW_WITH_APPROVAL

public record InvocationDecision(
        boolean allowed,
        boolean approvalRequired,
        Set scopes,
        Duration credentialTtl,
        int maximumCalls,
        List reasons) {
}

这样模型仍然可以规划：

我需要 deploy

但执行停在 Approval。

Tool 调用次数也属于能力策略

一些 Tool 风险不高，但成本很高。

例如：

大型数据查询
昂贵搜索 API
GPU 任务

Registry 可以声明：

limits:
  max_calls_per_run: 3
  timeout: 30s
  estimated_cost: 0.08

运行时 Budget Service 再根据 Run 剩余额度决定。

Capability Health

如果能力正在故障，Discovery 不应该继续高频推荐。

public record CapabilityHealth(
        HealthStatus status,
        double successRate,
        Duration p95Latency,
        double errorRate,
        Instant measuredAt) {
}

Rank 时考虑 Health。

如果：

UNHEALTHY

可以：

隐藏
降权
切 Provider

Registry 最终会形成 Dependency Graph

有了统一目录，可以画：

Agent
→ Capability
→ MCP Server
→ Backend

例如：

sales-renewal-agent
→ crm.customer.read
→ crm-mcp
→ Salesforce

另一个：

release-agent
→ cloudrun.service.deploy
→ google-cloudrun-mcp
→ Cloud Run

这个图非常有价值。

当 crm-mcp 出问题，可以立即查：

影响哪些 Agent？
影响哪些 Workflow？
影响哪些租户？

这就是为什么 Control Plane 需要 Registry

上一期 Control Plane 管：

Run
Budget
Approval
Policy
Feedback

Registry 管：

“系统能做什么”

两者结合以后：

Control Plane
+
Capability Plane

才完整。

Control Plane 决定：

这次 Run 能不能做

Capability Plane 决定：

有什么东西可以做

Invocation Ledger

每次调用写：

public record CapabilityInvocationRecord(
        String invocationId,
        String runId,
        String agentId,
        String subjectId,
        String tenantId,
        String capabilityId,
        String capabilityVersion,
        String providerBinding,
        RiskLevel risk,
        String approvalId,
        InvocationStatus status,
        long inputBytes,
        long outputBytes,
        Duration latency,
        BigDecimal cost,
        Instant startedAt) {
}

之后可以做：

审计
成本归因
热度
可靠度
Deprecated 分析
推荐

从 Registry 走向 Marketplace

当基础治理稳定以后，才有资格做 Marketplace。

Marketplace 可以增加：

Rating
Usage
Owner
Examples
Templates
Install
Subscription

但最重要的仍然不是 UI。

而是每个能力必须先有：

Owner
Version
Permission
Risk
SLO
Contract

没有这些，Marketplace 只是把混乱展示得更漂亮。

一个内部 Marketplace 页面应该显示什么

例如：

Customer Renewal Analysis

Type:
Workflow

Owner:
Sales Platform

Version:
v8

Risk:
Medium

Used by:
18 Agents

Success Rate:
94.1%

P95:
12.8s

Cost:
$0.031 / invocation

Permissions:
crm.read
contract.read

Approval:
No

用户点击：

Add to Agent

不是直接安装。

先走：

Policy Check

Marketplace 的推荐也要小心

如果按：

调用量

排序，很容易产生：

热门越来越热门

更合理的推荐要看：

任务相关性
权限
组织认可
可靠度
成本
风险

不是 App Store 的下载排行榜。

Capability Duplication

Registry 还有一个很实在的作用：

减少重复造 Tool

团队 A 做：

customer_search

团队 B 又做：

crm_lookup

团队 C 再做：

find_account

三套代码访问同一个 CRM。

如果没有目录，很难发现重复。

Registry 可以在新建 Capability 时做：

Semantic Duplicate Detection

提示：

已有 3 个相似能力

让团队决定复用还是新建。

Capability Promotion 流程

新能力不是提交完就生产。

DRAFT
↓
REVIEW
↓
STAGING
↓
PRODUCTION

检查：

Schema
权限
风险
Owner
测试
SLO
审计
成本

高风险 Tool 再加安全 Review。

Deprecated 也要有生命周期

DEPRECATED

不等于立刻下线。

Manifest 里保存：

announced_at
disable_at
replacement
migration_note

Discovery 结果可以提醒 Agent：

这个 Capability 即将下线

新 Run 不再选择。

旧 Workflow 有迁移期。

Emergency Disable

真正生产 Registry 必须支持：

一键禁止发现
一键禁止调用

两个动作可以分开。

例如先：

disable_discovery=true

阻止新任务使用。

正在运行的任务按风险：

继续
取消
人工

如果是安全事故：

disable_invocation=true

立即阻断。

Kill Switch 范围

public enum CapabilityKillScope {
    CAPABILITY,
    PROVIDER_BINDING,
    AGENT,
    TENANT,
    GLOBAL
}

这样不必一出问题就停整个 Agent 平台。

Observability

Registry 层指标：

capability_discovery_total
capability_discovery_empty_total
capability_invocation_total
capability_policy_denied_total
capability_approval_required_total
capability_schema_error_total
capability_provider_failure_total
capability_cost_total

Marketplace 层再看：

capability_reuse_count
capability_unique_agents
capability_deprecation_remaining_users

一个非常有用的指标：Reuse Ratio

被 ≥ 2 个 Agent 使用的 Capability
/
全部生产 Capability

如果只有：

8%

说明公司所谓“平台能力”很可能仍是各项目私有代码。

如果逐步增长：

20%
40%
60%

才说明复用层开始形成。

另一个指标：Orphan Capability

没有 Owner
没有调用
没有消费者

的能力应该定期清理。

否则 Registry 会变成：

工具坟场

Agent Registry 本身

除了 Capability，还需要 Agent Registry。

public record AgentManifest(
        String agentId,
        String version,
        String ownerTeam,
        AgentStatus status,
        String modelProfile,
        Set capabilityPolicies,
        String promptRef,
        String memoryPolicyRef,
        String runtimeProfile,
        String evaluatorSuiteRef) {
}

这样可以建立：

Agent ↔ Capability

关系。

一个 Agent 不应该绑定具体 Tool

差：

tools:
  - crm_get_customer_v3
  - crm_get_contract_v2

更成熟：

capabilities:
  - crm.customer.read
  - contract.current.read

运行时 Registry 决定绑定哪个 Provider 和具体实现。

这让底层 Tool 升级不会强迫所有 Agent 改 Prompt。

Capability Marketplace 的真正终点

不是：

让员工像装 App 一样装 Agent

而是：

让组织中已经验证过的 AI 能力，能够被安全、低成本地重新组合。

一个销售团队跑通：

customer-risk

以后，续约 Agent、售前 Agent、客服 Agent 都可以复用。

不再每个团队重写 Prompt、重接 CRM。

这才是平台真正产生规模效应的地方。

本篇上线检查清单

□ Tool、Skill、MCP、Sub-Agent 和 Workflow 有统一 Capability ID
□ Capability 有 Owner、Version、Risk 和 Status
□ Discovery 与 Invocation 权限分离
□ Policy 在语义搜索之前执行
□ Agent 不一次加载全部 Tool Schema
□ Credential 不存 Registry
□ 调用使用短期 Credential
□ 高风险 Capability 支持 Approval
□ Breaking Schema 有兼容期
□ MCP Server 被视为 Provider Binding
□ Registry 可以查询 Agent → Capability 影响图
□ 每次调用进入 Invocation Ledger
□ Capability Health 参与路由
□ Deprecated 有替代项和截止时间
□ Emergency Disable 可以阻止发现和调用
□ Marketplace 上线前先完成治理字段
□ 重复 Capability 能被发现
□ Agent 绑定业务 Capability，不绑定具体实现

总结

生产 Agent 平台发展到一定规模以后，瓶颈会从：

“模型会不会调用 Tool”

变成：

“整个组织到底有哪些能力，
谁能发现，
谁能调用，
谁负责，
出了问题怎么停。”

Capability Registry 解决的是能力治理。

Marketplace 解决的是能力复用。

真正成熟的结构是：

Agent Registry
↓
Capability Discovery
↓
Policy
↓
Credential
↓
Provider Binding
↓
Invocation Ledger
↓
Feedback

当 Tool、Skill、MCP Server、Sub-Agent 和 Workflow 都进入同一个能力层以后，Agent 才能从“每个项目自己接工具”真正进入平台化。

下一篇我会继续沿着这个 Control Plane 展开：

手搓生产级 AI Agent 系统（17）：Agent Identity 与 Delegated Authority——让每一次工具调用都能回答“谁授权、代表谁、为什么做”。

更多企业级 AI 应用、Agent、RAG 与模型工程化内容，我会继续整理在 智元界：

https://www.zyentor.com/