crew.py에서 어노테이션 사용하기

crew.py에서 어노테이션 사용하기 (Using Annotations in crew.py)

이 가이드에서는 클래식(고전) crew.py 파일에서 agents, tasks 및 기타 구성 요소를 올바르게 참조하기 위해 어노테이션(annotation)을 사용하는 방법을 설명해요.

crewai create crew <name>으로 만든 새 crew 프로젝트는 JSON 우선 방식이며 crew.jsonc와 agents/*.jsonc를 사용해요. 이 어노테이션 가이드는 crewai create crew <name> --classic으로 만든 클래식 프로젝트에서 작업하거나, 기존 Python/YAML 프로젝트를 마이그레이션하거나, 데코레이터 기반 Python 제어가 필요할 때 사용하면 돼요.

출처: 문서

본문

Introduction (소개)

CrewAI 프레임워크의 어노테이션은 클래스와 메서드를 데코레이팅해서 crew의 다양한 구성 요소에 메타데이터와 기능을 제공하는 데 사용돼요. 클래식 Python/YAML 프로젝트에서 이 어노테이션들은 config/agents.yaml, config/tasks.yaml을 로드하고 Crew 객체를 반환하는 코드를 정리해 주는 역할을 해요.

Available Annotations (사용 가능한 어노테이션)

CrewAI 프레임워크는 다음과 같은 어노테이션을 제공해요:

  • @CrewBase — 메인 crew 클래스를 데코레이팅해요.
  • @agent — Agent 객체를 정의·반환하는 메서드를 데코레이팅해요.
  • @task — Task 객체를 정의·반환하는 메서드를 데코레이팅해요.
  • @crew — Crew 객체를 생성·반환하는 메서드를 데코레이팅해요.
  • @llm — Language Model 객체를 초기화·반환하는 메서드를 데코레이팅해요.
  • @tool — Tool 객체를 초기화·반환하는 메서드를 데코레이팅해요.
  • @callback — 콜백 메서드를 정의할 때 사용해요.
  • @output_json — JSON 데이터를 출력하는 메서드에 사용해요.
  • @output_pydantic — Pydantic 모델을 출력하는 메서드에 사용해요.
  • @cache_handler — 캐시 처리 메서드를 정의할 때 사용해요.

Usage Examples (사용 예시)

이 어노테이션들을 사용하는 예시를 함께 살펴볼게요.

1. Crew Base Class

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

@CrewBase 어노테이션은 메인 crew 클래스를 데코레이팅하는 데 사용돼요. 이 클래스는 보통 에이전트, 태스크, 그리고 crew 자체를 만들기 위한 설정과 메서드를 포함해요.

@CrewBase는 클래스를 등록하는 것 이상의 일을 해요:

  • 설정 부트스트래핑: 클래스 파일 옆에서 agents_config와 tasks_config(기본값은 config/agents.yaml, config/tasks.yaml)를 찾아 인스턴스화 시 로드하고, 파일이 없으면 빈 딕셔너리로 안전하게 폴백해요.
  • 데코레이터 오케스트레이션: @agent, @task, @before_kickoff, @after_kickoff로 표시된 모든 메서드의 메모이즈된 참조를 유지해서 crew당 한 번씩 선언 순서대로 인스턴스화돼요.
  • 훅 연결(Hook wiring): @crew 메서드가 반환한 Crew 객체에 보존된 kickoff 훅을 자동으로 연결해서 .kickoff() 전후에 실행되게 해요.
  • MCP 통합: 클래스가 mcp_server_params를 정의하면 get_mcp_tools()가 MCP 서버 어댑터를 지연 시작(lazily)하고, 선언된 툴을 로드하며, 내부 after-kickoff 훅이 어댑터를 중지해요. 어댑터 구성 세부 사항은 MCP 개요를 참조하세요.

2. Tool Definition (Tool 정의)

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

@tool 어노테이션은 툴 객체를 반환하는 메서드를 데코레이팅하는 데 사용돼요. 이 툴들은 에이전트가 특정 태스크를 수행하는 데 사용할 수 있어요.

3. LLM Definition (LLM 정의)

@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 어노테이션은 Language Model 객체를 초기화·반환하는 메서드를 데코레이팅하는 데 사용돼요. 이 LLM은 에이전트가 자연어 처리 태스크에 사용해요.

4. Agent Definition (Agent 정의)

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

@agent 어노테이션은 Agent 객체를 정의·반환하는 메서드를 데코레이팅하는 데 사용돼요.

5. Task Definition (Task 정의)

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

@task 어노테이션은 Task 객체를 정의·반환하는 메서드를 데코레이팅하는 데 사용돼요. 이 메서드들은 태스크 구성과 태스크를 담당하는 에이전트를 지정해요.

6. Crew Creation (Crew 생성)

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

@crew 어노테이션은 Crew 객체를 생성·반환하는 메서드를 데코레이팅하는 데 사용돼요. 이 메서드는 모든 구성 요소(에이전트와 태스크)를 하나의 동작 가능한 crew로 조립해요.

Classic YAML Configuration (클래식 YAML 구성)

클래식 프로젝트에서는 에이전트 구성이 보통 YAML 파일에 저장돼요. researcher 에이전트에 대한 agents.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로 데코레이팅된 메서드와 어떻게 대응하는지 주목하세요.

Best Practices (모범 사례)

  • 일관된 네이밍(Consistent Naming) — 메서드에 명확하고 일관된 네이밍 규칙을 사용하세요. 예를 들어 에이전트 메서드는 역할 이름으로 지을 수 있어요 (예: researcher, reporting_analyst).
  • 환경 변수(Environment Variables) — API 키 같은 민감한 정보에는 환경 변수를 사용하세요.
  • 유연성(Flexibility) — 에이전트와 태스크를 쉽게 추가·제거할 수 있도록 crew를 유연하게 설계하세요.
  • YAML-코드 대응(YAML-Code Correspondence) — 클래식 프로젝트에서 YAML 파일의 이름과 구조가 Python 코드의 데코레이팅된 메서드와 올바르게 대응하는지 확인하세요.

이 지침을 따르고 어노테이션을 제대로 사용하면 클래식 Python/YAML crew를 깔끔하게 유지할 수 있어요. 새로운 crew에서는 Crews에서 다루는 JSON 우선 구조를 선호하세요.

더 알아보기 (Learn more)