AI 助手总是答非所问，可能是没给它指定角色

定义框：内置 Agent 是一类由平台预先构建和维护的专用 AI 助手，每个都绑定一个明确的职能领域（如流水线、安全分析、数据洞察、权限配置）。与通用 AI 助手的区别在于，它内置了该领域的术语体系、工作流与最佳实践，回答时会按从业者的实际工作方式组织，而不是按通用语义平均用力。

通用助手在具体场景里为什么总差一口气

很多团队引入 AI 助手后的第一个落差，不是"它不会写代码"，而是"它说的都对，但没一句能用"。

典型场景：你问一条流水线为什么跑挂了，它给你讲了一遍 CI 配置的语法规范；你问某个漏洞该怎么修，它回了一段通用加密建议。信息没有错，但层级不对——你要的是针对当前仓库、当前 Runner、当前日志的定位结论，它给的是教科书。

根因在于上下文与角色是两件事。把仓库全文塞进上下文，只能解决"它知道代码"，解决不了"它知道该以什么身份来读这段代码"。同一个 .gitlab-ci.yml，流水线工程师关心的是阶段依赖与缓存命中，安全工程师关心的是密钥注入与镜像来源，两个人读同一份文件的顺序完全不同。

角色缺失带来的代价是隐性的：

• 正确率波动。同一个问题多问几次，答案风格与结论漂移，团队不敢把它接进流程。

• 无法验收。没有角色边界，就没有"这个答案算不算合格"的判断标准，最后还是人来兜底。

• 知识无法沉淀。每次对话都是平地起高楼，沉淀不下来团队自己的规范。

内置 Agent 的一个容易忽略的特征是它由平台方构建和维护，并带有极狐GitLab 维护徽章。这意味着它的行为随平台版本演进，而不是随某次对话随机变化——这对要把 AI 接进研发流程的团队来说，是可验收性的前提。

内置 Agent 有哪些，各自管什么

按官方公开的能力清单，目前在界面、VS Code 与 JetBrains 中可用的内置 Agent 覆盖八类职能。各 Agent 的适用版本不同，具体以各自页面为准。

这张表的价值不在于"有八个 AI 可用"，而在于它给出了一个划分标准：按职能切，而不是按模型切。团队真正要做的决策是，哪些职能值得先交给 Agent，哪些暂时不放。

一个务实的排序建议是先从"高频且结论可验证"的职能切入。流水线调试与安全告警分诊就属于这一类——答案对不对，跑一次就知道了。而产品规划类的问题，验证周期长、主观成分多，初期放进流程里反而容易消耗团队耐心。

怎么给团队开起来，并改成自己的版本

内置 Agent 默认处于启用状态。真正需要动手的是两件事：按群组做可用性治理，以及把某个内置 Agent 复制成团队自己的版本。

步骤一，确认前置条件

需要满足极狐GitLab Duo Agent Platform 的先决条件，并已启用内置 Agent。几个容易踩的版本细节：

• 已开启极狐GitLab Duo；若没有 Duo Pro 或 Enterprise，需要为顶级群组或实例开启极狐GitLab Duo Core。

• 在极狐GitLab 18.9 及更早版本中，无法将 Agent Platform 与 Duo Enterprise 附加组件一起使用，需升级到 18.10 或更高版本。

• 在 18.8 及更高版本中，Agent Platform 已默认开启；在 18.7 及更早版本中，需要手动开启测试版和实验性功能。

• 本地环境使用还需安装编辑器扩展并完成认证，在群组命名空间中拥有项目，并具备开发者、维护者或所有者角色。

步骤二，按群组开关内置 Agent

默认全部开启，但生产环境通常需要收口。路径是：在顶部栏选择"搜索或跳转到"并找到你的群组，左侧边栏进入"设置 > 极狐GitLab Duo"，选择"更改配置"，在"内置 Agent"下对"默认可用性"选择开启或关闭，再在"可用性设置"中逐个 Agent 选择开启、关闭或使用默认值，最后保存。

这里有一个必须提前想清楚的副作用：如果你为某个顶级群组禁用了内置 Agent，那么将该群组作为默认 Duo 命名空间的用户，在任何命名空间中都无法访问内置 Agent。这个限制是跨命名空间的，不是只在该群组内生效。很多团队在试点时只想在单个群组关掉某个 Agent，结果发现成员在其他项目里也用不了，就是这个机制导致的。

步骤三，复制内置 Agent 成自定义版本

内置 Agent 不可直接编辑。要改它的行为，正确做法是复制一份：

1. 在顶部栏选择"搜索或跳转到 > 探索"。

2. 选择 AI 目录，进入 Agents 选项卡。

3. 选择要复制的 Agent，在右上角选择"操作 > 复制"。

4. 在"可见性与访问权限"下，为"受管方"选择一个项目；"可见性"选择私有或公开。

5. 按需编辑字段，选择"创建 Agent"。

复制出来的是一个自定义 Agent，创建后必须手动启用才能使用。这一步经常被跳过，表现为"明明复制成功了，对话里却找不到"。

复制机制的实际意义在于：它把"平台给的通用能力"和"团队自己的规范"分离了。内置版本随平台升级演进，你的副本固定在一套经过验证的行为上。对于要过合规的团队，这个可冻结性比能力本身更重要。

一个可落地的例子：把团队规范写进 AGENTS.md

角色只是解决了"以什么身份回答"，要让答案真正贴合你的仓库，还需要给 Agent 一份可执行的规范。极狐GitLab Duo 支持用仓库中的 AGENTS.md 文件提供上下文与指令，在执行内置任务流和自定义任务流时都会遵循。

一个最小可用的写法示例：

# AGENTS.md

## 仓库背景
这是一个 Java 微服务仓库，构建工具为 Gradle 8.x，JDK 17。

## 修改约束
- 任何新增依赖必须先确认已在内部制品源中存在，不允许直连公网仓库。
- 流水线文件只允许修改 .gitlab-ci.yml，不允许新增同级配置文件。
- 涉及密钥的改动一律不允许提交，必须使用 CI 变量。

## 输出要求
- 回答优先给出可复制的命令或配置片段，再解释原因。
- 若结论依赖某个版本号，必须显式标注该版本。

提交到仓库根目录即可被读取：

git add AGENTS.md
git commit -m "chore: 补充 Agent 执行规范"
git push

这份文件的作用不是让 Agent 更聪明，而是把"团队默认怎么做"变成每次执行都会读到的一部分。它和内置 Agent 是互补关系——内置 Agent 决定以什么身份理解问题，AGENTS.md 决定在这个仓库里该遵守哪些约束。

五个容易踩的坑

1. 在顶级群组关掉内置 Agent 会波及所有项目。该限制是跨命名空间的，试点阶段建议优先用"可用性设置"逐个 Agent 关闭，而不是直接关默认开关。

2. 复制出来的自定义 Agent 默认不可用。创建后必须启用，否则在对话里找不到，容易被误判为复制失败。

3. 复制操作有角色门槛。需要对目标项目具备维护者或所有者角色，开发者角色看不到"操作 > 复制"。

4. 各内置 Agent 的适用版本不一致。清单里写的是当前可用范围，具体到某个 Agent 在哪一版本起可用，需要查它自己的页面，不要按清单统一推断。

5. 别一上来就自动化主观性强的职能。先做结论可立即验证的（流水线调试、告警分诊），再考虑规划类。顺序反了，团队对 Agent 的信任会提前透支。

另外要明确一个边界：内置 Agent 解决的是角色与规范问题，不是能力边界问题。它不会让模型凭空具备它没有的知识，也不会替代人工审批。把它定位成"把重复判断标准化"的手段，预期才不会跑偏。

常见问题

内置 Agent 和自定义 Agent 该怎么选？

内置 Agent 适合覆盖通用职能，开箱即用、随平台升级演进，适合作为团队能力的基线。自定义 Agent 适合承载团队特有的流程与规范，行为可冻结。实践中的常见组合是：内置 Agent 打底，把差异化的部分通过复制改成自定义版本。

内置 Agent 可以直接编辑吗？

不可以。内置 Agent 由平台构建和维护，不可直接修改。要改变它的行为，需要复制一份成为自定义 Agent，再在副本上编辑字段并启用。

关掉某个内置 Agent，会不会影响其他群组的项目？

会。如果关闭发生在顶级群组，那么将该群组作为默认 Duo 命名空间的用户，在任何命名空间中都无法访问内置 Agent。这个影响范围是跨群组的，改动前建议先确认成员的默认命名空间设置。

把团队的重复判断交给 Agent，从一次流水线调试开始

与其讨论 AI 能替代多少工作，不如先挑一个每周都要做、结论又能立刻验证的场景试一次。极狐GitLab 提供专业版试用，可以在自己的仓库里完整走一遍内置 Agent 的启用、复制与规范配置流程。

👉 申请极狐GitLab 专业版试用 ｜ 查看内置 Agent 官方文档