看到“Harness Agent”这个词很多人的第一反应是它到底是个 CI/CD 工具还是今年爆火的 AI Agent 框架这不是你一个人困惑。在 2026 年“Harness”和“Agent”几乎成了两套技术语境里的“两栖词汇”——一边是持续交付平台 Harness 里负责执行任务的代理组件另一边是 AI 工程里反复讨论的“Agent 运行框架”。如果你只盯着某个版本的按钮和命令去学大概率学完就过时真正值钱的是先搞懂这两套语境下 agent 与 harness 各自扮演的角色再动手把一个最小任务跑通。这篇文章会从底层架构讲起先帮你彻底拆开“Harness”和“Agent”两个词在不同场景下的含义然后带你完成一套可复现的实战流程从环境准备、Delegate执行代理安装到编写 Pipeline YAML再到用 Python 脚本让 Agent 执行真实任务。最后还会补充 AI Agent 语境下 open agent harness 的设计思路以及我在工程里见过的高频踩坑点。如果读完你只能记住一句话我希望是这句不要背按钮要理解“谁在决策、谁在执行、谁在兜底”这条链路。下面开始。1. Harness Agent 为什么值得花时间学先从一个最常见的场景切入。假设你所在团队正在做微服务改造代码仓库越来越多发布频率从每周一次变成每天十几次。过去靠运维手动点按钮发布的模式撑不住了于是你们开始调研持续交付平台。Harness 是这类平台里比较有代表性的一款它把持续集成、持续交付、Feature Flags、云成本管理整合在一起主打“软件交付自动化”。但第一次接触 Harness 的人几乎都会在概念上卡住。你打开官方文档一会儿看到 Harness Delegate一会儿看到 Harness Pipeline一会儿又看到 AI Agent 相关的能力说明。你问同事“Agent 到底是个什么东西”同事也说不清只能告诉你“照着文档装一个”。你照着装完发现 Delegate 在你的服务器上跑起来了但你还是不知道它为什么存在。这种情况很普遍。因为 Harness Agent 不是一个孤立功能它是整个平台架构里“执行侧”的关键组件。理解它等于理解了 Harness 平台的任务分发模型控制台负责编排Delegate 负责执行。同时如果你正好也在研究 AI Agent 开发会发现“agent harness”这个说法在 OpenAI Codex 等项目的讨论里频繁出现指的是让 Agent 在受控环境中运行工具、调用模型、管理上下文的框架层。所以学 Harness Agent 的意义不只是学会安装一个组件而是建立一种能力面对一个新平台能快速看出它的控制面、数据面、执行面分别在哪出了问题知道该去哪里查。2. 先厘清概念Harness、Agent、Harness Agent 到底指什么很多教程上来就铺概念结果读者越看越晕。这里我用“两个语境”把术语拆开。2.1 CI/CD 语境下的 HarnessHarness 是一个软件交付平台核心能力包括持续集成CI、持续交付CD、 Feature Flags功能开关、云成本管理等。它的目标是把“代码提交到生产环境”这条链路标准化、自动化同时让发布过程可观测、可回滚。在这个语境下Harness 平台本身属于“控制面”负责管理 Pipeline 的定义、状态、权限、审批策略、日志聚合等。你登录 Harness Web Console创建 Project编排 Pipeline这些操作都发生在控制面。2.2 Agent 在 CI/CD 语境下指什么在 Harness 平台里Agent 通常指 Delegate也就是执行代理。它是以 Docker 容器或 Kubernetes Pod 形式运行在你自己的基础设施中的组件。它定期轮询 Harness 控制台的任务队列拿到任务后在本地执行再把日志和结果回传。为什么需要 Delegate因为控制台不应该直接连接你的生产集群、云账号或内网服务。如果平台直接连你的 Kubernetes 集群意味着你需要把集群凭证暴露给外部 SaaS安全风险很大。Delegate 是一个“反向连接”模式由你的环境主动向外发起连接这样凭证留在你自己的环境里Harness 控制台通过 Delegate 间接完成所有操作。2.3 Harness、Agent 的区别一张表看懂术语所属语境核心职责典型对应物Harness软件交付平台提供发布编排、审批、观察、安全策略Harness Platform / 控制台AgentDelegateHarness 平台内在客户环境中执行构建、部署、脚本任务Delegate 容器 / Kubernetes PodHarness Agent泛指平台中的代理执行体系连接控制面与执行面承载任务执行能力Delegate 执行环境Agent HarnessAI 工程领域承载 AI Agent 运行的框架提供工具调用、上下文、沙箱、生命周期管理OpenAI Codex 的 open agent harness、各类 Agent 框架要特别注意“Agent Harness”和“Harness Agent”不是同一个词。前者在 AI 领域指“承载 Agent 的框架”后者在 CI/CD 平台里指“Harness 中的执行代理”。两个词只是单词顺序不同含义相差很大。这也是很多新手搜索资料时彻底绕晕的原因。2.4 判断Harness Agent Delegate AI 能力从 Harness 平台的发展方向看Harness Agent 不再只是传统 Delegate。平台正在把 AI 能力融入发布链路例如通过自然语言描述发布意图、自动生成 Pipeline 步骤、自动分析部署失败原因等。这些能力本质上是由平台侧的 AI Agent 与客户侧的 Delegate 协同完成的。从工程视角看你仍然可以把 Harness Agent 理解为一条链路控制面根据 Pipeline 定义生成任务通过任务队列下发给 DelegateDelegate 执行实际步骤再把结果回报给控制面。理解这条链路比记任何一个具体配置项都重要。3. 底层架构原理控制面、执行面与 Agent 的生命周期要理解 Harness Agent先理解整个平台的任务分发模型。这里可以用一个很常见的类比外包项目。你是一个甲方Harness 控制台手里有一份需求文档Pipeline YAML。你不会亲自去工地搬砖而是把任务派给包工头Delegate。包工头在工地现场你的 Kubernetes 集群、AWS 账号、内网环境找人干活干完向你汇报。关键点在于包工头是你的人不是甲方的人所以工地上的钥匙凭证不用交给甲方。对应到 Harness 架构Harness Manager / Platform控制面负责存储 Pipeline 定义、管理用户权限、生成任务、接收执行结果。Delegate执行面跑在客户环境里通过长连接或轮询方式从控制面拉取任务。Connector凭证管理告诉控制面“访问某个 Kubernetes 集群用哪个凭据”但实际访问由 Delegate 完成。Pipeline发布流程定义描述要执行哪些阶段、哪些步骤、需要什么参数。Service / Environment / InfrastructureCD 的核心抽象分别描述“发布什么”“发布到哪”“用什么基础设施发布”。Agent 的生命周期可以拆成四步注册用户在 Harness 控制台创建 Delegate Token安装 Delegate 时传入 Token 和 Account IDDelegate 启动后向控制台注册。轮询Delegate 定期拉取任务队列发现新任务后更新状态为“已接收”。执行Delegate 按照任务内容执行构建、部署、脚本等操作期间把实时日志回传控制台。回报任务完成后Delegate 上报成功/失败状态和产物信息控制台更新 Pipeline 执行历史。这里有一个特别容易踩坑的认知误区不要以为 Delegate 是“跟着 Pipeline 走的”。Delegate 是你的基础设施里的常驻组件Pipeline 只是被它消费的任务描述。如果 Delegate 挂了你在控制台上点多少次“运行”都没用。另一个容易踩坑的点是网络方向。Delegate 是主动向外连接控制台的所以它所在的环境通常只需要出站网络不需要把 Harness 控制台的请求转发到你的内网。但如果你的环境出站代理配置不完整Delegate 可能一直处于“未连接”状态而问题并不是 Delegate 本身坏了而是它连不上任务队列。4. 从零搭建环境准备与 Delegate 安装在开始安装前先明确你要准备什么。这里我不会写死某个版本号因为 Harness 控制台在不同账号、不同时间生成的安装命令会有差异。最可靠的方式是打开 Harness Console 的 Delegates 页面复制它为你生成的命令。下面讲的是通用思路和每一步为什么要这么做。4.1 环境准备清单Harness 账号并且有权限创建项目和管理 Delegate。一台能运行 Docker 的主机或者一个 Kubernetes 集群。本地学习建议直接用 Docker。网络要求这台机器需要能访问 Harness 控制台的 HTTPS 端点同时能访问你要部署的目标环境。目标环境例如一个测试用的 Kubernetes 集群或者你本地的 Docker 环境。4.2 在 Harness 平台创建项目和 Token登录 Harness 后先创建一个 Project。Project 是资源隔离单位Pipeline、Service、Environment 都挂在 Project 下。然后进入 Delegate 管理页面选择 Delegate 安装方式。平台会要求你为 Delegate 设置名称并生成一个 Delegate Token。这个 Token 是 Delegate 向平台注册身份的凭证要妥善保管不要提交到代码仓库。4.3 使用 Docker 安装 Delegate示意命令假设你选择了 Docker 方式平台生成的安装命令通常类似下面的结构。实际操作时请把其中 Token 和 Account ID 替换为平台给你的真实值docker run -d \ --name harness-delegate \ --restart unless-stopped \ -e DELEGATE_TOKENyour-delegate-token \ -e ACCOUNT_IDyour-account-id \ -e DELEGATE_NAMEmy-demo-delegate \ -e MANAGER_HOST_AND_PORThttps://app.harness.io/gratis \ harness/delegate:latest这里的变量含义DELEGATE_TOKENDelegate 注册凭证在控制台生成。ACCOUNT_ID你的 Harness 账号 ID。DELEGATE_NAME给这个 Delegate 起的名字方便在控制台识别。MANAGER_HOST_AND_PORTHarness 控制台地址免费版和付费版可能不同。启动后执行docker logs -f harness-delegate查看日志。如果日志中出现成功连接并开始轮询任务的记录说明 Delegate 已经注册成功。回到 Harness 控制台的 Delegates 页面应该能看到这个 Delegate 处于“Connected”状态。4.4 使用 Kubernetes 安装 Delegate示意命令如果团队用 Kubernetes更推荐以 Deployment 方式部署 Delegate。同样地实际命令以控制台生成为准。常见安装思路如下kubectl create namespace harness-delegate helm repo add harness https://harness.github.io/delegate-helm-chart helm install my-delegate harness/harness-delegate \ --namespace harness-delegate \ --create-namespace \ --set delegateNamemy-delegate \ --set accountIdyour-account-id \ --set delegateTokenyour-delegate-token \ --set managerEndpointhttps://app.harness.io/gratis安装完成后检查 Pod 状态kubectl get pods -n harness-delegatePod 处于 Running 状态后再到控制台确认 Delegate 是否连接成功。这一步很容易出问题先把排查思路记下来Pod 一直 CrashLoopBackOff查看日志可能是 Token 无效或网络不通。Pod Running 但控制台显示未连接检查出站网络和安全组确认能访问 Harness 控制台端点。5. 核心能力拆解Pipeline、Service、Infrastructure安装好 Delegate 之后就可以创建 Pipeline 让 Agent 干活了。在写 YAML 之前先理解 CD 里的几个核心抽象否则你会在配置页面里迷路。5.1 Service服务Service 描述“要部署什么应用”。它包含服务名称、制品来源Artifact Source、运行配置。制品来源可以是 Docker 镜像仓库、Jenkins 产物、或者自定义仓库。在 Harness 的 CD Pipeline 中Service 是独立资产可以跨 Pipeline 复用。5.2 Environment 与 Infrastructure环境与基础设施Environment 描述“部署到哪里”比如开发环境、测试环境、生产环境。Infrastructure 进一步指明具体基础设施例如某个 Kubernetes 集群的某个命名空间。环境可以设置审批策略、变更窗口等安全规则。5.3 Pipeline流水线Pipeline 描述“怎么部署”。它由多个 Stage 组成每个 Stage 可以指定执行类型比如部署Deployment、构建CI、自定义Custom等。Stage 内部是具体步骤。从执行角度看Pipeline 只是“任务定义”真正干活的是 Delegate。你在控制台里可视化编排出来的 Pipeline底层其实是一份 YAML。反之你也可以直接编辑 YAML 来维护 Pipeline实现 Pipeline as Code。6. 代码实战让 Agent 执行真实任务这里我们分三个实战步骤先写一个最小 Pipeline YAML再写一个带 Python 脚本的步骤最后跑通并验证结果。6.1 先写一个最小 Pipeline YAML下面是一个简化示例演示如何定义一个运行脚本的 Pipeline。实际项目中字段会更多但这个结构足够你理解主体脉络。请注意创建 Pipeline 时建议先用控制台可视化方式生成再切换到 YAML 视图避免手写时遗漏必填字段。pipeline: name: demo-pipeline identifier: demo_pipeline projectIdentifier: my_project orgIdentifier: my_org tags: {} stages: - stage: name: run-script identifier: run_script type: CI spec: cloneCodebase: false execution: steps: - step: type: Run name: PythonScript identifier: python_script spec: connectorRef: account.harnessPublicImage image: python:3.11 shell: Sh command: |- echo Hello from Harness Delegate python --version tags: {}这段 YAML 的关键点projectIdentifier和orgIdentifier必须与你的 Project/Org 匹配。connectorRef: account.harnessPublicImage指向 Harness 公共镜像连接器。如果账号里没有需先在 Connectors 里创建或改成你已有的镜像仓库连接器。image: python:3.11指定任务运行镜像。Delegate 会从镜像仓库拉取这个镜像并执行命令。type: Run表示这是一个基础命令执行步骤适合快速验证 Agent 是否能拉取任务并执行。6.2 编写一个可复用的 Python 脚本步骤很多时候你需要在 Pipeline 里跑一段脚本例如读取制品信息、调用内部 API、做数据校验。这里给出一个稍微实用一点的场景假设部署前需要检查某个 HTTP 接口是否健康如果接口返回状态码不是 200就让任务失败。在 Pipeline 的 YAML 里可以把 Python 脚本写进command字段- step: type: Run name: HealthCheck identifier: health_check spec: connectorRef: account.harnessPublicImage image: python:3.11 shell: Sh command: |- python - EOF import urllib.request url https://httpbin.org/status/200 try: with urllib.request.urlopen(url, timeout10) as resp: if resp.status 200: print([OK] health check passed) else: raise SystemExit(f[ERROR] unexpected status {resp.status}) except Exception as e: raise SystemExit(f[ERROR] health check failed: {e}) EOF说明使用python - EOF语法可以在 Shell 命令中嵌入多行 Python 代码避免在 YAML 里写难以转义的长脚本。脚本逻辑很简单请求一个 URL判断返回状态码失败直接抛出非零退出码。Harness 会把步骤的非零退出码视为任务失败从而终止 Pipeline。6.3 结合 AI 辅助让 Agent 自动分析失败原因如果你对 Harness 的 AI 能力感兴趣可以关注失败后的“自动分析”入口。通常当一个部署步骤失败后Harness 会汇总日志并提供失败原因分析你可以把它看成一个“排障副驾驶”。这段分析不一定 100% 准确但能帮你快速缩小排查范围。实际上你可以把 AI 能力通过脚本串起来Pipeline 失败后调用一个 Python 脚本把错误日志发送到你自己的诊断服务再做进一步分析。这属于工程上常见的“扩展 Agent 能力”方式不是 Harness 本身限制了你而是你愿不愿意接一层胶水代码。6.4 运行与效果验证创建好 Pipeline 后点击运行。运行过程中可以在 Harness Console 实时查看每一步日志。如果一切正常PythonScript 这一步会打印 “Hello from Harness Delegate” 和 Python 版本号HealthCheck 步骤会打印 “[OK] health check passed”。如果运行失败优先按这个顺序排查看 Delegate 是否在线。Delegate 离线时任务会一直处于等待或失败状态。看日志里是否出现镜像拉取失败。如果 Delegate 所在环境无法访问公共镜像仓库就需要配置镜像仓库连接器或镜像缓存。看脚本退出码。如果脚本没有执行权限或依赖缺失通常会体现在日志末尾的异常信息里。7. AI Agent 语境下的 Harnessopen agent harness 是什么聊完 Harness 平台我们把视角切到 AI Agent 开发。这也是最近一年搜索热度很高的方向尤其当 Codex 被当作平台开放出来官方强调“build on the open agent harness”很多开发者开始困惑这里的 agent harness 和 Harness Agent 是一回事吗7.1 为什么 AI 工程需要 agent harness一个 AI Agent 不能只是“一个大模型”。它需要接收用户指令、调用外部工具、观察工具结果、决定下一步动作并在完成目标后输出结论。如果没有一个统一框架来管理这些循环过程Agent 的行为会非常不可控模型可能乱调用工具、上下文会无限膨胀、错误处理会变得极其混乱。agent harness 就是用来解决这个问题的框架层。它在 Agent 和底层模型、工具之间加了一层“基础设施”负责管理 Agent 的循环什么时候调用模型、什么时候调用工具、什么时候结束。提供工具注册和调用规范Agent 决定调用某个工具时框架负责执行并把结果返回给模型。维护上下文控制哪些信息进入模型上下文避免上下文爆炸。设置安全边界工具执行在什么沙箱里、能访问哪些资源、命令是否白名单。生命周期和可观测性记录每一步的输入输出方便调试和回放。7.2 一个最简的 agent harness 教学示例不用任何外部框架用 Python 写一个最简 harness 循环你就能理解它的本质。下面的代码故意简化目的是展示“模型决策 工具执行 结果回合”这个循环骨架。# 文件路径minimal_agent_harness.py import json class Tool: name def run(self, **kwargs): raise NotImplementedError class ShellTool(Tool): name shell def run(self, command): print(f[tool] executing: {command}) # 真实项目中这里会真正执行 subprocess 命令 return ok class MinimalAgentHarness: def __init__(self, model_call, max_turns3): self.model_call model_call self.max_turns max_turns self.tools {} self.messages [] def register_tool(self, tool): self.tools[tool.name] tool def run(self, user_prompt): self.messages.append({role: user, content: user_prompt}) for turn in range(self.max_turns): response self.model_call(self.messages) self.messages.append({role: assistant, content: response}) action self.parse_action(response) if action is None: return response tool self.tools.get(action[name]) if tool is None: return funknown tool: {action[name]} result tool.run(**action[arguments]) self.messages.append({role: tool, content: result}) return reached max turns staticmethod def parse_action(response): try: return json.loads(response) except json.JSONDecodeError: return None def fake_model_call(messages): # 真实项目里替换为 LLM API 调用 return json.dumps({ name: shell, arguments: {command: echo hello} }) if __name__ __main__: harness MinimalAgentHarness(model_callfake_model_call) harness.register_tool(ShellTool()) final_result harness.run(请执行一个命令) print([final], final_result)这段代码里最核心的就是run方法里的循环模型返回一段 JSON解析成工具调用执行工具把结果追加到消息列表然后进入下一轮。真实生产级的 agent harness 会把model_call换成真实的大模型 API把ShellTool.run放到 Docker 容器或沙箱中执行并加入更严格的安全校验。7.3 两个语境的联系现在你再看这两个词Harness Agent 是 CI/CD 平台里的执行代理agent harness 是 AI Agent 的运行框架。但它们有一个共同点都在解决“让某个智能体在受控环境中安全地执行任务”的问题。在 CI/CD 里Harness 用 Delegate 把任务下发到客户环境避免控制台直接接触生产凭证。在 AI 工程里agent harness 用沙箱把工具调用隔离起来避免大模型乱执行危险命令。本质上都是“控制面与执行面分离”的思想。如果你已经理解了 Harness 的 Manager/Delegate 模型再去看 OpenAI Codex 的 open agent harness、LangGraph 的执行图会发现很多设计思路是相通的谁决策谁执行谁审批谁负责回滚。8. 常见问题与排查思路下面是 Harness Agent 实际使用中最高频的几个问题整理成表格方便你收藏。问题现象可能原因排查方式解决方案Delegate 一直显示未连接出站网络受限无法访问 Harness 控制台端点检查 Delegate 日志确认连接错误信息放通控制台 HTTPS 端点的出站访问或配置 HTTP 代理Delegate Pod CrashLoopBackOffDelegate Token 错误、Account ID 错误查看 Pod 日志中的认证错误在控制台重新生成 Delegate Token确认安装命令中的参数Pipeline 任务一直卡在等待没有在线 Delegate或 Delegate 标签不匹配检查 Delegates 页面是否显示 Connected启动新的 Delegate或调整 Pipeline 的 Delegate 选择器步骤镜像拉取失败Delegate 所在环境无法访问公共镜像仓库查看日志中的 Pull access denied / timeout使用私有镜像仓库连接器或提前在环境中缓存镜像Python 脚本执行失败脚本依赖缺失、YAML 转义错误先手动在容器内运行脚本验证改用python - EOF多行写法减少 YAML 转义YAML 保存失败Project/Org 标识与当前环境不匹配查看控制台报错字段从控制台可视化创建一个 Pipeline 后导出 YAML 作为基线还有一个新手常犯的错误在 Delegate 还没连接成功时就开始创建 Pipeline 并运行。这会让人误以为 Harness 很难用其实只是执行侧没就绪。建议把“Delegates 页面显示 Connected”当作一切实验的前置条件。9. 最佳实践与工程建议最后这部分是你在真实项目里能直接用上的经验不是空泛建议。9.1 命名规范Delegate、Service、Environment、Pipeline 都要有清晰的命名规范。建议格式项目-环境-用途例如order-service-dev-deploy。Delegate 可以按用途命名比如k8s-prod-delegate、docker-local-delegate方便在多个 Delegate 并存时快速区分。9.2 把 Pipeline 当作代码管理Harness 的 Pipeline 本质是 YAML建议在代码仓库里建立harness/目录存放 Pipeline 和配置资产的模板通过 Git 做版本管理。修改 Pipeline 前先评审再同步到 Harness 平台。这样你的发布流程可追溯、可回滚。9.3 最小权限原则Delegate 在客户环境里拥有执行能力权限越大风险越大。生产环境建议使用独立的 Service Account不要直接复用管理员权限。Kubernetes 集群访问使用单独的 Connector并且限制命名空间。Delegate Token 定期轮换避免长期有效凭证泄露。不在 YAML 或命令中硬编码阿里云/AWS 密钥、数据库密码等敏感信息改用 Harness Secret。9.4 善用秒级回滚CD 平台的重要价值之一是快速回滚。在配置部署步骤时提前验证回滚步骤是否可用不要等到线上故障才测试。建议在非生产环境做一次“故意发布坏版本再回滚”的演练确认流程真正能跑通。9.5 自定义脚本要幂等如果 Pipeline 里包含自定义脚本务必保证脚本可以重复执行而不会产生副作用。例如创建资源前先检查是否已存在写入数据时使用唯一键失败后可以安全重试。这样即使某次执行中途失败修复后重跑也不会留下脏数据。9.6 AI Agent 能力接入的边界如果你要把 AI 能力接进发布链路比如自动分析日志、自动生成发布总结务必加人工审批节点。AI 可以辅助决策但在生产发布场景里最终把关仍然应该有人。在 Harness Pipeline 中可以在关键 Stage 前配置 Approval Step让 AI 生成的变更需要人工确认后才继续。10. 总结与后续学习方向这篇文章真正想帮你解决的不是记住某个按钮而是建立一套理解 Harness Agent 的心智模型控制面负责编排执行面负责干活Agent 是连接两者的桥梁。你学了 Delegate 的安装、Pipeline YAML 的编写、Python 脚本的执行验证也看到了 AI 工程里 agent harness 的相似设计逻辑。这个心智模型可以迁移到很多同类系统中以后再看其他 CI/CD 平台或 Agent 框架你都会迅速定位到“决策层、执行层、安全边界”这三个关键点。下一步建议你按照这篇文章的流程在 Harness 免费版上创建一个最小实验装一个本地 Docker Delegate跑通一个打印日志的 Pipeline再加一个健康检查脚本。跑通之后再尝试接入自己的 Kubernetes 集群逐步增加审批、回滚、通知等环节。如果遇到问题优先去看 Delegate 日志和 Pipeline 日志这两个地方能回答 80% 的故障原因。至于 AI Agent 方向可以从阅读 open agent harness 相关项目的源码开始用它对照本文第 7 节的最小示例理解生产级框架在安全、并发、可观测性上的增强。后面我还会写更多关于 Delegate 运维、Harness Pipeline as Code、以及如何在企业里落地 AI 辅助发布的文章建议先收藏备用。