Agent Experience 是新的 Developer Experience（DX）

Developer Experience (DX) 关注的是人们能多好地使用你的工具。Agent Experience 则是对机器提出同样的问题。

本页聚焦于 AI 编码智能体：例如 Claude Code、Cursor 等工具，以及在不同程度人工监督下编写、运行和迭代代码的自定义智能体工作流。同样的原则适用于任何模型代表某人与软件或基础设施交互的场景。

Agent Experience 是一门设计学科，而不是一个产品类别。它体现在 API、命令行工具、文档、权限、环境、错误消息、日志和反馈系统中。这些界面大多最初是为人设计的。

良好的 Developer Experience (DX) 能缩短意图与有用结果之间的距离。人类能从视觉层次结构、渐进式信息呈现、易懂的说明以及支持探索的界面中受益。

智能体与相同系统的交互方式不同。为方便人眼快速浏览而设计的仪表盘，可能几乎不会向机器暴露任何可用信息。详细的错误消息也许能帮助开发者理解上下文，但会迫使智能体耗费 token 去从噪音中分辨出有用信号。交互式提示能让人更容易使用命令行工具，却可能让自动化工作流彻底卡住。

同时为两类使用者设计

Agent Experience 并不会取代 Developer Experience (DX)。软件系统正越来越多地同时服务于这两类使用者。

开发者可能在可视化界面中审查拉取请求，而智能体则通过 API 获取同一变更。开发者可能查看完整的构建日志，而智能体只请求失败的步骤和相关错误。有人可能更喜欢引导式的设置流程，而智能体则需要一个具有可预测输出的非交互式命令。

优秀的工具能以适合每类使用者的形式，提供相同的底层能力。

几十年来，开发者工具的设计都假定键盘前坐着一个人：一个能够浏览仪表盘、察觉异常情况、查找更多信息，并凭借判断力消除歧义的人。

智能体正在改变这一假设。版本控制系统、构建基础设施、软件包仓库、云平台、内部 API 和开发者工具，正越来越多地收到代表某人行事的软件发出的请求。

智能体正在成为软件的使用者

智能体越来越多地直接与那些曾经由开发者手动操作的系统交互。

它们读取文档、调用 API、执行命令、修改代码仓库、检查日志、查询基础设施并触发工作流。这条路径上的每一个接口，都会影响智能体能否可靠地完成任务。

糟糕的 AX 最终会变成人的工作

面对一堵非结构化输出的墙，智能体不得不花费时间和 token 去判断哪些内容才是重要的。模棱两可的 API 响应可能导致不必要的重试，或做出错误的下一步操作。交互式提示可能会让自动化任务卡住，并把它退回给人来处理。

问题会在整个工作流中不断累积。每一步中很小的歧义，都可能让一个本应自主完成的任务变成反复的澄清、审查和善后。

更强的模型并不能取代界面设计

模型的能力会持续提升。相比之下，团队对模型所交互的系统拥有更直接的控制权：API 模式、文档、命令行行为、日志、权限、环境和反馈。

更强的模型能更有效地应对糟糕的界面，但更好的界面能从源头上减少所需的推理量。

平台团队已经在为开发者做类似的工作，通过共享基础设施打造出一条条铺好的路径（paved path）。智能体化开发带来了另一个需要为之设计的使用者。

Agent Experience 是智能体用来完成任务的每一个界面所具有的特性。

对于编码智能体来说,单个更改可能需要阅读文档、查询代码仓库、执行命令、修改文件、调用外部工具、解读测试输出、检查 CI 状态以及更新拉取请求。

获取正确的上下文

智能体需要以可预测检索和解读的形式获取信息。

API 得益于稳定的模式和结构化的响应。文档得益于准确的示例、清晰的版本管理和权威的说明。CLI 工具得益于机器可读的输出模式。工具描述得益于精确的名称、输入、输出和边界。

像 MCP 这样的协议让界面设计变得格外重要。工具描述有助于决定智能体何时选择某个工具,以及如何构造请求。

可用的上下文越多,并不会自动带来更好的 AX。真正起作用的是相关的上下文。

安全地执行操作

智能体需要可预测的方式来更改系统。

命令行工具应支持非交互式执行、有意义的退出代码,以及结果明确的操作。在可行的情况下,重复执行命令应当是安全的,或能明显看出产生了重复操作。

权限决定了在不增加错误代价的前提下,智能体能获得多大的自主权。缩小的权限范围、审批边界、隔离环境和策略执行,可以让智能体完成有用的工作,同时限制意外影响。

了解发生了什么

智能体需要知道某项操作是成功、失败,还是产生了意外状态。

机器可读的状态、具体的错误信息、结构化的日志以及明确的状态,能让下一步更容易判断。一条有用的错误信息会告诉智能体哪里失败了、失败发生在何处,以及系统原本期望什么。

完整的细节应在需要时仍可获取,但不必作为默认返回内容。

查找状态与历史记录

智能体常常需要一些信息,而这些信息开发者通常需要打开另一个界面才能获取。

当前正在运行哪个部署?哪个流水线失败了?上次尝试之后发生了什么变化?API 调用是否完成?是否已经存在打开的拉取请求?

以程序化方式暴露运维状态,能让智能体在无需依赖他人从仪表盘中转译信息的情况下,回答这些问题。

改善 Agent Experience 很少需要围绕 AI 重建整个平台。许多最有价值的改动,只是让现有界面变得更明确、更结构化、更可预测。

1. 返回结构化信息

为代理会重复使用的工作流提供机器可读的输出。

对于 CLI,这可能意味着按照文档化的模式输出 JSON。对于 API,这意味着稳定的响应类型和明确的错误状态。对于文档,这意味着提供代理无需自行补全缺失假设就能直接执行的示例。

人类可读的输出仍然可以保留给用户使用。代理则能从通往同一信息的机器导向路径中获益。

2. 在源头筛选上下文

只返回当前决策所需的信息,而不是所有可用信息。

如果三个测试失败了,先指出这三处失败并提供相关细节,而不是先返回成千上万行无关的输出。如果某个操作因参数无效而失败,直接指出该参数以及期望的值。

在源头进行过滤可以减少 token 消耗,并缩小代理需要考虑的合理解释的范围。

3. 让操作可预测、可重复

代理式工作流经常会重试操作、切换到其他方案,或回到之前的步骤。

幂等操作让重试变得安全。清晰的状态转换能帮助代理判断某件事是否已经发生。诚实的退出码和明确的状态,能避免代理必须从文字描述中推断是否成功。

护栏应尽可能内置在系统本身中。权限边界和策略检查,比指望每个代理都能自行发现并遵守某条书面约定要可靠得多。

4. 把延迟当作界面的一部分

反馈最有价值的时刻,是代理仍在处理产生这条反馈的任务时。

可接受的延迟取决于具体工作流。本地语法检查可能需要近乎即时返回结果。完整的集成测试可能需要更长时间。部署本身可能就需要几分钟。

关键问题在于,这个响应时间是否契合代理接下来需要做出的决策。

5. 衡量代理的结果

传统的 UX 指标无法完整描述代理与系统交互的好坏。定义一小组有代表性的任务,并在产品迭代过程中反复运行它们。

有用的 AX 信号可以包括:

• 首次尝试成功完成的频率
• 一项任务需要的重试次数或工具调用次数
• 达成结果所需的时间或推理预算
• 需要人工介入的频率
• 哪些工具或界面最常出现在失败尝试之前

当某个反复出现的失败暴露出界面问题时,先修复它,再把这个案例保留为回归评估用例。将这些评估与面向代理的契约测试(例如 API 模式、工具定义、结构化输出、退出码和权限边界)一起放进 CI 中运行。

有了基线,才能区分哪些是真正的 AX 改进,哪些只是在人工评审者看来更整洁的改动。

从反复出现的失败入手

选择一个代理经常执行的任务,从头到尾检查失败的尝试。

找出代理第一次缺乏上下文、误解状态、选错工具、收到模糊反馈或需要人工介入的那个环节。

最有用的 AX 改进,往往始于一个熟悉的软件界面,而不是模型内部。修复一个反复出现的失败后,把它加入你的评估集,以便日后捕捉回归问题。

AI 代理具有非确定性。同一个任务尝试两次,可能产生不同的推理路径、工具调用顺序和解决方案。

界面设计既可以放大这些差异带来的变动,也可以缩小它。

如果给代理提供完整的作业日志,它可以追踪的信号会非常多。如果给代理提供相关的失败信息、受影响的文件、预期行为和辅助上下文,它就能从一个范围小得多的问题定义出发。

第二种界面并不会让模型变得确定,它只是减少了不必要的歧义。

精确的工具描述能缩小工具选择范围。稳定的模式能减少解读空间。显式状态能减少猜测。定义清晰的权限边界能限制可执行的操作。

良好的 AX 会设计周围的系统,让模型的波动性更难转化为错误或代价高昂的行为。

上述原则适用于整个软件技术栈。CircleCI 专注于 Agent Experience 中的一个特定部分:代理在开发软件的过程中如何获得有用的验证反馈,以及团队如何在代理生成的改动上线之前对其进行独立验证。

代码生成正变得越来越快、越来越便宜。但每一项新增的改动,仍然需要证据证明它满足合并和部署所要求的标准。

CircleCI 的方法,把代理工作循环内的快速反馈与 CI 中的独立验证连接了起来。

编码代理可以很快地生成一个看似合理的改动。但评估这个改动,可能需要多得多的工作。

测试通过能提供有用的证据,但它只能说明你运行的那些检查通过了。一项改动可以满足某一个测试,同时却在其他地方引入回归问题、解决了错误的问题,或者未能满足当前测试套件未覆盖到的另一项要求。

代理式开发同时提高了快速反馈和独立验证的重要性。代理需要足够的信号才能在工作过程中高效迭代,而团队则需要在代码可共享或可部署之前,拥有更全面的验证层。

我们用合并质量来描述一项改动是否有足够的证据满足团队的合并要求,而不是把单一的通过信号当成正确性的证明。

CI 提供了一个独立的地方,用来收集并强制执行这些证据。

智能体化软件开发跨越两个反馈循环运作。

内循环

内循环是指智能体在积极处理一项变更时所发生的过程:

编写 → 运行 → 检查 → 修复 → 重复

智能体的活跃上下文中仍保留着问题、实现方案以及最近的工具输出。在这里进行快速验证有助于在 push 或 pull request 之前发现问题。

外循环

外循环始于变更到达共享交付基础设施之时。

它可以包括CI/CD 流水线、集成与系统测试、安全检查、评审、部署以及部署后验证。

外循环服务于不同的目的。其结果会在开发者、智能体、评审者以及下游系统之间共享。它为一项变更提供了独立于创建环境之外的证据。

连接两个循环

强大的 Agent Experience 能让有用的反馈在两者之间持续流动。

在内循环中发现的故障,往往可以在智能体仍拥有完整工作上下文时立即修复。而由 CI 发现的故障,则应带着足够的结构化信息返回给智能体,使其能够继续任务,而无需重新梳理整个问题。

目标并非把外循环的每一项检查都搬进内循环,而是让每个循环都能做好自己的本职工作,并让两者之间的交接高效顺畅。

CircleCI 正在为内循环与外循环构建面向智能体的接口,让智能体能够更早地验证代码、从 CI 获得信号更强的反馈,并在无需开发者转译结果的情况下针对故障采取行动。

1. 内循环中的 CI 级验证

Chunk sidecars 会在推送之前,在隔离环境中对受影响的代码执行有针对性的验证。

智能体可以在仍保留实现细节上下文的情况下验证工作目录中的变更,而无需等待完整的 CI 流水线运行。Sidecars 的设计目标是,对于属于内循环的检查项,能在一分钟以内返回 CI 级别的反馈。

快速的内循环验证能在问题引入的源头附近及时发现直接的问题,让外循环可以专注于更深层次的共享检查。

2. 外循环中信号更强的验证

Smarter Testing 利用测试影响分析,只运行受变更影响的测试,在可用计算资源之间智能地拆分测试执行,并能重新运行失败用例以识别不稳定测试(flaky tests)。

智能体驱动的开发可能会增加流经 CI 的变更数量和验证周期。快速运行最相关的测试有助于在数量增长的同时保持反馈的有效性。

减少不稳定和不必要的测试执行,也能让智能体和开发者都更清楚地判断一项变更是否需要关注。

3. 将外循环的故障带回上下文中

当相关信息能够直接返回智能体的工作环境时,CI 故障对智能体才最有价值。

CircleCI CLI 支持 --failure-report 标志,可以将失败的任务提炼为智能体诊断所需的信息,而无需先解析完整的日志。

CircleCI 还支持 Fix with Claude Code,它会将失败的 CircleCI 运行中的结构化故障摘要发送回终端中的 Claude Code。

外循环负责检测问题。智能体接收相关上下文、提出修复方案,而 CI 会独立验证下一次变更。

4. 让智能体直接访问 CircleCI

CircleCI CLI 提供了面向机器的 CircleCI 接口,具备结构化 JSON 输出、故障报告、流水线操作以及部署工具等能力。

CircleCI MCP 服务器 将 CircleCI 工具直接开放给兼容 MCP 的智能体。智能体可以获取流水线状态、检查故障和测试结果、重新运行工作流、触发流水线,并执行其他受支持的操作,而无需开发者在系统之间手动搬运信息。

对于新项目,circleci onboard 可以检查代码仓库、生成初始的 CircleCI 配置,并将项目连接到 CircleCI。

综上所述,这些接口让智能体能够直接参与交付工作流,而 CircleCI 则始终作为围绕其产出代码的独立验证层。

优秀的 Agent Experience,始于把智能体当作产品的用户来对待。为它们提供相关的上下文、可预测的行动方式、明确的系统状态,以及能让下一步决策一目了然的反馈。

从一个高频工作流入手,让智能体能够端到端地使用它。反复测试具有代表性的任务,把反复出现的故障转化为具体的界面改进。智能体评估和契约测试可以成为 CI 反馈循环的一部分,帮助你在产品变化时及时发现 Agent Experience (AX) 的退化。

借助 CircleCI,Agent Experience (AX) 可以延伸到交付工作流本身。编码智能体可以访问结构化的 CLI 输出和 MCP 工具,在内循环中验证变更,并在外循环中从 CI 获得信号更强的反馈,从而无需依赖开发者转译结果就能持续工作。

把 Agent Experience (AX) 构建进你的产品,然后让它成为你持续测试和改进的对象。