Blueprint 声明式装配：YAML → 校验 → AgentFactory → Agent

Blueprint 声明式装配：YAML → 校验 → AgentFactory → Agent 由 Archify 生成的架构图。 blueprint.yaml · version: ai4j.agent/v1 · P1-A 文档模型与校验（不运行） blueprint.yaml version: ai4j.agent/v1 AgentBlueprintLoader · load(path/串/流) · P1-A 文档模型与校验（不运行） AgentBlueprintLoader load(path/串/流) AgentBlueprint · 11 顶层字段 DTO · P1-A 文档模型与校验（不运行） AgentBlueprint 11 顶层字段 DTO AgentFactoryContext · 宿主供给依赖 · P1-B 宿主装配 AgentFactoryContext 宿主供给依赖 ValidationReport · issues + JSONPath · P1-A 文档模型与校验（不运行） ValidationReport issues + JSONPath AgentBlueprintValidator · 分项校验 · P1-A 文档模型与校验（不运行） AgentBlueprintValidator 分项校验 AgentFactory · create(bp, ctx) · P1-B 宿主装配 AgentFactory create(bp, ctx) AgentBuilder → Agent · builder.build() · P1-B 宿主装配 AgentBuilder → Agent builder.build() ① load ② DTO ③ 宿主依赖 ④ create(bp,ctx) ⑤ validate() ⑥ issues ⑦ isValid? : AgentFactoryException ⑧ 装配 P1-A 文档模型与校验（不运行） P1-B 宿主装配

P1-A 只做文档

  • • Loader 白名单 11 个顶层字段（version/id/name/model/instructions/plugins/tools/session/sandbox/workflow/extensions），未知字段进 unknownFields
  • • Validator 逐项校验：version 必须 ai4j.agent/v1、id 字符集、model/plugins/tools/session/sandbox/workflow——不创建也不运行任何 Agent

P1-B 宿主供给

  • • AgentFactoryContext 提供 modelClient 与各项 Supplier——Factory 不读 provider token、不解析本地 profile、不安装插件
  • • sandbox.enabled 声明必须配合 ctx.allowSandboxDeclaration，否则抛 AgentFactoryException（不创建真实沙箱会话）

校验闸门

  • • Factory 内部复用同一 Validator：report.isValid=false → AgentFactoryException(blueprint.validation.failed) 携带报告
  • • 每条 issue 带 JSONPath（如 $.version、$.tools[0].name）+ 错误码 + severity，便于定位非法声明