AI Agent 的第一课：先定义边界，再赋予能力

示例文章：以下是架构设计练习。本站没有部署 AI 模型或 Agent 后端。

先把任务说清楚

“帮我完成工作”很难被可靠验证，而“从给定文档中提取三个字段，并列出出处”就有明确的输入、输出和结束条件。

在接入模型之前，先写出任务契约，能够避免把流程中的每个不确定环节都交给模型猜测。

工具应该足够小

一个工具最好只承担一个可解释的动作。读取文档与发送邮件是不同权限等级的行为，应当拆开设计，而不是放在一个万能函数里。

type ExperimentResult =
  | { ok: true; output: string }
  | { ok: false; code: 'RATE_LIMITED' | 'UNAVAILABLE'; message: string };

明确的失败结果与成功结果同样重要。界面需要知道什么时候可以重试、什么时候应提示配置缺失，不能把所有异常都伪装成空白回答。

服务边界在哪里

静态网页适合负责输入、显示状态和呈现结果。模型密钥、访问控制、限流与调用预算必须放在服务端。

浏览器中的环境变量会被打包到可下载的代码里，因此带有 PUBLIC_ 前缀的变量只能保存本就可以公开的信息。

为中断和失败留出空间

• 为请求设置超时与取消机制。
• 为每次调用设定输入大小与预算上限。
• 将用户可见错误与内部诊断信息分开。
• 在具有外部影响的动作前保留明确的授权边界。

如何逐步接入

第一阶段先建立一个不可运行但状态明确的实验介绍页。第二阶段部署最小后端接口并验证限流和错误处理。最后再把界面与接口连接起来。

这种分步方式让“规划中”和“可体验”有清楚的区别，也能避免访问者对当前功能形成错误预期。

用结果判断复杂度是否值得

如果一个固定脚本已经能可靠解决问题，就没有必要为了使用 Agent 而使用 Agent。只有当动态决策确实带来价值时，额外的调试、成本与可观测性建设才有意义。