8.0
热点
AI SCORE
技术实践2026-08-11 12:40
AI Agent工作区架构设计指南
dev.to · AI#Agent#AI编程#架构设计
Editor brief · 编辑速览
AI Agent需要文件、工具、状态和权限边界的组合，而非更长的prompt。
一个 AI Agent 变得有用，不是因为它有了更长的 prompt，而是因为它有了合适的工作场所：可以检查的文件、可以调用的工具、可以恢复的状态、以及不能忽视的限制。
这正是许多构建者现在正在感受到的转变。聊天机器人负责回答，Agent 负责操作。但如果你只是给一个 Agent 配备一个系统 prompt 和少量 API 工具就把它丢进你的产品，你会很快遇到同样的问题：混乱的上下文、不清晰的权限、难以调试的工具调用，以及在后台悄然上涨的成本。
解决办法不是“更多的自主权”。解决办法是工作区架构。
一个好的 AI Agent 工作区为模型提供了一个受控环境，在其中可以探索、规划、执行、暂停，并留下证据。本指南涵盖：为真实客户存储什么、暴露什么、限定什么、审查什么、以及追踪什么。
AI Agent 工作区是 Agent 进行工作的运行时环境。
可以把它想象成：给一个承包商发一条模糊的 Slack 消息，与给他们一个项目文件夹、访问规则、检查清单、以及提交工作供审查的方式，这两者之间的区别。
工作区决定了模型可以看到什么、修改什么、恢复什么、以及证明什么。
最近的 AI 工具趋势指向一个方向：Agent 正在从聊天框进入工作环境。
新闻和搜索信号表明，人们对以下方面的兴趣日益增长：
开发者们不再只问：“我应该使用哪个模型？”他们开始问：“Agent 应该在哪儿工作？”
这很关键，因为许多生产环境故障是环境故障，而不是纯粹的模型故障。
如果你在为客户构建 AI 功能，工作区不是一个可有可无的附加项。它是控制平面。
一个可用于生产环境的 Agent 工作区有五层。
任务层定义了 Agent 试图做什么。
不要只发送原始的用户 prompt。用户 prompt 通常模糊、带有情绪或缺少上下文。把请求转换成一个系统可以检查的任务对象。
{
"task_id": "task_481",
"tenant_id": "tenant_acme",
"goal": "Create a draft onboarding email sequence from the approved product notes.",
"success_criteria": [
"Use only approved product notes",
"Create 5 emails",
"Include subject lines",
"Do not send emails"
],
"risk_level": "draft_only",
"max_model_cost_usd": 1.25,
"requires_human_approval": false
}
这将一个松散的 prompt 变成了一份合同。
上下文层决定了 Agent 可以读取什么。
这正是许多团队犯第一个大错误的地方。他们要么发送太少的上下文，导致 Agent 靠猜；要么发送太多的上下文，导致 Agent 变慢、变贵，而且更容易被操纵。
使用上下文数据包而不是上下文倾倒。
一个好的上下文数据包包含：
{
"context_packet": {
"summary": "Customer is configuring billing alerts for usage-based plans.",
"sources": [
{
"id": "doc_17",
"type": "help_doc",
"title": "Usage Billing Alerts",
"freshness": "current",
"permission": "tenant_read"
},
{
"id": "ticket_3391",
"type": "support_ticket",
"permission": "user_visible"
}
],
"excluded": ["internal_pricing_notes", "other_tenant_tickets"],
"citation_required": true
}
}
要点不是隐藏有用的信息。要点是让上下文变得有意图。
当 Agent 可以创建和修改产物时，它们工作得更好。
工作区应该提供一个小型文件系统或产物存储，让 Agent 可以：
这对编码 Agent、报告生成器、入职助手、研究 Agent 和数据分析工作流特别有用。
按用途分离文件：
/workspace
/input
product_notes.md
customer_profile.json
/scratch
plan.md
extracted_claims.json
/output
onboarding_sequence.md
/evidence
source_map.json
tool_trace.json
/scratch 文件夹很重要。Agent 需要空间来推理工作，但 scratch 内容不应该自动变成面向客户的输出。
工具层定义了 Agent 可以做什么。
给每个工具包装一份合同；不要给予原始 API 访问。
工具合同应该定义：
TypeScript 风格的合同示例：
type AgentTool<I, O> = {
name: string;
description: string;
risk: "read" | "draft" | "write" | "external";
inputSchema: unknown;
requiresApproval: boolean;
run: (input: I, ctx: ToolContext) => Promise<O>;
};
const createDraftEmail: AgentTool<
{ customerId: string; subject: string; body: string },
{ draftId: string; status: "created" }
> = {
name: "create_draft_email",
description: "Create an email draft. Does not send it.",
risk: "draft",
inputSchema: {
customerId: "string",
subject: "string",
body: "string"
},
requiresApproval: false,
async run(input, ctx) {
await ctx.policy.assertTenant(input.customerId);
return ctx.email.createDraft(input);
}
};
注意措辞："Does not send it." 工具描述应该消除歧义。如果一个工具会写入、发送、删除、支付、邀请、导出或更改权限，要清楚地说出来，并加上门控。
状态层让 Agent 可以恢复。追踪层让人类可以调试。
你不需要永久记录每一个 token。但你确实需要足够的证据来回答：
没有追踪，每一次生产问题都会变成一个谜。
下面是 AI Agent 工作区的一个实用流程：
User request
↓
Task builder
↓
Policy check ── rejects unsafe or unsupported tasks
↓
Context packet builder
↓
Workspace created
↓
Agent explores files and tools
↓
Plan generated
↓
Risk check
↓
Tool execution / draft artifact creation
↓
Approval gate if needed
↓
Final output + evidence summary
↓
Trace stored for audit and improvement
这不是绑定在某个特定框架上的。你可以用自定义编排器、工作流引擎、Agent SDK、无服务器函数、队列或后台 Worker 来构建它。
重要的部分是边界：Agent 不是在你的产品中自由飘浮的。它在有规则的工作区内工作。
文件访问应该是平淡且明确的。
默认拒绝。除非任务构建器包含，否则 Agent 看不到任何文件。
分离 input、scratch、output 和 evidence。不要把原始数据和生成的答案混在一起。
为文件附加权限。工单、发票和内部备注不应该有相同的可见性。
使写入可逆。先起草，再应用。
让工作区过期。不要保留敏感的临时上下文超过必要的时间。
一个常见模式是按任务创建工作区：
/workspaces/{tenant_id}/{task_id}/
然后通过工作区服务强制执行所有读写操作。模型永远不应该收到原始存储桶路径或无限制的文件浏览器。
工具权限应该跟随操作，而不仅仅是用户。
用户可能有权限删除一条记录。但这不意味着 Agent 应该在每个任务中都继承删除访问权。
这个模型保持简单任务快速，同时防止静默损害。
还要添加工具预算：
{
"tool_budget": {
"max_calls_total": 25,
"max_search_calls": 5,
"max_write_calls": 2,
"max_runtime_seconds": 180,
"max_cost_usd": 2.00
}
}
预算不仅仅是为了成本。它们也可以捕获卡住的工作流。
Agent 记忆是有用的，但不应该存储所有东西。把它分成三个桶：
不要让运行记忆静默地变成用户记忆。如果 Agent 学到了长期的东西，要把它作为一个明确的产品决策来对待。添加简单的规则：运行记忆 TTL 短、用户记忆需要同意、默认不含敏感字段、以及不跨租户记忆。
人在回路应该内置到工作区中，而不是事后追加。当任务跨越风险边界时，暂停运行并创建一个包含以下内容的审查数据包：请求的操作、确切的工具输入、预期的副作用、来源证据，以及批准/拒绝/编辑控件。
糟糕的审查 UX 说："Agent 想要继续。批准？"
良好的审查 UX 说："Agent 想要用这些来源向这 142 个用户发送这封邮件，使用这个主题和正文。批准、编辑还是取消？"
审批是一个信任界面，不是一个复选框。
如果你处于早期阶段，从最小可行工作区开始：
这足以从“酷炫 demo”转变为“受控工作流”。
具体的代码会因技术栈而异，但形态不应该变：创建任务、构建限定上下文、附加允许的工具、强制执行预算、记录追踪，并在需要审批时暂停。
削弱 Agent 工作区最快的方法是把软指令当作硬控制来对待。注意这些陷阱：
大多数排名靠前的内容都在解释 Agent 工具、记忆、权限或宽泛的企业架构图。真正缺乏的是实用粘合剂：文件、scratch 空间、任务限定工具、审查数据包、状态和重放如何融入一个开发者实际可以构建的工作区。
在交付 Agent 工作区之前，问自己：
如果这几个问题的答案是“否”，那么 Agent 还没有为生产自主权做好准备。在工作区跟上之前，保持在草稿模式。
下一波有用的 AI 产品不会仅仅靠 prompt 赢得。它会由给 Agent 一个安全、结构化工作场所的构建者赢得。
AI Agent 工作区把一次模型调用转变为一个操作系统环境。它给 Agent 文件、工具、记忆、权限、预算、追踪和人工审查。它也给你的团队提供了同样重要的东西：一种理解当 Agent 成功、失败或请求帮助时发生了什么的方式。
从小处开始：创建任务对象、构建上下文数据包、限定工具、存储追踪，并在外部操作前要求审批。
什么是 AI Agent 工作区？
AI Agent 工作区是一个受控的运行时，Agent 可以在其中读取上下文、使用工具、创建文件、存储状态，并在定义的权限和预算下产生输出。
Agent 工作区和 prompt 有什么不同？
Prompt 告诉模型要做什么。工作区控制 Agent 可以访问什么、可以在哪里写入、可以调用哪些工具、可以花费多少，以及什么时候必须请求批准。
小团队需要 AI Agent 工作区吗？
需要，但它可以很简单。小团队可以从任务对象、上下文数据包、限定工具、追踪日志和外部操作的审批门控开始。这足以减少许多早期生产风险。
Agent 工作区应该存储什么？
存储任务状态、选定的上下文、输入文件、scratch 文件、输出产物、工具调用、模型调用、审批、成本、错误和证据链接。在需要的地方对敏感字段进行脱敏。
Agent 应该继承用户权限吗？
Agent 不应该盲目继承所有用户权限。它们应该根据当前目标、风险等级、租户和审批状态获得任务限定的权限。
如何控制 Agent 工作区成本？
为模型支出、工具调用、重试、运行时间和上下文大小设置预算。按步骤追踪成本，并停止超过预算或停止取得进展的运行。