自定义提示

为何要自定义提示？

虽然 CrewAI 的默认提示在许多场景下都表现良好，但低级自定义为实现更灵活、更强大的代理行为打开了大门。以下是您可能希望利用这种更深层次控制的原因：

为特定 LLM 优化 – 不同的模型（如 GPT-4、Claude 或 Llama）在针对其独特架构量身定制的提示格式下会表现得更好。
更改语言 – 构建专门使用英语以外的语言运行的代理，并能精确处理其中的细微差别。
针对复杂领域进行专门化 – 调整提示以适应高度专业化的行业，如医疗、金融或法律。
调整语气和风格 – 使代理变得更正式、休闲、富有创意或更具分析性。
支持超级定制化用例 – 利用高级提示结构和格式来满足复杂、特定项目的需求。

本指南将探讨如何在较低级别上利用 CrewAI 的提示，让您对代理的思考和交互方式进行精细控制。

理解 CrewAI 的提示系统

在底层，CrewAI 采用了一个模块化的提示系统，您可以对其进行广泛的自定义：

代理模板 – 控制每个代理执行其指定角色的方式。
提示片段 – 控制专业行为，如任务、工具使用和输出结构。
错误处理 – 指导代理如何响应失败、异常或超时。
工具特定提示 – 定义关于如何调用或使用工具的详细说明。

请查看 CrewAI 仓库中的原始提示模板，了解这些元素是如何组织的。您可以根据需要覆盖或调整它们，以解锁高级行为。

理解默认系统指令

生产透明度问题：CrewAI 会自动向您的提示中注入您可能不知道的默认指令。本节将解释底层发生了什么以及如何获得完全控制。

当您使用 `role`、`goal` 和 `backstory` 定义一个代理时，CrewAI 会自动添加额外的系统指令来控制格式和行为。理解这些默认注入对于需要完全提示透明度的生产系统至关重要。

CrewAI 自动注入了什么

根据您的代理配置，CrewAI 会添加不同的默认指令：

对于没有工具的代理

"I MUST use these formats, my job depends on it!"

对于有工具的代理

"IMPORTANT: Use the following format in your response:

Thought: you should always think about what to do
Action: the action to take, only one name of [tool_names]
Action Input: the input to the action, just a simple JSON object...

对于结构化输出 (JSON/Pydantic)

"Ensure your final answer contains only the content in the following format: {output_format}
Ensure the final output does not include any code block markers like ```json or ```python."

查看完整的系统提示

要确切了解发送给 LLM 的提示是什么，您可以检查生成的提示：

from crewai import Agent, Crew, Task
from crewai.utilities.prompts import Prompts

# Create your agent
agent = Agent(
    role="Data Analyst",
    goal="Analyze data and provide insights",
    backstory="You are an expert data analyst with 10 years of experience.",
    verbose=True
)

# Create a sample task
task = Task(
    description="Analyze the sales data and identify trends",
    expected_output="A detailed analysis with key insights and trends",
    agent=agent
)

# Create the prompt generator
prompt_generator = Prompts(
    agent=agent,
    has_tools=len(agent.tools) > 0,
    use_system_prompt=agent.use_system_prompt
)

# Generate and inspect the actual prompt
generated_prompt = prompt_generator.task_execution()

# Print the complete system prompt that will be sent to the LLM
if "system" in generated_prompt:
    print("=== SYSTEM PROMPT ===")
    print(generated_prompt["system"])
    print("\n=== USER PROMPT ===")
    print(generated_prompt["user"])
else:
    print("=== COMPLETE PROMPT ===")
    print(generated_prompt["prompt"])

# You can also see how the task description gets formatted
print("\n=== TASK CONTEXT ===")
print(f"Task Description: {task.description}")
print(f"Expected Output: {task.expected_output}")

覆盖默认指令

您有多种选项可以完全控制提示：

选项 1：自定义模板（推荐）

from crewai import Agent

# Define your own system template without default instructions
custom_system_template = """You are {role}. {backstory}
Your goal is: {goal}

Respond naturally and conversationally. Focus on providing helpful, accurate information."""

custom_prompt_template = """Task: {input}

Please complete this task thoughtfully."""

agent = Agent(
    role="Research Assistant",
    goal="Help users find accurate information",
    backstory="You are a helpful research assistant.",
    system_template=custom_system_template,
    prompt_template=custom_prompt_template,
    use_system_prompt=True  # Use separate system/user messages
)

选项 2：自定义提示文件

创建一个 `custom_prompts.json` 文件来覆盖特定的提示片段：

{
  "slices": {
    "no_tools": "\nProvide your best answer in a natural, conversational way.",
    "tools": "\nYou have access to these tools: {tools}\n\nUse them when helpful, but respond naturally.",
    "formatted_task_instructions": "Format your response as: {output_format}"
  }
}

然后在您的 crew 中使用它：

crew = Crew(
    agents=[agent],
    tasks=[task],
    prompt_file="custom_prompts.json",
    verbose=True
)

选项 3：为 o1 模型禁用系统提示

agent = Agent(
    role="Analyst",
    goal="Analyze data",
    backstory="Expert analyst",
    use_system_prompt=False  # Disables system prompt separation
)

使用可观测性工具进行调试

为了实现生产透明度，请与可观测性平台集成，以监控所有提示和 LLM 交互。这使您能够确切地看到发送给 LLM 的提示（包括默认指令）是什么。请参阅我们的可观测性文档，了解与 Langfuse、MLflow、Weights & Biases 以及自定义日志记录解决方案等各种平台的详细集成指南。

生产最佳实践

在部署到生产环境之前，务必检查生成的提示
当需要完全控制提示内容时，使用自定义模板
集成可观测性工具以进行持续的提示监控（请参阅可观测性文档）
用不同的 LLM 进行测试，因为默认指令在不同模型上的效果可能不同
为您的提示自定义编写文档，以确保团队透明度

默认指令的存在是为了确保代理行为的一致性，但它们可能会与特定领域的需求冲突。使用上述自定义选项来在生产系统中保持对代理行为的完全控制。

管理提示文件的最佳实践

在进行低级提示自定义时，请遵循以下准则以保持代码的组织性和可维护性：

保持文件分离 – 将您的自定义提示存储在主代码库之外的专用 JSON 文件中。
版本控制 – 在您的代码仓库中跟踪更改，确保提示调整有清晰的文档记录。
按模型或语言组织 – 使用像 `prompts_llama.json` 或 `prompts_es.json` 这样的命名方案来快速识别专门的配置。
记录更改 – 提供注释或维护一个 README 文件，详细说明您自定义的目的和范围。
最小化修改 – 只覆盖您真正需要调整的特定片段，保持其他所有内容的默认功能不变。