Visão Geral dos Hooks de Execução

Os Hooks de Execução fornecem controle fino sobre o comportamento em tempo de execução dos seus agentes CrewAI. Diferentemente dos hooks de kickoff que são executados antes e depois da execução da crew, os hooks de execução interceptam operações específicas durante a execução do agente, permitindo que você modifique comportamentos, implemente verificações de segurança e adicione monitoramento abrangente.

Tipos de Hooks de Execução

O CrewAI fornece duas categorias principais de hooks de execução:

1. Hooks de Chamada LLM

Controle e monitore interações com o modelo de linguagem:

Antes da Chamada LLM: Modifique prompts, valide entradas, implemente gates de aprovação
Depois da Chamada LLM: Transforme respostas, sanitize saídas, atualize histórico de conversação

Casos de Uso:

Limitação de iterações
Rastreamento de custos e monitoramento de uso de tokens
Sanitização de respostas e filtragem de conteúdo
Aprovação humana para chamadas LLM
Adição de diretrizes de segurança ou contexto
Logging de debug e inspeção de requisição/resposta

Ver Documentação de Hooks LLM →

2. Hooks de Chamada de Ferramenta

Controle e monitore execução de ferramentas:

Antes da Chamada de Ferramenta: Modifique entradas, valide parâmetros, bloqueie operações perigosas
Depois da Chamada de Ferramenta: Transforme resultados, sanitize saídas, registre detalhes de execução

Casos de Uso:

Guardrails de segurança para operações destrutivas
Aprovação humana para ações sensíveis
Validação e sanitização de entrada
Cache de resultados e limitação de taxa
Análise de uso de ferramentas
Logging de debug e monitoramento

Ver Documentação de Hooks de Ferramenta →

Métodos de Registro

1. Hooks Baseados em Decoradores (Recomendado)

A maneira mais limpa e pythônica de registrar hooks:

from crewai.hooks import before_llm_call, after_llm_call, before_tool_call, after_tool_call

@before_llm_call
def limit_iterations(context):
    """Previne loops infinitos limitando iterações."""
    if context.iterations > 10:
        return False  # Bloquear execução
    return None

@after_llm_call
def sanitize_response(context):
    """Remove dados sensíveis das respostas do LLM."""
    if "API_KEY" in context.response:
        return context.response.replace("API_KEY", "[CENSURADO]")
    return None

@before_tool_call
def block_dangerous_tools(context):
    """Bloqueia operações destrutivas."""
    if context.tool_name == "delete_database":
        return False  # Bloquear execução
    return None

@after_tool_call
def log_tool_result(context):
    """Registra execução de ferramenta."""
    print(f"Ferramenta {context.tool_name} concluída")
    return None

2. Hooks com Escopo de Crew

Aplica hooks apenas a instâncias específicas de crew:

from crewai import CrewBase
from crewai.project import crew
from crewai.hooks import before_llm_call_crew, after_tool_call_crew

@CrewBase
class MyProjCrew:
    @before_llm_call_crew
    def validate_inputs(self, context):
        # Aplica-se apenas a esta crew
        print(f"Chamada LLM em {self.__class__.__name__}")
        return None

    @after_tool_call_crew
    def log_results(self, context):
        # Logging específico da crew
        print(f"Resultado da ferramenta: {context.tool_result[:50]}...")
        return None

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential
        )

Fluxo de Execução de Hooks

Fluxo de Chamada LLM

Agente precisa chamar LLM
    ↓
[Hooks Antes da Chamada LLM Executam]
    ├→ Hook 1: Validar contagem de iterações
    ├→ Hook 2: Adicionar contexto de segurança
    └→ Hook 3: Registrar requisição
    ↓
Se algum hook retornar False:
    ├→ Bloquear chamada LLM
    └→ Lançar ValueError
    ↓
Se todos os hooks retornarem True/None:
    ├→ Chamada LLM prossegue
    └→ Resposta gerada
    ↓
[Hooks Depois da Chamada LLM Executam]
    ├→ Hook 1: Sanitizar resposta
    ├→ Hook 2: Registrar resposta
    └→ Hook 3: Atualizar métricas
    ↓
Resposta final retornada

Fluxo de Chamada de Ferramenta

Agente precisa executar ferramenta
    ↓
[Hooks Antes da Chamada de Ferramenta Executam]
    ├→ Hook 1: Verificar se ferramenta é permitida
    ├→ Hook 2: Validar entradas
    └→ Hook 3: Solicitar aprovação se necessário
    ↓
Se algum hook retornar False:
    ├→ Bloquear execução da ferramenta
    └→ Retornar mensagem de erro
    ↓
Se todos os hooks retornarem True/None:
    ├→ Execução da ferramenta prossegue
    └→ Resultado gerado
    ↓
[Hooks Depois da Chamada de Ferramenta Executam]
    ├→ Hook 1: Sanitizar resultado
    ├→ Hook 2: Fazer cache do resultado
    └→ Hook 3: Registrar métricas
    ↓
Resultado final retornado

Objetos de Contexto de Hook

LLMCallHookContext

Fornece acesso ao estado de execução do LLM:

class LLMCallHookContext:
    executor: CrewAgentExecutor  # Acesso completo ao executor
    messages: list               # Lista de mensagens mutável
    agent: Agent                 # Agente atual
    task: Task                   # Tarefa atual
    crew: Crew                   # Instância da crew
    llm: BaseLLM                 # Instância do LLM
    iterations: int              # Iteração atual
    response: str | None         # Resposta do LLM (hooks posteriores)

ToolCallHookContext

Fornece acesso ao estado de execução da ferramenta:

class ToolCallHookContext:
    tool_name: str               # Ferramenta sendo chamada
    tool_input: dict             # Parâmetros de entrada mutáveis
    tool: CrewStructuredTool     # Instância da ferramenta
    agent: Agent | None          # Agente executando
    task: Task | None            # Tarefa atual
    crew: Crew | None            # Instância da crew
    tool_result: str | None      # Resultado da ferramenta (hooks posteriores)

Padrões Comuns

Segurança e Validação

@before_tool_call
def safety_check(context):
    """Bloqueia operações destrutivas."""
    dangerous = ['delete_file', 'drop_table', 'system_shutdown']
    if context.tool_name in dangerous:
        print(f"🛑 Bloqueado: {context.tool_name}")
        return False
    return None

@before_llm_call
def iteration_limit(context):
    """Previne loops infinitos."""
    if context.iterations > 15:
        print("⛔ Máximo de iterações excedido")
        return False
    return None

Humano no Loop

@before_tool_call
def require_approval(context):
    """Requer aprovação para operações sensíveis."""
    sensitive = ['send_email', 'make_payment', 'post_message']

    if context.tool_name in sensitive:
        response = context.request_human_input(
            prompt=f"Aprovar {context.tool_name}?",
            default_message="Digite 'sim' para aprovar:"
        )

        if response.lower() != 'sim':
            return False

    return None

Monitoramento e Análise

from collections import defaultdict
import time

metrics = defaultdict(lambda: {'count': 0, 'total_time': 0})

@before_tool_call
def start_timer(context):
    context.tool_input['_start'] = time.time()
    return None

@after_tool_call
def track_metrics(context):
    start = context.tool_input.get('_start', time.time())
    duration = time.time() - start

    metrics[context.tool_name]['count'] += 1
    metrics[context.tool_name]['total_time'] += duration

    return None

Gerenciamento de Hooks

Limpar Todos os Hooks

from crewai.hooks import clear_all_global_hooks

# Limpa todos os hooks de uma vez
result = clear_all_global_hooks()
print(f"Limpou {result['total']} hooks")

Limpar Tipos Específicos de Hooks

from crewai.hooks import (
    clear_before_llm_call_hooks,
    clear_after_llm_call_hooks,
    clear_before_tool_call_hooks,
    clear_after_tool_call_hooks
)

# Limpar tipos específicos
llm_before_count = clear_before_llm_call_hooks()
tool_after_count = clear_after_tool_call_hooks()

Melhores Práticas

1. Mantenha os Hooks Focados

Cada hook deve ter uma responsabilidade única e clara.

2. Trate Erros Graciosamente

@before_llm_call
def safe_hook(context):
    try:
        if some_condition:
            return False
    except Exception as e:
        print(f"Erro no hook: {e}")
        return None  # Permitir execução apesar do erro

3. Modifique o Contexto In-Place

# ✅ Correto - modificar in-place
@before_llm_call
def add_context(context):
    context.messages.append({"role": "system", "content": "Seja conciso"})

# ❌ Errado - substitui referência
@before_llm_call
def wrong_approach(context):
    context.messages = [{"role": "system", "content": "Seja conciso"}]

4. Use Type Hints

from crewai.hooks import LLMCallHookContext, ToolCallHookContext

def my_llm_hook(context: LLMCallHookContext) -> bool | None:
    return None

def my_tool_hook(context: ToolCallHookContext) -> str | None:
    return None

5. Limpe em Testes

import pytest
from crewai.hooks import clear_all_global_hooks

@pytest.fixture(autouse=True)
def clean_hooks():
    """Reseta hooks antes de cada teste."""
    yield
    clear_all_global_hooks()

Quando Usar Qual Hook

Use Hooks LLM Quando:

Implementar limites de iteração
Adicionar contexto ou diretrizes de segurança aos prompts
Rastrear uso de tokens e custos
Sanitizar ou transformar respostas
Implementar gates de aprovação para chamadas LLM
Fazer debug de interações de prompt/resposta

Use Hooks de Ferramenta Quando:

Bloquear operações perigosas ou destrutivas
Validar entradas de ferramenta antes da execução
Implementar gates de aprovação para ações sensíveis
Fazer cache de resultados de ferramenta
Rastrear uso e performance de ferramentas
Sanitizar saídas de ferramenta
Limitar taxa de chamadas de ferramenta

Use Ambos Quando:

Construir sistemas abrangentes de observabilidade, segurança ou aprovação que precisam monitorar todas as operações do agente.

Documentação Relacionada

Hooks de Chamada LLM → - Documentação detalhada de hooks LLM
Hooks de Chamada de Ferramenta → - Documentação detalhada de hooks de ferramenta
Hooks Antes e Depois do Kickoff → - Hooks do ciclo de vida da crew
Humano no Loop → - Padrões de entrada humana

Conclusão

Os Hooks de Execução fornecem controle poderoso sobre o comportamento em tempo de execução do agente. Use-os para implementar guardrails de segurança, fluxos de trabalho de aprovação, monitoramento abrangente e lógica de negócio personalizada. Combinados com tratamento adequado de erros, segurança de tipos e considerações de performance, os hooks permitem sistemas de agentes seguros, prontos para produção e observáveis.

Começando

Guias

Conceitos-Chave

Integração MCP

Ferramentas

Observabilidade

Aprenda

Telemetria

Visão Geral dos Hooks de Execução

Tipos de Hooks de Execução

1. Hooks de Chamada LLM

2. Hooks de Chamada de Ferramenta

Métodos de Registro

1. Hooks Baseados em Decoradores (Recomendado)

2. Hooks com Escopo de Crew

Fluxo de Execução de Hooks

Fluxo de Chamada LLM

Fluxo de Chamada de Ferramenta

Objetos de Contexto de Hook

LLMCallHookContext

ToolCallHookContext

Padrões Comuns

Segurança e Validação

Humano no Loop

Monitoramento e Análise

Gerenciamento de Hooks

Limpar Todos os Hooks

Limpar Tipos Específicos de Hooks

Melhores Práticas

1. Mantenha os Hooks Focados

2. Trate Erros Graciosamente

3. Modifique o Contexto In-Place

4. Use Type Hints

5. Limpe em Testes

Quando Usar Qual Hook

Use Hooks LLM Quando:

Use Hooks de Ferramenta Quando:

Use Ambos Quando:

Documentação Relacionada

Conclusão

Começando

Guias

Conceitos-Chave

Integração MCP

Ferramentas

Observabilidade

Aprenda

Telemetria

​Tipos de Hooks de Execução

​1. Hooks de Chamada LLM

​2. Hooks de Chamada de Ferramenta

​Métodos de Registro

​1. Hooks Baseados em Decoradores (Recomendado)

​2. Hooks com Escopo de Crew

​Fluxo de Execução de Hooks

​Fluxo de Chamada LLM

​Fluxo de Chamada de Ferramenta

​Objetos de Contexto de Hook

​LLMCallHookContext

​ToolCallHookContext

​Padrões Comuns

​Segurança e Validação

​Humano no Loop

​Monitoramento e Análise

​Gerenciamento de Hooks

​Limpar Todos os Hooks

​Limpar Tipos Específicos de Hooks

​Melhores Práticas

​1. Mantenha os Hooks Focados

​2. Trate Erros Graciosamente

​3. Modifique o Contexto In-Place

​4. Use Type Hints

​5. Limpe em Testes

​Quando Usar Qual Hook

​Use Hooks LLM Quando:

​Use Hooks de Ferramenta Quando:

​Use Ambos Quando:

​Documentação Relacionada

​Conclusão

Tipos de Hooks de Execução

1. Hooks de Chamada LLM

2. Hooks de Chamada de Ferramenta

Métodos de Registro

1. Hooks Baseados em Decoradores (Recomendado)

2. Hooks com Escopo de Crew

Fluxo de Execução de Hooks

Fluxo de Chamada LLM

Fluxo de Chamada de Ferramenta

Objetos de Contexto de Hook

LLMCallHookContext

ToolCallHookContext

Padrões Comuns

Segurança e Validação

Humano no Loop

Monitoramento e Análise

Gerenciamento de Hooks

Limpar Todos os Hooks

Limpar Tipos Específicos de Hooks

Melhores Práticas

1. Mantenha os Hooks Focados

2. Trate Erros Graciosamente

3. Modifique o Contexto In-Place

4. Use Type Hints

5. Limpe em Testes

Quando Usar Qual Hook

Use Hooks LLM Quando:

Use Hooks de Ferramenta Quando:

Use Ambos Quando:

Documentação Relacionada

Conclusão