构建 NVIDIA NeMo Fabric 适配器
开始之前
- 阅读当前适配器契约。
- 使用 JSON Schema 定义数据类型，不要从示例重建 schema。
确定边界
- 定义适配器的稳定
adapter_id和类型。 - 区分
harness.settings、workflow.settings和extensions。 - 安装、环境准备、第三方编排等功能应放在适配器之外。
描述符定义
创建 *.fabric-adapter.json，声明：
contract_version、adapter_id、adapter_kind。config.accepts、system_instruction_modes。- 仅在实际支持时声明 MCP oauth2/服务账号认证。
- 发布 settings/model/tool/extension schema。
- 启动时验证凭据与目标可用性，不在描述符中放秘密值。
- 支持流式时再开启
capabilities.streaming。
每个注册目标还要创建 *.fabric-target.json，指定对应 adapter_id、入口点和 workflow settings schema。
打包
将描述符通过 setuptools data-files 安装到 share/nemo-fabric/adapters/<厂商>。
Python 适配器依赖 nemo-fabric-adapter-contract；TypeScript 适配器依赖同名 npm 包。推荐依赖轻量，不引入运行时。
AgentConfig 映射
在边界将 AgentConfig 转换成目标原生配置：
- 模型角色、指令、工具、MCP 服务器、技能等。
- 执行开始时读取 RuntimeContext 提供身份、环境等信息。
- 不支持的字段返回稳定错误码，不记录敏感信息。
生命周期实现
实现 start、invoke（可能多个）、stop。
- 在
start中创建目标状态。 invoke返回 AgentRunResult。stop在异常退出时也要安全。- 支持流式时实现
invoke_openai_stream，并遵循 OpenAI chunk 规范。 - 不要为 Relay 流式添加额外方法。
参考适配器可通过 common host 的 lifecycle.serve() 启动。
自定义 Agent
共享框架适配器使用 FabricConfig.workflow.target_id 选择目标，以入口点 kind/ref 解析工厂工厂上下文。专用适配器则直接将目标视为一个 Agent。
验证与交接
安装后在隔离环境验证：
- wheel 安装和
share/nemo-fabric下发现。 - 用
plan()检查描述符。 - 测试配置接受/拒绝和每个 schema。
- 运行
doctor()。 - 测试生命周期、并发隔离、流式边界。
- 按需验证 Relay 关联。
- 汇报版本与能力，不声称官方一致性。