Harness Agent 开发方案：从 Worker Agent 到生产落地

2026 年 Agent 从"概念验证"走进"生产交付"，决定它能否真正落地的不再是模型本身，而是模型外面那套驾驭工程（Harness Engineering） 。Anthropic 给出的精炼定义是：Agent = Model + Harness，Harness 是让"会说话的模型"变成"能干活的智能体"的整套系统------处理输入、编排工具调用、返回结果。在 Harness 平台上，这套体系被产品化成 Worker Agents：把 Prompt + Model Connector + MCP Servers 打包成一个可在 CI/CD/IaCM/STO/SCS 流水线里复用的 step。本文给一份从架构、YAML 规格、三种创建路径到避坑铁律的完整开发方案，附零依赖 Python 脚手架代码。

一、整体架构：四层堆叠 + 双脊柱

一个生产级 Harness Agent 的运行时分四层：

层级	职责	关键组件
Trigger & Channel	入口触发	GitHub PR webhook / Slack / Jira / CLI / cron
Agent Core	Prompt + 推理循环	Intent Parser、Tool Router、Reasoning Loop、Memory、Guardrails（RBAC + 审计）
Tool & Integration	工具与集成	Pipeline API、Code Repo、CCM、STO、Feature Flags、IDP、Observability
Foundation & Runtime	运行底座	Harness Delegate（k8s/docker）、Vector DB、Audit log、Secret Manager、OPA

右侧是 AIDA LLM Backend （默认 Claude Opus 4.5，回退 GPT-4o，2026.2.18 升级，左侧是 DevSecOps 全生命周期 闭环（Plan → Code → Build → Test → Deploy → Operate）。Worker Agent 可以挂在闭环的任意一环作为 pipeline step。

二、Worker Agent 规格：YAML 即合同

Harness 把 Agent 定义统一为 YAML，五个核心字段决定它怎么工作：

yaml 复制代码

name: PR Review Agent
description: 自动审查 GitHub PR，输出 APPROVE/REVIEW/REJECT 决策
containerImage: harness/agent-runtime:latest
instructions: |
  你是一名资深 DevSecOps 评审员......
with:
  modelConnector: anthropic_bedrock_99cf4be5
  modelName: anthropic_bedrock_claude_4_5
  mcpConnectors:
    - harness_hosted_mcp
    - github_mcp
  inputs:
    pr_url:  {type: string, required: true}
    depth:   {type: string, default: standard}
  output:
    - {name: recommendation, type: string}
    - {name: risk_score,     type: number}
    - {name: summary,        type: string}

几个关键约定：

instructions 是 Agent 的灵魂：不是写一段提示词，而是写一份"岗位说明书"------角色、目标、权限边界、决策规则、禁止行为；
modelConnector + modelName 双指针：Connector 只负责认证/路由，模型名才决定推理能力，两者解耦让你可以一键换模型；
mcpConnectors 决定 Agent 能调什么外部能力 ：harness_hosted_mcp 给 pipeline/build/deploy 操作权，github_mcp 接 PR/issue，缺这一环 Agent 就只能"想"不能"做"；
output 必须显式声明 ：下游 pipeline step 才能拿到 <+steps.agent.output.recommendation> 做条件判断或网关；
containerImage 决定运行时沙箱，默认 Harness 提供，也可以替换成自有镜像跑私有依赖。

三、三种创建路径：选择适合团队的入口

Harness 提供三条等效路径，对应"产品/工程师/AI Native"三类用户：

路径	适合谁	操作要点
UI Visual/YAML	产品经理 / 平台工程师	Worker Agent Catalog → + Create → Visual 表单或 YAML 直贴 → Save
AI Chat（Harness AI）	探索期、快速 PoC	自然语言下达"Create a PR Review Agent..."，AIDA 自动检查重名、收集需求、生成 YAML、调 Agent API 创建；还能顺手生成挂载该 Agent 的 pipeline
IDE via MCP Server	重度工程师 / GitOps	Cursor / Windsurf / VS Code Copilot / Claude Code 安装 Harness MCP 后，直接用 `agent.create` / `agent_run` 资源类型，YAML 入仓走 PR review

三条路径背后是同一个 Agent API，所以可以混用：UI 上建好原型 → 导出 YAML 入 Git → IDE 维护 → AI Chat 触发运行。

四、实战脚手架：Python DSL + 校验 + 模拟运行

为了把"YAML 描述 → 校验 → 试跑"压缩成本地可验证的一步，我写了一个零依赖的 Python 脚手架。核心是一个 WorkerAgent 类：

python 复制代码

pr_agent = WorkerAgent(
    name="PR Review Agent",
    description="自动审查 PR，输出决策与风险评分",
    instructions="你是一名资深 DevSecOps 评审员......",
    model_connector="anthropic_bedrock_99cf4be5",
    model_name="anthropic_bedrock_claude_4_5",
    mcp_connectors=["harness_hosted_mcp", "github_mcp"],
    inputs={"pr_url": {"type":"string","required":True}},
    outputs=[{"name":"recommendation"}, {"name":"risk_score","type":"number"}],
)
print(pr_agent.to_yaml())     # 一键生成 Harness Agent YAML
validate(pr_agent)            # 6 项静态校验
agent_run(pr_agent, pr)       # 模拟 Harness MCP 的 agent_run 调用

校验器覆盖 6 类常见问题：Name 合规、Description 长度、Instructions 充实度、Model 白名单、MCP 挂载、Output 声明。任何 CRIT 直接 BLOCK，WARN 每项扣 8 分。我用 PR Review Agent 跑了一遍：

复制代码

✅ 全部通过       健康分：100/100   决策：PUBLISH

模拟运行喂 3 类典型 PR，Agent 路由到不同决策桶：

复制代码

[docs-only] 🟢 APPROVE  risk=12   tokens=1335  2150ms
             · 仅文档改动 · 无依赖变更 · 通过全部 lint
[dep-bump ] 🟡 REVIEW   risk=58   tokens=1343  2150ms
             · 新增第三方依赖 axios@1.7.2 · 缺少单元测试 · 改动 src/auth/*
[auth-leak] 🔴 REJECT   risk=92   tokens=1346  2150ms
             · 硬编码 sk-prod-xxx 密钥 · 禁用 CSRF 校验 · SBOM 含 CVE-2026-22172

三档决策正好对应 Harness 的 IaC Plan Safety Agent 标准输出范式（APPROVE / REVIEW / REJECT），下游 pipeline step 可以直接 when: <+output.recommendation> != "REJECT" 做卡点。

五、治理与安全：企业级 Agent 的硬标线

Worker Agent 跑在你的生产 pipeline 上，治理不是锦上添花：

RBAC 三件套：Pipeline 的 View/Create/Execute、Connector 的 View/Create/Delete、Secret 的 View/Access 必须按角色分发；
凭证零落盘：Model Connector 与 MCP Connector 都通过 Secret Manager 引用，YAML 里只见 connector ID 不见 key；
数据生命周期：默认走 Vertex AI + Claude，推理后立即清空 0 留存；故障回退到 OpenAI 时保留 30 天，Harness 已 opt-out 训练；
审计与回放 ：每次 agent_run 写入 audit log，含 inputs / outputs / token / duration，便于事后追责；
Dry Run Validation API：pipeline YAML 入仓前用 OPA 策略 + schema 校验提前拦截，对 Agent step 同样适用。

六、避坑铁律

description 越具体越好------它决定 Agent 何时被自动触发，"general productivity" 这种泛词约等于不被使用；
output 必须声明------不声明就只能看日志，无法做下游 gating，相当于 Agent 跑了个寂寞；
mcpConnectors 至少挂一个------空 MCP 的 Agent 只是个会聊天的 prompt，谈不上"做事"；
AI Chat 创建后必导出 YAML 入 Git------否则下次没法 PR review、没法 rollback；
生产前用 Dry Run + 静态校验双保险------不要让第一次 prod run 就是第一次问题暴露。