Taming the agent beast: From monolithic prompt to modular agentic workflow

驯服智能体：从单块提示到模块化智能代理工作流

组件 | 文章摘要

2026年8月26日

10分钟阅读

应用开发与交付

Ioannis Angelakopoulos

Joseph (Sephi) Berry

高级机器学习工程师

Subpattern | social_share_set

组件 | 社交分享

分享

Subpattern | 订阅

组件 | 社交图标

订阅RSS

组件 | 图标

© Red Hat, Inc. CC-BY-4.0授权

Subpattern | 结果导航

组布局

组件 | 导航链接

• 返回所有文章

组件 | 通用内容

当你不再将AI代理视为聊天机器人，而是将其视为流水线中的工人时会发生什么？这就是我们将庞大的Jira待办事项列表转化为自主协调系统的历程，以及沿途学到的经验教训。

TL;DR

我们构建了一个智能代理工作流，该工作流能够自动发现Jira工单，从源代码控制中为其补充上下文信息，并生成结构化摘要使工单可操作，整个过程无需人工干预。实际上，该流水线每周处理数十个工单，将分类时间从小时缩短到分钟，为开发人员提供可操作工作的即时上下文。我们的旅程从一个勉强能用的单块提示开始，最终演变为模块化、分区域的流水线，每个工单通过独立的代理会话进行处理。本文将涵盖整体设计、大规模协调AI代理的挑战以及我们的收获。后续文章将深入探讨技术实现细节。

问题：工单过多，时间不足

如果你曾经盯着一个包含数十个开放工单的Jira看板，这些工单分散在多个冲刺周期、待办事项列表和被遗忘的史诗任务中，你就会明白这种感受。在不同工单之间切换上下文、理解每个工单需求、判断哪些工单真正可操作所带来的认知负担是巨大的。将这种负担乘以每个工单涉及的仓库数量，你就得到了导致瘫痪的配方。

我们想验证智能代理工程是否能处理这些繁琐工作：从Jira提取工单、用源代码控制的上下文信息丰富工单，并生成下游代理（或人类）可以立即采取行动的结构化摘要。同时要在及时完成这些任务的前提下，无需专人全程监控单个会话。

结果是一个模块化、分区域的自动化流水线，将每个Jira工单视为独立的工作单元，通过明确定义的阶段流动处理。我们称之为"驯服智能体"，因为将AI代理整合到可靠、可重复的工作流中，实际上才是真正的挑战。

为什么不只是一个脚本？

显而易见的初始想法是编写一个调用Jira应用程序编程接口（API）、格式化一些Markdown然后就完事的Python脚本。我们考虑过这个方案，但很快发现了其局限性：

• 上下文至关重要。脚本可以提取工单字段，但无法判断工单描述是否模糊、验收标准是否有意义，或持续集成（CI）流水线是否以与工单相关的方式失败。

• 信息补充需要判断力。确定工单针对的仓库、从评论中埋藏的统一资源定位符（URL）映射项目路径，以及评估工单是否包含足够的信息来采取行动，这些都受益于语言模型的推理能力。

• 管道需要状态。工单不是一次性处理的。它们会被发现、分类、阻塞、补充信息并验证。脚本只能处理一个步骤；你需要一个工作流来管理整个生命周期。

因此，我们没有使用脚本，而是构建了一个通过基于看板的状态机协调的智能会话管道。

关键概念：构建模块

在深入架构之前，有几个概念值得介绍：

• Agor 是一个跨仓库协调 AI 智能体会话的框架。它提供了一个基于看板的界面（类似于 Kanban），工作项在列之间移动，每列都可以通过特定提示和工具集触发智能体会话。我们在此演示中使用 Agor 作为协调层，但这里描述的设计模式（如基于区域的管道、结构化输出契约和有状态协调）是与框架无关的。Red Hat 不会将你绑定到特定的智能体框架，而是提供运行它们的基础。在企业环境中，你可以使用 Red Hat OpenShift AI 部署这些模式，这为你提供了托管、扩展和运营所选智能体的手段。

• 区域是看板上的列。每个区域代表工作流中的一个阶段（发现、分类、准备等），并拥有自己的智能体配置：专用提示、一组模型上下文协议（MCP）工具集成，以及确定会话何时启动的触发规则。

• 工作树是工作的基本单位。每个 Jira 工单都有自己的工作树，由目标仓库中的 Git 工作树支持，在管道中通过不同区域移动。工作树携带元数据（Jira 问题 URL、拉取请求（PR）/合并请求（MR）URL、注释、自定义上下文），其所在区域位置精确说明了工单在工作流中的位置。可以将其视为既是看板卡片，又是一个真实且隔离的 Git 工作目录。

架构：区域作为状态机

核心思想借鉴自看板：每个工单通过区域移动，每个区域都有一个专用智能体和专用提示。没有智能体会试图处理所有事情。发现智能体负责发现，分类智能体负责分类，依此类推。

工作流

基于区域的管道可视化图，展示了工作树从初始发现到分类，然后进入准备状态或阻塞路径以进行上下文补充的生命周期。

| 区域 | 发生内容 | |----------|--------------------------------------------------------------------------| | 发现 | 定时任务：查询 Jira，分配工作树，并运行看板健康检查 | | 分类 | 每个工单：分析原始工单，判断其是否有足够的上下文以采取行动 | | 阻塞 | 每个工单：暂停需要额外上下文的工单，通过自动化补充或人工干预 | | 补充 | 每个工单：为工单补充源代码控制上下文（CI 状态、MR 和相关问题），并生成结构化摘要 | | 准备 | 已验证摘要的补充工单，准备进行人工审核或后续操作 |

关键洞察是工作树使管道具有状态性。与在每次运行后忘记所有内容的无状态脚本不同，每个工单的工作树会在会话之间持续存在。其所在区域位置就是状态，其元数据就是记忆。当工单流经分类、补充并进入准备状态时，沿途的每个智能体都会为工作树的累积上下文做出贡献，而区域位置会精确告诉下一个智能体该做什么。

让我们逐步了解每个实现的阶段。

发现代理：系统的心跳

发现区域按照可配置的定时任务计划运行一个单一的"哨兵"工作树。可以将其视为流水线的心跳，是保持所有组件同步的控制回路。在定期间隔中，它会：

• 使用3个Jira查询语言（JQL）查询（活跃的史诗任务、冲刺任务和待办事项）向Jira发起查询，以获取所有已分配的开放工作的完整视图。

• 与看板进行对比，找出尚未拥有工作树的新工单。

• 从Jira工单描述和评论中提取仓库URL，解析GitHub和GitLab URL以确定每个工单的目标仓库。

• 注册并克隆系统尚未知晓的仓库。如果工单引用了gitlab.com/org/project且该仓库尚未存在于磁盘上，发现代理会克隆它并在编排框架中进行注册。

• 批量创建工作树，在每个新工单的目标仓库中创建工作树并将其放置在待处理区域。

• 执行心跳检查以检测过期工作树、区域不匹配（例如Jira显示已完成但工作树仍在待处理区域）和过时摘要。

• 生成每日报告，记录发现的内容、创建的项目以及看起来不健康的工单。

关键设计决策：发现代理从不生成工单摘要。它仅执行发现、创建和路由操作。丰富信息和摘要生成在专用区域下游进行。这种职责分离使每个代理保持专注，并使故障相互隔离。发现代理中的问题不会破坏丰富信息流水线的输出，反之亦然。

待处理代理：一个工单，一个会话

这就是设计变得有趣的地方。与单个代理按顺序处理所有工单不同，每个工单都会获得自己的独立会话。真正的按工单并行处理：5个工单可以同时进行待处理操作，且没有跨工单依赖。

发现代理为每个新工作树设置计划，使编排框架自动为其启动一个待处理会话。每个待处理会话：

• 获取完整的Jira工单（所有字段、最近评论）以获得完整视图。

• 验证工单是否具有足够的上下文以采取行动。是否至少引用了1个仓库？是否有具体要求？明确的验收标准？

• 路由工作树：定义明确的工单直接进入就绪状态，而信息不足的工单则进入阻塞状态以进行丰富处理。

待处理阶段刻意保持轻量：它做出路由决策，而非内容决策。繁重的工作将在下一阶段进行。

丰富代理：补充缺失的上下文

进入阻塞区域的工单在变得有用之前需要更多上下文。丰富代理负责轮询这些工单并触发丰富会话，通过从目标源代码控制项目和相关Jira工单中补充信息来增强它们。

每个丰富会话：

• 通过源代码控制上下文进行丰富，包括CI流水线状态、开放的合并请求以及来自GitLab或GitHub的相关问题。

• 生成结构化markdown摘要，包含YAML（YAML Ain't Markup Language）前缀，这是下游消费者（人类审阅者或未来代理）的输入契约。

• 根据结构化摘要更新Jira工单，将丰富后的上下文写回真相来源。

• 路由工作树：足够丰富的工单将进入就绪状态，而仍缺乏关键上下文的工单将退回阻塞状态以等待人工干预。

摘要格式是流水线的核心。YAML前置信息包含可被机器解析的元数据：工单编号、类型、状态、仓库、持续集成状态和开放的合并请求。Markdown正文包含标准化的章节：描述、上下文与分析、详细需求、技术考量、验收标准和依赖项。

演进：从单体到模块

最初我们使用单个会话中的单体提示处理所有任务。虽然勉强能运行，但很快遇到了运行时间过长、上下文窗口溢出和缺乏状态跟踪的问题。单个工单的错误会导致整个批次失败，而顺序处理意味着零并行性。转向模块化区域设计通过隔离关注点并将每个工单视为独立的工作树解决了这些问题。

架构也演进为直接在每个工单的目标仓库内创建工作树，而非集中式流水线文件夹。这意味着每个代理会话启动时都能立即访问代码库，无需额外导航步骤。

协调AI代理的挑战

构建这个系统暴露了超出任何特定工具范围的挑战。这些问题会在你尝试在自动化流水线中可靠运行AI代理时反复出现。

代理需要护栏而非自由

关于代理工作流的最大误解是应该给予代理最大自主权。实际上恰恰相反。当代理的范围狭窄且输出格式严格时表现最佳。"处理这些工单"的提示会产生高度不一致的结果，而"获取这个特定工单，使用这些特定工具进行丰富，用这种精确格式编写摘要，根据这些标准进行验证，并路由到两个区域中的一个"的提示会产生更可靠的输出。

每次我们缩小代理的范围，质量都会提升，失败率都会下降。

调度问题

AI代理会话并非瞬时完成，可能需要数分钟甚至更久。当你在cron上调度代理而前一个会话尚未完成时，会出现重复运行处理相同工单的情况。我们的解决方案是让每个分诊会话在其最后一步禁用自己的调度。但这创造了脆弱的耦合：如果会话在禁用调度前崩溃，下一次cron触发时重复处理会重新开始。更健壮的解决方案（幂等性令牌、外部锁管理器）是可能的，但会增加复杂性。

无状态代理的有状态编排

每个代理会话都是全新启动的，没有任何之前运行的记忆。但流水线需要连续性："这个工单昨天已经分诊并丰富过，不要重复处理"。我们通过将状态外部化到工作树元数据和区域位置中解决了这个问题。代理不需要记住上次做了什么，看板会告诉它现在该做什么。这种模式（无状态代理，有状态编排）最终被证明对可靠性至关重要。

当API未暴露所需信息时

并非所有编排框架都会通过其API暴露所有功能。我们遇到过关键功能（例如我们的案例中的计划管理）无法通过标准工具接口使用，必须通过直接数据库访问等变通方法实现的情况。这种方式脆弱且依赖版本。教训是：评估编排平台时，应检查所需自动化功能是否可通过API访问，而不仅仅是用户界面（UI）可操作。

无人值守操作的权限模型

要让流水线无需人工值守运行，每个计划会话都必须在无确认提示的情况下执行。大多数代理框架的权限模型都是为交互式使用设计的，需要人工确认每个操作。通过cron运行代理需要更宽松的权限模式，这意味着必须信任代理的提示不会越界。在自动化与安全性之间找到平衡是一项持续的设计挑战，尤其在共享环境中更是如此。

经验教训

运行此流水线的一些操作经验：

• 批量处理，而非一次性全部处理。同时创建大量worktree可能导致文件系统配给过载。我们以3个为一组分批创建，并在批次间进行验证。失败的配给在清理后有一次重试机会；持续失败的情况会被记录并跳过。仅这一措施就消除了整个类别“worktree目录不存在”的崩溃问题。

• 心跳机制可检测偏差。Jira和看板最终必然会出现偏差。票证可能在流水线外被解决，冲刺周期轮换，负责人变更。定期执行的心跳机制用于将看板与Jira同步是必不可少的。没有它，过时的worktree会悄无声息地累积。

• 结构化输出是不可妥协的。YAML-frontmatter摘要格式使流水线具备可组合性。每个阶段都可以信任前一阶段的输出，而无需解析自由文本。如果必须从头重做一件事，我们会首先定义输出模式，然后逆向构建。

• 将编排与执行分离。Discover代理负责编排（创建worktree、设置计划、监控健康状态）。Triage代理负责执行（处理单个票证）。在单个代理中混合这些职责是单体版本中大多数故障的根本原因。

• 在提示中泛化工具引用。早期的提示中充斥着特定工具的细节（特定命令行界面（CLI）标志、硬编码字段ID）。所有这些都成为维护负担或可移植性问题。尽可能抽象化，并将特定工具的细节保留在配置中而非提示中。

运行良好的方面

尽管存在一些粗糙之处，但以下方面确实运行良好：

• 零接触发现。新的Jira票证会自动作为worktree出现在看板上，无需任何人工干预。由cron驱动的Discover代理处理整个生命周期。

• 真正的并行处理。多个票证可同时处理，每个都在自己的会话中，没有跨票证依赖或共享状态。

• 结构化输出契约。增强后的Jira票证和摘要都保持一致，可被机器解析，并包含足够上下文供人工审核者或下游代理理解票证内容。

• 健康监控。心跳机制可检测过时worktree、区域不匹配和过时摘要。这是一种轻量但有效的自愈机制。

• 仓库感知的worktree。每个票证的worktree位于其目标仓库中。会话从正确位置启动，代码已可访问。

下一步计划

未来，我们希望深入探讨使用Agor进行技术实现，包括区域配置、MCP工具集成以及调度机制。

请注意，本系列文章以Agor作为示例框架，探讨代理工作流设计模式。Agor不是Red Hat的产品，也不属于Red Hat OpenShift AI支持的堆栈。如需在Red Hat支持的堆栈上部署生产级代理工作负载，或了解如何使用我们的官方工具应用这些概念，请查阅Red Hat OpenShift AI文档并访问我们的代理AI落地页面。

Block | Dynamic pattern deluxe promo

Component | Band_header

Resource

适应性强的企业：为什么AI准备就是应对变革的准备

这本电子书由Red Hat首席运营官兼首席安全官Michael Ferris撰写，帮助IT领导者应对当前面临的AI技术变革和快速发展。

Component | spacer

Component | Cta_multi_basic

Subpattern | simple_cta

Component | CTA

获取资源

Deluxe mbox

Component | Card_header

关于作者

Subpattern | speaker

Card layout

Component | Image_embed

Component | Person

Ioannis Angelakopoulos

Joseph (Sephi) Berry

Subpattern | social_links

Joseph Berry是Red Hat的高级机器学习工程师，专注于AI基础设施、机器学习系统和性能基准测试。他拥有近十年构建生产级机器学习和数据平台的经验，专注于弥合研究与可靠、可扩展生产系统之间的差距。

在加入Red Hat之前，Joseph曾在多个领域担任机器学习工程师，包括保险科技、媒体科技、移动科技和国土安全。在这些职位上，他领导了MLOps和数据工程计划，构建了基于云的机器学习基础设施，并开发了用于大规模部署多模态模型的工具。职业生涯早期，他在初创公司和成熟企业中担任过各种地理信息系统相关职位。

他的技术兴趣涵盖分布式计算、MLOps、云平台、地理信息系统和开源技术，重点在于使AI系统在生产环境中更加高效、可复现和易于访问。

更多该作者的文章

类似内容推荐

Dynamic pattern

Blog post

在Red Hat OpenShift上现代化数据库工作负载

突破锁定：某领先保险公司如何在10个月内将1500个工作负载迁移至ROSA

Original podcast

Press Start | Command Line Heroes

谁害怕编译器？| 编译器

Subpattern | card_flex

Subpattern | text_basic

继续探索

• 什么是代理AI？文章

• 预测性AI与生成性AI对比 文章

• 构建生产级AI/ML环境的首要考虑因素 电子书

• 以Ansible方式实现生成性AI 视频

• 通过现代应用平台实现创新与转型 电子书

Keep Exploring mbox

Subpattern | simple_text

按频道浏览

探索所有频道

Pattern | raw_html

自动化

关于IT自动化在技术、团队和环境中的最新动态

人工智能

关于使客户能够随时随地运行AI工作负载的平台的最新动态

混合云

探索我们如何通过混合云构建更加灵活的未来

安全

关于我们在不同环境和技术中降低风险的最新动态

边缘计算

关于简化边缘操作平台的最新动态

基础设施

全球领先的企业的Linux平台最新进展

应用

深入我们的解决方案，应对最严峻的应用挑战

虚拟化

企业虚拟化的未来，无论是本地部署还是跨云环境中的工作负载