---
title: "给 Agent 原语，而不是替它封装工作流"
author: "Shawn Jiang"
lang: zh
date: 2026-08-28
canonical: https://tplog.dev/zh/essay/give-agents-primitives/
translations:
  en: https://tplog.dev/en/essay/give-agents-primitives/
  ja: https://tplog.dev/ja/essay/give-agents-primitives/
---

# 给 Agent 原语，而不是替它封装工作流

给 Agent 设计 Harness 时，可以从少量清晰的原语开始，让具体工具和工作流随任务出现。

## Agent 改变了封装的成本

没有 AI 时，SDK 通常是一项合理的权衡。它替开发者处理认证、分页、重试和类型转换，把复杂的 API 包装成更容易使用的函数。开发者少写一些代码，也不必了解所有底层细节。

但 Agent 改变了这笔账。

过去，针对一个具体任务编写几十行适配代码，需要占用工程师的时间，所以我们倾向于把常见需求预先封装进 SDK。现在，Agent 可以阅读 API 文档，根据当前任务生成请求，再随手写一个 parser、adapter 或批处理脚本。一次性代码的边际成本已经接近于零。

此时，过度封装反而可能成为限制。

SDK 会替调用者决定对象模型、参数结构、错误处理和调用方式。这些决定可以降低人类的认知负担，却也可能遮蔽服务原本拥有的能力。只要需求超出 SDK 预设的范围，Agent 就不得不绕过封装，或者等待 Harness 再增加一个专用工具。

## 让 Agent 按需生成工具

相比之下，一套文档清楚、行为稳定、状态可见的 API，更像是可以被 Agent 直接使用的材料。Agent 可以按需调用接口，观察返回结果，再在执行循环中生成当前任务缺少的工具：调用 API，检查 response，写一段转换脚本，然后继续下一步。

这个工具不必成为 Harness 的永久组成部分，也不必覆盖未来的所有需求。它只需要解决眼前的问题。等同类操作反复出现、行为已经稳定之后，再把它固化成正式工具也不迟。

因此，Harness 的目标不应该是提前预测 Agent 可能需要的每一种能力，而应该是提供一个足够开放的操作面：少量语义完整的基础操作，清晰且可以直接读取的文档，原始、可观察的输入和输出，一个受控的代码执行环境，以及明确的权限与不可逆操作边界。

## 仍然值得封装的部分

认证签名、速率限制、事务一致性等复杂而稳定的机制，仍然适合封装。需要重新考虑的，是那些为了方便人类编程而预设的对象模型和业务流程，是否还有必要原封不动地交给 Agent。

好的 Harness 提供稳定的原语和安全边界，Agent 再根据当前任务临时造出需要的工具。

当同一种临时工具在多个任务里反复出现，接口和错误处理已经稳定，再把它吸收到 Harness。此前，原语应当保持为能力的直接来源。