托管 Agent 运行

Managed agent runs in the Agent Hub

托管 Agent 运行允许您直接从 Archyl 调度自主 AI Agent。为其分配任务，选择决定其行为方式的配置文件，通过 MCP 连接器接入外部服务，设置定期执行计划，让 Agent 在完整架构上下文中对您的代码库执行操作。

在侧边栏中前往 代理中心 → 执行记录 管理运行，前往 代理中心 → 配置文件 定义 Agent 的行为方式，或前往 代理中心 → 定时任务 设置定期自动化任务。

概述

一次托管运行即为一次 Agent 执行。Agent 会：

克隆您项目的代码仓库到 Agent 工作进程上的全新工作区
接收架构上下文（C4 模型、ADR、合规规则、API 契约、技术栈），以及本次工作会话的简报：任务涉及的元素、之前的会话对这些元素了解到的内容，以及预检（preflight）结论
执行您定义的任务，在配置文件允许的范围内调用工具并做出决策
发布代码变更为 Pull Request，并报告所有操作的完整追踪记录

运行可以手动触发（一次性），也可以通过定时任务自动执行。

启动运行

前往 代理中心 → 执行记录
从下拉菜单中选择项目
点击 新建执行
选择配置文件
编写任务描述（例如："检查过时的依赖项并生成摘要"）
可选择附加连接器（详见下文）
点击 开始执行

Agent 会立即开始工作。您可以在运行详情页面实时监控进度。

Agent 配置文件

配置文件是对 Agent 行为方式的可复用定义。每次运行和每个定时任务都会使用一个配置文件。首次访问时，Archyl 会为您的组织创建 backend-fixer 配置文件；更多配置文件可在 代理中心 → 配置文件 中创建。

删除配置文件后，它产生的运行历史会被保留。使用该配置文件的定时任务会被暂停并标记为 配置文件已删除；在定时任务中选择其他配置文件即可恢复。

设置	作用
系统提示词	添加到该配置文件每次运行中的指令
技能	Agent 遵循的内置操作手册（详见下文）
允许的工具	限制 Agent 可调用工具的 glob 模式，例如 `read_file`、`list_`、`github__`。留空则允许运行所附加的全部工具。无论列表如何设置，平台工具（`report_outcome`、`propose_plan`、`update_plan`、`ask_human`、`open_repository`）始终可用
最高成本	运行的预估模型花费一旦超过该上限，运行即停止
最长时长	运行的实际耗时上限
最大输出 token 数	每次模型调用的输出上限
最大输入 token 数	降低使用 Anthropic 模型（Archyl 的模型、Anthropic 或 Bedrock）的运行的提示词预算：较早的对话轮次会被压缩以保持在预算之内，且无论如何设置都会低于 90,000 个 token。OpenAI 及 OpenAI 兼容的运行会忽略此设置，由提供商截断上下文

技能

技能是由 Archyl 维护的操作手册，始终与 Agent 实际拥有的工具保持同步。请按配置文件启用技能，而不是把指令复制到提示词里。

技能	Agent 会…
Architecture memory	在处理某个元素之前，先调取之前的会话对它了解到的内容，并记住仅凭代码看不出来的陷阱和约定
Conformance first	在结束前，对照您的合规规则检查它修改过的每个文件
Decision records	为值得写成 ADR 的决策创建 ADR，且只为这类决策创建
Impact analysis	在修改接口之前检查其调用方，并在需要协同变更时指明负责的团队
Model sync	当它的变更新增、删除或重命名容器、组件或关系时，同步更新 C4 模型

如果配置文件包含未知的技能或无效的允许工具模式，保存时会被拒绝。

默认的 backend-fixer 配置文件启用了 Architecture memory、Conformance first 和 Decision records。

运行详情页

每次运行都有一个详情页面，显示以下内容：

字段	说明
状态	`pending`、`awaiting_approval`、`running`、`waiting_for_input`、`succeeded`、`failed` 或 `cancelled`
已用时间	Agent 已运行的时长
心跳	Agent 工作进程最近一次上报的时间，以及本次运行的截止时间
Run ID	用于追踪的唯一标识符
计划	Agent 的计划，以实时更新的检查清单呈现
活动	Agent 执行的每个操作，按时间顺序排列
变更	Agent 写入的文件及其 diff，以及 Pull Request

事件流以可展开卡片形式展示每个操作：

工具调用 — 显示工具名称、输入参数和输出结果。每张卡片会标注来源标签，指示该工具来自哪个连接器（例如 github、archyl、linear）。
消息 — Agent 的推理过程和决策。
结果 — 运行结果、token 用量、Pull Request，以及 Agent 修改过的文件。
错误 — 高亮显示，便于快速定位。

引导运行中的 Agent

运行进行期间，您可以在引导输入框中输入消息，在不取消运行的情况下调整 Agent 的方向（"跳过迁移，专注于 handler"）。消息会立即进入队列，并在 Agent 的下一步注入其对话；Agent 收到后，事件流会显示 引导消息已送达代理。

运行提前停止时

如果运行失败、达到成本或时间上限，或用完了迭代次数，已经完成的工作不会被丢弃：Archyl 会将其发布为一个草稿 Pull Request，说明运行停止的原因。详见下文的 Pull Request。由您手动取消的运行不会发布任何内容。

可靠性保障

能够发现失联的工作进程。 Agent 工作进程每 10 秒上报一次。如果某次运行的工作进程已经 3 分钟没有响应，或超过时间上限 10 分钟后仍在运行，该运行会被自动标记为 failed，并释放其占用的名额。
卡住的运行不会占用名额。 10 分钟内没有被任何 Agent 工作进程领取的运行会失败；等待人工回复超过 1 小时 10 分钟的运行也会失败。
凭据不会比运行存活得更久。 每次运行都会获得专属的短期 Archyl API 密钥，运行一结束即被吊销。
取消一定会传达到 Agent。 即使直接发出的停止请求没有到达工作进程，被取消的运行也会在下一次上报时停止。

工作会话与协作

每次运行都在一个 Archyl 工作会话中进行，这与 Archyl Harness 为本地编码 Agent 提供的协议相同。会话由平台开启和关闭，Agent 从不自行管理。

运行的工作会话

运行启动时，Archyl 会针对任务涉及的架构元素开启会话：为这些元素获取租约，计算预检关卡的判定结果（allow、warn 或 deny），并把相关的决策、护栏和记忆放进 Agent 的简报。判定结果会以关卡事件的形式出现在事件流中。

尊重其他 Agent 的工作

尊重其他代理的工作 是配置文件中协作下的一项设置，默认关闭。开启后，会话以独占方式开启：

其他 Agent 正持有这些元素。 如果另一个 Agent（例如 Claude Code 这样的编码 Agent，或另一个托管运行）持有相同元素的租约，运行会被拒绝，拒绝原因会写明是谁在处理这些元素。
关卡仅给出警告，例如适用了 error 级别的护栏。此时运行进入 等待批准 状态，不占用并发名额。运行页面会列出原因，并提供 批准并开始 和 取消执行 两个按钮。

批准时会重新检查关卡：期间新出现的冲突仍会导致运行被拒绝。24 小时内无人批准的运行会被取消。

该设置关闭时，无论关卡判定如何，运行都会启动；Agent 会在简报中看到相应原因。

文件写入 Guard

只要 Agent 在代码仓库中工作，无论该仓库关联到项目还是通过 GitHub 连接器打开，每次 write_file 和 edit_file 调用都会在变更生效前与项目的合规规则进行比对：

违规级别	结果
`critical`	写入被拒绝。Agent 会看到违反了哪条规则，并修正变更
`high`	写入照常进行，同时向 Agent 发出警告

如果检查本身失败，写入照常进行：Guard 不会因为自身出错而阻塞 Agent。其行为与本地编码 Agent 使用的 Guard 钩子一致，详见 Harness 指南。

工作会话成果

结束前，Agent 会报告成果：摘要、决策、后续事项，以及它所依据的记忆。运行结束时，Archyl 会：

将变更的文件归属到会话，从而确定实际工作落在哪些租约元素上
关闭会话，并将摘要作为记忆保存到这些元素上
将决策记录为项目记忆，并开启一份架构变更请求草稿供评审。只有成功的运行才会记录决策

运行页面会显示 工作会话成果 卡片，包含摘要、决策、后续事项、涉及的元素以及变更请求链接。被其他会话持有的元素会标记为 已被另一个工作会话占用。

实时跟进运行

运行页面有两个视图：活动（即事件流）和变更（即 Agent 写入的文件）。当 Agent 需要您处理时，视图上方会出现横幅，说明它在等待什么（等待你审阅计划 或 代理有一个问题），并带您直接前往。

计划

在做出任何改动之前，Agent 会先分享一份计划：一句话摘要和若干具体步骤，最多 12 步。运行页面顶部的计划面板会把它变成检查清单。Agent 会将每个步骤标记为 进行中、已完成 或 已跳过，有时附上简短说明；面板则显示当前所在的步骤和进度（3/7）。

先审阅计划 是配置文件中协作下的一项设置，默认关闭。开启后，Agent 会在做出任何改动之前等待审阅：

面板切换为 审阅计划。您可以重命名步骤、补充细节，以及添加、删除步骤或调整顺序。
点击 批准计划（编辑过后为 批准编辑后的计划），Agent 即可继续。您编辑后的版本就是 Agent 遵循、检查清单跟踪的计划。
点击 要求修改 会发送您的反馈。Agent 修改计划后提出新的修订版供您审阅。之前的修订版会保留在事件流中。

在计划获得批准之前，Agent 可以读取，但不能做任何更改：写入文件，以及任何执行创建、更新、删除、关联、导入、推送或合并操作的工具（包括 Archyl 和所有连接器上的工具，例如 linear__create_issue），都会被拒绝，remember 也一样。Agent 会被告知等待审阅。

提问

当某个决定需要人来做时，例如需求不明确、权衡取舍没有明显优解或涉及破坏性操作，Agent 会提问。问题显示在事件流上方：如果 Agent 给出了选项，会附带 建议的回答，另有一个自由作答的输入框（按 Cmd/Ctrl + Enter 发送）。任何能编辑该项目的人都可以回答，事件流会记录回答者。

每次运行中 Agent 最多提出 5 个问题，并且被要求绝不询问自己能查到的内容。

等待您处理时

Agent 等待计划审阅或回答期间，运行显示为 等待你处理，并在运行列表中与处于 等待批准 的运行一起归入 需要你处理。

等待时间不计入运行的时间上限：截止时间会按等待时长顺延。运行仍占用其并发名额。
问题在一小时内无人回答：Agent 按自己的判断继续工作，并在成果中说明所做的假设。
计划在一小时内无人审阅：运行失败，且不会做出任何改动。

Agent 在哪里工作

Agent 在其工作区（代码仓库的一个克隆）中读取和修改代码：

项目已关联代码仓库：运行开始时由 Archyl 克隆。
未关联代码仓库，但附加了 GitHub 连接器：Agent 在改动任何文件之前，会使用连接器的凭据自行克隆任务所涉及的代码仓库。仅支持 GitHub 托管的 MCP 服务器（api.githubcopilot.com）。连接器必须使用 Authorization: Bearer 请求头进行认证，且其令牌需要有该代码仓库的访问权限。

工作区一旦打开，Agent 就只在其中修改文件：通过连接器工具推送文件或创建 Pull Request 都会被拒绝。正因如此，每项变更都会经过 Guard、出现在变更视图中，并汇入同一个 Pull Request。

变更

变更会在 Agent 写入文件的同时列出每个文件，状态为新增、已修改 或 已拦截，并显示每个文件以及整个运行新增和删除的行数。选择一个文件即可查看每次写入改动了什么。

被 Guard 拒绝的写入状态为 已拦截：diff 会显示 Agent 试图写入的内容以及它违反的规则。Guard 仅发出警告的写入会照常生效，并在文件上显示警告。
较长的 diff 会在 600 行处截断，超过 128 KB 的文件不显示 diff。

评论某一行

在 Agent 工作期间即可审阅 diff。在变更中点击行号即可评论该行，然后点击 发送给代理（Cmd/Ctrl + Enter）。Agent 会收到文件、行号及该行内容，处理评论后继续执行计划。

评论显示在对应行下方，Agent 读取前为 已排队，读取后为 已送达。评论也会出现在活动中，每个文件会显示其评论数。
新增行、未改动行和删除行都可以评论。被 Guard 拦截的写入无法评论。
Agent 工作中或等待您处理时均可接收评论。运行结束时仍为 已排队 的评论会显示为 未送达。

对于已结束的运行，评论会成为留给下一次运行的备注：留待继续执行 会将其保存在您的浏览器中，文件列表上方的横条（3 条评论留待继续执行）可带上这些评论继续运行（带上这些评论继续）。

Pull Request

运行结束时，Archyl 会将工作区中的变更提交到以 archyl/agent- 加上运行 ID 前 8 个字符命名的分支，并以克隆时所基于的分支为目标创建 Pull Request。其链接显示在变更顶部（打开拉取请求）以及结果中。

运行如何结束	Archyl 发布的内容
成功	Pull Request
失败，或因时间或成本上限而停止	说明运行停止原因的草稿 Pull Request
已取消	无

在 GitLab 上，草稿为 Draft: 合并请求。在 Bitbucket 上只推送分支，不创建 Pull Request。未修改任何文件的运行不会发布任何内容。

Pull Request 会在 github.com、gitlab.com 和 bitbucket.org 上创建。Archyl 只会将您的 Git 凭据发送到这些主机：位于自托管 Git 服务器（GitHub Enterprise、私有 GitLab、Azure DevOps、Gitea）上的代码仓库会在不带凭据的情况下克隆，因此私有仓库无法克隆，也不会创建 Pull Request。

继续运行

已结束的运行无论结果如何，都提供两个按钮：

继续会启动一次新的运行，接手本次运行的工作。写下 Agent 接下来要做什么：您留待继续的评论会预先填入指令，每行一条（路径:行 — 评论）。默认沿用本次运行的配置文件，您也可以选择连接器。
再次执行 会以相同的任务和配置文件打开启动对话框，从头开始一次新的运行。

继续的运行了解上一次运行被要求做什么以及做了什么。它从上一次运行发布的分支开始，在该分支上提交，并将变更添加到同一个 Pull Request，而不是另开一个。如果上一次运行推送了分支但没有创建 Pull Request，继续的运行会创建一个，目标为新运行所针对的分支。如果上一次运行通过 GitHub 连接器打开了仓库，继续的运行会在该分支上重新打开它。

如果该分支已不存在（例如已合并并删除），继续的运行会从新运行的起始分支（项目关联的分支或代码仓库的默认分支）开始，并创建新的 Pull Request。事件流中会注明这一点。
草稿 Pull Request 仍保持草稿状态：工作完成后请将其标记为可供审阅。
Archyl 只会在其 Agent 创建的分支上继续，绝不会提交到您自己的分支。

新运行的页面会链接到它所继续的运行（源自执行），上一次运行会链接到其后续运行（后续执行）。仍在进行中的运行无法继续：请改为评论它的代码行。

MCP 连接器

连接器可将外部服务附加到 Agent 运行中。任何暴露 MCP（Model Context Protocol）服务端的服务都可以接入。

支持的服务

服务	功能
GitHub	读取 PR、检查 CI 状态、列出 Issue、审查代码
GitLab	与 GitHub 相同的功能，适用于 GitLab 托管的项目
Linear	读取/更新 Issue、查看 Sprint 进度
Slack	发送消息、读取频道、通知团队
Custom	任何兼容 MCP 的服务端

创建连接器

前往 代理中心 → 连接器
点击 新建连接器
输入名称（例如："github"）
粘贴 MCP 服务端 URL
如有需要，添加认证头信息
点击 创建连接器 — Archyl 会探测服务端并显示可用工具

工具命名空间

当连接器附加到运行时，其工具会以连接器名称作为前缀：

连接器	工具示例
`github`	`github__list_pull_requests`
`linear`	`linear__get_issue`
`slack`	`slack__post_message`

Archyl 内置 MCP 服务端的工具不带前缀（例如 get_agent_context、list_conformance_rules）。

这种命名空间机制确保不会发生工具名称冲突，使事件流易于浏览，还能让配置文件的允许工具列表用 github__* 这样的单个模式覆盖整个连接器。

定时任务

定时任务允许您使用标准 cron 表达式定义定期执行的 Agent 运行。

创建定时任务

前往 代理中心 → 定时任务
点击 新建定时任务
选择配置文件并编写任务描述
选择 cron 表达式（可使用预设值或输入自定义表达式）
根据需要附加连接器
点击 创建定时任务

定时任务管理

每个定时任务显示以下信息：

Cron 表达式 — Agent 的运行时间
下次运行 — 下次执行的预定时间
上次运行 — 上次执行的时间
状态 — 活跃或暂停；配置文件被删除时显示 配置文件已删除

您可以：

暂停定时任务而不删除它
恢复已暂停的定时任务
立即运行 — 在正常节奏之外立即执行
编辑任务描述、cron 表达式或附加的连接器
删除定时任务

配置文件已被删除的定时任务会保持暂停：在您编辑该定时任务并选择其他配置文件之前，恢复或 立即运行 都会被拒绝。

定时任务示例

用例	Cron 表达式	说明
每周架构审查	`0 9 * * 1`	每周一上午 9 点
每日依赖审计	`0 7 * * *`	每天上午 7 点
每周文档同步	`0 14 * * 5`	每周五下午 2 点

架构上下文

每次托管运行都会自动获得对 Archyl 项目 MCP 服务端的访问权限。Agent 可以：

查询 C4 模型以了解系统边界
读取 ADR 以了解过去的架构决策
检查合规规则以了解应遵循的模式
浏览 API 契约以了解服务接口
查阅技术分配以选择合适的工具
通过架构记忆调取和记录关于元素的事实

这些上下文在 Agent 开始工作前即已注入 — 无需从零开始发现您的架构。此外，每次运行都包裹在一个 harness 工作会话中，因此其结果会沉淀为所涉及元素的记忆。

AI 提供商

除非您的组织启用了自带 AI 提供商，否则运行使用由 Archyl 管理的模型。启用 BYO 后，运行会在您自己的提供商上、使用您自己的凭据执行，支持 Anthropic、AWS Bedrock、OpenAI，以及实现了 Responses API 的 OpenAI 兼容端点。Google Gemini 暂时还不能运行托管 Agent：此类运行会被明确拒绝并给出提示，而不会悄悄改用 Archyl 的模型。

配额与并发

托管 Agent 运行适用于 Scale 和 Custom 套餐。使用量按组织维度追踪，设有月度配额，配额状态显示在执行记录和定时任务页面顶部。继续运行和批准被暂挂的运行也会计为运行。启用了 BYO AI 的组织不计入配额，手动运行和定时运行均是如此。

每个活跃的运行（pending、running 或 waiting_for_input）都会占用组织的一个并发运行名额。无论出于何种原因，运行一结束，名额即被释放。

最佳实践

任务描述要具体 — "检查是否有存在已知 CVE 的 Go 包，并按严重程度列出"比"检查依赖"效果更好
为每项工作单独设置配置文件 — 一个将 allowedTools 限定为 list_*、get_* 和 read_file 的只读审查者，不可能意外修改任何内容。
仅附加必要的连接器 — 每个连接器都会向 Agent 上下文中添加工具。工具越少，执行越专注。
先用手动运行测试 — 在创建定时任务之前，先用一次性运行测试您的任务描述。
结合合规规则使用 — 先定义约束规则，然后启用 Conformance first 技能，让运行自动进行验证。