精读 12 条构建生产级 AI Agent 的实战指南（上）

引言

我在过去一年里构建了十几个不同类型的 Agent 应用。期间踩了无数坑：Agent "失忆"、工具调用失败、提示词效果不稳定等等问题

直到我看到了 HumanLayer 团队总结的"12 条构建可靠 AI 应用的实践原则"，很多困扰我的问题终于有了系统性的解决方案。它们可能会让你的 Agent 能力提升 10 倍。

12 条实践原则

1. 使用自然语言调用工具

Agent 构建最常见的模式就是将自然语言转成结构化的工具调用。

想象一下，我们对 AI 说 创建 750 美元的付款给小明的链接，用于赞助二月份聚会的费用。
LLMs 会转成结构化的数据

{
  "function":{
    "name":"create_payment_link",
    "parameters":{
      "amount":750,
      "customer":"cust_128934ddasf9",
      "product":"prod_8675309",
      "price":"prc_09874329fds",
      "quantity":1,
      "memo":"赞助二月份聚会的付款链接"
    }
}
}

这就是 Agent 构建的核心：自然语言到结构化调用的转换。

2. 定义自己的提示词

我们应该使用自己的提示词，而不是让框架自己来包装提示词。

很多框架提供了“黑盒”方法：

agent = Agent(
  role="...",
  goal="...",
  personality="...",
  tools=[tool1, tool2, tool3]
)

task = Task(
  instructions="...",
  expected_output=OutputModel
)

result = agent.run(task)

这种方式适合入门，但是很难调整，你根本不知道框架背后到底在说什么。

我们应该把提示词作为一等公民来对待，下面是一段比较粗糙但直观的示例

# 系统提示词
你是一名【主要功能】的【角色】。

你的执行流程是
- 【步骤1】
- 【步骤2】

你可以使用【Tool1】【Tool2】

# 用户提示词

【用户的输入】

使用自己的提示词带来的好处：

• • 完全控制：准确编写提示词，极大的灵活性，可以自由尝试和调整
• • 测试评估：可以像测试代码一样测试提示词
• • 迭代：根据效果随时调整
• • 支持多种框架：换框架也能直接用

3. 定义自己的上下文

和 LLMs 聊天，本质上就是在说“这是目前的情况，下一步要做什么”。

这是目前的情况 就是我们的上下文。通常包括：

• • 系统提示词
• • 检索的文档或者外部数据（RAG）
• • 历史记录和工具调用结果
• • 从其他聊天记录中提取的关键信息（记忆）
• • 输出格式说明

大多数框架会生成标准格式的上下文：

[
  {
    "role":"system",
    "content":"你是一个乐于助人的助手..."
},
{
    "role":"user",
    "content":"你能部署后端吗？"
},
{
    "role":"assistant",
    "content":null,
    "tool_calls":[
      {
        "id":"1",
        "name":"list_git_tags",
        "arguments":"{}"
      }
    ]
},
{
    "role":"tool",
    "name":"list_git_tags",
    "content":"{\"tags\": [{\"name\": \"v1.2.3\", \"commit\": \"abc123\", \"date\": \"2024-03-15T10:00:00Z\"}.....]}",
    "tool_call_id":"1"
}
]

但你可以设计更高效的自定义格式，最大化模型性能。（还是那句话，完全自己控制，获得极大的灵活性）

[
  {
    "role":"system",
    "content":"你是一个乐于助人的助手..."
},
{
    "role":"user",
    "content": |
      以下是截至目前发生的所有事件:

      <slack_message>
        From: @alex
        Channel: #deployments
        Text: Can you deploy the backend?
      </slack_message>

      <list_git_tags>
        intent:"list_git_tags"
      </list_git_tags>

      <list_git_tags_result>
        tags:
          - name:"v1.2.3"
            commit:"abc123"
            date:"2024-03-15T10:00:00Z"
          - name:"v1.2.2"
            commit:"def456"
            date:"2024-03-14T15:30:00Z"
          - name:"v1.2.1"
            commit:"ghi789"
            date:"2024-03-13T09:15:00Z"
      </list_git_tags_result>

      下一步是什么？
    }
]

自定义的格式可以更节省 Token、更有利于模型注意力分配的方式传递信息，从而提升性能。你可以使用更适合你应用的格式，而不是局限于 XML。

自定义格式的核心优势：

• • 信息密度高：LLMs 理解起来更轻松
• • 错误处理：有助于 LLMs 理解错误从中恢复，也可以在后续动作隐藏错误信息（避免冗余）
• • 安全性：根据需要过滤敏感信息
• • 灵活性：根据使用情况自由调整格式
• • 节省Token：优化上下文可以节省 Token，提高 LLMs 的理解

4. 工具调用只是结构化的输出

很多人把工具调用想得很复杂，其实就三步：

• • LLMs 输出结构化的内容（可能是 JSON，也可以是其他结构化格式）
• • 执行确定性的代码（本地命令执行、API 调用等等）
• • 将执行的结果返回到上下文中

输出格式不一定要是JSON。，JSON 格式太严格，LLM 可能输出语法有问题的 JSON，其他任何结构化（XML、YAML等）的我们能够解析的格式都可以。

拓展阅读：Schema-Aligned Parsing^[1] 、When should I use function calling, structured outputs or JSON mode?^[2]

5. 统一执行状态和业务状态

传统软件开发习惯分离执行状态（当前步骤、等待、重试）和业务状态（数据、消息）。但在AI应用中，这样做可能过度复杂。LLM可以通过上下文自动推断所有状态。

统一管理的好处：

• • 简洁性：只有一个数据源
• • 序列化：整个对话历史可以轻松保存和恢复
• • 调试：所有历史记录都集中在一处，容易排查问题
• • 灵活性：只需定义新的事件类型，就能轻松扩展 Agent 的状态和能力
• • 可恢复性：只需加载历史记录即可从任意节点恢复运行
• • 可分叉：可以随时复制部分历史记录到一个新的上下文中，轻松创建分支
• • 人机界面与可观测性：将事件历史转换为可读的格式（如 Markdown）或富文本 UI 界面变得非常简单

6. 实现启动、暂停、恢复

把AI Agent想象成普通程序，提供标准的控制接口：

• • 启动 (Launch)：开始执行任务
• • 暂停 (Pause)：临时停止，保存状态
• • 恢复 (Resume)：从中断处继续

这些能力特别适用于：

• • 长时间运行的任务
• • 需要人工审核的操作

比如，Agent 想执行某个脚本时，可以暂停让人类检查修改，然后继续执行。