AGW · 让 Agent 在你的工作空间里协作 on AGW

自定义 Agent

Fri, 25 Sep 2026 00:00:00 +0000

为任务定义自己的 Agent

在 AGW 中，你可以把模型、指令和工具组合成一个可复用的 Agent。它根据任务和上下文作出判断，选择可用工具执行操作，再根据结果继续处理。

Agentflow

Fri, 25 Sep 2026 00:00:00 +0000

把确定的步骤编排成流程

Agentflow 是 Agent Workflow（Agent 工作流）。Agent 负责判断与执行，Agentflow 负责编排路由、执行预先确定的步骤。 你在画布上连接节点，定义先做什么、结果交给谁，以及何时需要人工确认。

AGW 是什么

Fri, 25 Sep 2026 00:00:00 +0000

AGW 是面向个人和小型研发团队的自托管 Agent 工作平台，也可作为 Agent 网关提供服务。它将自定义 Agent、Claude Code、Codex 和 Pi 等外部 Agent 放在统一界面中，围绕项目保留对话与执行记录。

单机与 Docker 部署

Fri, 25 Sep 2026 00:00:00 +0000

Standalone 在一个 Server 中提供管理页面、对话执行和定时任务，适合本机试用或单台主机部署。默认使用 SQLite 保存数据，由当前进程运行任务，无需另行部署数据库服务。

可以使用 Docker 镜像，或自行构建与操作系统及处理器架构匹配的 Portable Server。两种方式都包含 Web 界面；下面先完成本机访问，再说明目录挂载和远程访问。

多 Agent 上下文复用

Fri, 25 Sep 2026 00:00:00 +0000

让不同 Agent 接力

分析需求、编写代码和审查结果可以交给不同 Agent。在同一个 Project 的同一个会话中切换目标时，AGW 会把其他目标新增的公开文字提供给接手的 Agent，减少反复复制背景和解释进度的工作。

开发环境与运行

Fri, 25 Sep 2026 00:00:00 +0000

前提：.NET 10 SDK、Node.js 24、pnpm 12.5.1（版本由 src/clients/package.json 的 packageManager 指定）和 Git。只有构建容器镜像时才需要 Docker Buildx。以下应用命令在 AGW 仓库执行，文档站本身不依赖这些工具链。

模型提供商

Fri, 25 Sep 2026 00:00:00 +0000

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

核心概念

Fri, 25 Sep 2026 00:00:00 +0000

在 AGW 中，模型负责推理，Agent 组织指令和能力，Project 提供工作空间。你可以通过 Chat 与 Agent 交互，也可以用 Agentflow 编排步骤、用 Job 安排执行时间。

模型与 Model Provider

模型相关配置分为三层：

Control/Data Plane 分离部署

Fri, 25 Sep 2026 00:00:00 +0000

分离部署把管理和调度放在 Control Plane（控制面），把任务执行放在 Data Plane（数据面）。需要单独维护执行环境或增加执行节点时，可以采用这种方式；只在一台主机试用时，Standalone更容易配置。

安装与配置 Server

Fri, 25 Sep 2026 00:00:00 +0000

AGW 需要一个持续运行的 Server，以及用来操作它的客户端。首次在本机使用可选 Desktop Full；已有 Server 则选 Desktop Client，或直接使用浏览器。安装后再配置模型服务或外部 Agent，即可开始对话。

创建自定义 Agent

Fri, 25 Sep 2026 00:00:00 +0000

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

架构与模块边界

Fri, 25 Sep 2026 00:00:00 +0000

本页帮助开发者判断一项改动应放在哪个模块、哪一层。AGW 按业务拆分代码，例如 Agents、Projects 和 Jobs；它们可以共享一个部署进程和数据库，但各自负责自己的数据和操作。

图片输入

Fri, 25 Sep 2026 00:00:00 +0000

用图片补充文字

遇到界面问题、设计稿或图表时，可以直接把图片附在消息中，让 Agent 结合图片和文字理解任务。例如，附上错误截图并说明操作步骤，或让支持视觉的模型检查页面布局。

API 与执行协议

Fri, 25 Sep 2026 00:00:00 +0000

AGW 的管理操作和任务执行使用不同接口。创建或查询配置使用普通 HTTP JSON API；持续接收 Agent 回复和状态使用 SignalR 执行连接；对接其他 Agent 系统时可以使用 A2A。

接入前，先准备可访问的开发 Server 和有效的认证身份，例如 API Key 或浏览器登录会话。具体参数以运行实例的 OpenAPI 及所属模块 Contracts 中的类型定义为准，避免照抄与运行版本不一致的请求。

记忆：个人偏好与项目知识

Fri, 25 Sep 2026 00:00:00 +0000

保留值得长期使用的信息

对话可以结束，但工作习惯和项目知识往往需要继续保留。AGW 提供两类 Memory，让 Agent 在后续工作中使用已保存的信息。

接入外部 Agent

Fri, 25 Sep 2026 00:00:00 +0000

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

配置与认证

Fri, 25 Sep 2026 00:00:00 +0000

本页说明 AGW Server 的运行设置：服务地址、数据存放位置、任务执行方式、日志和登录认证。模型、Agent、Project 和集成账号则在管理界面中设置。修改本页配置后，请重启相应的 Server 程序。

Chat 与执行记录

Fri, 25 Sep 2026 00:00:00 +0000

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

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

Plan 与 Execute 模式

Fri, 25 Sep 2026 00:00:00 +0000

先想清楚，再动手

准备修改代码或执行复杂任务时，可以先让 Agent 分析现状和提出方案，再决定是否进入执行阶段。在自定义 Agent 或 Project 上配置 Mode ToolBlock 后，自定义 Agent 支持 Plan 与 Execute 两种工作模式；配置在 Project 上时，该 Project 中运行的自定义 Agent 都会获得这项能力。

开始第一次对话

Fri, 25 Sep 2026 00:00:00 +0000

前提：已完成初始化，可以进入管理界面，并有可用模型提供商的凭据。此流程先创建自定义 Agent，不需要外部 CLI。

1. 准备模型连接

打开模型管理页面，配置下面三项。不同客户端的表单布局可能不同，但需要的信息相同。

扩展 Tools 与 Integrations

Fri, 25 Sep 2026 00:00:00 +0000

扩展前先确定要增加什么：一个具体操作可以写成 Tool，一组任务说明和专属工具可以通过 Skill 提供，需要用户连接外部账号的能力则适合 Integration。

先阅读模块边界，确认能力由哪个模块负责。本页说明放置代码、注册能力和验证调用的顺序；具体声明写法可参考文末的工具示例。

工具扩展路径

手写的 IAgwTool、IContextualTool 和 IToolBlock 实现放在 Agw.Tools，全局目录只扫描这个程序集中的手写工具。业务工具放在所属模块的 Application/Tools，以 Attribute 容器声明或通过 Skill 提供，DTO 放 Contracts/Tools。
引用 Agw.Tools.Abstractions，需要 Attribute 声明时将 Agw.Tools.Generators 作为 Analyzer 引用。
显式声明权限、参数说明和返回类型。独立工具及使用 Attribute 声明的工具容器不能保存会话状态；状态放在 Provider、会话对象或所属存储中。
在所属模块注册所需服务与生成声明。选择通过 Skill 提供，或显式加入全局目录。
验证工具发现、参数、权限、项目绑定和错误映射。

生成器输出元数据、JSON Schema 和直接调用委托。不要加入运行时反射扫描兜底。Skill 工具有两个来源：IAgentSkillRegistration.Tools 提供手写的 IProjectScopedAgwTool 实例，ToolTypes 提供 Attribute 容器类型（由 IAgwToolSet<T> 生成）。它们在执行时绑定 Project，不因注册生成模块就自动进入全局目录。

数据目录、备份与升级

Fri, 25 Sep 2026 00:00:00 +0000

备份需要同时保留 AGW 的配置和记录、加密密钥，以及项目文件。只复制安装目录，或只保存代码仓库，都可能遗漏恢复服务所需的数据。

开始前，确认实际数据库、数据目录和各 Project 工作目录的位置；下面的默认路径仅用于帮助定位，以运行中的配置为准。

JSON Schema 结构化响应

Fri, 25 Sep 2026 00:00:00 +0000

让回复可以被程序读取

Agent 默认返回 Markdown 文本，适合阅读，却不便于程序提取字段。在 Agent 上配置 Response Schema 后，最终回复会按你提供的 JSON Schema 返回一个 JSON 对象，Job、Agentflow 和调用 API 的程序可以直接读取其中的字段。

Projects、文件与工作目录

Fri, 25 Sep 2026 00:00:00 +0000

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

测试与贡献约定

Fri, 25 Sep 2026 00:00:00 +0000

前提：依赖已安装。修改前阅读根目录 AGENTS.md 和 docs/human/ 中的相关规则，保留无关的本地改动。

后端检查

从仓库根运行：

dotnet build Agw.slnx
dotnet test Agw.slnx
dotnet csharpier check .

测试项目使用 xUnit v3，并通过根目录 global.json 使用 Microsoft.Testing.Platform 运行。定位问题时先运行相关测试，例如 dotnet test tests/Agw.Files.Tests。单元和组合测试使用真实实现和纯选项辅助方法，不使用 mock 或 fake 实现。构造 CodexAIAgent 或 ClaudeCodeAIAgent 时会探测 CLI，这类测试作为真实 CLI 测试运行，需要显式启用并确认可执行文件可用，不放进默认测试套件。

工具审批

Fri, 25 Sep 2026 00:00:00 +0000

在操作前确认

Agent 调用工具时，AGW 可以根据权限设置请求你的确认。你可以先查看工具名称和参数，再决定是否继续，适合需要检查文件修改或命令执行的任务。

日志与常见问题

Fri, 25 Sep 2026 00:00:00 +0000

排查时先确定故障发生在哪一步：页面连接、登录、模型调用，还是文件和工具操作。用一个简单任务重现问题，通常比反复重启更容易找到原因。

记录出错的 Server、Project、会话和时间，再查看对应服务日志。分离部署的管理问题主要查控制面日志，任务执行问题主要查数据面日志。

文件浏览与 Git 变更审查

Fri, 25 Sep 2026 00:00:00 +0000

在对话旁边检查 Agent 的修改

Agent 修改代码后，需要确认它改了哪些文件、每处改动是否符合预期。在 Chat 工作区切换到 Files，可以浏览 Project 工作目录中的文件、查看 Git 变更，并把需要调整的地方写成行评论交给 Agent，整个过程无需另开编辑器或终端。

Agentflow

Fri, 25 Sep 2026 00:00:00 +0000

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

多端客户端

Fri, 25 Sep 2026 00:00:00 +0000

在合适的设备上继续工作

AGW 提供 Web、Desktop 和 Mobile 客户端。连接同一个 Server 并使用相应身份后，可以访问自己有权限的项目和服务端保存的会话记录，按场景选择设备。

Jobs 定时任务

Fri, 25 Sep 2026 00:00:00 +0000

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

第三方账号登录

Wed, 23 Sep 2026 00:00:00 +0000

用已有账号进入自己的工作区

部署者在 Server 上启用身份提供商后，登录页会出现“Continue with …”按钮。你用组织账号（例如 Keycloak、Microsoft Entra ID、Google）或 OAuth2 服务（例如 GitHub）完成验证，就能进入 AGW，不需要再记一个管理员密码。

Tools 与 Skills

Fri, 25 Sep 2026 00:00:00 +0000

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

MCP 服务

Fri, 25 Sep 2026 00:00:00 +0000

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

配置 Integrations

Fri, 25 Sep 2026 00:00:00 +0000

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

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

Web、Desktop 与 Mobile

Fri, 25 Sep 2026 00:00:00 +0000

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

客户端	连接方式	适用场景
Web	管理员密码或第三方账号登录得到的会话 Cookie；同源 API 访问	浏览器管理与对话
Desktop	API Key，可手动填写或由第三方账号登录签发，支持多个 Server profile	本机或远程的日常工作空间
Mobile	API Key，可手动填写或导入 Web 生成的连接配置，支持多个 Server profile	移动设备上的对话与项目访问

使用步骤

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

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