多Agent协作工具CrewAI使用指南——如何做How-To

1. 安装 crewAI

欢迎使用 crewAI！本指南将带领您完成 crewAI 及其依赖项的安装过程。crewAI 是一个灵活而强大的人工智能框架，可以帮助您高效地创建和管理 AI 代理、工具和任务。让我们开始吧！

(1). 安装

要安装 crewAI，您需要在系统上安装 Python 版本 >=3.10 且 <=3.13：

# 安装主要的 crewAI 包
pip install crewai

# 安装主要的 crewAI 包和工具包
# 包括一系列有用的工具，供您的代理使用
pip install 'crewai[tools]'

2. 在 crewAI 中创建和利用工具

本指南详细介绍了如何为 crewAI 框架创建自定义工具以及如何高效管理和利用这些工具，包括最新功能，如工具委派、错误处理和动态工具调用。它还强调了协作工具的重要性，使代理能够执行各种操作。

(1). 先决条件

在创建自己的工具之前，请确保已安装 crewAI 额外工具包：

pip install 'crewai[tools]'

(2). 子类化 BaseTool

要创建个性化工具，请继承自 BaseTool 并定义必要的属性和 _run 方法。

from crewai_tools import BaseTool

class MyCustomTool(BaseTool):
    name: str = "我的工具名称"
    description: str = "这个工具的作用。对于有效利用至关重要。"

    def _run(self, argument: str) -> str:
        # 在这里编写工具的逻辑
        return "工具的结果"

(3). 使用 tool 装饰器

或者，使用 tool 装饰器以直接方式创建工具。这需要在函数内指定属性和工具的逻辑。

from crewai_tools import tool

@tool("工具名称")
def my_simple_tool(question: str) -> str:
    """用于澄清的工具描述。"""
    # 在这里编写工具的逻辑
    return "工具输出"

(4). 为工具定义缓存函数

为了通过缓存优化工具性能，可以使用 cache_function 属性定义自定义缓存策略。

@tool("带缓存的工具")
def cached_tool(argument: str) -> str:
    """工具功能描述。"""
    return "可缓存的结果"

def my_cache_strategy(arguments: dict, result: str) -> bool:
    # 定义自定义缓存逻辑
    return True if 某些条件 else False

cached_tool.cache_function = my_cache_strategy

通过遵循这些准则，并将新功能和协作工具纳入工具创建和管理流程中，您可以充分利用 crewAI 框架的全部功能，提升开发体验和 AI 代理的效率。

3. 顺序流程概述

CrewAI 提供了一个灵活的框架，以结构化方式执行任务，支持顺序和分层流程。本指南概述了如何有效实施这些流程，以确保任务执行高效并完成项目。顺序流程确保任务按顺序一个接一个地执行，遵循线性进展。这种方法非常适合需要按特定顺序完成任务的项目。

(1). 主要特点

• 线性任务流程：通过按照预定顺序处理任务，确保有序进展。
• 简单性：最适合具有清晰、逐步任务的项目。
• 易监控：便于跟踪任务完成情况和项目进度。

(2). 实施顺序流程

召集你的团队，并按照需要执行的顺序定义任务。

from crewai import Crew, Process, Agent, Task

# 定义你的代理人
researcher = Agent(
  role='研究员',
  goal='进行基础研究',
  backstory='一位经验丰富的研究员，热衷于发现洞察'
)
analyst = Agent(
  role='数据分析师',
  goal='分析研究结果',
  backstory='一位细致的分析师，擅长发现模式'
)
writer = Agent(
  role='作家',
  goal='起草最终报告',
  backstory='一位技艺高超的作家，擅长撰写引人入胜的叙事'
)

# 按顺序定义任务
research_task = Task(description='收集相关数据...', agent=researcher)
analysis_task = Task(description='分析数据...', agent=analyst)
writing_task = Task(description='撰写报告...', agent=writer)

# 以顺序流程形式组建团队
report_crew = Crew(
  agents=[researcher, analyst, writer],
  tasks=[research_task, analysis_task, writing_task],
  process=Process.sequential
)

(3). 工作流程示例

1. 初始任务：在顺序流程中，第一个代理人完成他们的任务并发出完成信号。
2. 后续任务：代理人根据流程类型接手任务，前期任务的结果或管理者的指导指引他们的执行。
3. 完成：一旦执行最终任务，流程结束，项目完成。

(4). 结论

CrewAI 中的顺序和分层流程为任务执行提供了清晰、适应性强的路径。它们非常适合需要逻辑进展和动态决策的项目，确保每一步都有效完成，从而促进一个连贯的最终产品。

4. 分层流程概述

CrewAI 中的分层流程引入了一种结构化的任务管理方法，模拟传统组织层级结构，实现任务委派和执行的高效性。这种系统化的工作流通过确保任务以最佳效率和准确性处理，增强了项目结果。

“复杂性和效率”：分层流程旨在利用像 GPT-4 这样的先进模型，优化令牌使用，同时处理复杂任务，提高效率。

在 CrewAI 中，默认情况下，任务通过顺序流程管理。然而，采用分层方法可以实现任务管理中的清晰层次结构，其中一个“经理”代理协调工作流程，委派任务，并验证结果，以实现流畅和有效的执行。这个经理代理是由 CrewAI 自动创建的，因此您无需担心。

(1). 主要特点

• 任务委派：经理代理根据成员的角色和能力分配任务。
• 结果验证：经理评估结果，确保其符合要求的标准。
• 高效工作流：模拟公司结构，提供组织良好的任务管理方法。

(2). 实施分层流程

要利用分层流程，必须将流程属性明确设置为 Process.hierarchical，因为默认行为是 Process.sequential。定义一个具有指定经理的团队，并建立清晰的指挥链。

!!! note “工具和代理分配”
在代理级别分配工具，以便由经理指导下的指定代理执行任务委派和执行。还可以在任务级别指定工具，以精确控制任务执行期间的工具可用性。

!!! note “经理 LLM 要求”
配置 manager_llm 参数对于分层流程至关重要。系统需要设置经理 LLM 以确保适当的功能，确保定制决策。

from langchain_openai import ChatOpenAI
from crewai import Crew, Process, Agent

# 代理定义了背景故事、缓存和详细模式等属性
researcher = Agent(
    role='研究员',
    goal='进行深入分析',
    backstory='经验丰富的数据分析师，擅长发现隐藏的趋势。',
    cache=True,
    verbose=False,
    # tools=[]  # 可选指定；默认为空列表
)
writer = Agent(
    role='作家',
    goal='创作引人入胜的内容',
    backstory='对技术领域中的叙事充满激情的创意作家。',
    cache=True,
    verbose=False,
    # tools=[]  # 可选指定工具；默认为空列表
)

# 使用分层流程和其他配置建立团队
project_crew = Crew(
    tasks=[...],  # 在经理监督下委派和执行的任务
    agents=[researcher, writer],
    manager_llm=ChatOpenAI(temperature=0, model="gpt-4"),  # 分层流程必需
    process=Process.hierarchical,  # 指定分层管理方法
    memory=True,  # 启用内存使用以增强任务执行
)

(3). 工作流程实例

1. 任务分配：经理根据每个代理的能力和可用工具策略性地分配任务。
2. 执行和审查：代理完成任务，可以选择异步执行，并使用回调函数实现流畅的工作流程。
3. 顺序任务进展：尽管是分层流程，任务按照逻辑顺序进行，经理的监督促进了任务的顺利进行。

(4). 结论

在 CrewAI 中采用分层流程，正确配置并了解系统的能力，有助于实现项目管理的有序和高效方法。

5. 将 CrewAI 连接到 LLMs

“默认 LLM”：默认情况下，CrewAI 使用 OpenAI 的 GPT-4 模型进行语言处理。您可以配置您的代理以使用不同的模型或 API。本指南展示了如何通过环境变量和直接实例化将您的代理连接到各种 LLMs。

CrewAI 提供了连接到各种 LLMs 的灵活性，包括通过 Ollama 连接到本地模型以及与 Azure 等不同 API 集成。它与所有 LangChain LLM 组件兼容，为定制的 AI 解决方案提供了多样化的集成。

(1). CrewAI 代理概述

Agent 类是在 CrewAI 中实现 AI 解决方案的基石。以下是反映最新代码库更改的更新概述：

• 属性:
  • role: 定义解决方案中代理的角色。
  • goal: 指定代理的目标。
  • backstory: 为代理提供背景故事。
  • llm: 将运行代理的语言模型。默认情况下，它使用环境变量 “OPENAI_MODEL_NAME” 中定义的 GPT-4 模型。
  • function_calling_llm: 将处理此代理的工具调用的语言模型，覆盖 crew function_calling_llm。可选。
  • max_iter: 代理执行任务的最大迭代次数，默认为 15。
  • memory: 允许代理在执行过程中保留信息。默认为 False。
  • max_rpm: 代理执行应遵守的每分钟请求的最大数量。可选。
  • verbose: 启用对代理执行的详细记录。默认为 False。
  • allow_delegation: 允许代理将任务委托给其他代理。默认为 True。
  • tools: 指定代理用于任务执行的工具。可选。
  • step_callback: 提供在每个步骤之后执行的回调函数。可选。
  • cache: 确定代理是否应使用缓存进行工具使用。默认为 True。

# 必需
os.environ["OPENAI_MODEL_NAME"]="gpt-4-0125-preview"

# 代理将自动使用环境变量中定义的模型
example_agent = Agent(
  role='本地专家',
  goal='提供有关城市的见解',
  backstory="一位知识渊博的当地向导。",
  verbose=True,
  memory=True
)

(2). Ollama 集成

Ollama 是首选的本地 LLM 集成方式，提供定制和隐私优势。要将 Ollama 与 CrewAI 集成，设置如下适当的环境变量。注意：详细的 Ollama 设置超出了本文档的范围，但提供了一般指导。

设置 Ollama

• 环境变量配置：要集成 Ollama，请设置以下环境变量：

OPENAI_API_BASE='http://localhost:11434/v1'
OPENAI_MODEL_NAME='openhermes'  # 根据可用模型进行调整
OPENAI_API_KEY=''

(3). HuggingFace 集成

您可以使用 HuggingFace 托管您的 LLM 的几种不同方式。

您自己的 HuggingFace 端点

from langchain_community.llms import HuggingFaceEndpoint

llm = HuggingFaceEndpoint(
    endpoint_url="<YOUR_ENDPOINT_URL_HERE>",
    huggingfacehub_api_token="<HF_TOKEN_HERE>",
    task="text-generation",
    max_new_tokens=512
)

agent = Agent(
    role="HuggingFace 代理",
    goal="使用 HuggingFace 生成文本",
    backstory="GitHub 文档的勤奋探索者。",
    llm=llm
)

从 HuggingFaceHub 端点

from langchain_community.llms import HuggingFaceHub

llm = HuggingFaceHub(
    repo_id="HuggingFaceH4/zephyr-7b-beta",
    huggingfacehub_api_token="<HF_TOKEN_HERE>",
    task="text-generation",
)

(4). OpenAI 兼容的 API 端点

通过环境变量无缝切换 API 和模型，支持 FastChat、LM Studio 和 Mistral AI 等平台。

配置示例

FastChat

OPENAI_API_BASE="http://localhost:8001/v1"
OPENAI_MODEL_NAME='oh-2.5m7b-q51'
OPENAI_API_KEY=NA

LM Studio

启动 LM Studio 并转到 Server 选项卡。然后从下拉菜单中选择一个模型，等待加载。加载完成后，点击绿色的 Start Server 按钮，并使用显示的 URL、端口和 API 密钥（您可以修改它们）。以下是截至 LM Studio 0.2.19 的默认设置示例：

OPENAI_API_BASE="http://localhost:1234/v1"
OPENAI_API_KEY="lm-studio"

Mistral API

OPENAI_API_KEY=your-mistral-api-key
OPENAI_API_BASE=https://api.mistral.ai/v1
OPENAI_MODEL_NAME="mistral-small"

Solar

from langchain_community.chat_models.solar import SolarChat
# 初始化语言模型
os.environ["SOLAR_API_KEY"] = "your-solar-api-key"
llm = SolarChat(max_tokens=1024)

免费的开发者 API 密钥在此处获取：https://console.upstage.ai/services/solar
Langchain 示例：https://github.com/langchain-ai/langchain/pull/18556

text-gen-web-ui

OPENAI_API_BASE=http://localhost:5000/v1
OPENAI_MODEL_NAME=NA
OPENAI_API_KEY=NA

Cohere

from langchain_community.chat_models import ChatCohere
# 初始化语言模型
os.environ["COHERE_API_KEY"] = "your-cohere-api-key"
llm = ChatCohere()

免费的开发者 API 密钥在此处获取：https://cohere.com/
Langchain 文档：https://python.langchain.com/docs/integrations/chat/cohere

Azure Open AI 配置

要进行 Azure OpenAI API 集成，请设置以下环境变量：

AZURE_OPENAI_VERSION="2022-12-01"
AZURE_OPENAI_DEPLOYMENT=""
AZURE_OPENAI_ENDPOINT=""
AZURE_OPENAI_KEY=""

使用 Azure LLM 的示例代理

from dotenv import load_dotenv
from crewai import Agent
from langchain_openai import AzureChatOpenAI

load_dotenv()

azure_llm = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_key=os.environ.get("AZURE_OPENAI_KEY")
)

azure_agent = Agent(
  role='示例代理',
  goal='演示自定义 LLM 配置',
  backstory='GitHub 文档的勤奋探索者。',
  llm=azure_llm
)

(5). 结论

将 CrewAI 与不同的 LLMs 集成扩展了框架的多样性，允许在各种领域和平台上定制高效的 AI 解决方案。

6. 可定制属性

打造高效的 CrewAI 团队的关键在于能够动态地调整 AI 代理，以满足任何项目的独特需求。本节将介绍您可以定制的基础属性。

(1). 定制的关键属性

• 角色：指定代理在团队中的工作，如“分析师”或“客服代表”。
• 目标：定义代理的目标，与其角色和团队整体目标保持一致。
• 背景故事：为代理的角色赋予深度，丰富其动机和在团队中的参与。
• 工具：代表代理用于执行任务的能力或方法，从简单功能到复杂集成。

(2). 高级定制选项

除了基本属性外，CrewAI 还允许进行更深入的定制，以显著增强代理的行为和能力。

语言模型定制

代理可以使用特定的语言模型（llm）和函数调用语言模型（function_calling_llm）进行定制，提供对其处理和决策能力的高级控制。值得注意的是，设置 function_calling_llm 允许覆盖默认的团队函数调用语言模型，提供更高程度的定制。

(3). 性能和调试设置

调整代理的性能并监控其操作对于高效执行任务至关重要。

冗长模式和 RPM 限制

• 冗长模式：启用对代理操作的详细记录，有助于调试和优化。具体来说，它提供了关于代理执行过程的见解，有助于性能优化。
• RPM 限制：设置每分钟请求的最大数量（max_rpm）。此属性是可选的，可以设置为 None 以取消限制，如果需要的话，允许对外部服务进行无限查询。

任务执行的最大迭代次数

max_iter 属性允许用户定义代理为单个任务执行的最大迭代次数，防止无限循环或执行时间过长。默认值设置为 15，在彻底性和效率之间提供平衡。一旦代理接近这个数字，它将尽力给出一个好答案。

(4). 定制代理和工具

通过在初始化期间定义其属性和工具来定制代理。工具对代理的功能至关重要，使其能够执行专业任务。tools 属性应该是代理可以利用的工具数组，默认情况下初始化为空列表。可以在代理初始化后添加或修改工具，以适应新的需求。

pip install 'crewai[tools]'

示例：为代理分配工具

import os
from crewai import Agent
from crewai_tools import SerperDevTool

# 为工具初始化设置 API 密钥
os.environ["OPENAI_API_KEY"] = "Your Key"
os.environ["SERPER_API_KEY"] = "Your Key"

# 初始化一个搜索工具
search_tool = SerperDevTool()

# 使用高级选项初始化代理
agent = Agent(
  role='研究分析师',
  goal='提供最新的市场分析',
  backstory='一位对市场趋势敏锐的专业分析师。',
  tools=[search_tool],
  memory=True, # 启用记忆功能
  verbose=True,
  max_rpm=None, # 每分钟请求无限制
  max_iter=15, # 最大迭代次数的默认值
  allow_delegation=False
)

(5). 委托和自主权

控制代理委托任务或提问的能力对于定制其自主权和在 CrewAI 框架内的协作动态至关重要。默认情况下，allow_delegation 属性设置为 True，允许代理根据需要寻求帮助或委托任务。这种默认行为促进了 CrewAI 生态系统内的协作解决问题和效率。如果需要，可以禁用委托以适应特定的操作需求。

示例：禁用代理的委托

agent = Agent(
  role='内容撰稿人',
  goal='撰写有关市场趋势的引人入胜内容',
  backstory='一位在市场分析方面拥有专业知识的资深撰稿人。',
  allow_delegation=False # 禁用委托
)

(6). 结论

通过设置代理的角色、目标、背景故事和工具，以及高级选项如语言模型定制、记忆、性能设置和委托偏好，定制 CrewAI 中的代理，为复杂挑战做好准备，使其成为一个细致而有能力的 AI 团队。

7. 代理执行中的人类输入

在几种代理执行场景中，人类输入至关重要，允许代理在必要时请求额外信息或澄清。这一功能在复杂决策过程中特别有用，或者当代理需要更多细节以有效完成任务时。

(1). 使用 CrewAI 进行人类输入

要将人类输入整合到代理执行中，在任务定义中设置 human_input 标志。启用后，代理会在提供最终答案之前提示用户输入。这种输入可以提供额外的上下文，澄清模糊之处，或验证代理的输出。

(2). 示例：

pip install crewai

import os
from crewai import Agent, Task, Crew
from crewai_tools import SerperDevTool

os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key
os.environ["OPENAI_API_KEY"] = "Your Key"

# 加载工具
search_tool = SerperDevTool()

# 使用角色、目标、工具和其他属性定义您的代理
researcher = Agent(
  role='高级研究分析师',
  goal='发现人工智能和数据科学领域的前沿发展',
  backstory=(
    "您是一家领先科技智库的高级研究分析师。"
    "您擅长识别人工智能和数据科学领域的新兴趋势和技术。"
    "您善于剖析复杂数据并提供可操作的见解。"
  ),
  verbose=True,
  allow_delegation=False,
  tools=[search_tool],
  max_rpm=100
)
writer = Agent(
  role='科技内容策略师',
  goal='撰写关于科技进步的引人入胜内容',
  backstory=(
    "您是一位著名的科技内容策略师，以撰写富有洞察力和引人入胜的科技和创新文章而闻名。"
    "凭借对科技行业的深刻理解，您将复杂概念转化为引人入胜的叙事。"
  ),
  verbose=True,
  allow_delegation=True,
  tools=[search_tool],
  cache=False, # 为该代理禁用缓存
)

# 为您的代理创建任务
task1 = Task(
  description=(
    "对2024年人工智能领域的最新进展进行全面分析。"
    "识别关键趋势、突破性技术和潜在的行业影响。"
    "将您的研究结果编制成详细报告。"
    "在最终确定答案之前，请确保与人类核对草稿是否合适。"
  ),
  expected_output='一份关于2024年最新人工智能进展的全面报告，不遗漏任何细节',
  agent=researcher,
  human_input=True,
)

task2 = Task(
  description=(
    "利用研究员报告中的见解，撰写一篇引人入胜的博客文章，重点介绍最重要的人工智能进展。"
    "您的文章应既具信息性又易于理解，迎合科技爱好者的观众。"
    "力求以叙述方式捕捉这些突破性进展的本质及其对未来的影响。"
  ),
  expected_output='一篇引人入胜的、格式为 markdown 的三段博客文章，介绍2024年最新人工智能进展',
  agent=writer
)

# 使用顺序流程实例化您的团队
crew = Crew(
  agents=[researcher, writer],
  tasks=[task1, task2],
  verbose=2
)

# 让您的团队开始工作！
result = crew.kickoff()

print("######################")
print(result)

8. AgentOps

可观察性是开发和部署会话式人工智能智能体的关键方面。它使开发人员能够了解他们的智能体的性能如何，他们的智能体如何与用户交互，以及他们的智能体如何使用外部工具和API。AgentOps是一个与CrewAI无关的产品，为智能体提供了全面的可观察性解决方案。

AgentOps 提供了智能体的会话重放、指标和监控。

在高层次上，AgentOps使您能够监控成本、令牌使用情况、延迟、智能体故障、会话范围统计数据等。欲了解更多信息，请查看AgentOps Repo。

(1). 概述

AgentOps为开发和生产中的智能体提供监控。它提供了用于跟踪智能体性能、会话重放和自定义报告的仪表板。

此外，AgentOps提供了会话详细信息，可实时查看Crew智能体交互、LLM调用以及工具使用情况。此功能对于调试和了解智能体如何与用户以及其他智能体交互非常有用。

(2). 特点

• LLM成本管理和跟踪：跟踪基础模型提供商的支出
• 重放分析：观看逐步智能体执行图
• 递归思考检测：识别智能体何时陷入无限循环
• 自定义报告：创建关于智能体性能的自定义分析
• 分析仪表板：监视有关开发和生产中智能体的高级统计信息
• 公共模型测试：针对基准和排行榜测试您的智能体
• 自定义测试：针对特定领域的测试运行您的智能体
• 时光旅行调试：从检查点重新启动您的会话
• 合规性和安全性：创建审计日志并检测潜在威胁，如粗话和个人身份信息泄漏
• 提示注入检测：识别潜在的代码注入和秘密泄漏

(3). 使用AgentOps

1. 创建API密钥：
   在此处创建用户API密钥：创建API密钥

2. 配置您的环境：
   将您的API密钥添加到您的环境变量中

AGENTOPS_API_KEY=<YOUR_AGENTOPS_API_KEY>

3. 安装AgentOps：
   使用以下命令安装AgentOps：

pip install crewai[agentops]

或

pip install agentops

在脚本中使用Crew之前，包含以下行：

import agentops
agentops.init()

这将启动一个AgentOps会话，并自动跟踪Crew智能体。欲了解更多关于如何为更复杂的智能系统配备装备的信息，请查看AgentOps文档或加入Discord。

(4). Crew + AgentOps示例

• 职位发布
• Markdown验证器
• Instagram帖子

(5). 更多信息

要开始使用，请创建一个AgentOps账户。

如有功能请求或错误报告，请联系AgentOps团队，访问AgentOps Repo。