猫头虎AI分享｜2025最新构建生产级智能体的12条实践指南

猫头虎AI分享｜2025最新构建生产级智能体的12条指南（12-factor-agents）——如果想构建一个真正好用的生产级AI应用，这是一个值得参考的路径

随着人工智能技术的飞速发展，越来越多的企业和开发者希望将AI应用投入生产环境，以提高效率、优化流程并提升用户体验。然而，构建一个稳定且高效的生产级AI智能体并非易事，它需要遵循一系列经过验证的架构原则和最佳实践。12-factor-agents提供了12条关键指南，帮助开发者在设计AI应用时避免常见陷阱，确保构建出可以应对各种生产环境需求的高质量智能体。

这些原则不仅适用于当前流行的大语言模型（LLM）应用，还能够推动AI系统的可扩展性和易维护性。无论你是初创公司还是正在扩展业务的技术团队，12-factor-agents的框架和最佳实践都能为你提供明确的指导，确保智能体在高负载、复杂场景和多变需求下都能稳定运行。

在本文中，我们将深入探讨12-factor-agents的12条核心原则，逐条解析它们在AI应用中的重要性，并通过具体示例帮助你理解如何在实际开发中实现这些原则，打造一个真正好用且高效的生产级AI应用。

通过本文的学习，你将能够：

• 更清晰地理解如何将自然语言转化为工具调用，优化AI模型的表现。
• 掌握如何管理上下文窗口、设计结构化输出以及控制流程，确保AI智能体在各种场景中都能做出正确的决策。
• 深入了解如何设计无状态的智能体，简化状态管理并提高系统的可靠性与可维护性。

如果你正在开发或计划构建AI智能体，这篇文章将是你不可错过的必读指南。继续阅读，了解如何将这些原则应用到你的AI系统中，助力你的团队在2025年及未来的竞争中脱颖而出。

下面，我们将详细解析每一条原则，并提供可操作的示例，帮助你理解和实施这些最佳实践，打造更可靠、可扩展的AI应用。

猫头虎开源fork项目仓库：https://github.com/MaoTouHU/12-factor-agents

文章目录

• 猫头虎AI分享｜**2025最新构建生产级智能体的12条指南**（12-factor-agents）——如果想构建一个真正好用的生产级AI应用，这是一个值得参考的路径
• • 1. **自然语言到工具调用：将自然语言指令转换为对工具的具体调用**
  • • 详细解析：
    • 关键步骤：
    • 示例代码：
  • 2. **掌控你的提示词：不要依赖框架的默认提示词，自行设计和优化提示词**
  • • 详细解析：
    • 提示词优化：
    • 示例代码：
  • 3. **掌控你的上下文窗口：有效管理上下文窗口，确保LLM 拥有足够的信息进行推理**
  • • 详细解析：
    • 管理上下文窗口的方法：
    • 示例代码：
  • 4. **工具只是结构化输出：将工具视为具有结构化输出的函数，方便LLM解析和使用**
  • • 详细解析：
    • 实现步骤：
    • 示例代码：
  • 5. **统一执行状态和业务状态：将LLM的执行状态与应用的业务状态统一管理**
  • • 详细解析：
    • 统一管理策略：
    • 示例：
  • 6. **通过简单的API启动/暂停/恢复：提供简单的API来控制LLM的执行流程**
  • • 详细解析：
    • 关键设计：
    • 示例API设计：
  • 7. **通过工具调用联系人工：在需要时通过工具调用与人类用户交互**
  • • 详细解析：
    • 设计思路：
    • 示例代码：
  • 8. **掌控你的控制流程：不要完全依赖LLM的自主决策，自行设计和控制应用的流程**
  • • 详细解析：
    • 设计思路：
    • 示例代码：
  • 9. **将错误压缩到上下文窗口：将错误信息压缩到上下文窗口中，方便LLM进行调试和纠错**
  • • 详细解析：
    • 错误处理策略：
    • 示例代码：
  • 10. **小而专注的智能体：构建功能单一且专注的智能体**
  • • 详细解析：
    • 设计思路：
    • 示例代码：
  • 11. **从任何地方触发，满足用户需求：让智能体可以从任何地方触发，方便用户使用**
  • • 详细解析：
    • 设计思路：
    • 示例代码：
  • 12. **将你的代理变成无状态的 Reducer：设计无状态的代理，简化状态管理**
  • • 详细解析：
    • 设计思路：
    • 示例代码：
• 附件📎
• • • 1. **自然语言到工具调用：将自然语言指令转换为对工具的具体调用**
    • 2. **掌控你的提示词：不要依赖框架的默认提示词，自行设计和优化提示词**
    • 3. **掌控你的上下文窗口：有效管理上下文窗口，确保LLM拥有足够的信息进行推理**
    • 4. **工具只是结构化输出：将工具视为具有结构化输出的函数，方便LLM解析和使用**
    • 5. **统一执行状态和业务状态：将LLM的执行状态与应用的业务状态统一管理**
    • 6. **通过简单的API启动/暂停/恢复：提供简单的API来控制LLM的执行流程**
    • 7. **通过工具调用联系人工：在需要时通过工具调用与人类用户交互**
    • 8. **掌控你的控制流程：不要完全依赖LLM的自主决策，自行设计和控制应用的流程**
    • 9. **将错误压缩到上下文窗口：将错误信息压缩到上下文窗口中，方便LLM进行调试和纠错**
    • 10. **小而专注的智能体：构建功能单一且专注的智能体**
    • 11. **从任何地方触发，满足用户需求：让智能体可以从任何地方触发，方便用户使用**
    • 12. **将你的代理变成无状态的 Reducer：设计无状态的代理，简化状态管理**
• 总结

1. 自然语言到工具调用：将自然语言指令转换为对工具的具体调用

在许多AI应用中，用户的指令往往以自然语言的形式表达。智能体需要能够理解并将这些指令转化为计算机可执行的任务。此过程需要一套精准的自然语言处理（NLP）系统以及工具调用机制。

详细解析：

自然语言到工具调用的关键在于构建一个高效的指令解析引擎，它能够根据自然语言的输入，动态选择并调用相应的工具。在实现时，你需要使用LLM来解析指令并通过API与工具系统进行交互。

关键步骤：

示例代码：

import openai

def call_tool_with_natural_language(input_text):
response = openai.Completion.create(
model="gpt-4",
prompt=f"Execute the following task: {input_text}",
max_tokens=100
)
return response.choices[0].text.strip()

# 用户输入：生成一份基于今天数据的报告
result = call_tool_with_natural_language("Generate a report based on today's data")
print(result)

通过这种方式，AI应用能够自动将用户的自然语言指令转换为具体的计算机可执行任务，从而完成复杂的功能。

2. 掌控你的提示词：不要依赖框架的默认提示词，自行设计和优化提示词

LLM框架通常提供一些默认的提示词（prompt），但这些默认设置并不适合所有场景，尤其是在复杂任务中。为了确保模型能够准确高效地执行任务，开发者需要设计和优化自定义的提示词。

详细解析：

精心设计的提示词可以帮助LLM更好地理解任务的目标，确保AI系统在多种场景下表现优秀。例如，对于生成文本的任务，使用具有上下文和目标描述的提示词，能显著提高结果的相关性和质量。

提示词优化：

示例代码：

prompt = "Translate the following text into French: 'Hello, how are you?'"
response = openai.Completion.create(model="gpt-4", prompt=prompt)
print(response.choices[0].text)

通过优化提示词，开发者可以大大提高智能体的推理精度和任务执行质量。

3. 掌控你的上下文窗口：有效管理上下文窗口，确保LLM 拥有足够的信息进行推理

LLM的上下文窗口决定了模型能够处理的最大信息量。要确保AI系统在推理时拥有完整的上下文信息，开发者需要设计有效的上下文管理策略。

详细解析：

在长时间或复杂交互中，智能体需要记住用户的需求和系统的状态，这时上下文窗口就显得尤为重要。上下文窗口的管理需要平衡信息的数量与质量，过多的信息可能导致模型的推理效率下降，而过少的信息可能导致推理不准确。

管理上下文窗口的方法：

示例代码：

# 定义一个动态更新上下文窗口的函数
context_window = []

def update_context_window(new_info):
context_window.append(new_info)
if len(context_window) > 5: # 限制上下文窗口大小
context_window.pop(0)

update_context_window("New instruction: Analyze market trends.")

通过精细的上下文管理，智能体能够始终在有效的信息范围内做出决策，避免信息过载或不足。

4. 工具只是结构化输出：将工具视为具有结构化输出的函数，方便LLM解析和使用

当你在开发智能体时，工具不应当只是一个黑箱系统，而应该是一个结构化输出的函数，便于LLM解析和后续处理。

详细解析：

智能体通过调用工具来执行任务时，工具的输出应该是结构化的，而不是一堆杂乱的数据。通过将工具的输出标准化为JSON等结构化格式，LLM能够更加高效地处理和利用这些数据。

实现步骤：

示例代码：

def tool_output_as_structure(input_data):
# 工具处理的结果以结构化数据形式输出
return {"result": input_data.lower(), "status": "success"}

tool_result = tool_output_as_structure("DATA PROCESSING COMPLETED")
print(tool_result)

通过这种方式，AI应用能够轻松处理和使用不同工具的输出，使得任务处理更加高效。

5. 统一执行状态和业务状态：将LLM的执行状态与应用的业务状态统一管理

在生产级AI应用中，LLM的执行状态与业务状态应该是统一管理的，这能够确保系统的一致性和高效性。

详细解析：

将LLM的执行状态与应用的业务状态整合，可以避免由于状态不一致导致的错误和混乱。通过集中管理状态，开发者可以更好地监控和控制AI系统的执行过程。

统一管理策略：

示例：

# 业务状态与执行状态的同步管理
execution_state = {"status": "idle", "task": None}
business_state = {"user_query": None, "result": None}

def update_execution_state(status, task=None):
execution_state["status"] = status
execution_state["task"] = task

def update_business_state(user_query, result=None):
business_state["user_query"] = user_query
business_state["result"] = result

统一状态管理使得系统能够清晰地了解当前执行的任务和所处的业务场景。

6. 通过简单的API启动/暂停/恢复：提供简单的API来控制LLM的执行流程

在构建生产级的AI应用时，灵活的控制流程是至关重要的。你可能希望在某些时候启动、暂停或恢复AI系统的执行，尤其是在多任务、多用户环境下。通过设计一套简单、直观的API，可以帮助开发者轻松管理和控制系统的执行状态。

详细解析：

在很多场景中，AI的执行需要根据外部条件进行调整。例如，可能会因为资源限制、用户操作或任务优先级的变化而暂停或恢复任务。通过提供启动、暂停、恢复等控制接口，开发者可以动态管理智能体的运行，确保任务的顺利进行。

关键设计：

示例API设计：

from flask import Flask, jsonify

app = Flask(__name__)

execution_state = {
"status": "idle",
"task": None
}

@app.route('/start', methods=['POST'])
def start_execution():
execution_state["status"] = "running"
execution_state["task"] = "Analyzing data"
return jsonify({"status": "Execution started"}), 200

@app.route('/pause', methods=['POST'])
def pause_execution():
execution_state["status"] = "paused"
return jsonify({"status": "Execution paused"}), 200

@app.route('/resume', methods=['POST'])
def resume_execution():
execution_state["status"] = "running"
return jsonify({"status": "Execution resumed"}), 200

if __name__ == '__main__':
app.run(debug=True)

通过这种设计，开发者可以通过REST API快速控制智能体的执行状态，并根据实际需求调整运行流程。

7. 通过工具调用联系人工：在需要时通过工具调用与人类用户交互

虽然AI系统有很强的自主决策能力，但在处理某些复杂任务时，可能仍然需要人类的干预。此时，智能体应该能够通过调用预定的工具与人工用户进行互动，从而获得人工反馈或帮助。

详细解析：

通过工具调用与人工用户进行交互是一种常见的增强AI决策的策略。例如，当智能体遇到无法解答的问题或进行复杂推理时，它可以向指定的人工服务发送请求，并等待人工确认或指导。

设计思路：

示例代码：

def contact_human_for_assistance(task_details):
# 通过API或其他方式通知人工
# 假设这里通过Slack或Email工具发送消息
send_to_slack(f"Need human help for task: {task_details}")
return "Waiting for human input"

response = contact_human_for_assistance("Complex data analysis required")
print(response) # 输出："Waiting for human input"

通过这种方式，AI系统能够在遇到困难时与人工用户保持互动，并确保任务的顺利完成。

8. 掌控你的控制流程：不要完全依赖LLM的自主决策，自行设计和控制应用的流程

尽管LLM具有强大的推理能力，但在某些情况下，开发者应该设计明确的控制流程，避免完全依赖LLM的决策。智能体的任务执行流程应当符合预定的业务逻辑，确保智能体不会做出不符合预期的行为。

详细解析：

智能体的自主决策虽然便捷，但有时可能导致错误或不符合业务需求的行为。通过设计控制流程，开发者可以对智能体的决策进行引导，确保任务按预期进行。控制流程的设计应尽量简洁、明确，并与LLM的推理过程协同工作。

设计思路：

示例代码：

# 控制流程示例
def execute_task_with_control_flow(task_details):
if task_details == "Data Analysis":
# 选择特定流程进行数据分析
return analyze_data(task_details)
elif task_details == "Report Generation":
# 选择特定流程生成报告
return generate_report(task_details)
else:
return "Unknown task"

def analyze_data(task_details):
return "Data analysis complete"

def generate_report(task_details):
return "Report generated"

result = execute_task_with_control_flow("Data Analysis")
print(result) # 输出："Data analysis complete"

通过在控制流程中嵌入明确的任务分类和决策逻辑，开发者能够确保智能体在不同场景下的行为符合预期。

9. 将错误压缩到上下文窗口：将错误信息压缩到上下文窗口中，方便LLM进行调试和纠错

在生产环境中，错误是不可避免的，因此开发者必须设计出有效的错误处理机制。当智能体遇到错误时，错误信息应该被压缩并嵌入上下文窗口，以帮助LLM进行调试和纠错。

详细解析：

错误信息不仅仅是日志记录的工具，它还可以作为上下文的一部分，帮助智能体在后续的推理过程中识别并修复错误。通过将错误信息压缩到上下文窗口中，LLM可以迅速获取到错误的来源，并采取必要的措施进行调整。

错误处理策略：

示例代码：

# 错误信息与上下文窗口结合
context_window = []

def add_error_to_context(error_message):
context_window.append({"type": "error", "message": error_message})
if len(context_window) > 5: # 限制上下文大小
context_window.pop(0)

add_error_to_context("Failed to connect to the database.")
print(context_window) # 输出错误信息作为上下文的一部分

通过将错误信息与上下文窗口结合，开发者可以让智能体更加智能地进行错误识别和修复，提升系统的鲁棒性。

10. 小而专注的智能体：构建功能单一且专注的智能体

在AI系统设计中，小而专注的智能体往往比庞大而复杂的系统更容易管理和优化。每个智能体应专注于完成一个特定的任务，从而避免复杂性导致的潜在问题。

详细解析：

小而专注的智能体不仅更容易开发和维护，还能够在特定领域内发挥更强的作用。通过将复杂的任务分解成多个小型智能体，每个智能体都可以专注于处理自己擅长的部分，最终协同工作完成更大的任务。

设计思路：

示例代码：

# 小而专注的智能体示例
def process_order(order_details):
if order_details['type'] == "food":
return handle_food_order(order_details)
elif order_details['type'] == "electronics":
return handle_electronics_order(order_details)
else:
return "Unsupported order type"

def handle_food_order(order_details):
return "Food order processed"

def handle_electronics_order(order_details):
return "Electronics order processed"

order = {"type": "food", "details": "Pizza"}
result = process_order(order)
print(result) # 输出："Food order processed"

通过小而专注的智能体设计，系统的复杂性得以降低，维护和扩展变得更加容易。

11. 从任何地方触发，满足用户需求：让智能体可以从任何地方触发，方便用户使用

为了提升智能体的可用性和灵活性，智能体应该能够在任何时候、任何地方被触发。这意味着无论是在Web应用、移动端、命令行界面（CLI）、还是其他平台，用户都能够方便地与智能体交互并启动任务。

详细解析：

传统的AI应用通常局限于固定的触发方式（如按钮点击、特定时间任务等），而“从任何地方触发”意味着要设计一个开放的触发机制，让智能体能够在不同环境中响应用户的需求。这种设计提高了应用的灵活性，能够满足各种用户需求，并增强用户体验。

设计思路：

示例代码：

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/trigger-task', methods=['POST'])
def trigger_task():
task_type = request.json.get('task_type')
if task_type == "data-analysis":
return jsonify({"status": "Data analysis started"}), 200
elif task_type == "report-generation":
return jsonify({"status": "Report generation started"}), 200
else:
return jsonify({"status": "Unknown task type"}), 400

if __name__ == '__main__':
app.run(debug=True)

通过这种设计，智能体可以通过POST请求被从不同地方触发。例如，用户在Web界面、API接口、或其他系统中提交任务请求，智能体会根据请求类型执行相应任务。

12. 将你的代理变成无状态的 Reducer：设计无状态的代理，简化状态管理

在复杂的AI应用中，代理（Agent）的状态管理是一个挑战。为了简化开发和提高系统的可维护性，设计无状态的代理（Stateless Agent）成为一种最佳实践。无状态的代理不依赖于内部的长期状态，它们只根据输入数据进行计算并返回结果，从而避免了复杂的状态管理。

详细解析：

无状态的代理可以大大简化AI应用的状态管理问题，特别是在分布式和高并发的环境下。因为无状态的代理不需要维护用户上下文或执行历史，它们可以更加灵活地与其他系统交互，同时减少出错的概率。

设计思路：

示例代码：

def stateless_agent(input_data):
# 无状态的代理：每次调用仅基于输入数据进行处理
processed_data = input_data.lower()
return {"status": "success", "data": processed_data}

# 测试
input_data = "HELLO WORLD"
result = stateless_agent(input_data)
print(result) # 输出：{'status': 'success', 'data': 'hello world'}

通过无状态的设计，智能体避免了复杂的状态存储和管理，只关心当前的输入数据。它能够在任何地方调用，并且每次调用都能得到一致的输出。这种设计非常适合需要高并发和高可靠性的应用场景。

附件📎

为了让您更清晰地理解12-factor-agents的每一条原则，我们可以通过Mermaid和Flowchart的流程图来展示这些概念的结构和执行流程。以下是每个关键点的图形结构设计。

1. 自然语言到工具调用：将自然语言指令转换为对工具的具体调用

在智能体中，自然语言指令需要被解析并转化为工具调用。通过此流程，用户输入的自然语言命令会触发对相应工具的调用。

#mermaid-svg-TG1HnUFROSGlaI1v {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-TG1HnUFROSGlaI1v .error-icon{fill:#552222;}#mermaid-svg-TG1HnUFROSGlaI1v .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-TG1HnUFROSGlaI1v .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-TG1HnUFROSGlaI1v .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-TG1HnUFROSGlaI1v .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-TG1HnUFROSGlaI1v .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-TG1HnUFROSGlaI1v .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-TG1HnUFROSGlaI1v .marker{fill:#333333;stroke:#333333;}#mermaid-svg-TG1HnUFROSGlaI1v .marker.cross{stroke:#333333;}#mermaid-svg-TG1HnUFROSGlaI1v svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-TG1HnUFROSGlaI1v .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-TG1HnUFROSGlaI1v .cluster-label text{fill:#333;}#mermaid-svg-TG1HnUFROSGlaI1v .cluster-label span{color:#333;}#mermaid-svg-TG1HnUFROSGlaI1v .label text,#mermaid-svg-TG1HnUFROSGlaI1v span{fill:#333;color:#333;}#mermaid-svg-TG1HnUFROSGlaI1v .node rect,#mermaid-svg-TG1HnUFROSGlaI1v .node circle,#mermaid-svg-TG1HnUFROSGlaI1v .node ellipse,#mermaid-svg-TG1HnUFROSGlaI1v .node polygon,#mermaid-svg-TG1HnUFROSGlaI1v .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-TG1HnUFROSGlaI1v .node .label{text-align:center;}#mermaid-svg-TG1HnUFROSGlaI1v .node.clickable{cursor:pointer;}#mermaid-svg-TG1HnUFROSGlaI1v .arrowheadPath{fill:#333333;}#mermaid-svg-TG1HnUFROSGlaI1v .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-TG1HnUFROSGlaI1v .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-TG1HnUFROSGlaI1v .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-TG1HnUFROSGlaI1v .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-TG1HnUFROSGlaI1v .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-TG1HnUFROSGlaI1v .cluster text{fill:#333;}#mermaid-svg-TG1HnUFROSGlaI1v .cluster span{color:#333;}#mermaid-svg-TG1HnUFROSGlaI1v div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-TG1HnUFROSGlaI1v :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户输入自然语言指令

解析指令

确定目标工具

调用工具

返回结果

用户获取结果

2. 掌控你的提示词：不要依赖框架的默认提示词，自行设计和优化提示词

为了保证更高的任务执行精度，开发者需要设计自定义的提示词，而不是依赖默认的框架提示。

#mermaid-svg-LAMrs72LOWEjVURS {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-LAMrs72LOWEjVURS .error-icon{fill:#552222;}#mermaid-svg-LAMrs72LOWEjVURS .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-LAMrs72LOWEjVURS .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-LAMrs72LOWEjVURS .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-LAMrs72LOWEjVURS .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-LAMrs72LOWEjVURS .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-LAMrs72LOWEjVURS .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-LAMrs72LOWEjVURS .marker{fill:#333333;stroke:#333333;}#mermaid-svg-LAMrs72LOWEjVURS .marker.cross{stroke:#333333;}#mermaid-svg-LAMrs72LOWEjVURS svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-LAMrs72LOWEjVURS .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-LAMrs72LOWEjVURS .cluster-label text{fill:#333;}#mermaid-svg-LAMrs72LOWEjVURS .cluster-label span{color:#333;}#mermaid-svg-LAMrs72LOWEjVURS .label text,#mermaid-svg-LAMrs72LOWEjVURS span{fill:#333;color:#333;}#mermaid-svg-LAMrs72LOWEjVURS .node rect,#mermaid-svg-LAMrs72LOWEjVURS .node circle,#mermaid-svg-LAMrs72LOWEjVURS .node ellipse,#mermaid-svg-LAMrs72LOWEjVURS .node polygon,#mermaid-svg-LAMrs72LOWEjVURS .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-LAMrs72LOWEjVURS .node .label{text-align:center;}#mermaid-svg-LAMrs72LOWEjVURS .node.clickable{cursor:pointer;}#mermaid-svg-LAMrs72LOWEjVURS .arrowheadPath{fill:#333333;}#mermaid-svg-LAMrs72LOWEjVURS .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-LAMrs72LOWEjVURS .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-LAMrs72LOWEjVURS .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-LAMrs72LOWEjVURS .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-LAMrs72LOWEjVURS .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-LAMrs72LOWEjVURS .cluster text{fill:#333;}#mermaid-svg-LAMrs72LOWEjVURS .cluster span{color:#333;}#mermaid-svg-LAMrs72LOWEjVURS div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-LAMrs72LOWEjVURS :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户输入任务

选择自定义提示词

生成提示词

模型执行

返回任务结果

用户获取结果

3. 掌控你的上下文窗口：有效管理上下文窗口，确保LLM拥有足够的信息进行推理

上下文窗口的管理至关重要，它决定了LLM能否从足够的信息中进行准确的推理。

#mermaid-svg-fCtKDAgnFJZ7DyH6 {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .error-icon{fill:#552222;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .marker.cross{stroke:#333333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .cluster-label text{fill:#333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .cluster-label span{color:#333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .label text,#mermaid-svg-fCtKDAgnFJZ7DyH6 span{fill:#333;color:#333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .node rect,#mermaid-svg-fCtKDAgnFJZ7DyH6 .node circle,#mermaid-svg-fCtKDAgnFJZ7DyH6 .node ellipse,#mermaid-svg-fCtKDAgnFJZ7DyH6 .node polygon,#mermaid-svg-fCtKDAgnFJZ7DyH6 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .node .label{text-align:center;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .node.clickable{cursor:pointer;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .arrowheadPath{fill:#333333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .cluster text{fill:#333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 .cluster span{color:#333;}#mermaid-svg-fCtKDAgnFJZ7DyH6 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-fCtKDAgnFJZ7DyH6 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户输入任务

获取初始上下文

添加新信息到上下文窗口

更新上下文窗口

确保上下文信息完整

LLM推理并生成输出

4. 工具只是结构化输出：将工具视为具有结构化输出的函数，方便LLM解析和使用

工具调用的输出应为结构化数据，便于LLM的后续处理和决策。

#mermaid-svg-hX758LSq7YWxh00W {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-hX758LSq7YWxh00W .error-icon{fill:#552222;}#mermaid-svg-hX758LSq7YWxh00W .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-hX758LSq7YWxh00W .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-hX758LSq7YWxh00W .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-hX758LSq7YWxh00W .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-hX758LSq7YWxh00W .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-hX758LSq7YWxh00W .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-hX758LSq7YWxh00W .marker{fill:#333333;stroke:#333333;}#mermaid-svg-hX758LSq7YWxh00W .marker.cross{stroke:#333333;}#mermaid-svg-hX758LSq7YWxh00W svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-hX758LSq7YWxh00W .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-hX758LSq7YWxh00W .cluster-label text{fill:#333;}#mermaid-svg-hX758LSq7YWxh00W .cluster-label span{color:#333;}#mermaid-svg-hX758LSq7YWxh00W .label text,#mermaid-svg-hX758LSq7YWxh00W span{fill:#333;color:#333;}#mermaid-svg-hX758LSq7YWxh00W .node rect,#mermaid-svg-hX758LSq7YWxh00W .node circle,#mermaid-svg-hX758LSq7YWxh00W .node ellipse,#mermaid-svg-hX758LSq7YWxh00W .node polygon,#mermaid-svg-hX758LSq7YWxh00W .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-hX758LSq7YWxh00W .node .label{text-align:center;}#mermaid-svg-hX758LSq7YWxh00W .node.clickable{cursor:pointer;}#mermaid-svg-hX758LSq7YWxh00W .arrowheadPath{fill:#333333;}#mermaid-svg-hX758LSq7YWxh00W .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-hX758LSq7YWxh00W .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-hX758LSq7YWxh00W .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-hX758LSq7YWxh00W .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-hX758LSq7YWxh00W .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-hX758LSq7YWxh00W .cluster text{fill:#333;}#mermaid-svg-hX758LSq7YWxh00W .cluster span{color:#333;}#mermaid-svg-hX758LSq7YWxh00W div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-hX758LSq7YWxh00W :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

调用工具

工具返回结构化数据

LLM解析结构化数据

进行后续推理和决策

返回最终结果

5. 统一执行状态和业务状态：将LLM的执行状态与应用的业务状态统一管理

LLM的执行状态和业务状态应统一管理，以确保任务按预定流程进行。

#mermaid-svg-JLu4nHMijwIw8aaF {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-JLu4nHMijwIw8aaF .error-icon{fill:#552222;}#mermaid-svg-JLu4nHMijwIw8aaF .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-JLu4nHMijwIw8aaF .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-JLu4nHMijwIw8aaF .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-JLu4nHMijwIw8aaF .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-JLu4nHMijwIw8aaF .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-JLu4nHMijwIw8aaF .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-JLu4nHMijwIw8aaF .marker{fill:#333333;stroke:#333333;}#mermaid-svg-JLu4nHMijwIw8aaF .marker.cross{stroke:#333333;}#mermaid-svg-JLu4nHMijwIw8aaF svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-JLu4nHMijwIw8aaF .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-JLu4nHMijwIw8aaF .cluster-label text{fill:#333;}#mermaid-svg-JLu4nHMijwIw8aaF .cluster-label span{color:#333;}#mermaid-svg-JLu4nHMijwIw8aaF .label text,#mermaid-svg-JLu4nHMijwIw8aaF span{fill:#333;color:#333;}#mermaid-svg-JLu4nHMijwIw8aaF .node rect,#mermaid-svg-JLu4nHMijwIw8aaF .node circle,#mermaid-svg-JLu4nHMijwIw8aaF .node ellipse,#mermaid-svg-JLu4nHMijwIw8aaF .node polygon,#mermaid-svg-JLu4nHMijwIw8aaF .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-JLu4nHMijwIw8aaF .node .label{text-align:center;}#mermaid-svg-JLu4nHMijwIw8aaF .node.clickable{cursor:pointer;}#mermaid-svg-JLu4nHMijwIw8aaF .arrowheadPath{fill:#333333;}#mermaid-svg-JLu4nHMijwIw8aaF .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-JLu4nHMijwIw8aaF .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-JLu4nHMijwIw8aaF .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-JLu4nHMijwIw8aaF .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-JLu4nHMijwIw8aaF .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-JLu4nHMijwIw8aaF .cluster text{fill:#333;}#mermaid-svg-JLu4nHMijwIw8aaF .cluster span{color:#333;}#mermaid-svg-JLu4nHMijwIw8aaF div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-JLu4nHMijwIw8aaF :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

业务状态

执行状态

更新状态

状态同步管理

确保执行与业务状态一致

6. 通过简单的API启动/暂停/恢复：提供简单的API来控制LLM的执行流程

提供API接口来控制任务的执行流程，使得智能体能够在不同的阶段进行启动、暂停或恢复。

#mermaid-svg-epw2dps66I6cOnYM {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-epw2dps66I6cOnYM .error-icon{fill:#552222;}#mermaid-svg-epw2dps66I6cOnYM .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-epw2dps66I6cOnYM .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-epw2dps66I6cOnYM .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-epw2dps66I6cOnYM .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-epw2dps66I6cOnYM .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-epw2dps66I6cOnYM .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-epw2dps66I6cOnYM .marker{fill:#333333;stroke:#333333;}#mermaid-svg-epw2dps66I6cOnYM .marker.cross{stroke:#333333;}#mermaid-svg-epw2dps66I6cOnYM svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-epw2dps66I6cOnYM .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-epw2dps66I6cOnYM .cluster-label text{fill:#333;}#mermaid-svg-epw2dps66I6cOnYM .cluster-label span{color:#333;}#mermaid-svg-epw2dps66I6cOnYM .label text,#mermaid-svg-epw2dps66I6cOnYM span{fill:#333;color:#333;}#mermaid-svg-epw2dps66I6cOnYM .node rect,#mermaid-svg-epw2dps66I6cOnYM .node circle,#mermaid-svg-epw2dps66I6cOnYM .node ellipse,#mermaid-svg-epw2dps66I6cOnYM .node polygon,#mermaid-svg-epw2dps66I6cOnYM .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-epw2dps66I6cOnYM .node .label{text-align:center;}#mermaid-svg-epw2dps66I6cOnYM .node.clickable{cursor:pointer;}#mermaid-svg-epw2dps66I6cOnYM .arrowheadPath{fill:#333333;}#mermaid-svg-epw2dps66I6cOnYM .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-epw2dps66I6cOnYM .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-epw2dps66I6cOnYM .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-epw2dps66I6cOnYM .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-epw2dps66I6cOnYM .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-epw2dps66I6cOnYM .cluster text{fill:#333;}#mermaid-svg-epw2dps66I6cOnYM .cluster span{color:#333;}#mermaid-svg-epw2dps66I6cOnYM div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-epw2dps66I6cOnYM :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户发起API请求

启动任务

任务正在执行

暂停任务请求

任务暂停

恢复任务请求

任务恢复执行

7. 通过工具调用联系人工：在需要时通过工具调用与人类用户交互

智能体可以在遇到困难时，通过工具调用与人工用户进行交互。

#mermaid-svg-yb2QZ1WKBifyShkE {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-yb2QZ1WKBifyShkE .error-icon{fill:#552222;}#mermaid-svg-yb2QZ1WKBifyShkE .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-yb2QZ1WKBifyShkE .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-yb2QZ1WKBifyShkE .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-yb2QZ1WKBifyShkE .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-yb2QZ1WKBifyShkE .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-yb2QZ1WKBifyShkE .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-yb2QZ1WKBifyShkE .marker{fill:#333333;stroke:#333333;}#mermaid-svg-yb2QZ1WKBifyShkE .marker.cross{stroke:#333333;}#mermaid-svg-yb2QZ1WKBifyShkE svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-yb2QZ1WKBifyShkE .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-yb2QZ1WKBifyShkE .cluster-label text{fill:#333;}#mermaid-svg-yb2QZ1WKBifyShkE .cluster-label span{color:#333;}#mermaid-svg-yb2QZ1WKBifyShkE .label text,#mermaid-svg-yb2QZ1WKBifyShkE span{fill:#333;color:#333;}#mermaid-svg-yb2QZ1WKBifyShkE .node rect,#mermaid-svg-yb2QZ1WKBifyShkE .node circle,#mermaid-svg-yb2QZ1WKBifyShkE .node ellipse,#mermaid-svg-yb2QZ1WKBifyShkE .node polygon,#mermaid-svg-yb2QZ1WKBifyShkE .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-yb2QZ1WKBifyShkE .node .label{text-align:center;}#mermaid-svg-yb2QZ1WKBifyShkE .node.clickable{cursor:pointer;}#mermaid-svg-yb2QZ1WKBifyShkE .arrowheadPath{fill:#333333;}#mermaid-svg-yb2QZ1WKBifyShkE .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-yb2QZ1WKBifyShkE .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-yb2QZ1WKBifyShkE .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-yb2QZ1WKBifyShkE .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-yb2QZ1WKBifyShkE .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-yb2QZ1WKBifyShkE .cluster text{fill:#333;}#mermaid-svg-yb2QZ1WKBifyShkE .cluster span{color:#333;}#mermaid-svg-yb2QZ1WKBifyShkE div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-yb2QZ1WKBifyShkE :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

智能体执行任务

遇到复杂问题

调用人工帮助工具

人工反馈

智能体继续执行任务

8. 掌控你的控制流程：不要完全依赖LLM的自主决策，自行设计和控制应用的流程

开发者设计控制流程，避免完全依赖LLM自主决策，确保系统的稳定性。

#mermaid-svg-rcQfC69bH9aLNy8k {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-rcQfC69bH9aLNy8k .error-icon{fill:#552222;}#mermaid-svg-rcQfC69bH9aLNy8k .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-rcQfC69bH9aLNy8k .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-rcQfC69bH9aLNy8k .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-rcQfC69bH9aLNy8k .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-rcQfC69bH9aLNy8k .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-rcQfC69bH9aLNy8k .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-rcQfC69bH9aLNy8k .marker{fill:#333333;stroke:#333333;}#mermaid-svg-rcQfC69bH9aLNy8k .marker.cross{stroke:#333333;}#mermaid-svg-rcQfC69bH9aLNy8k svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-rcQfC69bH9aLNy8k .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-rcQfC69bH9aLNy8k .cluster-label text{fill:#333;}#mermaid-svg-rcQfC69bH9aLNy8k .cluster-label span{color:#333;}#mermaid-svg-rcQfC69bH9aLNy8k .label text,#mermaid-svg-rcQfC69bH9aLNy8k span{fill:#333;color:#333;}#mermaid-svg-rcQfC69bH9aLNy8k .node rect,#mermaid-svg-rcQfC69bH9aLNy8k .node circle,#mermaid-svg-rcQfC69bH9aLNy8k .node ellipse,#mermaid-svg-rcQfC69bH9aLNy8k .node polygon,#mermaid-svg-rcQfC69bH9aLNy8k .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-rcQfC69bH9aLNy8k .node .label{text-align:center;}#mermaid-svg-rcQfC69bH9aLNy8k .node.clickable{cursor:pointer;}#mermaid-svg-rcQfC69bH9aLNy8k .arrowheadPath{fill:#333333;}#mermaid-svg-rcQfC69bH9aLNy8k .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-rcQfC69bH9aLNy8k .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-rcQfC69bH9aLNy8k .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-rcQfC69bH9aLNy8k .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-rcQfC69bH9aLNy8k .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-rcQfC69bH9aLNy8k .cluster text{fill:#333;}#mermaid-svg-rcQfC69bH9aLNy8k .cluster span{color:#333;}#mermaid-svg-rcQfC69bH9aLNy8k div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-rcQfC69bH9aLNy8k :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户输入任务

选择执行流程

控制流程

执行决策

继续执行任务

完成任务

9. 将错误压缩到上下文窗口：将错误信息压缩到上下文窗口中，方便LLM进行调试和纠错

将错误信息加入到上下文窗口，帮助LLM在后续执行时进行错误修正。

#mermaid-svg-9Gc6JZIWI6b5uzHQ {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .error-icon{fill:#552222;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .marker.cross{stroke:#333333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .cluster-label text{fill:#333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .cluster-label span{color:#333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .label text,#mermaid-svg-9Gc6JZIWI6b5uzHQ span{fill:#333;color:#333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .node rect,#mermaid-svg-9Gc6JZIWI6b5uzHQ .node circle,#mermaid-svg-9Gc6JZIWI6b5uzHQ .node ellipse,#mermaid-svg-9Gc6JZIWI6b5uzHQ .node polygon,#mermaid-svg-9Gc6JZIWI6b5uzHQ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .node .label{text-align:center;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .node.clickable{cursor:pointer;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .arrowheadPath{fill:#333333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .cluster text{fill:#333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ .cluster span{color:#333;}#mermaid-svg-9Gc6JZIWI6b5uzHQ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-9Gc6JZIWI6b5uzHQ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

错误发生

压缩错误信息

将错误信息加入上下文

LLM调试和纠错

继续执行任务

10. 小而专注的智能体：构建功能单一且专注的智能体

每个智能体应专注于完成一个特定的功能，避免过度复杂化。

#mermaid-svg-VjVWJV7MZCa5fkmm {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-VjVWJV7MZCa5fkmm .error-icon{fill:#552222;}#mermaid-svg-VjVWJV7MZCa5fkmm .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-VjVWJV7MZCa5fkmm .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-VjVWJV7MZCa5fkmm .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-VjVWJV7MZCa5fkmm .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-VjVWJV7MZCa5fkmm .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-VjVWJV7MZCa5fkmm .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-VjVWJV7MZCa5fkmm .marker{fill:#333333;stroke:#333333;}#mermaid-svg-VjVWJV7MZCa5fkmm .marker.cross{stroke:#333333;}#mermaid-svg-VjVWJV7MZCa5fkmm svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-VjVWJV7MZCa5fkmm .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-VjVWJV7MZCa5fkmm .cluster-label text{fill:#333;}#mermaid-svg-VjVWJV7MZCa5fkmm .cluster-label span{color:#333;}#mermaid-svg-VjVWJV7MZCa5fkmm .label text,#mermaid-svg-VjVWJV7MZCa5fkmm span{fill:#333;color:#333;}#mermaid-svg-VjVWJV7MZCa5fkmm .node rect,#mermaid-svg-VjVWJV7MZCa5fkmm .node circle,#mermaid-svg-VjVWJV7MZCa5fkmm .node ellipse,#mermaid-svg-VjVWJV7MZCa5fkmm .node polygon,#mermaid-svg-VjVWJV7MZCa5fkmm .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-VjVWJV7MZCa5fkmm .node .label{text-align:center;}#mermaid-svg-VjVWJV7MZCa5fkmm .node.clickable{cursor:pointer;}#mermaid-svg-VjVWJV7MZCa5fkmm .arrowheadPath{fill:#333333;}#mermaid-svg-VjVWJV7MZCa5fkmm .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-VjVWJV7MZCa5fkmm .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-VjVWJV7MZCa5fkmm .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-VjVWJV7MZCa5fkmm .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-VjVWJV7MZCa5fkmm .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-VjVWJV7MZCa5fkmm .cluster text{fill:#333;}#mermaid-svg-VjVWJV7MZCa5fkmm .cluster span{color:#333;}#mermaid-svg-VjVWJV7MZCa5fkmm div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-VjVWJV7MZCa5fkmm :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户需求

拆分功能

构建专注的智能体

智能体执行任务

返回结果

11. 从任何地方触发，满足用户需求：让智能体可以从任何地方触发，方便用户使用

智能体应该能够在任何环境中被触发，支持不同的用户需求和接口。

#mermaid-svg-XeFKMeSZ5MP8PTjh {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .error-icon{fill:#552222;}#mermaid-svg-XeFKMeSZ5MP8PTjh .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XeFKMeSZ5MP8PTjh .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .marker.cross{stroke:#333333;}#mermaid-svg-XeFKMeSZ5MP8PTjh svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XeFKMeSZ5MP8PTjh .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .cluster-label text{fill:#333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .cluster-label span{color:#333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .label text,#mermaid-svg-XeFKMeSZ5MP8PTjh span{fill:#333;color:#333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .node rect,#mermaid-svg-XeFKMeSZ5MP8PTjh .node circle,#mermaid-svg-XeFKMeSZ5MP8PTjh .node ellipse,#mermaid-svg-XeFKMeSZ5MP8PTjh .node polygon,#mermaid-svg-XeFKMeSZ5MP8PTjh .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-XeFKMeSZ5MP8PTjh .node .label{text-align:center;}#mermaid-svg-XeFKMeSZ5MP8PTjh .node.clickable{cursor:pointer;}#mermaid-svg-XeFKMeSZ5MP8PTjh .arrowheadPath{fill:#333333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-XeFKMeSZ5MP8PTjh .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-XeFKMeSZ5MP8PTjh .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-XeFKMeSZ5MP8PTjh .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-XeFKMeSZ5MP8PTjh .cluster text{fill:#333;}#mermaid-svg-XeFKMeSZ5MP8PTjh .cluster span{color:#333;}#mermaid-svg-XeFKMeSZ5MP8PTjh div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-XeFKMeSZ5MP8PTjh :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

用户触发任务

通过API触发

智能体执行任务

用户获取结果

任务完成

12. 将你的代理变成无状态的 Reducer：设计无状态的代理，简化状态管理

设计无状态的代理，使得每次执行任务时都不依赖于历史状态，只处理当前输入数据。

#mermaid-svg-qpdBf2HgQclnkcXG {font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-qpdBf2HgQclnkcXG .error-icon{fill:#552222;}#mermaid-svg-qpdBf2HgQclnkcXG .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-qpdBf2HgQclnkcXG .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-qpdBf2HgQclnkcXG .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-qpdBf2HgQclnkcXG .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-qpdBf2HgQclnkcXG .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-qpdBf2HgQclnkcXG .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-qpdBf2HgQclnkcXG .marker{fill:#333333;stroke:#333333;}#mermaid-svg-qpdBf2HgQclnkcXG .marker.cross{stroke:#333333;}#mermaid-svg-qpdBf2HgQclnkcXG svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-qpdBf2HgQclnkcXG .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-qpdBf2HgQclnkcXG .cluster-label text{fill:#333;}#mermaid-svg-qpdBf2HgQclnkcXG .cluster-label span{color:#333;}#mermaid-svg-qpdBf2HgQclnkcXG .label text,#mermaid-svg-qpdBf2HgQclnkcXG span{fill:#333;color:#333;}#mermaid-svg-qpdBf2HgQclnkcXG .node rect,#mermaid-svg-qpdBf2HgQclnkcXG .node circle,#mermaid-svg-qpdBf2HgQclnkcXG .node ellipse,#mermaid-svg-qpdBf2HgQclnkcXG .node polygon,#mermaid-svg-qpdBf2HgQclnkcXG .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-qpdBf2HgQclnkcXG .node .label{text-align:center;}#mermaid-svg-qpdBf2HgQclnkcXG .node.clickable{cursor:pointer;}#mermaid-svg-qpdBf2HgQclnkcXG .arrowheadPath{fill:#333333;}#mermaid-svg-qpdBf2HgQclnkcXG .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-qpdBf2HgQclnkcXG .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-qpdBf2HgQclnkcXG .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-qpdBf2HgQclnkcXG .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-qpdBf2HgQclnkcXG .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-qpdBf2HgQclnkcXG .cluster text{fill:#333;}#mermaid-svg-qpdBf2HgQclnkcXG .cluster span{color:#333;}#mermaid-svg-qpdBf2HgQclnkcXG div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-qpdBf2HgQclnkcXG :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

输入数据

无状态代理处理

返回处理结果

结束任务

通过这些Mermaid流程图，每个原则的工作流程变得更加直观和易于理解。无论是自然语言指令转化为工具调用，还是如何管理上下文窗口，都能通过这些图形帮助读者快速掌握核心概念。在实际应用中，开发者可以通过这些流程图来设计和实现高效的AI应用。

总结

通过遵循12-factor-agents的12条原则，我们能够构建出更加稳定、灵活和高效的生产级AI应用。这些原则不仅适用于LLM应用，还能为所有类型的智能体设计提供指导。在实际开发中，通过将这些原则逐步引入到应用中，开发者可以避免很多常见的陷阱，提升智能体的质量和用户体验。

猫头虎开源fork项目仓库：https://github.com/MaoTouHU/12-factor-agents

以下是每条原则的要点总结：

通过这些最佳实践，开发者可以大大提升AI应用的质量与可维护性，构建出高效且可靠的生产级智能体。希望这些原则和示例对你在AI应用开发过程中有所帮助，让你能够构建出满足用户需求的高质量智能体！