이벤트 리스너

개요

CrewAI는 강력한 이벤트 시스템을 제공하여 crew 실행 중 발생하는 다양한 이벤트를 수신하고 이에 반응할 수 있도록 합니다. 이 기능을 통해 맞춤형 통합, 모니터링 솔루션, 로깅 시스템 또는 CrewAI의 내부 이벤트에 따라 트리거되어야 하는 기타 모든 기능을 구축할 수 있습니다.

작동 방식

CrewAI는 실행 수명 주기 전반에 걸쳐 이벤트를 발생시키는 이벤트 버스 아키텍처를 사용합니다. 이벤트 시스템은 다음과 같은 구성 요소로 구축되어 있습니다:

CrewAIEventsBus: 이벤트 등록 및 발생을 관리하는 싱글톤 이벤트 버스
BaseEvent: 시스템 내 모든 이벤트의 기본 클래스
BaseEventListener: 커스텀 이벤트 리스너 생성을 위한 추상 기본 클래스

CrewAI에서 특정 동작(예: Crew가 실행을 시작하거나 Agent가 task를 완료하거나 tool이 사용될 때)이 발생하면, 시스템은 해당 이벤트를 발생시킵니다. 이러한 이벤트에 대한 핸들러를 등록하여 해당 이벤트가 발생할 때 커스텀 코드를 실행할 수 있습니다.

CrewAI AOP는 event 시스템을 활용하여 모든 prompt, completion 및 관련 메타데이터를 추적, 저장 및 시각화하는 내장 Prompt Tracing 기능을 제공합니다. 이 기능을 통해 agent 운영에 대한 강력한 디버깅 기능과 투명성을 얻을 수 있습니다.

Prompt Tracing을 통해 다음과 같은 작업이 가능합니다:

LLM에 전송된 모든 prompt의 전체 기록 보기
token 사용량 및 비용 추적
agent reasoning 실패 디버깅
팀 내에서 prompt 시퀀스 공유
다양한 prompt 전략 비교
컴플라이언스 및 감사를 위한 trace 내보내기

커스텀 이벤트 리스너 생성하기

커스텀 이벤트 리스너를 생성하려면 다음 단계를 따라야 합니다:

BaseEventListener를 상속하는 클래스를 생성합니다.
setup_listeners 메서드를 구현합니다.
원하는 이벤트에 대한 핸들러를 등록합니다.
해당 파일에서 리스너의 인스턴스를 생성합니다.

아래는 커스텀 이벤트 리스너 클래스의 간단한 예시입니다:

from crewai.events import (
    CrewKickoffStartedEvent,
    CrewKickoffCompletedEvent,
    AgentExecutionCompletedEvent,
)
from crewai.events import BaseEventListener

class MyCustomListener(BaseEventListener):
    def __init__(self):
        super().__init__()

    def setup_listeners(self, crewai_event_bus):
        @crewai_event_bus.on(CrewKickoffStartedEvent)
        def on_crew_started(source, event):
            print(f"Crew '{event.crew_name}' has started execution!")

        @crewai_event_bus.on(CrewKickoffCompletedEvent)
        def on_crew_completed(source, event):
            print(f"Crew '{event.crew_name}' has completed execution!")
            print(f"Output: {event.output}")

        @crewai_event_bus.on(AgentExecutionCompletedEvent)
        def on_agent_execution_completed(source, event):
            print(f"Agent '{event.agent.role}' completed task")
            print(f"Output: {event.output}")

리스너를 올바르게 등록하기

리스너 클래스를 정의하는 것만으로는 충분하지 않습니다. 해당 클래스의 인스턴스를 생성하고 애플리케이션에 임포트되었는지 확인해야 합니다. 이렇게 하면 다음과 같은 효과가 있습니다:

이벤트 핸들러가 이벤트 버스에 등록됩니다.
리스너 인스턴스가 메모리에 유지됩니다(가비지 컬렉션되지 않음).
이벤트가 발생할 때 리스너가 활성화됩니다.

옵션 1: Crew 또는 Flow 구현에서 가져오기 및 인스턴스화

가장 중요한 것은 Crew 또는 Flow가 정의되고 실행되는 파일에서 리스너의 인스턴스를 생성하는 것입니다.

크루 기반 애플리케이션의 경우

크루 구현 파일 상단에 리스너를 생성하고 임포트하세요:

# In your crew.py file
from crewai import Agent, Crew, Task
from my_listeners import MyCustomListener

# Create an instance of your listener
my_listener = MyCustomListener()

class MyCustomCrew:
    # Your crew implementation...

    def crew(self):
        return Crew(
            agents=[...],
            tasks=[...],
            # ...
        )

플로우 기반 애플리케이션의 경우

플로우 구현 파일 상단에 리스너를 생성하고 임포트하세요:

# main.py 또는 flow.py 파일에서
from crewai.flow import Flow, listen, start
from my_listeners import MyCustomListener

# 리스너 인스턴스 생성
my_listener = MyCustomListener()

class MyCustomFlow(Flow):
    # 플로우 구현...

    @start()
    def first_step(self):
        # ...

이렇게 하면 크루 또는 플로우가 실행될 때 리스너가 로드되고 활성화됩니다.

옵션 2: 리스너를 위한 패키지 생성

여러 개의 리스너가 있는 경우 등 보다 구조적인 접근 방식을 원한다면 다음과 같이 진행하세요:

리스너를 위한 패키지를 생성합니다:

my_project/
  ├── listeners/
  │   ├── __init__.py
  │   ├── my_custom_listener.py
  │   └── another_listener.py

my_custom_listener.py에서 리스너 클래스를 정의하고 인스턴스를 생성합니다:

# my_custom_listener.py
from crewai.events import BaseEventListener
# ... import events ...

class MyCustomListener(BaseEventListener):
    # ... implementation ...

# 리스너 인스턴스 생성
my_custom_listener = MyCustomListener()

__init__.py에서 리스너 인스턴스를 임포트하여 로드되도록 합니다:

# __init__.py
from .my_custom_listener import my_custom_listener
from .another_listener import another_listener

# 다른 곳에서 접근이 필요하다면 익스포트할 수도 있습니다
__all__ = ['my_custom_listener', 'another_listener']

Crew나 Flow 파일에서 리스너 패키지를 임포트합니다:

# crew.py 또는 flow.py 파일 내에서
import my_project.listeners  # 모든 리스너가 로드됩니다

class MyCustomCrew:
    # Your crew implementation...

이것이 CrewAI 코드베이스에서 서드파티 이벤트 리스너가 등록되는 방식입니다.

사용 가능한 이벤트 유형

CrewAI는 여러분이 청취할 수 있는 다양한 이벤트를 제공합니다:

Crew 이벤트

CrewKickoffStartedEvent: Crew가 실행을 시작할 때 발생
CrewKickoffCompletedEvent: Crew가 실행을 완료할 때 발생
CrewKickoffFailedEvent: Crew가 실행을 완료하지 못할 때 발생
CrewTestStartedEvent: Crew가 테스트를 시작할 때 발생
CrewTestCompletedEvent: Crew가 테스트를 완료할 때 발생
CrewTestFailedEvent: Crew가 테스트를 완료하지 못할 때 발생
CrewTrainStartedEvent: Crew가 훈련을 시작할 때 발생
CrewTrainCompletedEvent: Crew가 훈련을 완료할 때 발생
CrewTrainFailedEvent: Crew가 훈련을 완료하지 못할 때 발생
CrewTestResultEvent: Crew 테스트 결과가 사용 가능할 때 발생합니다. 품질 점수, 실행 시간, 사용된 모델을 포함합니다.

에이전트 이벤트

AgentExecutionStartedEvent: 에이전트가 작업 실행을 시작할 때 발생함
AgentExecutionCompletedEvent: 에이전트가 작업 실행을 완료할 때 발생함
AgentExecutionErrorEvent: 에이전트가 실행 도중 오류를 만날 때 발생함
LiteAgentExecutionStartedEvent: LiteAgent가 실행을 시작할 때 발생합니다. 에이전트 정보, 도구, 메시지를 포함합니다.
LiteAgentExecutionCompletedEvent: LiteAgent가 실행을 완료할 때 발생합니다. 에이전트 정보와 출력을 포함합니다.
LiteAgentExecutionErrorEvent: LiteAgent가 실행 중 오류를 만날 때 발생합니다. 에이전트 정보와 오류 메시지를 포함합니다.
AgentEvaluationStartedEvent: 에이전트 평가가 시작될 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수를 포함합니다.
AgentEvaluationCompletedEvent: 에이전트 평가가 완료될 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수, 메트릭 카테고리, 점수를 포함합니다.
AgentEvaluationFailedEvent: 에이전트 평가가 실패할 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수, 오류 메시지를 포함합니다.

작업 이벤트

TaskStartedEvent: 작업이 실행을 시작할 때 발생
TaskCompletedEvent: 작업이 실행을 완료할 때 발생
TaskFailedEvent: 작업이 실행을 완료하지 못할 때 발생
TaskEvaluationEvent: 작업이 평가될 때 발생

도구 사용 이벤트

ToolUsageStartedEvent: 도구 실행이 시작될 때 발생함
ToolUsageFinishedEvent: 도구 실행이 완료될 때 발생함
ToolUsageErrorEvent: 도구 실행 중 오류가 발생할 때 발생함
ToolValidateInputErrorEvent: 도구 입력 검증 중 오류가 발생할 때 발생함
ToolExecutionErrorEvent: 도구 실행 중 오류가 발생할 때 발생함
ToolSelectionErrorEvent: 도구 선택 시 오류가 발생할 때 발생함

MCP 이벤트

MCPConnectionStartedEvent: MCP 서버 연결을 시작할 때 발생합니다. 서버 이름, URL, 전송 유형, 연결 시간 초과, 재연결 시도 여부를 포함합니다.
MCPConnectionCompletedEvent: MCP 서버에 성공적으로 연결될 때 발생합니다. 서버 이름, 연결 시간(밀리초), 재연결 여부를 포함합니다.
MCPConnectionFailedEvent: MCP 서버 연결이 실패할 때 발생합니다. 서버 이름, 오류 메시지, 오류 유형(timeout, authentication, network 등)을 포함합니다.
MCPToolExecutionStartedEvent: MCP 도구 실행을 시작할 때 발생합니다. 서버 이름, 도구 이름, 도구 인수를 포함합니다.
MCPToolExecutionCompletedEvent: MCP 도구 실행이 성공적으로 완료될 때 발생합니다. 서버 이름, 도구 이름, 결과, 실행 시간(밀리초)을 포함합니다.
MCPToolExecutionFailedEvent: MCP 도구 실행이 실패할 때 발생합니다. 서버 이름, 도구 이름, 오류 메시지, 오류 유형(timeout, validation, server_error 등)을 포함합니다.
MCPConfigFetchFailedEvent: MCP 서버 구성을 가져오는 데 실패할 때 발생합니다(예: 계정에서 MCP가 연결되지 않았거나, API 오류, 구성을 가져온 후 연결 실패). slug, 오류 메시지, 오류 유형(not_connected, api_error, connection_failed)을 포함합니다.

지식 이벤트

KnowledgeRetrievalStartedEvent: 지식 검색이 시작될 때 발생
KnowledgeRetrievalCompletedEvent: 지식 검색이 완료될 때 발생
KnowledgeQueryStartedEvent: 지식 쿼리가 시작될 때 발생
KnowledgeQueryCompletedEvent: 지식 쿼리가 완료될 때 발생
KnowledgeQueryFailedEvent: 지식 쿼리가 실패할 때 발생
KnowledgeSearchQueryFailedEvent: 지식 검색 쿼리가 실패할 때 발생

LLM 가드레일 이벤트

LLMGuardrailStartedEvent: 가드레일 검증이 시작될 때 발생합니다. 적용되는 가드레일에 대한 세부 정보와 재시도 횟수를 포함합니다.
LLMGuardrailCompletedEvent: 가드레일 검증이 완료될 때 발생합니다. 검증의 성공/실패, 결과 및 오류 메시지(있는 경우)에 대한 세부 정보를 포함합니다.
LLMGuardrailFailedEvent: 가드레일 검증이 실패할 때 발생합니다. 오류 메시지와 재시도 횟수를 포함합니다.

Flow 이벤트

FlowCreatedEvent: Flow가 생성될 때 발생
FlowStartedEvent: Flow가 실행을 시작할 때 발생
FlowFinishedEvent: Flow가 실행을 완료할 때 발생
FlowPausedEvent: 사람의 피드백을 기다리며 Flow가 일시 중지될 때 발생합니다. Flow 이름, Flow ID, 메서드 이름, 현재 상태, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다.
FlowPlotEvent: Flow가 플롯될 때 발생
MethodExecutionStartedEvent: Flow 메서드가 실행을 시작할 때 발생
MethodExecutionFinishedEvent: Flow 메서드가 실행을 완료할 때 발생
MethodExecutionFailedEvent: Flow 메서드가 실행을 완료하지 못할 때 발생
MethodExecutionPausedEvent: 사람의 피드백을 기다리며 Flow 메서드가 일시 중지될 때 발생합니다. Flow 이름, 메서드 이름, 현재 상태, Flow ID, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다.

Human In The Loop 이벤트

FlowInputRequestedEvent: Flow.ask()를 통해 Flow가 사용자 입력을 요청할 때 발생합니다. Flow 이름, 메서드 이름, 사용자에게 표시되는 질문 또는 프롬프트, 선택적 메타데이터(예: 사용자 ID, 채널, 세션 컨텍스트)를 포함합니다.
FlowInputReceivedEvent: Flow.ask() 이후 사용자 입력이 수신될 때 발생합니다. Flow 이름, 메서드 이름, 원래 질문, 사용자의 응답(시간 초과 시 None), 선택적 요청 메타데이터, 프로바이더의 선택적 응답 메타데이터(예: 응답자, 스레드 ID, 타임스탬프)를 포함합니다.
HumanFeedbackRequestedEvent: @human_feedback 데코레이터가 적용된 메서드가 사람 리뷰어의 입력을 필요로 할 때 발생합니다. Flow 이름, 메서드 이름, 사람에게 검토를 위해 표시되는 메서드 출력, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다.
HumanFeedbackReceivedEvent: @human_feedback 데코레이터가 적용된 메서드에 대해 사람이 피드백을 제공할 때 발생합니다. Flow 이름, 메서드 이름, 사람이 제공한 원본 텍스트 피드백, 축약된 결과 문자열(emit이 지정된 경우)을 포함합니다.

LLM 이벤트

LLMCallStartedEvent: LLM 호출이 시작될 때 발생
LLMCallCompletedEvent: LLM 호출이 완료될 때 발생
LLMCallFailedEvent: LLM 호출이 실패할 때 발생
LLMStreamChunkEvent: 스트리밍 LLM 응답 중 각 청크를 받을 때마다 발생
LLMThinkingChunkEvent: thinking 모델에서 사고/추론 청크가 수신될 때 발생합니다. 청크 텍스트와 선택적 응답 ID를 포함합니다.

메모리 이벤트

MemoryQueryStartedEvent: 메모리 쿼리가 시작될 때 발생합니다. 쿼리, limit, 선택적 score threshold를 포함합니다.
MemoryQueryCompletedEvent: 메모리 쿼리가 성공적으로 완료될 때 발생합니다. 쿼리, 결과, limit, score threshold, 쿼리 실행 시간을 포함합니다.
MemoryQueryFailedEvent: 메모리 쿼리 실행에 실패할 때 발생합니다. 쿼리, limit, score threshold, 오류 메시지를 포함합니다.
MemorySaveStartedEvent: 메모리 저장 작업이 시작될 때 발생합니다. 저장할 값, 메타데이터, 선택적 agent 역할을 포함합니다.
MemorySaveCompletedEvent: 메모리 저장 작업이 성공적으로 완료될 때 발생합니다. 저장된 값, 메타데이터, agent 역할, 저장 실행 시간을 포함합니다.
MemorySaveFailedEvent: 메모리 저장 작업에 실패할 때 발생합니다. 값, 메타데이터, agent 역할, 오류 메시지를 포함합니다.
MemoryRetrievalStartedEvent: 태스크 프롬프트를 위한 메모리 검색이 시작될 때 발생합니다. 선택적 태스크 ID를 포함합니다.
MemoryRetrievalCompletedEvent: 태스크 프롬프트를 위한 메모리 검색이 성공적으로 완료될 때 발생합니다. 태스크 ID, 메모리 내용, 검색 실행 시간을 포함합니다.
MemoryRetrievalFailedEvent: 태스크 프롬프트를 위한 메모리 검색이 실패할 때 발생합니다. 선택적 태스크 ID와 오류 메시지를 포함합니다.

추론 이벤트

AgentReasoningStartedEvent: 에이전트가 태스크에 대한 추론을 시작할 때 발생합니다. 에이전트 역할, 태스크 ID, 시도 횟수를 포함합니다.
AgentReasoningCompletedEvent: 에이전트가 추론 과정을 마칠 때 발생합니다. 에이전트 역할, 태스크 ID, 생성된 계획, 에이전트가 진행할 준비가 되었는지 여부를 포함합니다.
AgentReasoningFailedEvent: 추론 과정이 실패할 때 발생합니다. 에이전트 역할, 태스크 ID, 오류 메시지를 포함합니다.

관찰 이벤트

StepObservationStartedEvent: Planner가 단계 결과를 관찰하기 시작할 때 발생합니다. 매 단계 실행 후, 관찰 LLM 호출 전에 발생합니다. 에이전트 역할, 단계 번호, 단계 설명을 포함합니다.
StepObservationCompletedEvent: Planner가 단계 결과 관찰을 마칠 때 발생합니다. 단계 성공 여부, 학습된 핵심 정보, 남은 계획의 유효성, 전체 재계획 필요 여부, 제안된 개선 사항을 포함합니다.
StepObservationFailedEvent: 관찰 LLM 호출 자체가 실패할 때 발생합니다. 시스템은 기본적으로 계획을 계속 진행합니다. 오류 메시지를 포함합니다.
PlanRefinementEvent: Planner가 전체 재계획 없이 다음 단계 설명을 개선할 때 발생합니다. 개선된 단계 수와 적용된 개선 사항을 포함합니다.
PlanReplanTriggeredEvent: 남은 계획이 근본적으로 잘못된 것으로 판단되어 Planner가 전체 재계획을 트리거할 때 발생합니다. 재계획 이유, 재계획 횟수, 보존된 완료 단계 수를 포함합니다.
GoalAchievedEarlyEvent: Planner가 목표가 조기에 달성되었음을 감지하고 나머지 단계를 건너뛸 때 발생합니다. 남은 단계 수와 완료된 단계 수를 포함합니다.

A2A (Agent-to-Agent) 이벤트

위임 이벤트

A2ADelegationStartedEvent: A2A 위임이 시작될 때 발생합니다. 엔드포인트 URL, 태스크 설명, 에이전트 ID, 컨텍스트 ID, 멀티턴 여부, 턴 번호, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보, 선택적 skill ID를 포함합니다.
A2ADelegationCompletedEvent: A2A 위임이 완료될 때 발생합니다. 완료 상태(completed, input_required, failed 등), 결과, 오류 메시지, 컨텍스트 ID, agent card 메타데이터를 포함합니다.
A2AParallelDelegationStartedEvent: 여러 A2A 에이전트로의 병렬 위임이 시작될 때 발생합니다. 엔드포인트 목록과 태스크 설명을 포함합니다.
A2AParallelDelegationCompletedEvent: 여러 A2A 에이전트로의 병렬 위임이 완료될 때 발생합니다. 엔드포인트 목록, 성공 수, 실패 수, 결과 요약을 포함합니다.

대화 이벤트

A2AConversationStartedEvent: 멀티턴 A2A 대화 시작 시 한 번 발생합니다. 첫 번째 메시지 교환 전에 발생합니다. 에이전트 ID, 엔드포인트, 컨텍스트 ID, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보를 포함합니다.
A2AMessageSentEvent: A2A 에이전트에 메시지가 전송될 때 발생합니다. 메시지 내용, 턴 번호, 컨텍스트 ID, 메시지 ID, 멀티턴 여부를 포함합니다.
A2AResponseReceivedEvent: A2A 에이전트로부터 응답이 수신될 때 발생합니다. 응답 내용, 턴 번호, 컨텍스트 ID, 메시지 ID, 상태, 최종 응답 여부를 포함합니다.
A2AConversationCompletedEvent: 멀티턴 A2A 대화 종료 시 한 번 발생합니다. 최종 상태(completed 또는 failed), 최종 결과, 오류 메시지, 컨텍스트 ID, 총 턴 수를 포함합니다.

스트리밍 이벤트

A2AStreamingStartedEvent: A2A 위임을 위한 스트리밍 모드가 시작될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 엔드포인트, 턴 번호, 멀티턴 여부를 포함합니다.
A2AStreamingChunkEvent: 스트리밍 청크가 수신될 때 발생합니다. 청크 텍스트, 청크 인덱스, 최종 청크 여부, 태스크 ID, 컨텍스트 ID, 턴 번호를 포함합니다.

폴링 및 푸시 알림 이벤트

A2APollingStartedEvent: A2A 위임을 위한 폴링 모드가 시작될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 폴링 간격(초), 엔드포인트를 포함합니다.
A2APollingStatusEvent: 각 폴링 반복 시 발생합니다. 태스크 ID, 컨텍스트 ID, 현재 태스크 상태, 경과 시간, 폴링 횟수를 포함합니다.
A2APushNotificationRegisteredEvent: 푸시 알림 콜백이 등록될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 콜백 URL, 엔드포인트를 포함합니다.
A2APushNotificationReceivedEvent: 원격 A2A 에이전트로부터 푸시 알림이 수신될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 현재 상태를 포함합니다.
A2APushNotificationSentEvent: 콜백 URL로 푸시 알림이 전송될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 콜백 URL, 상태, 전달 성공 여부, 선택적 오류 메시지를 포함합니다.
A2APushNotificationTimeoutEvent: 푸시 알림 대기가 시간 초과될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 시간 초과 시간(초)을 포함합니다.

연결 및 인증 이벤트

A2AAgentCardFetchedEvent: agent card가 성공적으로 가져올 때 발생합니다. 엔드포인트, 에이전트 이름, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보, 캐시 여부, 가져오기 시간(밀리초)을 포함합니다.
A2AAuthenticationFailedEvent: A2A 에이전트 인증이 실패할 때 발생합니다. 엔드포인트, 시도된 인증 유형(예: bearer, oauth2, api_key), 오류 메시지, HTTP 상태 코드를 포함합니다.
A2AConnectionErrorEvent: A2A 통신 중 연결 오류가 발생할 때 발생합니다. 엔드포인트, 오류 메시지, 오류 유형(예: timeout, connection_refused, dns_error), HTTP 상태 코드, 시도 중인 작업을 포함합니다.
A2ATransportNegotiatedEvent: A2A 에이전트와 전송 프로토콜이 협상될 때 발생합니다. 협상된 전송, 협상된 URL, 선택 소스(client_preferred, server_preferred, fallback), 클라이언트/서버 지원 전송을 포함합니다.
A2AContentTypeNegotiatedEvent: A2A 에이전트와 콘텐츠 유형이 협상될 때 발생합니다. 클라이언트/서버 입출력 모드, 협상된 입출력 모드, 협상 성공 여부를 포함합니다.

아티팩트 이벤트

A2AArtifactReceivedEvent: 원격 A2A 에이전트로부터 아티팩트가 수신될 때 발생합니다. 태스크 ID, 아티팩트 ID, 아티팩트 이름, 설명, MIME 유형, 크기(바이트), 콘텐츠 추가 여부를 포함합니다.

서버 태스크 이벤트

A2AServerTaskStartedEvent: A2A 서버 태스크 실행이 시작될 때 발생합니다. 태스크 ID와 컨텍스트 ID를 포함합니다.
A2AServerTaskCompletedEvent: A2A 서버 태스크 실행이 완료될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 결과를 포함합니다.
A2AServerTaskCanceledEvent: A2A 서버 태스크 실행이 취소될 때 발생합니다. 태스크 ID와 컨텍스트 ID를 포함합니다.
A2AServerTaskFailedEvent: A2A 서버 태스크 실행이 실패할 때 발생합니다. 태스크 ID, 컨텍스트 ID, 오류 메시지를 포함합니다.

컨텍스트 수명 주기 이벤트

A2AContextCreatedEvent: A2A 컨텍스트가 생성될 때 발생합니다. 컨텍스트는 대화 또는 워크플로우에서 관련 태스크를 그룹화합니다. 컨텍스트 ID와 생성 타임스탬프를 포함합니다.
A2AContextExpiredEvent: TTL로 인해 A2A 컨텍스트가 만료될 때 발생합니다. 컨텍스트 ID, 생성 타임스탬프, 수명(초), 태스크 수를 포함합니다.
A2AContextIdleEvent: A2A 컨텍스트가 유휴 상태가 될 때(설정된 임계값 동안 활동 없음) 발생합니다. 컨텍스트 ID, 유휴 시간(초), 태스크 수를 포함합니다.
A2AContextCompletedEvent: A2A 컨텍스트의 모든 태스크가 완료될 때 발생합니다. 컨텍스트 ID, 총 태스크 수, 지속 시간(초)을 포함합니다.
A2AContextPrunedEvent: A2A 컨텍스트가 정리(삭제)될 때 발생합니다. 컨텍스트 ID, 태스크 수, 수명(초)을 포함합니다.

이벤트 핸들러 구조

각 이벤트 핸들러는 두 개의 매개변수를 받습니다:

source: 이벤트를 발생시킨 객체
event: 이벤트별 데이터를 포함하는 이벤트 인스턴스

이벤트 객체의 구조는 이벤트 타입에 따라 다르지만, 모든 이벤트는 BaseEvent를 상속하며 다음을 포함합니다:

timestamp: 이벤트가 발생한 시간
type: 이벤트 타입을 나타내는 문자열 식별자

추가 필드는 이벤트 타입에 따라 다릅니다. 예를 들어, CrewKickoffCompletedEvent에는 crew_name과 output 필드가 포함됩니다.

고급 사용법: Scoped Handlers

임시 이벤트 처리가 필요한 경우(테스트 또는 특정 작업에 유용함), scoped_handlers 컨텍스트 관리자를 사용할 수 있습니다:

from crewai.events import crewai_event_bus, CrewKickoffStartedEvent

with crewai_event_bus.scoped_handlers():
    @crewai_event_bus.on(CrewKickoffStartedEvent)
    def temp_handler(source, event):
        print("This handler only exists within this context")

    # Do something that emits events

# 컨텍스트 밖에서는 임시 핸들러가 제거됩니다

사용 사례

이벤트 리스너는 다양한 목적으로 사용할 수 있습니다:

로깅 및 모니터링: Crew의 실행을 추적하고 중요한 이벤트를 기록합니다
분석: Crew의 성능과 동작에 대한 데이터를 수집합니다
디버깅: 특정 문제를 디버깅하기 위해 임시 리스너를 설정합니다
통합: CrewAI를 모니터링 플랫폼, 데이터베이스 또는 알림 서비스와 같은 외부 시스템과 연결합니다
사용자 정의 동작: 특정 이벤트에 따라 사용자 정의 동작을 트리거합니다

모범 사례

핸들러를 가볍게 유지하세요: 이벤트 핸들러는 경량이어야 하며, 블로킹 작업을 피해야 합니다.
오류 처리: 예외가 메인 실행에 영향을 주지 않도록 이벤트 핸들러에 적절한 오류 처리를 포함하세요.
정리: 리스너가 자원을 할당한다면, 이를 적절하게 정리하는지 확인하세요.
선택적 리스닝: 실제로 처리해야 하는 이벤트에만 리스닝하세요.
테스트: 이벤트 리스너가 예상대로 동작하는지 독립적으로 테스트하세요.

CrewAI의 이벤트 시스템을 활용하면 기능을 확장하고 기존 인프라와 원활하게 통합할 수 있습니다.

시작 안내

가이드

핵심 개념

MCP 통합

도구 (Tools)

Observability

학습

Telemetry

​개요

​작동 방식

​커스텀 이벤트 리스너 생성하기

​리스너를 올바르게 등록하기

​옵션 1: Crew 또는 Flow 구현에서 가져오기 및 인스턴스화

​크루 기반 애플리케이션의 경우

​플로우 기반 애플리케이션의 경우

​옵션 2: 리스너를 위한 패키지 생성

​사용 가능한 이벤트 유형

​Crew 이벤트

​에이전트 이벤트

​작업 이벤트

​도구 사용 이벤트

​MCP 이벤트

​지식 이벤트

​LLM 가드레일 이벤트

​Flow 이벤트

​Human In The Loop 이벤트

​LLM 이벤트

​메모리 이벤트

​추론 이벤트

​관찰 이벤트

​A2A (Agent-to-Agent) 이벤트

​위임 이벤트

​대화 이벤트

​스트리밍 이벤트

​폴링 및 푸시 알림 이벤트

​연결 및 인증 이벤트

​아티팩트 이벤트

​서버 태스크 이벤트

​컨텍스트 수명 주기 이벤트

​이벤트 핸들러 구조

​고급 사용법: Scoped Handlers

​사용 사례

​모범 사례

개요