使用指南

最近更新：2026-09-15

• 1: 模型提供商
• 2: 创建自定义 Agent
• 3: 接入外部 Agent
• 4: Chat 与执行记录
• 5: Projects、文件与工作目录
• 6: Agentflow
• 7: Jobs 定时任务
• 8: Tools 与 Skills
• 9: MCP 服务
• 10: 配置 Integrations
• 11: Web、Desktop 与 Mobile

1 - 模型提供商

最近更新：2026-09-25

让自定义 Agent 回答问题之前，需要告诉 AGW 使用哪个模型、请求发往哪里，以及如何认证。模型服务商通常会提供 API 地址、模型 ID 和 API Key；请先准备好这些信息。

本页介绍 AGW 中的模型配置。已有命令行工具配置的用户，也可以按外部 Agent 指南接入。

三类配置

Provider 描述服务端点和认证；Model 描述模型及其限制；Model Provider 将两者关联，供 Agent 选择。仅创建 Model 不等于已经连通服务。

1. 在 Providers 中打开 Create provider，选择匹配的协议类型并填写地址，在 Auth Configs 中添加并启用凭据。
2. 切换到 Models 标签，勾选这个 Provider 提供的模型。协议为 OpenAI Chat Completions 或 OpenAI Responses，且 Auth Configs 中已有启用的 ApiKey 时，可以点击 Fetch Models 从服务端获取模型列表；Anthropic Provider 需要先在 Models 页面用 Create model 手动创建模型，再回到 Provider 中勾选。
3. 保存 Provider。勾选的模型由此与 Provider 建立 Model Provider 关联，新获取的模型也会在这时创建。
4. 在 Models 页面用 Edit model 核对模型标识，按服务商公布的限制填写 Context window 和 Maximum output。
5. 在 Agent 中选择该关联，用短问题验证回复。

当前协议类型包括 OpenAI Chat Completions、OpenAI Responses 和 Anthropic。兼容服务也需要匹配具体协议，不能仅凭名称包含 OpenAI 判断可用性。

上下文限制

每个模型都有内容长度限制，填写时需要区分两个值：

• 上下文窗口：一次请求能容纳的内容总量，包括历史对话、当前问题、工具结果以及模型的回复。
• 最大输出 token：模型一次最多能生成多长的回复。token 是模型计算内容长度的单位，不等同于字数。

两个值都必须是正整数，且最大输出必须小于上下文窗口；表单会显示两者之差，即 Effective input budget（有效输入预算）。自定义 Agent 每次调用模型前按这个预算检查要发送的内容：超过 50% 时，较早工具调用的结果正文会从请求中移除；超过 80% 时，较早的消息组会被截断。两个阶段都保留最近 2 组消息，数据库中保存的会话历史不受影响。External Agent 的上下文由外部工具自行管理。

自动发现模型时，AGW 可能填入 256,000（上下文窗口）和 64,000（最大输出 token）作为默认值。这不代表所选模型实际支持这么长的内容，请按模型服务商公布的限制填写。数值设得过大，可能导致请求被拒绝；如果短对话正常、聊久后报错，先核对这两个值，再查看 Server 日志中的具体错误。

成功标志是 Agent 能完成一次对话。凭据无效、地址错误或模型不可用时，先修复连接，再添加工具。不要把真实 API Key 放入共享提示词或 Git 文件。

实现与参考

• Provider UI
• Execution behavior

2 - 创建自定义 Agent

最近更新：2026-09-25

Agent 是一份可重复使用的助手配置：模型决定它如何理解问题，指令说明它要做什么，工具决定它能执行哪些操作。例如，可以分别创建“代码解释助手”和“文档审查助手”，在 Chat 中按任务选择。

开始前，先按模型提供商指南准备可用的 Model Provider。本页介绍由 AGW 运行的自定义 Agent；Claude Code、Codex 和 Pi 请参阅外部 Agent。

创建步骤

1. 打开 Agents，点击 Create。Agent Type 保持 System（自定义 Agent），在 Display Name 中填写能表达职责的名称。
2. 选择 Model Provider，在 Instructions 中写明任务、输入以及预期输出。填写 Display Name 并选择 Model Provider 之前，Create 按钮不可用。
3. 按需在 Tools、Skills、MCP Tool Server、Integrations 和 Environment Variables 标签中配置能力；文件相关能力需要正确的 Project 工作目录。
4. 保存并确认 Agent 已启用，在 Chat 选择它运行一个小任务。

例如，先创建只回答问题的“代码解释助手”，确认模型可用后再加入只读文件能力。提示词不能授予超出实际运行权限的工具访问。

写清 Agent 的职责

指令最好包含任务范围和输出要求。例如，文档审查助手可以使用：

审查我提供的文档，找出难懂、重复或缺少解释的地方。
按“原文、问题、建议改写”列出结果。保留原文中的事实与限制。
无法确认的内容请标出来，不要补写未经证实的功能。

先粘贴一小段文字验证输出。需要它直接读取项目文档时，再添加文件读取工具，并在对应 Project 中运行。能力是否可用取决于实际工具配置和权限，写在指令里的要求本身不会授予访问权。

让回复按 JSON 结构返回

需要由程序读取结果时，在创建或编辑对话框的 Response Schema 中粘贴一个 JSON Schema 对象：

{"type":"object","properties":{"summary":{"type":"string"},"issues":{"type":"array","items":{"type":"string"}}},"required":["summary","issues"]}

保存要求内容是合法 JSON，且根节点为对象；留空表示关闭结构化响应。Anthropic 模型还要求写明 type 为 object、properties 为对象、required 为数组。Schema 会作为响应格式交给模型。自定义 Agent 同时开启“Generate Turn Summary”时，AGW 要求最后一条完整回复中恰好有一个 JSON 对象或数组，否则该回合报错结束；这份 JSON 直接作为本轮 Result，不再调用 Summary Model Provider。

外部 Agent 中，Claude Code 和 Codex 支持该配置；Pi 的 Response Schema 标签显示为不可用，Server 也会拒绝为 Pi 保存 Schema。完整说明见 JSON Schema 结构化响应。

每轮总结

自定义 Agent 可以打开 Generate Turn Summary：每个成功的回合结束后，AGW 用 Summary Model Provider 追加一段 Markdown 总结，作为本轮的 Result。未选择 Summary Model Provider 时使用 Agent 自己的 Model Provider。总结的输入只包含本轮用户文字和 Agent 的回复文字，不加载历史、工具或 Skills。External Agent 不提供这个开关。

开启后，这个 Agent 的回合会产生 Result，Conversation Settings 中的 Only Stream Turn Result 也会对它生效。

修改与复用

Agent 定义修改在下一回合生效，同时保留现有会话身份。活跃回合使用开始时的配置快照，不会在执行中途切换权限或目录。

Agents 列表中的 Copy agent 可以复制任何 Agent。复制 External Agent 时保留 Engine 类型、Model Provider、环境变量、Extra Settings 和 Response Schema，Instructions、Tools、Skills、MCP Tool Server 与 Integrations 不会复制。复制后应检查模型、能力与项目环境再运行。

验证

用一条与职责相符的问题验证输出，并检查工具活动是否只包含预期能力。若没有工具，检查绑定、工具目录以及 Connection 的 Ready 状态；不要用提高权限代替修复缺失配置。

实现与参考

• Agents module
• Runtime lifecycle

3 - 接入外部 Agent

最近更新：2026-09-25

接入外部 Agent 后，任务由 Claude Code、Codex 或 Pi 等外部工具实际执行，AGW 提供统一的配置、对话和工作流入口。你可以继续使用熟悉的外部工具，同时在 AGW 中管理它们的使用方式。

前提：对应 CLI 已安装在实际执行节点，并能在 Server 使用的账号与环境下工作。浏览器里安装 CLI 无效；容器执行需要容器内可用。

同一种外部 Agent，多份独立配置

同一种外部 Agent 可以在 AGW 中创建多份 Agent 定义，每份分别选择模型和配置。例如，都使用 Claude Code 执行任务，但根据用途建立两个 Agent：

创建这两个 Agent 时，都选择 External → Claude Code，再分别选择指向 model1 和 model2 的 Model Provider。这里的模型名称仅为示例，需要替换为服务商实际提供、且兼容 Anthropic 协议的模型。

这样，在 Chat 中选择 Coding 或 Review，就会使用各自配置的模型；也可以在 Agentflow 的不同节点中使用它们。无需为了切换用途反复修改同一份 Agent 配置。

这里的隔离是指 AGW 中各份 Agent 定义的配置独立，不会自动创建独立的操作系统账号或文件环境。如果未选择 Model Provider，模型来自该 Agent 的 Extra Settings 或外部工具自身的模型配置。

配置步骤

1. 先在执行节点验证 CLI 可用，并完成它所需的认证或模型配置。
2. 在 Agents 中点击 Create，Agent Type 选择 External，再选择外部 Agent 类型。类型创建后不能修改。
3. 选择 Project，并确认主工作目录对执行进程可见。
4. 按需选择兼容的 Model Provider；留空时使用 Extra Settings 或外部工具自身配置。需要传给外部工具的其他选项，填写在 Extra Settings 标签的 JSON 对象中。
5. 发送一个简短任务，核对工作目录、输出和权限模式。

Claude Code 和 Codex 通过各自 SDK 的目录选项获得 Project 的附加目录，Pi 通过每一回合的上下文获得目录清单；三者的默认工作目录都是主目录。

配置生效与限制

Chat 的权限下拉框始终列出三种模式，目标不支持的模式显示为不可选并说明原因；服务端也会验证能力。修改权限或 Agent 配置影响下一回合，当前回合保留开始时的配置快照。

在 Chat 中直接运行 External Agent 需要 InProcess 执行模式。Distributed 模式（包括 Control/Data Plane 分离部署）下，这类回合会报错 “Distributed execution currently supports System Agents only.”。

AGW 中的 Instructions、Tools、Skills、MCP Tool Server 和 Integrations 配置都不会交给任何 External Agent（包括 Pi），表单中的这些标签不可编辑；External Agent 只会读到已有的 User Memory 作为上下文。外部工具自身支持什么能力，需要在其环境中配置和验证。

CLI 不可用时检查可执行文件、运行账号、环境变量及服务日志。例如，终端中可运行而 AGW 中无法启动时，先检查 Server 账号的程序搜索路径（PATH）是否包含该 CLI。

实现与参考

• External agent runtime
• Integration limits

4 - Chat 与执行记录

最近更新：2026-09-25

Chat 是向 Agent 或 Agentflow 提交任务、查看结果的地方。同一会话可以连续讨论一个问题，并保留回复和工具活动；不同主题可以新建会话，方便以后查找。

开始前，确认已连接预期的 Server，并有一个可运行的 Agent 或 Agentflow。第一次使用可先完成简单对话。

一次交互

1. 打开 Chat，选择 Project：Desktop 在窗口顶部的项目标签页中选择，Web 在左侧栏顶部的下拉框中选择。然后在输入框左上方的选择器中选择执行目标。
2. 输入任务，按需附加图片，按 Ctrl/Shift+Enter 或点击发送按钮发送；单独按 Enter 换行。
3. 查看流式回复与工具活动；如果出现审批或用户输入请求，在当前会话中处理。
4. 回看会话记录，确认结果与执行状态。

Web、Desktop、Mobile 支持文本和 JPEG、PNG、GIF、WebP 图片。Web 和 Desktop 通过粘贴添加图片，Mobile 从相册选择。每条消息最多 5 张，单张最多 5 MB，总计最多 10 MB。模型是否理解图片还取决于所选模型能力。

输入框中的辅助功能

Quick prompts 页面分为 My prompts（当前用户自己的条目）和 System prompts（所有用户可见，只有管理员可以编辑）。Web 在导航中打开这个页面，Desktop 在 Settings 中打开。

怎样判断任务进行到哪一步

会话列表中的图标显示每个会话的状态：Running 表示仍在运行，Last turn failed 表示上一轮失败，Last turn interrupted 表示上一轮被中断。

回合结束并产生 Result 后，这一回合的工具活动和中间消息会收起为一行 “Worked for …”，点击可以展开查看。模型的推理内容默认收起，点击 Expand reasoning 展开。鼠标移到用户消息或 Result 上时，会显示发送时间和 Copy message 按钮。

“执行成功”表示处理过程成功结束，结果是否满足要求仍需检查。例如，要求修改文档时，应查看实际改动，而不只看 Agent 的完成说明。

会话列表与会话设置

会话列表顶部可以刷新列表、删除全部历史（Delete All History），并通过 Info 按钮打开 Conversation Settings；每个会话可以重命名或删除。

Conversation Settings 显示当前会话的 ID、消息数、创建时间和更新时间，还提供两项设置：

• Only Stream Turn Result：只推送每一回合的 Result，并自动拒绝需要人工处理的提问和工具审批；会话历史仍完整保存。它只对 External Agent 和开启 Generate Turn Summary 的自定义 Agent 生效，从下一回合开始生效。
• Environment Variables：随执行发送的环境变量。

这些设置按 Project 保存在当前客户端中，换一台设备或浏览器需要重新设置。

状态与连接

关闭页面或断开连接通常不会取消执行。InProcess 模式下，如果断线时本轮正在等待审批、用户输入或 HumanGate，Server 会中断本轮；Distributed 模式下断线不会中断执行。需要停止任务时使用界面提供的中断操作。

连接中断时，界面显示 “Reconnecting to Server…” 并自动重试，也可以点击 Retry now 立即重试。重新连接后客户端恢复执行状态；检查任务是否仍在运行、等待输入或已经结束。

Desktop 的每个 Server、Project、Conversation 组合有独立执行连接。切换 Project 页签会改变当前显示的会话，不会自动停止后台任务；项目标签页上的状态点显示后台任务状态，关闭仍有任务运行的标签页前会先确认。

历史

会话与工具活动由服务端持久化，历史采用批量写入。Host 模板将刷新间隔设为 10 秒，省略配置时的代码回退为 5 秒；不要把尚未刷新的实时输出当成已完成持久化。

打开会话时先显示最近的消息，向上滚动时每次加载 50 条较早的消息。Desktop 还提供用户输入导航，列出会话中的每一条用户输入，包括尚未加载的早期输入；点击后跳转到该输入，并按需加载更早的历史。

回合被中断或失败时，未完成的消息和带致命错误的消息仍显示在会话中，但不会进入后续回合的模型上下文，也不会交给切换后的 Agent。

如界面与预期不符，先确认 Server 和会话选择，检查等待输入状态，再看服务日志。工作目录与权限调整会在下一回合生效。

实现与参考

• Conversation persistence
• Execution connections

5 - Projects、文件与工作目录

最近更新：2026-09-25

Project 把一项工作的文件目录、背景资料和会话放在一起。例如，为一个代码仓库创建 Project 后，可以分别建立“阅读代码”和“排查问题”的会话，同时使用同一份工作目录。

运行 AGW Server 的账号必须能够访问这些目录。主工作目录不存在时，保存 Project 会自动创建；附加目录必须是已经存在的绝对路径或 ~ 路径，且不能与其他目录重复。连接远程 Server 时应填写远程主机上的路径；使用 Docker 时应填写容器内的路径。

配置工作空间

1. 创建 Project，填写 Primary directory（主工作目录，必填）。在 Settings 的 Projects 表单中输入名称时，会自动填入 ~/.agw/<项目文件夹名>；Desktop 标题栏新建 Project 时，Workspace (optional) 留空也使用这个路径。
2. 如需同时浏览其他路径，添加 Additional directories。每个关联有稳定 ID；修改路径会生成新 ID。
3. 在 Chat 工作区的 Files 中用目录下拉框切换浏览根，检查文件与 Git 访问，详见文件浏览与 Git 变更审查。
4. 在该 Project 中运行 Agent，验证任务使用预期的主工作目录。

Project 表单还提供 Tools、Skills、MCP Tool Server、Integrations 和 Environment Variables 标签。这里的配置在运行时与自定义 Agent 自身的配置合并，适合放置整个 Project 共用的能力。

切换文件浏览目录不会改变 Agent 的默认工作目录。移除附加目录关联不会删除磁盘文件。网络存储应先通过操作系统或容器挂载，再将挂载后的路径配置为工作目录。

一个主目录与附加目录的例子

假设代码位于 /work/app，参考资料位于 /work/reference：将前者设为 Workspace，将后者添加为附加目录。Files 中可以切换到参考资料目录浏览，但 Agent 默认仍从 /work/app 开始工作。任务需要参考资料时，应说明资料位于哪个目录，并确保 Agent 具备读取能力。

Docker 中需要先把两个目录挂入容器。例如，主机的 /home/me/app 挂载为容器内的 /work/app 后，Workspace 应填写 /work/app。只在表单填写路径不会创建容器挂载。

自定义 Agent 的指令中会列出主目录和每个附加目录，并以目录名作为别名；对话时可以用别名指代某个目录，用 default 指代主目录。

通过 API 创建 Project 时如果不提供工作目录，Server 使用 ~/.agw/projects/{projectId:N}，其中 {projectId:N} 是项目 ID 去掉连字符后的值。

修改何时生效

Project 更新会使本机文件系统缓存失效，文件浏览立即刷新。Agent 在每回合开始时捕获不可变目录快照；目录变更会在下一回合重建运行时并保留会话身份。当前回合、子执行与持久化恢复继续使用已经捕获的路径。

分布式执行的每个节点都必须能看到快照中的相同主机路径。不可用或不属于该 Project 的附加目录会失败，不会自动退回主目录。

排查

文件不存在时，核对当前浏览根、实际挂载、执行账号和 Server 路径。不要只在本地终端验证与 Server 不同的目录。非内置 Project 可以复制。副本会复制 Tools、Skills、MCP Tool Server、Integrations 和环境变量，但主目录改为 ~/.agw/projects/{新 ID:N}，也不带任何附加目录；复制后需要重新设置目录。

实现与参考

• Filesystem resolver
• Directory snapshots

6 - Agentflow

最近更新：2026-09-25

Agentflow 指 Agent Workflow（Agent 工作流），把多个处理步骤连接起来。例如，先由一个 Agent 整理材料，再由另一个 Agent 审查，最后请人确认结果。各步骤的输入、输出和先后关系都可以在画布中查看。

先单独验证每个 Agent 能完成自己的任务，再把它们接成流程。第一版建议只保留一条从输入到输出的路径，验证后再添加分支和审批。

创建第一个流程

1. 打开 Agentflows 编辑器，从唯一的 Input 节点开始。
2. 添加一个 Agent 节点，选择已验证的 Agent，连接 Input 与 Agent。
3. 添加 Output 并连接输出，保存后在 Chat 中选择该 Agentflow 运行。
4. 基础路径通过后，再加入 HumanGate、分支或并行节点。

编辑器画布右上角有 Undo 和 Redo 按钮，也可以使用 Cmd/Ctrl+Z、Cmd/Ctrl+Shift+Z 或 Ctrl+Y；节点面板和 Inspector 可以拖动分隔条调整宽度。存在未保存的修改时，对话框显示 Unsaved changes，关闭前会询问 Discard unsaved changes?；关闭对话框后，未保存的草稿不会保留。

Agentflows 列表中每个流程都有 Enabled 开关，以及 Run、Edit、Copy、View Mermaid chart 和 Delete 操作。Run 在右侧抽屉中打开一个使用内置默认 Project 的 Chat，适合快速试运行；需要在其他 Project 中运行时，在 Chat 中选择该 Agentflow。停用的 Agent 和 Agentflow 不会出现在编辑器的选择列表中。

flowchart LR
    I[Input] --> A[Agent]
    A --> H[HumanGate]
    H --> O[Output]

HumanGate 暂停并等待人工处理。Input 模式显示 Response 输入框和 Submit、Interrupt 按钮，提交的回复可用于下游条件判断；Approval 模式只有 Approve 和 Reject 两个按钮。Interrupt 和 Reject 都会停止流程。

Primitive Nodes（基础节点）

基础节点负责一个明确步骤：接收输入、调用 Agent、调整消息、等待人工处理或输出结果。在画布中选中节点后，在右侧 Inspector 配置其属性，再用连线确定前后关系。

Input：流程入口

Input 将本次用户输入传入流程。例如，在 Chat 中发送“审查这次修改”，这条请求会从 Input 进入下游节点。

每个流程只有一个 Input，ID 固定为 input，不能接收入边。可以从它连向一个节点，也可以通过 Fan Out 将输入分发给多个分支。

Agent：执行一项任务

选择一个已配置的 Agent，并按需填写节点名称和指令，说明它如何处理上游结果。例如，让“代码审查”节点检查上游提交的代码，并列出问题与修改建议。

节点接收上游内容，调用所选 Agent，再把执行结果传给下游。同一个 Agent 定义可以出现在多个节点中，各节点的模型会话历史分别保存；连线会传递任务内容，不会把另一个节点的完整模型会话合并过来。

先单独验证所选 Agent 的模型、工具和工作目录，再接入流程。节点指令也应符合该 Agent 类型支持的配置方式。

Workflow as Agent：复用子流程

通过 Select workflow 选择已有 Agentflow，将它作为一个步骤使用。上游消息成为子流程输入，子流程输出返回主流程，适合复用“收集资料 → 整理摘要”这样的固定过程。

先确认子流程可以独立运行，再将它放入主流程或编排块。流程之间不能形成递归引用，例如 A 调用 B、B 又调用 A；同一个子流程可以在不同分支中复用。

Prompt Adapter：补充处理指令

在 System Prompt / Instructions 中填写下游需要遵循的说明，例如“根据以下材料，按背景、问题、建议三个部分回答”。节点会把这段指令加到当前消息前面，再传给下游。

Prompt Adapter 本身不调用模型，也不会直接完成翻译、摘要或数据转换。要实际生成新内容，需要在后面连接 Agent。

Clear Messages：清除上游消息

Clear Messages 丢弃到达该节点的消息，以空消息继续下游流程，无需配置模型。例如，前一步已经把结果写入项目文件，下一步只需从文件重新读取，就可以用它避免继续携带前一步的大段文本。

它不会删除 Chat 记录，也不会清空下游 Agent 已有的会话历史。下游需要明确的任务指令或可读取的资料，不能再依赖已被丢弃的上游内容。

Human Gate：人工输入或审批

在需要人确认或补充信息的位置插入 Human Gate，并配置：

流程到达这里会暂停，在交互界面等待处理。Input 模式下，人在 Response 中填写回复并点击 Submit 后继续执行，这段回复可以用于下游连线的条件判断；Approval 模式下点击 Approve 继续执行，但不会带上文字回复。Interrupt 和 Reject 都会停止流程。因此，“需要修改”若应返回上游继续处理，应使用 Input 模式，通过人工回复和条件分支表达。

例如：Agent → Human Gate → Output 用于确认结果；也可以根据人工回复中的约定文字选择“修改”或“完成”分支。使用人工节点时，需要能够接收和回应请求的交互通道。

Checkpoint：保存恢复边界

Checkpoint 节点在代码中称为 CheckpointMarker。在 Checkpoint Name 中填写易于辨认的名称，例如“资料收集完成”，并将它放在希望保留执行进度的位置。

经过该节点后，系统在对应执行阶段结束时保存完整工作流检查点。Chat 中每个已保存的检查点显示为一张带 Checkpoint 标记的卡片，点击卡片上的 Resume 从这次保存恢复；检查点不可用时按钮禁用，并提示 “This checkpoint is unavailable”。恢复时选择的是一次具体保存记录，会从该状态创建新的执行分支，并移除当前会话中保存边界之后的记录。

恢复要求仍是同一用户、Project、会话和 Agentflow，流程定义未改变，且没有冲突的执行。单机 InProcess 检查点只在原运行时仍持有该记录时可恢复；Distributed 模式将检查点持久化到 PostgreSQL，可以跨断线或 Server 重启恢复。它不等于数据库备份，也不是任意节点的重新运行按钮。

Output：输出结果与可选总结

Output 将到达它的消息作为流程结果输出。简单流程可直接连接 Agent → Output。

新建的 Output 节点默认打开 Generate Summary，需要在 Summary Model Provider 中选择模型后才能保存；不需要总结时关闭这个开关。启用后会额外调用模型，把流入 Output 的多个结果整理成一份结论，追加在原有结果后；未启用时直接输出收到的消息。

Orchestration Blocks（编排块）

编排块把多个参与者组织成一个步骤，参与者可以是 Agent 或子 Agentflow。四种编排块在节点面板中分别显示为 Concurrent Block、Handoff Group、GroupChat Room 和 Magentic Team。添加编排块后，通过成员选择控件加入参与者；点击 Open 查看块内成员，分别配置名称和职责。主流程的连线连接到编排块，由块内部安排成员执行。

Concurrent：并行处理

加入多个能够独立完成工作的参与者，例如安全审查 Agent 和性能审查 Agent。块会把相同输入交给所有成员并发执行，等待全部完成后，将各自的响应消息合在一起传给下游。

这种合并不会自动消除重复意见或生成统一结论。如需汇总，可以再连接一个 Agent，或启用 Output 的总结。成员之间有先后依赖时，应使用顺序连线；多个成员操作同一批文件时，还需避免互相覆盖。

flowchart LR
    I[Input] --> C
    subgraph C[Concurrent]
        A[Security review]
        B[Performance review]
    end
    C --> S[Summary Agent] --> O[Output]

图中两个审查成员接收相同输入，汇总 Agent 在它们全部完成后处理结果。

Handoff：按需交接

第一个参与者是入口，负责先接收任务，再根据职责交给其他成员。例如，分诊 Agent 判断用户问题属于账单还是技术问题，然后转交对应专家。块完成后，结果继续传给主流程下游。

应为成员写清职责和交接条件，并为自治模式设置合理上限。Handoff 不保证每个成员都会被调用；如果每一步都必须执行，使用主流程的顺序连线更直接。

Group Chat：轮流讨论

加入参与者并确认成员顺序。当前实现按 Round Robin（轮询）顺序安排发言，成员围绕传入的任务轮流贡献结果，达到 Max Rounds 限制后结束。

例如，作者提出方案，审查者指出问题，再由作者修订。Max Rounds 限制调度迭代次数，不要理解成“每个成员都发言这么多次”；未配置时当前实现使用 10。

Group Chat 适合有明确讨论规则的有限轮协作。它不会自动等到所有成员达成共识；需要统一结论时，可以在块后增加总结 Agent。

Magentic：Manager 协调团队

加入参与者，并选择 Manager。未指定时使用第一个参与者，其余成员组成执行团队。Manager 根据输入任务安排计划和成员工作，适合需要在执行过程中调整分工的任务，例如调研后再决定需要哪些补充分析。

为 Manager 写清目标、完成标准及成员职责，并根据任务设置轮次、停滞和重置上限。启用计划确认时，需要可交互的执行入口。Manager 完成协调后，块的输出继续交给主流程下游；任务不保证按固定成员顺序执行，也不保证每个成员都会被调用。

与固定顺序或并行执行相比，这种模式通常需要额外的模型调用来规划和协调。若步骤已经明确，先采用普通节点连线或 Concurrent 更容易检查结果。

Advanced Config JSON：高级配置

Advanced Config JSON 是节点附加设置的 JSON 表示，与右侧的表单控件编辑的是同一份配置。通常先用表单选择成员、填写参数；需要检查或调整完整配置时，再编辑 JSON。

使用双引号，开关写成 true 或 false，数字不加引号；不要添加注释或末尾多余的逗号。这里填写一个对象，例如 {}，而不是整份工作流。名称、Agent 或子流程选择、System Prompt / Instructions 都有独立字段，不放进这个 JSON。

基础节点支持哪些字段

Human Gate 示例：

{
  "humanMode": "approval",
  "humanPrompt": "请确认审查结果，通过后继续。"
}

humanMode 使用 input（补充信息）或 approval（审批）；未填写时，编辑器显示和运行时都按 approval 处理。humanPrompt 是用户看到的提示文字。

Checkpoint Name 在保存的数据中对应：

{ "checkpointName": "资料收集完成" }

Output 的底层配置当前只有一个运行时字段 enableSummary，但 Output 节点不显示 Advanced Config JSON 编辑框，直接使用 Inspector 中的 Generate Summary UI 配置：

• enableSummary: true（新建 Output 节点的默认值）：Output 在主流程成功后，使用所选的 Model Provider 生成一段 Markdown 总结，并追加到最终输出末尾。
• enableSummary: false：Output 原样传递流入的消息，不额外调用模型。字段缺失时，Server 也按 false 处理。

启用总结后，必须同时满足以下条件，否则编辑器中的保存按钮不可用：

1. 在 Output 节点的 Summary Model Provider 中选择有效的模型。
2. 整个流程只能有一个 Output 节点，否则提示 “Summary requires exactly one Output node”。

总结模型接收的是流入该 Output 的消息。编辑器不为 Output 提供 Instructions 输入框。模型选择属于工作流配置，不能通过在节点 JSON 中添加 modelProviderId 或 summaryModelProviderId 来替代；任意其他字段不会增加 Output 能力。

编排块的成员配置

四种编排块都使用 participantNodeIds，值是成员的画布节点 ID，不是 Agent 定义 ID，也不是显示名称。编辑器已提供 Members、Max Rounds、Manager 等控件，编排块不显示 Advanced Config JSON；以下 JSON 说明这些控件保存的格式，不需要手动填写。

下面的 node-a、node-b 是占位示例，使用时必须替换为当前画布中真实的 Agent 或 Workflow as Agent 节点 ID。Concurrent 至少需要一个成员；Handoff、Group Chat 和 Magentic 至少需要两个成员。

Concurrent

只需指定并行成员，没有轮次或 Manager 配置：

{ "participantNodeIds": ["node-a", "node-b"] }

Handoff

{
  "participantNodeIds": ["node-a", "node-b"],
  "handoffInstructions": "由入口成员判断问题类型，需要专业分析时交给另一位成员。",
  "enableReturnToPrevious": true,
  "autonomous": true,
  "autonomousTurnLimit": 6,
  "continuationPrompt": "继续处理尚未完成的任务。"
}

数组中的第一个成员先接收任务。handoffInstructions 描述交接规则；enableReturnToPrevious 允许返回上一成员；autonomous 开启自动继续。后两个字段仅在 autonomous 为 true 时使用，分别指定继续轮次上限和继续时的提示词。两个开关省略时均不开启；数字示例不是默认值。

Group Chat

{
  "participantNodeIds": ["node-a", "node-b"],
  "maxRounds": 6
}

按成员顺序轮流执行。maxRounds 是调度迭代上限，填写正整数；省略时 AGW 使用 10。它不是每个成员分别发言的次数。

Magentic

{
  "participantNodeIds": ["node-a", "node-b"],
  "managerNodeId": "node-a",
  "maxRounds": 10,
  "maxStalls": 3,
  "maxResets": 2,
  "requirePlanSignoff": true
}

managerNodeId 必须是成员列表中的节点 ID，省略时由第一个成员担任 Manager。maxRounds 限制调度轮次，maxStalls 控制无进展状态的容忍次数，maxResets 限制重新规划或重置次数；在编辑器中填写正整数。requirePlanSignoff 控制是否要求确认计划。示例值用于说明格式；省略这些可选限制或确认开关时，采用底层工作流框架的默认行为。

保存前检查

确认成员 ID 存在、字段类型正确，并且参数属于当前节点。高级配置框不是脚本入口，添加任意键也不会自动获得新功能。修改 JSON 后检查 Inspector 中的表单显示是否符合预期，再保存并用小任务验证。

分支条件填写在连线的 Predicate JSON 中；If / Else If 连线不显示 Advanced Config JSON，分支顺序用 Move branch up 和 Move branch down 调整。它们都不放在节点的 Advanced Config JSON 中。

路由与约束

必须恰好有一个 ID 为 input 的 Input，且无入边；可运行节点必须从它可达。节点、边 ID 必须唯一，引用必须有效。

连线决定一个节点结束后，哪些步骤继续执行。在连线的 Edge Type 中选择：

同一来源节点不要混用 Direct、Fan Out 和 If / Else If。例如，If / Else If 只会选择一条分支，却让后续汇合点等待所有分支，就可能一直等不到结果。

工作流允许符合安全规则的受控循环。需要重复处理时，先验证退出条件，再增加嵌套流程、编排块或检查点，避免一次加入太多分支而难以定位问题。

验证与历史

分别测试正常路径、条件不匹配、人工拒绝及需要等待的路径。运行时，Chat 会在当前回合中把每个节点收到的输入显示为单独的输入气泡，并保留上游节点归属，可以据此检查执行顺序。CheckpointMarker 标记完整 MAF 检查点的边界；恢复不是随意从某个节点重新开始。修改流程前保留可工作的版本，查看执行记录确认节点归属。

实现与参考

• Graph contract

• Node and block configuration

• Orchestration block execution

7 - Jobs 定时任务

最近更新：2026-09-25

Job 用于在指定时间自动运行 Agent 或 Agentflow，适合例行检查和定期整理资料。任务要求、所属 Project 和执行时间保存后，Server 会按计划发起执行，并记录每次结果。

先在 Chat 中手动验证同样的任务，确认模型、工具和目录都可用。定时执行期间 Server 必须保持运行；分离部署时，控制面负责调度，数据面负责执行。

配置步骤

1. 在 Jobs 创建任务，在 Project ID 中选择 Project，在 Agent ID 中选择要运行的 Agent 或 Agentflow。没有选择执行目标的任务也能保存，但运行时会失败并进入重试。
2. 写明提示词，选择 Trigger Type 并填写执行时间或触发值。
3. 需要修改任务名称、失败重试次数或启用状态时，点击对话框底部的 Advanced，在 Job Name、Max Retry Count 和 Enabled 中设置。Max Retry Count 默认为 3，任务默认启用；Job Name 留空时自动生成。
4. 首先使用未来的一次性任务验证，确认 Job 日志和项目执行记录符合预期后，再新建一个周期任务。一次性任务成功后会暂停并禁用，之后把它改为周期触发或重新启用，它都不会再次运行。

客户端显示本地时间，但 Cron 按 UTC 计算。不要把过去的 Once 时间当作“立即执行”。Interval 不是正数的“小时:分钟:秒”时长，或 Cron 不是五段时，输入框下方会显示错误，保存按钮不可用；五段但字段取值无效的 Cron 在保存时由 Server 返回 “Invalid cron trigger value”。保存后在任务列表的 Next Run 中核对下一次执行时间。

写一条能独立执行的任务要求

定时任务开始时未必有人补充说明，提示词应交代资料位置、时间范围和输出要求。例如：“读取项目中的本周进展记录，列出已完成事项、未解决问题和下一步建议；缺少记录时明确说明，不要推测。”使用前要为目标 Agent 配好读取能力。

0 1 * * * 表示每天 UTC 01:00，对新加坡或中国标准时间是当天 09:00。保存后在任务列表或详情的 Next Run 中核对下一次执行时间。若设置最多重试 2 次，则本轮最多尝试 3 次：首次执行加两次重试。

执行、重试与暂停

同一 Project 的定时任务串行，不同 Project 可以并行。每次执行都会在该 Project 中新建一个会话，以 Full access 权限运行，并自动拒绝需要人工回答的提问和审批。一次性任务成功后暂停并禁用；周期任务成功后安排下一次执行。失败后在 30 秒后重试，MaxRetryCount 不含首次尝试。重试耗尽后任务暂停并禁用，周期任务也不再安排下一次执行；需要继续运行时，应修正问题后新建任务。

每次执行尝试都会记录时间、结果和错误。禁用任务只阻止后续调度，不会中断正在运行的任务；执行期间编辑或删除可能被拒绝，需要等本次执行结束。调度器会提前读取即将到期的任务，改期后应再次核对任务状态和执行记录。

没有执行时检查初始化、启用状态、下一次运行时间和有效目标。对于写入外部系统的任务，应让操作可重复执行，不能把项目锁视为 exactly-once 保证。

Job Logs：查看每次执行结果

Job Logs 记录一个 Job 的每次执行尝试，用来确认任务是否运行成功、是否发生重试，以及失败原因。它记录执行结果；模型的完整回复和工具活动需要进入 Chat 查看。

打开执行日志

1. 在 Jobs 列表找到任务，点击该行的日志入口，进入 Job Logs。
2. 根据执行时间找到要检查的记录，查看状态、尝试次数和错误信息。
3. 点击该行的 Go to Chat 打开这次执行对应的会话，查看对话和执行内容；这次执行还没有会话记录时，只打开该 Job 所属的 Project。

任务详情中的 Execution Logs 也可以查看尝试记录和错误，Back to Jobs 则返回任务列表。

如何理解字段

例如，同一轮执行先出现 Failed / #1，随后出现 Succeeded / #2，表示首次失败、重试成功。周期任务成功后会重置重试计数，因此后续记录再次出现 #1 是正常现象；应结合时间区分不同轮次。

用日志排查问题

• 没有记录：先检查任务是否启用、是否到达执行时间，以及当前是否仍在运行。日志在尝试结束并记录结果时写入，空列表不一定表示调度没有启动。
• 执行失败：先看 Error，再通过 Go to Chat 检查模型回复和工具活动。连接不到模型、工具执行失败或工作目录不可用时，结合 Server 日志定位原因。
• 日志成功但结果不符合预期：Succeeded 表示执行成功结束，仍需检查实际输出、生成文件或外部操作是否符合任务要求。
• 有失败记录但任务已恢复正常：保留的失败记录不会因后续重试成功而消失，按时间检查后续尝试和任务当前状态。

定时与后台执行

Jobs 可以在指定时间、固定间隔或 Cron 计划下运行 Agent 或 Agentflow，适合周期汇总、例行检查等工作。后台 Agent 能力则用于把子任务交给其他 Agent，并在后续获取结果。

1. 先确认 Project、执行目标和所需工具可以正常工作。
2. 为周期任务创建 Job，填写任务要求和触发时间；需要委派子任务时配置 Background Agents 能力。
3. 在任务记录中查看状态、结果与错误，按实际需要调整计划。

关闭 Chat 页面不会自动取消执行；但 Server 和实际执行节点必须保持运行。后台 Agent 不能停下来等待新的人工审批；无人值守 Job 遇到必须由人回答的问题或 HumanGate 时也无法自动完成。持续运行不代表所有任务都能在服务重启后无缝恢复，恢复能力取决于部署与执行方式。

配置工具与 Skills · 了解记忆能力 · 查看执行状态

实现与参考

• Scheduler

• Job Logs UI

• Attempt outcomes

8 - Tools 与 Skills

最近更新：2026-09-25

工具（Tool）负责具体操作，例如读取文件；Skill 提供完成某类任务的说明、资源和可选工具。为 Agent 选择能力时，先确定任务需要读什么、改什么，再配置相应工具和说明。

以下步骤面向已有自定义 Agent 和 Project 的用户。外部 Agent 的能力需要按其自身支持的方式配置。

添加能力

1. 在 Agent 或 Project 的 Tools 标签中查看可选工具：ToolBlock 卡片显示用途说明、包含的成员工具，可能需要审批时还会显示 Approval 标记；单个工具在下拉列表中显示名称、说明和分类。
2. 在 Skills 管理可用 Skill，阅读其说明与前提。
3. 在 Agent 中绑定本次任务需要的工具和 Skills。
4. 在正确的 Project 中开始新回合，先验证读取类任务，再验证确实需要的写操作。

每个工具显式声明 AgwToolPermission。运行权限由执行管线检查；提示词写“允许”不会跳过权限或资源归属验证。

内置 ToolBlock

File Access 中的 file_access_read、file_access_read_lines、file_access_ls 和 file_access_grep 是只读工具，可以在 Plan 模式中使用；file_access_write、file_access_delete、file_access_replace 和 file_access_replace_lines 需要写入权限。

Local 与 Remote Skill

创建 Skill 时，可以按内容的维护方式选择模式：

Local 中的“本地”指 AGW 服务端，不是浏览器所在的电脑。Remote 表示说明内容来自远程地址，任务仍由 Agent 执行。

1. 在 Skills 中创建 Skill，选择 Local 或 Remote。
2. Local 填写名称和描述，上传含 SKILL.md 的 ZIP 包；Remote 填写 ZIP 下载地址，无需上传文件。AGW 以不带认证信息的 GET 请求下载 Remote 地址，需要登录或 Token 才能访问的地址无法使用。
3. Remote 包中必须恰好有一个 SKILL.md，其中的 YAML 元信息需包含 name、description，正文需包含使用说明。名称和描述由远程文件提供。
4. 保存成功后，在 Agent 或 Project 中选择该 Skill，再用一个相关的小任务验证说明是否可用。

Remote Skill 当前读取包内的说明，不会下载并运行包中的脚本，也不会提供包内其他资源文件。需要这些文件时应选择 Local 模式，并准备好执行环境。

Remote Skill 缓存

AGW 在创建或保存 Remote Skill 时获取内容，并将其缓存到数据库中，缓存有效期为 1 小时。

• 有效期内读取同一个 Skill 时，直接使用缓存，减少重复下载。
• 缓存过期后，在下一次需要读取该 Skill 时重新获取；不是每小时定时下载。
• 远程内容更新后，可以等待缓存过期，或编辑并保存该 Remote Skill 来重新获取内容。
• 刷新失败时会报错，不会延长旧缓存的有效期或继续使用过期内容。先检查服务端能否访问下载地址，以及 ZIP 和 SKILL.md 格式是否正确。

自动刷新时，远程 name 必须与已保存的 Skill 名称一致。若远程改了名称，需要编辑并保存 Skill 以更新定义。缓存刷新也不会改写已经加载到当前对话中的内容，验证新版说明时应让 Agent 重新读取 Skill。

Skill 专属工具

Skill 拥有的工具只通过该 Skill 注册，在运行时绑定 Project，不是全局工具目录条目。没有在全局列表看到它，不代表它不可用。

例如 agw-job 提供 agw_job_list、agw_job_get、agw_job_create、agw_job_update、agw_job_delete。读取在 Plan 模式可用，写入在 Plan 模式禁止。

检查结果

查看工具活动的名称、参数及返回值，确认使用了预期的 Project。能力缺失时检查 Skill 绑定和运行模式；实际需要外部服务时，继续配置 MCP 或 Integrations。

实现与参考

• Tools

• Skill-owned Job tools

• Skill management

• Remote Skill cache

9 - MCP 服务

最近更新：2026-09-25

MCP（Model Context Protocol）是一种让 Agent 使用外部工具的协议。MCP 服务会列出自己提供的操作，AGW 连接后可将这些工具交给自定义 Agent 使用。具体能做什么取决于所连接的服务。

配置前，准备服务提供的启动命令或地址、连接方式，以及所需凭据。模型本身仍在 Model Provider 中配置。

连接路径

1. 在 MCP Tool Servers 页面点击 Add Server，在 Transport Type 中选择 stdio 或 http，按服务要求填写命令或端点与凭据。
2. 本地进程服务需要执行节点能启动对应命令；远程服务需要从执行节点访问。
3. 在列表中点击 Connect and list tools 检查连通性，成功时显示 “N tools available”。确认 Enabled 已打开，停用的服务不会被使用。
4. 在自定义 Agent 或 Project 的 MCP Tool Server 标签中绑定该服务，开启新回合；运行时使用 Agent 和 Project 绑定的全部服务。
5. 检查可发现的工具，使用一个只读操作验证返回内容。

目录、命令和网络都以实际 Server/执行节点为准。远程 Desktop 连接不会使本机安装的 MCP 服务自动出现在 Server 上。

选择连接方式

例如，stdio 命令在个人终端能运行，但 Server 使用另一个账号或运行在容器中时，可能找不到同一个程序。应在 Server 所用环境中检查命令和环境变量。远程地址则需要从执行主机测试连通性。

与 Integrations 的区别

MCP 是工具协议。Integration 是带目录定义、用户配置、凭据和 Connection 生命周期的能力接入方式；Integration 自身也可以通过 MCP 暴露工具。

Plugin MCP 支持 stdio、HTTP 和 SSE 源。向 HTTP/SSE 注入凭据的 Plugin MCP 源必须使用 HTTPS；凭据在调用作用域中解析，不应放进公开 URL 或提示词。

故障排查

运行时无法连接的 MCP 服务会被跳过，Server 日志中记录警告，本回合继续执行；工具名称无效或与其他工具重名时，本回合会报错。stdio 服务启动时，执行时传入的环境变量会覆盖服务配置中的同名变量。

工具未出现时检查绑定、启动命令、可执行文件、网络可达性与凭据。先在相同执行环境确认服务可用，再重试新的 Agent 回合。外部 CLI 的 MCP 配置按其自身机制处理，不等同于 AGW Connection 注入。

实现与参考

• Integrations and MCP
• Agent execution

10 - 配置 Integrations

最近更新：2026-09-25

集成让自定义 Agent 使用已授权的外部服务账号，例如读取 GitHub 中的资料。同一种服务可以配置多个账号，Agent 选择其中一个使用。当前内建目录提供 GitHub。

开始前，准备服务要求的认证资料，并确认该账号可以访问任务需要的资源。

选择服务并配置账号

• Available integrations：可供配置的全局目录定义。
• Configured integrations：当前用户配置好的账号或服务端点。
• Connection：实际选择和绑定的连接实例；同一集成可配置多个账号。

1. 在 Available integrations 的 GitHub 卡片上点击 Configure，完成所选认证方式要求的 setup。GitHub 的 OAuth 需要填写 OAuth App 的 Client ID 和 Client Secret；对话框中显示的 OAuth callback URL 需要登记到 GitHub 的 OAuth App 中。
2. 在目录卡片中对应认证方式的那一行点击 New integration 创建 Connection，填写 Display name 和清晰的 Alias。保存新的 OAuth Connection 后，AGW 会自动打开授权页面。
3. 确认连接状态为 Ready，再将具体连接绑定到 Agent 或 Project。连接卡片上的 Authorize 可以重新授权，Validate 可以重新检查连接。
4. 在自定义 Agent 的新回合执行一个读取操作，核对访问的是预期账号。

Alias 创建后不可修改，并在当前用户内唯一；只能使用小写字母、数字和单个连字符，最多 128 个字符，输入的大写字母会转为小写。Connection 工具名称使用 {alias}__{operation}，便于区分账号。GitHub 连接提供 {alias}__current_user、{alias}__list_repositories 和 {alias}__clone_repository 三个工具，分别用于读取当前账号、列出可访问的仓库，以及把仓库克隆到当前 Project 工作目录。

所有权与凭据

安装设置和 Connection 都属于当前用户。修改接入设置后，当前用户的相关连接需要重新检查；其他用户的连接不受影响。Agent 只能使用属于当前用户且处于 Ready 状态的连接。凭据读取、OAuth 和工具调用都验证所有权。

当前限制

没有远程 Plugin Marketplace 的下载、签名或升级机制；不执行第三方 Plugin Skill 自带脚本；Connection 不注入任何 External Agent（Claude Code、Codex、Pi）。连接变化不应被理解为实时改写已创建的工具列表，修改后使用新回合验证。

实现与参考

• Integrations

11 - Web、Desktop 与 Mobile

最近更新：2026-09-25

前提：Server 已完成初始化。客户端不会替代服务端的模型、文件或执行环境。

使用步骤

1. Web 打开 Server 地址；源码开发时打开端口 3001。
2. Desktop Full 可使用内置 Server。Client 在 Settings → Connections & app 中点击 +（Add remote Server），填写 Name、Server URL 和 API token。远程 Server 使用 http:// 地址时，需要勾选风险确认，说明 API token 和通信内容会在网络上以明文传输。
3. Mobile 配置可从设备访问的 Server 地址与 API Key；设备上的 localhost 通常不是开发电脑。也可以在 Web 的 Settings → Server access 创建 API Key 后点击 Copy config，再在 Mobile 的 Import Web configuration 中粘贴。删除 Mobile 上的 profile 不会撤销 Server 端的 API Key，需要在 Web 中撤销。
4. 创建一个短会话，确认连接目标、Project 与历史记录。

Desktop 以 Chat 为主界面，Projects 和其他管理入口在 Settings 中。Server profile 切换使用独立缓存，修改地址或 API Key 后，会清除旧连接使用的缓存，避免混入其他 Server 的数据。

第三方账号登录

Server 启用身份提供商后，Web 登录页会显示对应的账号按钮，选择后完成验证即可回到原来要访问的页面。Desktop 在 Server 配置中显示“Sign in with …”，系统浏览器完成验证后自动获得 API Key，无需手动粘贴；同一处提供“Sign out”撤销该 API Key。内置的本机 Server profile 处于第三方账号登录模式、且没有可用 API Key 时（例如退出登录或 API Key 过期后），还会显示“Use local administrator”。

Mobile 不支持第三方账号登录，使用手动填写或导入的 API Key。每个第三方账号是一个独立用户，数据与管理员账号分开。配置方法见配置与认证，行为说明见第三方账号登录。

运行差异

Desktop renderer 自用端口 3000，不依赖 Web 开发服务器。Full 的 Server 守护进程在关闭桌面窗口后仍继续运行；默认关闭窗口会缩到托盘。

Mobile 使用 Expo，原生工程由 CNG 生成。当前文档提供源码运行入口，不假设存在应用商店安装包。远程访问建议使用 HTTPS，确保代理允许执行所需的 WebSocket。

实现与参考

• Desktop
• Mobile