12要素AI代理：构建高效可扩展的AI系统

揭秘构建健壮、可扩展AI代理的12要素：从自然语言转换与提示词掌控，到人机协作与无状态设计。打造可投入生产、真正带来商业价值的AI系统。

AI Agents Automation AI Engineering Prompt Engineering
立即试用 预约演示

什么是高效的AI代理？

在介绍12要素之前，先澄清“AI代理”的含义。它本质上是能够理解自然语言请求、根据上下文做出决策，并通过工具或API执行特定动作，同时保持连贯持续交互的系统。

最强大的代理将语言模型的推理能力与确定性代码的可靠性相结合。但要达成这种平衡，需要精心的设计选择，而这正是12要素所要解决的问题。

构建健壮AI代理的12要素

1. 精通自然语言到工具调用的转换

将自然语言请求转化为结构化工具调用，是代理功能的核心。这让代理能够把“为Terri创建一条750美元的支付链接，用于2月AI Tinkerers聚会”这样的简单命令，转换为规范的API调用。

自然语言到工具调用的转换

图片链接

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

要让这一流程可靠运行，需用确定性代码处理语言模型的结构化输出。始终在执行前验证API负载，防止出错，并确保LLM返回始终如一、易于解析的JSON格式。

2. 完全掌控你的提示词

提示词是你应用与语言模型之间的接口——要像对待一流代码那样对待它们。虽然一些封装提示词的框架看似方便，但往往会掩盖指令如何传递给LLM，使微调变得困难甚至不可能。

因此，要直接、显式地编写和维护提示词：

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    You are a helpful assistant that manages deployments for frontend and backend systems.
    ...
    {{ _.role("user") }}
    {{ thread }}
    What should the next step be?
  "#
}

这样做有诸多优势：

  • 可针对具体场景编写精准指令
  • 能像测试其他代码一样测试和评估提示词
  • 完全透明，清楚LLM实际收到的内容
  • 可根据性能指标灵活迭代

3. 战略设计你的上下文窗口

上下文窗口是LLM的输入，包括提示词、对话历史和外部数据。优化窗口能显著提升性能和Token效率。

上下文工程

图片链接

突破传统消息格式，采用自定义结构以最大化信息密度：

<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"
</list_git_tags_result>

这种做法带来如下好处：

  • 使用紧凑格式减少Token消耗
  • 更好地过滤敏感数据后再传递给LLM
  • 可灵活实验，提升LLM理解力的结构

4. 将工具实现为结构化输出

工具本质上是LLM输出的JSON，用于触发代码中的确定性操作。这为AI决策和执行逻辑间建立了清晰界限。

清晰定义工具Schema：

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

接着编写可靠的LLM JSON输出解析器，用确定性代码执行操作，并将结果反馈到上下文，实现迭代式工作流。

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

许多代理框架将执行状态（如流程当前步骤）与业务状态（如工具调用历史及其结果）分开，这增加了不必要的复杂度。

更优做法是将所有状态直接存储在上下文窗口，通过事件序列推断执行状态：

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

这种统一方式带来：

  • 以唯一数据源简化状态管理
  • 所有历史集中，便于调试
  • 可随时加载线程，轻松恢复
FlowHunt 标志

准备好发展您的业务了吗？

今天开始免费试用，几天内即可看到结果。

申请演示 登录

推进AI代理投入生产

6. 设计支持启动、暂停与恢复的API

面向生产的代理需要与外部系统无缝集成，遇到长时间任务可暂停，待Webhook或其他事件触发后恢复。

实现支持启动、暂停、恢复的API，并在操作间可靠存储状态，可带来：

  • 灵活支持异步工作流
  • 与Webhook及其他系统的清晰集成
  • 中断后可靠恢复，无需重启

7. 通过工具调用实现人机协作

AI代理在高风险决策或模糊场景下，常需人工输入。结构化工具调用让交互无缝衔接：

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}
通过工具联系人工

图片链接

此方法可清晰指定交互类型及紧急程度，支持多用户输入，并结合API实现持久工作流。

8. 控制你的代理流程

自定义控制流程允许你为人工审批暂停、缓存结果或实现限流——让代理行为完全契合你的需求：

代理控制流

图片链接

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

这样可获得：

  • 可中断性，可在人审查前暂停关键操作
  • 灵活定制日志、缓存或摘要逻辑
  • 可靠处理长时间任务

9. 将错误浓缩进上下文，实现自愈

直接在上下文窗口中包含错误信息，可让AI代理从失败中学习并调整策略：

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

为确保效果：

  • 限制重试次数，防止死循环
  • 多次失败后升级为人工处理
  • 错误格式清晰，便于LLM理解问题所在

架构最佳实践

10. 构建小型、专注的代理

小型代理（处理3–20个步骤）可保持上下文窗口简洁，提升LLM性能和可靠性。这带来：

  • 明确边界，每个代理职责清晰
  • 降低代理跑偏风险
  • 单项功能更易于测试与验证
小型专注代理

图片链接

随着LLM不断提升，这些小型代理可逐步扩展范围、保证质量，实现长期可扩展性。

11. 支持多渠道触发

让你的代理可通过Slack、邮件或事件系统触发——满足用户在常用平台的需求。

实现可从多种渠道启动代理并通过相同媒介响应的API，可获得：

  • 更高可用性，集成用户偏好平台
  • 支持事件驱动自动化 工作流
  • 高风险操作支持人工审批流程

12. 设计为无状态Reducer

将代理视为无状态函数，将输入上下文转化为输出动作，简化状态管理，使其更易预测和调试。

无状态Reducer

图片链接

这种理念将代理视为纯函数，无需维护内部状态，带来：

  • 输入确定，输出可预测
  • 可通过上下文历史轻松溯源问题
  • 测试与验证更简单

面向未来的构建

AI代理领域正在飞速发展，但这些核心原则即使模型进化依然适用。从小型、专注的代理出发，遵循这些实践，你就能打造既能解决当下问题、又能快速适应未来变化的系统。

请牢记，最有效的AI代理将语言模型的推理能力与确定性代码的可靠性结合——而12要素正能助你达成这种平衡。

FlowHunt如何应用12要素方法论

在FlowHunt，我们将这些原则付诸实践，开发了自动为客户创建工作流自动化的AI代理。下面介绍我们如何用12要素方法论打造可靠、可投入生产的系统。

常见问题

阿尔西亚是 FlowHunt 的一名 AI 工作流程工程师。拥有计算机科学背景并热衷于人工智能，他专注于创建高效的工作流程，将 AI 工具整合到日常任务中，从而提升生产力和创造力。

阿尔西亚·卡哈尼
阿尔西亚·卡哈尼
AI 工作流程工程师

用FlowHunt构建可扩展AI代理

准备好打造健壮、可投入生产的AI代理了吗？了解FlowHunt的工具，看看12要素方法论如何彻底改变你的自动化。

立即试用 预约演示