如何为编码代理构建企业 API 网关

编码代理不仅仅是另一个 LLM 请求。它可以读取源代码、修改文件、运行 shell 命令、调用工具、打开拉取请求以及在多个模型轮次中继续执行任务。如果执行环境暴露机密或不受限制的网络访问，代理也可以接触这些内容。

这改变了网关问题。普通的 LLM 网关可以验证 API 调用、路由模型、计量令牌并强制执行支出限制。编码代理 API 网关需要这些控制，但它还需要管理模型调用周围的工作负载：存储库访问、沙箱隔离、工具权限、凭据交换、网络出口、审批流程和任务级审核跟踪。

本文定义了企业编码代理控制平面的实用参考架构。它是为跨 IDE、GitHub 工作流程、CLI 工具和托管沙箱推出代理的工程领导者和平台团队编写的。

控制平面边界

网关应位于开发人员、代理运行时、模型提供程序、存储库、MCP 服务器、秘密存储和内部网络之间。它不应仅限于代理聊天完成或模型响应。

实际上，控制平面必须在每个代理任务之前和期间回答七个问题：

• 该代理代表谁或做什么？
• 它可以访问哪些存储库、分支、文件和软件包注册表？
• 允许哪些 shell 命令、MCP 工具和网络目标？
• 可以颁发哪些凭据、出于什么目的以及持续多久？
• 适用哪些型号等级、预算和回合数限制？
• 哪些操作需要人工批准？
• 必须导出哪些跟踪、使用情况和审核记录？

这使得编码代理网关成为更广泛的企业 LLM API基础设施的一部分，但具有不同的执行面。模型调用只是工作负载中的一个步骤。

参考架构

可行的架构有六层：身份、政策、沙箱、凭据代理、模型网关以及审核和使用分类帐。这些层可以使用不同的产品来实现，但职责应保持独立。

1.身份层

身份层为每个代理任务提供一个可以归因、约束和撤销的持久身份。避免共享开发者 API 密钥或通用服务帐户，这会使每项任务看起来都一样。

每项任务至少应包含：

• 参与者：启动任务的用户、服务或自动化。
• 代理界面：IDE 扩展、CLI、GitHub 代理、CI 作业或托管沙箱。
• 存储库范围：组织、存储库、分支和工作目录。
• 环境：开发、测试、登台或生产。
• 团队和成本中心：用于审批、报告和预算执行。
• 任务 ID：跨模型调用、工具调用、Shell 命令和拉取请求活动的稳定标识符。

最强大的模式是使用短期令牌的每个代理或每个工作负载身份。工作负载身份联合在这里很有用，因为代理可以将可信断言交换为短期令牌，而不是携带长期提供者密钥。使用专用主体、精确声明匹配、最小权限以及单独的生产和非生产身份。

2.策略层

策略层是工作负载的决策点。它应该评估的不仅仅是模型访问。即使模型请求本身看起来无害，编码代理也可以通过 shell 命令、MCP 工具、包发布步骤或网络调用造成损害。

政策应涵盖：

• 存储库许可名单和分支限制。
• 读取、写入、测试、提交和拉取请求权限。
• 允许和不允许的 shell 命令类。
• MCP服务器发现、连接和工具调用。
• 出站网络模式：禁用、限制或例外开放。
• 按目的地、用途、环境和生命周期进行秘密访问。
• 模型层、最大轮次、最大工具调用次数和预算限制。
• 危险操作的人工批准要求。

策略决策点应在工具执行之前调用，而不仅仅是在模型调用之前调用。例如，可以允许代理向模型询问迁移计划，但禁止运行生产数据库命令或发布包。

3.沙盒层

沙箱是文件系统、shell、程序包和网络访问的执行边界。应将其视为工作负载环境，而不是便利容器。

实用的细分模型是：

• 低风险只读任务：每个用户或存储库隔离、无机密、网络受限。
• 代码修改任务：隔离的可写工作区、存储库范围的令牌、仅供测试的凭据。
• 基础设施任务：单独的强化沙箱、严格审批、无生产默认设置。
• 与生产相关的任务：罕见、有时限、日志记录较多且与普通开发者代理隔离。

请勿让不相关的代理共享可写文件系统、缓存、凭据或软件包注册表，除非该共享是故意的。共享缓存可以提高速度，但也会造成跨任务污染并使取证分析变得更加困难。

网络出口应该是明确的。有些任务需要包注册表、文档站点、内部工件存储或测试服务。这不需要任意出站访问。尽可能使用受限制的主机白名单，并记录实际目的地。

4.凭证代理

凭证代理将长期存在的秘密保留在沙箱之外。代理不应仅仅因为在开发人员工作流程中运行而接收广泛的云密钥、源代码控制管理员令牌或生产应用程序机密。

代理应仅在政策批准后颁发短期的、限定范围的凭据。对代理的请求应包含任务身份、存储库、目的地、请求的权限和预期操作。

有用的代理模式包括：

• 存储库令牌仅限于一个存储库且有效期较短。
• 包注册表令牌仅限于安装操作，不适用于发布。
• 云凭据仅限于非生产帐户和只读操作。
• 数据库凭据仅限于测试环境。
• 特定工件的签名网址或临时访问授权。

经纪人应拒绝含糊的请求。 “授予此代理 AWS 访问权限”不是一个安全的策略单元。 “允许此任务读取特定暂存对象存储路径 15 分钟”更接近于可治理单元。

5.模型网关

模型网关仍然很重要。编码代理可以通过计划循环、重复文件读取、测试失败、工具输出和重试来生成大量代币。网关应处理身份验证、模型路由、预算执行、使用情况计量和提供商抽象。

对于代理工作负载，添加普通 API 请求可能没有的字段：

• 代理任务 ID。
• 沙盒 ID。
• 存储库和分支。
• 工具调用计数。
• 最大转弯政策。
• 批准状态。
• 风险等级。
• 预期任务类，例如文档更新、测试生成、重构或依赖项升级。

该元数据允许平台团队比较不同任务类型的成本和可靠性，而不是将所有模型使用视为一个无差别的流。它还可以让安全团队识别异常的使用模式，例如文档代理重复调用与基础架构更改相关的调用。

6.审计和使用分类帐

编码代理审核跟踪需要将模型调用与实际操作联系起来。仅使用令牌是不够的。

导出任务跟踪，其中包括：

• 谁启动了任务以及从哪个表面开始。
• 使用了哪些模型提供程序和模型层。
• 令牌使用、延迟、错误和费用估算。
• 触及的存储库、分支和文件。
• 提议、批准、拒绝和执行 Shell 命令。
• MCP 调用服务器和工具。
• 网络目的地已到达或被阻止。
• 请求、颁发、拒绝和过期的凭据。
• 创建拉取请求、提交、评论或问题。
• 最终任务结果：已完成、已放弃、已阻止、已恢复或已升级。

留存需要小心谨慎。跟踪可能包括专有代码、提示、工具输出、错误日志和敏感配置片段。在广泛部署之前决定编辑、采样、访问控制和保留。任何人都无法安全访问的有用跟踪不会对操作有任何帮助。

示例策略：文档更新代理

具体的政策使架构更易于评估。考虑平台工程团队使用的文档更新代理。

代理可以：

• 读取已批准的文档存储库中的文件。
• 创建临时分支。
• 编辑 Markdown、示例和生成的文档。
• 运行示例的文档测试、链接检查和单元测试。
• 使用已批准的模型层和任务预算。
• 打开分配给发出请求的开发人员的拉取请求。
• 调用批准的MCP工具进行存储库搜索和问题查找。

代理不得：

• 访问生产机密。
• 直接推送到默认分支。
• 发布软件包或容器映像。
• 运行基础架构部署命令。
• 连接到任意出站主机。
• 使用特权源代码控制令牌。
• 未经批准即可在最大转弯数后继续。

此政策有意缩小范围。它仍然使代理有用，但它将影响范围限制为审查和回滚非常简单的工作类型。

实施步骤

第 1 步：库存代理表面

列出编码代理可以运行的每个位置：IDE 插件、CLI 工具、GitHub 或 Git 提供程序代理、CI 工作流程、托管沙箱、内部开发人员门户和实验脚本。包括当前非官方的工具。当团队在平台团队拥有控制模型之前找到有用的代理时，影子采用很常见。

第 2 步：定义任务类

按风险和权限对用例进行分组。有用的起始类包括文档更改、测试生成、代码解释、依赖项更新、重构、事件分析、基础架构更改和生产调试。

每个类都应映射到允许的存储库、写入权限、网络访问、工具、机密、模型层和审批规则。

第 3 步：标准化代理身份

要求每个任务都携带参与者、团队、存储库、环境和任务 ID 元数据。如果工具无法直接传递这些字段，请使用可以附加它们的启动器、代理或代理对其进行包装。

第 4 步：在执行之前放置策略

从高价值的实施点开始：存储库写入访问权限、shell 命令、MCP 工具调用、凭据请求、出站网络访问和模型预算。在发现过程中，不强制执行的日志记录很有用，但它不是治理。

第 5 步：将机密移出沙盒

从代理环境中删除静态机密。使用代理或保管库流程来获取短期凭证。按目的地和用途限制凭据，并记录颁发和过期。

第 6 步：导出代理感知遥测数据

将模型使用情况、工具事件、命令批准、存储库活动、凭据颁发和网络事件发送到同一分析平面。目标不仅仅是安全审查。这也是工程和财务团队可以信赖的 AI 使用分析。

第 7 步：逐步推出

默认情况下禁用广泛访问。为选定的组织、存储库或任务类启用代理。从只读和低风险写入工作流程开始，然后在审核日志、成本归因和审批路径正常运行后进行扩展。

事实、建议和预测

事实： 当前的代理平台已经公开了指向此方向的控件。 OpenAI 文档将托管代理工具与沙箱环境分开，并记录文件、包、shell 执行、MCP 服务器和出站网络访问的沙箱控制。 GitHub 记录企业对代理可用性、代理会话、审核事件、MCP 使用情况和编码代理策略的控制。 Anthropic 文档 Claude 用于集中身份验证、使用情况跟踪、成本控制、审核日志记录、模型路由和公司网络路由的代码网关和代理模式。

建议：将编码代理视为受管理的工作负载。使用每个代理或每个工作负载的身份，隔离沙箱，限制工具和网络访问，代理凭证，强制执行预算和轮次限制，以及导出任务级跟踪。将策略置于执行之前，而不仅仅是模型调用之前。

预测：随着采用从个人开发人员转向整个组织范围内的推广，编码代理治理将成为标准的平台工程责任。提供商原生控制仍然有用，但使用多个代理界面和模型提供商的企业将需要一个用于政策、报告和成本归因的规范化层。

权衡

中央网关为安全、平台和财务团队提供一致的控制，但增加了运营责任。拥有网关的团队必须支持通常设计用于直接连接到提供商的开发者工具。

严格的沙箱和网络隔离可以减少影响范围，但它们可能会破坏实际的工作流程。软件包安装、私有注册表、集成测试和内部文档可能都需要网络访问。答案通常是通过可观察性来限制访问，而不是全面禁止网络。

每个代理身份可以改善归因和撤销，但它需要生命周期自动化。手动管理数千个服务帐户或密钥将会失败。

代理秘密可以减少暴露，但代理成为关键的基础设施。像身份验证系统一样对其进行监控，因为失败的凭据颁发可能会停止代理工作流程，而过多的颁发可能会带来安全风险。

详细的跟踪有助于调试和合规性，但它们可能会捕获敏感代码和输出。密文和访问控制不是可选的附加功能。

可行的结论

管理编码代理的实用方法是停止将它们视为具有更大上下文窗口的聊天会话。它们是自主工程工作负载，具有模型访问权限、文件系统访问权限、工具访问权限、存储库访问权限，有时还具有凭据访问权限。

围绕这一现实构建网关。给每个任务一个标识。在运行工具和 shell 命令之前评估策略。隔离沙箱。让长期存在的秘密远离环境。通过受控网关路由模型调用。导出将令牌使用情况与实际工程操作联系起来的跟踪记录。

从小范围入手：一个代理表面、一个低风险任务类、一组存储库、受限的网络访问、无生产机密和任务级审核日志。仅当控制平面可以显示谁做了什么、使用了哪些工具、花费了多少以及发生了什么变化时才进行扩展。

常见问题解答

编码代理API网关与 LLM 网关相同吗？

不。 LLM 网关控制模型访问、路由、使用和成本。编码代理 API 网关还管理模型周围的执行环境：存储库、shell 命令、MCP 工具、凭据、网络访问、沙箱、批准和任务跟踪。

每个编码代理都应该拥有自己的API密钥吗？

不一定是长期有效的密钥。更强的模式是按代理或按工作负载身份，并通过代理或工作负载身份流颁发短期凭证。重要的要求是任务或工作负载级别的归属和撤销。

政策执行应在哪里进行？

应在模型调用之前和工具执行之前强制执行政策。存储库写入、shell 命令、MCP 调用、凭据请求、包发布和出站网络访问都需要策略检查。

什么是最安全的首次部署？

从只读或低风险写入任务开始，例如文档更新或测试生成。使用受限制的存储库、无生产密钥、有限的模型预算、受控的网络访问以及合并前的拉取请求审核。

相关阅读

• 代理工作负载的网关级支出限制