> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewai.com/llms.txt > Use this file to discover all available pages before exploring further. # Listeners de Evento > Acesse eventos do CrewAI para criar integrações e monitoramento personalizados ## Visão Geral O CrewAI oferece um sistema de eventos poderoso que permite escutar e reagir a diversos eventos que ocorrem durante a execução do seu Crew. Esse recurso possibilita a criação de integrações personalizadas, soluções de monitoramento, sistemas de log ou qualquer outra funcionalidade que precise ser acionada com base nos eventos internos do CrewAI. ## Como Funciona O CrewAI utiliza uma arquitetura de event bus para emitir eventos ao longo do ciclo de vida da execução. O sistema de eventos é construído a partir dos seguintes componentes: 1. **CrewAIEventsBus**: Um event bus singleton que gerencia o registro e emissão de eventos 2. **BaseEvent**: Classe base para todos os eventos do sistema 3. **BaseEventListener**: Classe base abstrata para criar listeners de evento personalizados Quando ações específicas ocorrem no CrewAI (como a inicialização de um Crew, um Agent concluindo uma tarefa ou o uso de uma ferramenta), o sistema emite os eventos correspondentes. Você pode registrar handlers para esses eventos para executar código personalizado quando eles acontecerem. O CrewAI AMP fornece o recurso Prompt Tracing, que aproveita o sistema de eventos para rastrear, armazenar e visualizar todos os prompts, respostas e metadados associados. Isso proporciona poderosas capacidades de depuração e transparência nas operações dos seus agentes. Prompt Tracing Dashboard Com o Prompt Tracing você pode: * Visualizar o histórico completo de todos os prompts enviados ao seu LLM * Monitorar o uso de tokens e custos * Depurar falhas de raciocínio dos agentes * Compartilhar sequências de prompts com sua equipe * Comparar diferentes estratégias de prompts * Exportar rastreamentos para compliance e auditoria ## Criando um Listener de Evento Personalizado Para criar um listener de evento personalizado, você precisa: 1. Criar uma classe que herde de `BaseEventListener` 2. Implementar o método `setup_listeners` 3. Registrar handles para os eventos de seu interesse 4. Instanciar seu listener no arquivo apropriado Veja um exemplo simples de uma classe de listener de evento personalizado: ```python theme={null} from crewai.events import ( CrewKickoffStartedEvent, CrewKickoffCompletedEvent, AgentExecutionCompletedEvent, ) from crewai.events import BaseEventListener class MeuListenerPersonalizado(BaseEventListener): def __init__(self): super().__init__() def setup_listeners(self, crewai_event_bus): @crewai_event_bus.on(CrewKickoffStartedEvent) def ao_iniciar_crew(source, event): print(f"Crew '{event.crew_name}' iniciou a execução!") @crewai_event_bus.on(CrewKickoffCompletedEvent) def ao_finalizar_crew(source, event): print(f"Crew '{event.crew_name}' finalizou a execução!") print(f"Saída: {event.output}") @crewai_event_bus.on(AgentExecutionCompletedEvent) def ao_finalizar_execucao_agente(source, event): print(f"Agente '{event.agent.role}' concluiu a tarefa") print(f"Saída: {event.output}") ``` ## Registrando Corretamente Seu Listener Apenas definir sua classe de listener não é suficiente. É necessário criar uma instância dela e garantir que ela seja importada na sua aplicação. Isso garante que: 1. Os event handlers estejam registrados no event bus 2. A instância do listener permaneça em memória (não seja coletada pelo garbage collector) 3. O listener esteja ativo quando os eventos forem emitidos ### Opção 1: Importar e Instanciar no Seu Crew ou Implementação de Flow O mais importante é criar uma instância do seu listener no arquivo onde seu Crew ou Flow está definido e executado: #### Para Aplicações Baseadas em Crew Crie e importe seu listener no início do arquivo de implementação do seu Crew: ```python theme={null} # No seu arquivo crew.py from crewai import Agent, Crew, Task from my_listeners import MyCustomListener # Crie uma instância do seu listener my_listener = MyCustomListener() class MyCustomCrew: # Sua implementação do crew... def crew(self): return Crew( agents=[...], tasks=[...], # ... ) ``` #### Para Aplicações Baseadas em Flow Crie e importe seu listener no início do arquivo de implementação do seu Flow: ```python theme={null} # Em seu arquivo main.py ou flow.py from crewai.flow import Flow, listen, start from my_listeners import MyCustomListener # Crie uma instância do seu listener my_listener = MyCustomListener() class MyCustomFlow(Flow): # Sua implementação do flow... @start() def first_step(self): # ... ``` Isso assegura que seu listener será carregado e estará ativo quando seu Crew ou Flow for executado. ### Opção 2: Criar um Pacote para Seus Listeners Para uma abordagem mais estruturada, especialmente se houver múltiplos listeners: 1. Crie um pacote para seus listeners: ``` my_project/ ├── listeners/ │ ├── __init__.py │ ├── my_custom_listener.py │ └── another_listener.py ``` 2. Em `my_custom_listener.py`, defina sua classe de listener e crie uma instância: ```python theme={null} # my_custom_listener.py from crewai.events import BaseEventListener # ... importe events ... class MyCustomListener(BaseEventListener): # ... implementação ... # Crie uma instância do seu listener my_custom_listener = MyCustomListener() ``` 3. Em `__init__.py`, importe as instâncias dos listeners para garantir seu carregamento: ```python theme={null} # __init__.py from .my_custom_listener import my_custom_listener from .another_listener import another_listener # Opcionalmente exporte-os se precisar acessá-los em outros lugares __all__ = ['my_custom_listener', 'another_listener'] ``` 4. Importe seu pacote de listeners no arquivo do seu Crew ou Flow: ```python theme={null} # No seu arquivo crew.py ou flow.py import my_project.listeners # Isso carrega todos os seus listeners class MyCustomCrew: # Sua implementação do crew... ``` É assim que listeners de eventos de terceiros são registrados no código do CrewAI. ## Tipos de Eventos Disponíveis O CrewAI fornece uma ampla variedade de eventos para escuta: ### Eventos de Crew * **CrewKickoffStartedEvent**: Emitido quando um Crew inicia a execução * **CrewKickoffCompletedEvent**: Emitido quando um Crew conclui a execução * **CrewKickoffFailedEvent**: Emitido quando um Crew falha ao concluir a execução * **CrewTestStartedEvent**: Emitido ao iniciar o teste de um Crew * **CrewTestCompletedEvent**: Emitido ao concluir o teste de um Crew * **CrewTestFailedEvent**: Emitido ao falhar no teste de um Crew * **CrewTrainStartedEvent**: Emitido ao iniciar o treinamento de um Crew * **CrewTrainCompletedEvent**: Emitido ao concluir o treinamento de um Crew * **CrewTrainFailedEvent**: Emitido ao falhar no treinamento de um Crew ### Eventos de Agent * **AgentExecutionStartedEvent**: Emitido quando um Agent inicia a execução de uma tarefa * **AgentExecutionCompletedEvent**: Emitido quando um Agent conclui a execução de uma tarefa * **AgentExecutionErrorEvent**: Emitido quando um Agent encontra um erro durante a execução ### Eventos de Task * **TaskStartedEvent**: Emitido ao iniciar a execução de uma Task * **TaskCompletedEvent**: Emitido ao concluir a execução de uma Task * **TaskFailedEvent**: Emitido ao falhar na execução de uma Task * **TaskEvaluationEvent**: Emitido quando uma Task é avaliada ### Eventos de Uso de Ferramentas * **ToolUsageStartedEvent**: Emitido ao iniciar a execução de uma ferramenta * **ToolUsageFinishedEvent**: Emitido ao concluir a execução de uma ferramenta * **ToolUsageErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta * **ToolValidateInputErrorEvent**: Emitido ao ocorrer erro de validação de entrada na ferramenta * **ToolExecutionErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta * **ToolSelectionErrorEvent**: Emitido ao ocorrer erro na seleção de uma ferramenta ### Eventos de Knowledge * **KnowledgeRetrievalStartedEvent**: Emitido ao iniciar recuperação de conhecimento * **KnowledgeRetrievalCompletedEvent**: Emitido ao concluir recuperação de conhecimento * **KnowledgeQueryStartedEvent**: Emitido ao iniciar consulta de conhecimento * **KnowledgeQueryCompletedEvent**: Emitido ao concluir consulta de conhecimento * **KnowledgeQueryFailedEvent**: Emitido ao falhar consulta de conhecimento * **KnowledgeSearchQueryFailedEvent**: Emitido ao falhar consulta de busca de conhecimento ### Eventos de Guardrail do LLM * **LLMGuardrailStartedEvent**: Emitido ao iniciar validação dos guardrails. Contém detalhes do guardrail aplicado e tentativas. * **LLMGuardrailCompletedEvent**: Emitido ao concluir validação dos guardrails. Contém detalhes sobre sucesso/falha na validação, resultados e mensagens de erro, se houver. ### Eventos de Flow * **FlowCreatedEvent**: Emitido ao criar um Flow * **FlowStartedEvent**: Emitido ao iniciar a execução de um Flow * **FlowFinishedEvent**: Emitido ao concluir a execução de um Flow * **FlowPlotEvent**: Emitido ao plotar um Flow * **MethodExecutionStartedEvent**: Emitido ao iniciar a execução de um método do Flow * **MethodExecutionFinishedEvent**: Emitido ao concluir a execução de um método do Flow * **MethodExecutionFailedEvent**: Emitido ao falhar na execução de um método do Flow ### Eventos de LLM * **LLMCallStartedEvent**: Emitido ao iniciar uma chamada LLM * **LLMCallCompletedEvent**: Emitido ao concluir uma chamada LLM * **LLMCallFailedEvent**: Emitido ao falhar uma chamada LLM * **LLMStreamChunkEvent**: Emitido para cada chunk recebido durante respostas em streaming do LLM ## Estrutura dos Handlers de Evento Cada handler de evento recebe dois parâmetros: 1. **source**: O objeto que emitiu o evento 2. **event**: A instância do evento, contendo dados específicos do evento A estrutura do objeto de evento depende do tipo do evento, mas todos herdam de `BaseEvent` e incluem: * **timestamp**: O horário em que o evento foi emitido * **type**: Identificador do tipo do evento Campos adicionais variam pelo tipo de evento. Por exemplo, `CrewKickoffCompletedEvent` inclui os campos `crew_name` e `output`. ## Uso Avançado: Handlers Escopados Para lidar temporariamente com eventos (útil para testes ou operações específicas), você pode usar o context manager `scoped_handlers`: ```python theme={null} 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("Este handler só existe neste contexto") # Faça algo que emita eventos # Fora do contexto, o handler temporário é removido ``` ## Casos de Uso Listeners de evento podem ser usados para várias finalidades: 1. **Log e Monitoramento**: Monitore a execução do seu Crew e registre eventos importantes 2. **Analytics**: Colete dados sobre o desempenho e comportamento do seu Crew 3. **Depuração**: Configure listeners temporários para debugar problemas específicos 4. **Integração**: Conecte o CrewAI a sistemas externos como plataformas de monitoramento, bancos de dados ou serviços de notificação 5. **Comportamento Personalizado**: Dispare ações personalizadas com base em eventos específicos ## Boas Práticas 1. **Mantenha Handlers Leves**: Handlers de eventos devem ser leves e evitar operações bloqueantes 2. **Tratamento de Erros**: Implemente tratamento de erros adequado nos event handlers para evitar que exceções afetem a execução principal 3. **Limpeza**: Se seu listener alocar recursos, garanta o devido fechamento/liberação 4. **Escuta Seletiva**: Escute apenas eventos que realmente precisa tratar 5. **Testes**: Teste seus listeners de evento isoladamente para garantir que se comportam conforme esperado Aproveitando o sistema de eventos do CrewAI, é possível estender a funcionalidade e integrá-lo facilmente à sua infraestrutura existente.