确认已发布 Agent 会使用哪个模型和凭据

发布 Agent 前，需要用本页回答两个问题：

1. 每个候选会使用哪个 provider route、endpoint 和 credential revision？
2. Agent 发布以后，执行期能否改变这个选择？

第二个问题的答案是否定的。配置平面负责选择，执行平面负责精确物化。 一次 Agent 发布会把模型、provider 路由、endpoint、凭据引用和有序 fallback 候选冻结进 ExecutableAgentSnapshot。

具体的管理 API 操作放在 配置 provider、模型与凭据； 那里不重复这些类型和边界。本页拥有架构与契约边界。

先决定应该修改哪里

静态结构：一份发布快照是唯一执行输入

flowchart LR
    UI["管理 API / UI<br/>Agent + model intent"] --> CS["ConfigService<br/>validate + publish"]
    CAT[("Model Catalog<br/>provider · endpoint · offering")]
    CREDS[("Credential inventory<br/>id · revision · status")]
    SECRET[("SecretStore<br/>sealed material")]
    RES["CatalogModelPublicationResolver<br/>one scoped resolution"]
    SNAP["ExecutableAgentSnapshot<br/>ResolvedModelCandidate[]<br/>secret-free + fingerprinted"]
    DISPATCH["Run / Dispatch<br/>copies snapshot"]
    MAT["PinnedCredentialMaterializer<br/>exact id/revision/scope/usage"]
    EXEC["Native provider or ACP<br/>execute selected candidate"]

    CS --> RES
    CAT --> RES
    CREDS --> RES
    RES --> SNAP --> DISPATCH --> MAT --> EXEC
    CREDS --> MAT
    SECRET --> MAT

    classDef control fill:#25203b,stroke:#9b7cf6,color:#f6f3ed;
    classDef data fill:#17322d,stroke:#55b89d,color:#f6f3ed;
    classDef runtime fill:#17303a,stroke:#55aeca,color:#f6f3ed;
    class UI,CS,RES control;
    class CAT,CREDS,SECRET,SNAP data;
    class DISPATCH,MAT,EXEC runtime;

ModelBinding 是小型运行身份：provider_identity_ref + model_ref + backend_ref。 ResolvedModelCandidate 在它之外补齐实际执行所需、但仍然无密钥的 provisioning 事实。 本地 provider、兼容网关和自托管 endpoint 都属于同一种 Provider 候选；只有测试或显式 嵌入式组合使用 HostExecutor。

动态行为：发布时选择一次，执行时只做精确校验

sequenceDiagram
    participant A as Author / Managed API
    participant C as ConfigService
    participant R as CatalogModelPublicationResolver
    participant S as Snapshot store
    participant W as Worker / Host
    participant M as PinnedCredentialMaterializer
    participant P as Provider or ACP

    A->>C: validate / publish Agent revision
    C->>R: resolve(workspace, model selection, fallbacks)
    R->>R: read one catalog + credential inventory view
    R-->>C: complete secret-free candidates
    C->>S: commit fingerprinted snapshot
    Note over C,S: checkpoint: publication fixes route and credential revision

    W->>S: load snapshot selected by Run
    W->>M: materialize exact candidate
    M->>M: verify owner, status, revision, provider, usage
    M-->>W: installed executor / typed last-mile material
    W->>P: inference using the pinned candidate
    Note over W,P: no catalog lookup, env fallback, or new credential selection

模型级编写（只填写 model_ref）只在发布边界被补全：恰好一个 Active offering 匹配时 成功，没有匹配或存在歧义都会拒绝发布。显式 provider/backend 轴不会被重写。 primary 与 fallback 的顺序同样属于快照 fingerprint；运行期只能在这组已发布候选中 执行，不能去全局目录寻找替代品。

先读结果，再改变配置

不要为了让某个 Run 继续而搜索全局 catalog 或注入环境值。这样会产生第二条选择路径， 使 replay 描述的执行不同于 published fingerprint。

1.0-dev 已实现的边界

• ConfigService 构造时必须获得一个 ModelPublicationResolver，不存在隐式 provider fallback。
• CatalogModelPublicationResolver 在 Workspace 范围内生成完整、无密钥的 ResolvedModelCandidate。
• CredentialKind::Env 只为旧数据解码保留；新建和物化都失败关闭。环境变量只能产生 无密钥的编写建议，不能成为运行配置。
• Native 与 ACP 共用 PinnedCredentialMaterializer，并校验精确 credential id、revision、 Workspace、provider、status 和 usage。
• 管理 API 的 inference profile / credential-pool resolve 是运营 dry-run。它可以验证 目录和凭据组合，但不是 Run 的第二份执行权威；发布快照才是。

推理重试与发布候选 fallback 也不是同一件事：前者重试同一已选 endpoint 的暂态失败； 后者只能切换到快照中已经冻结的下一个完整候选。

相关

• 配置 provider、模型与凭据
• 通过 API 选择模型与 ACP runtime
• Agents 架构
• 治理