在 crew.py 中使用注解

了解如何使用经典 Python 注解在 CrewAI 中组织智能体、任务和组件

本指南说明如何在经典 crew.py 文件中使用注解正确引用 智能体、任务及其他组件。

NOTE

使用 crewai create crew <name> 新建的团队项目是 JSON 优先的，使用 crew.jsonc 以及 agents/*.jsonc。当你在使用 crewai create crew <name> --classic 创建的经典项目中工作、迁移现有的 Python/YAML 项目，或需要基于装饰器的 Python 控制时，请使用本注解指南。

引言

CrewAI 框架中的注解用于装饰类和方法，为团队的各个组件提供元数据和功能。在经典 Python/YAML 项目中，这些注解帮助组织加载 config/agents.yaml、config/tasks.yaml 并返回 Crew 对象的代码。

可用注解

CrewAI 框架提供以下注解：

@CrewBase：用于装饰主团队类。
@agent：装饰定义并返回 Agent 对象的方法。
@task：装饰定义并返回 Task 对象的方法。
@crew：装饰创建并返回 Crew 对象的方法。
@llm：装饰初始化并返回语言模型对象的方法。
@tool：装饰初始化并返回 Tool 对象的方法。
@callback：用于定义回调方法。
@output_json：用于输出 JSON 数据的方法。
@output_pydantic：用于输出 Pydantic 模型的方法。
@cache_handler：用于定义缓存处理方法。

用法示例

下面通过示例介绍如何使用这些注解：

1. 团队基类

python

@CrewBase
class LinkedinProfileCrew():
    """LinkedinProfile crew"""
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

@CrewBase 注解用于装饰主团队类。该类通常包含配置以及创建智能体、任务和团队本身的方法。

TIP

@CrewBase 的作用不止于注册类：

配置引导： 在类文件旁查找 agents_config 和 tasks_config（默认为 config/agents.yaml 和 config/tasks.yaml），在实例化时加载它们，若文件缺失则安全回退为空 dict。
装饰器编排： 为标记了 @agent、@task、@before_kickoff 或 @after_kickoff 的每个方法保留记忆化引用，使其每个团队只实例化一次，并按声明顺序执行。
钩子接线： 自动将保留的 kickoff 钩子附加到 @crew 方法返回的 Crew 对象上，使其在 .kickoff() 前后运行。
MCP 集成： 当类定义了 mcp_server_params 时，get_mcp_tools() 会延迟启动 MCP 服务器适配器，装配声明的工具，并由内部的 kickoff 后钩子停止该适配器。适配器配置详情参见 MCP 概览。

2. 工具定义

python

@tool
def myLinkedInProfileTool(self):
    return LinkedInProfileTool()

@tool 注解用于装饰返回工具对象的方法。智能体可以使用这些工具执行特定任务。

3. LLM 定义

python

@llm
def groq_llm(self):
    api_key = os.getenv('api_key')
    return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768")

@llm 注解用于装饰初始化并返回语言模型对象的方法。智能体使用这些 LLM 执行自然语言处理任务。

4. 智能体定义

python

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config['researcher']
    )

@agent 注解用于装饰定义并返回 Agent 对象的方法。

5. 任务定义

python

@task
def research_task(self) -> Task:
    return Task(
        config=self.tasks_config['research_linkedin_task'],
        agent=self.researcher()
    )

@task 注解用于装饰定义并返回 Task 对象的方法。这些方法指定任务配置以及负责该任务的智能体。

6. 团队创建

python

@crew
def crew(self) -> Crew:
    """Creates the LinkedinProfile crew"""
    return Crew(
        agents=self.agents,
        tasks=self.tasks,
        process=Process.sequential,
        verbose=True
    )

@crew 注解用于装饰创建并返回 Crew 对象的方法。该方法将所有组件（智能体和任务）组装成一个可运行的团队。

经典 YAML 配置

在经典项目中，智能体配置通常存储在 YAML 文件中。下面是 researcher 智能体的 agents.yaml 文件示例：

yaml

researcher:
    role: >
        LinkedIn Profile Senior Data Researcher
    goal: >
        Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
        Generate a Dall-E image based on domain {domain}
    backstory: >
        You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
        Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
        professional information clearly and concisely.
    allow_delegation: False
    verbose: True
    llm: groq_llm
    tools:
        - myLinkedInProfileTool
        - mySerperDevTool
        - myDallETool

该 YAML 配置与 LinkedinProfileCrew 类中定义的 researcher 智能体相对应。配置指定了智能体的角色、目标、背景故事，以及它使用的 LLM 和工具等属性。

注意 YAML 文件中的 llm 和 tools 如何对应 Python 类中由 @llm 和 @tool 装饰的方法。

最佳实践

命名一致：为方法使用清晰一致的命名约定。例如，智能体方法可以按其角色命名（如 researcher、reporting_analyst）。
环境变量：对 API 密钥等敏感信息使用环境变量。
灵活性：设计团队时保持灵活，便于轻松添加或移除智能体和任务。
YAML 与代码对应：在经典项目中，确保 YAML 文件中的名称和结构与 Python 代码中装饰的方法正确对应。

遵循这些指南并正确使用注解，你可以让经典 Python/YAML 团队保持整洁。对于新团队，建议优先使用团队中介绍的 JSON 优先结构。

在 crew.py 中使用注解

引言

可用注解

用法示例

1. 团队基类

2. 工具定义

3. LLM 定义

4. 智能体定义

5. 任务定义

6. 团队创建

经典 YAML 配置

最佳实践

友情链接