Pular para o conteúdo
CrewAI Documentation

Avaliando Casos de Uso para CrewAI

Entendendo o Framework de Decisão

Seção intitulada “Entendendo o Framework de Decisão”

Ao construir aplicações de IA com CrewAI, uma das decisões mais importantes que você tomará é escolher a abordagem correta para o seu caso de uso específico. Você deve usar uma Crew? Um Flow? Uma combinação dos dois? Este guia vai ajudar você a avaliar seus requisitos e tomar decisões arquitetônicas embasadas.

No centro dessa decisão está o entendimento da relação entre complexidade e precisão em sua aplicação:

Matriz de Complexidade vs. Precisão
Matriz de Complexidade vs. Precisão para Aplicações CrewAI

Essa matriz ajuda a visualizar como diferentes abordagens se alinham com os requisitos variados de complexidade e precisão. Vamos explorar o significado de cada quadrante e como isso orienta suas escolhas arquiteturais.

Explicando a Matriz Complexidade-Precisão

Seção intitulada “Explicando a Matriz Complexidade-Precisão”

O que é Complexidade?

Seção intitulada “O que é Complexidade?”

No contexto das aplicações CrewAI, complexidade refere-se a:

  • O número de etapas ou operações distintas necessárias
  • A diversidade de tarefas que precisam ser realizadas
  • As interdependências entre diferentes componentes
  • A necessidade de lógica condicional e ramificações
  • A sofisticação do fluxo de trabalho como um todo

O que é Precisão?

Seção intitulada “O que é Precisão?”

Precisão nesse contexto refere-se a:

  • O grau de exatidão exigido no resultado final
  • A necessidade de resultados estruturados e previsíveis
  • A importância da reprodutibilidade
  • O nível de controle necessário sobre cada etapa
  • A tolerância à variação nos resultados

Os Quatro Quadrantes

Seção intitulada “Os Quatro Quadrantes”

1. Baixa Complexidade, Baixa Precisão

Seção intitulada “1. Baixa Complexidade, Baixa Precisão”

Características:

  • Tarefas simples e diretas
  • Tolerância a alguma variação nos resultados
  • Número limitado de etapas
  • Aplicações criativas ou exploratórias

Abordagem Recomendada: Crews simples com poucos agentes

Exemplos de Casos de Uso:

  • Geração básica de conteúdo
  • Brainstorming de ideias
  • Tarefas simples de sumarização
  • Assistência à escrita criativa

2. Baixa Complexidade, Alta Precisão

Seção intitulada “2. Baixa Complexidade, Alta Precisão”

Características:

  • Fluxos de trabalho simples que exigem resultados exatos e estruturados
  • Necessidade de resultados reproduzíveis
  • Poucas etapas, mas alto requisito de precisão
  • Frequentemente envolve processamento ou transformação de dados

Abordagem Recomendada: Flows com chamadas diretas a LLM ou Crews simples com saídas estruturadas

Exemplos de Casos de Uso:

  • Extração e transformação de dados
  • Preenchimento e validação de formulários
  • Geração estruturada de conteúdo (JSON, XML)
  • Tarefas simples de classificação

3. Alta Complexidade, Baixa Precisão

Seção intitulada “3. Alta Complexidade, Baixa Precisão”

Características:

  • Processos multiestágio com muitas etapas
  • Saídas criativas ou exploratórias
  • Interações complexas entre componentes
  • Tolerância à variação nos resultados finais

Abordagem Recomendada: Crews complexas com múltiplos agentes especializados

Exemplos de Casos de Uso:

  • Pesquisa e análise
  • Pipelines de criação de conteúdo
  • Análise exploratória de dados
  • Solução criativa de problemas

4. Alta Complexidade, Alta Precisão

Seção intitulada “4. Alta Complexidade, Alta Precisão”

Características:

  • Fluxos de trabalho complexos que requerem saídas estruturadas
  • Múltiplas etapas interdependentes com rígida exigência de precisão
  • Necessidade tanto de processamento sofisticado quanto de resultados precisos
  • Frequentemente aplicações críticas

Abordagem Recomendada: Flows orquestrando múltiplas Crews com etapas de validação

Exemplos de Casos de Uso:

  • Sistemas corporativos de suporte à decisão
  • Pipelines complexos de processamento de dados
  • Processamento de documentos em múltiplos estágios
  • Aplicações em indústrias reguladas

Escolhendo Entre Crews e Flows

Seção intitulada “Escolhendo Entre Crews e Flows”

Quando Escolher Crews

Seção intitulada “Quando Escolher Crews”

Crews são ideais quando:

  1. Você precisa de inteligência colaborativa - Múltiplos agentes com especializações diferentes precisam trabalhar juntos
  2. O problema requer pensamento emergente - A solução se beneficia de diferentes perspectivas e abordagens
  3. A tarefa é principalmente criativa ou analítica - O trabalho envolve pesquisa, criação de conteúdo ou análise
  4. Você valoriza adaptabilidade mais do que estrutura rígida - O fluxo de trabalho pode se beneficiar da autonomia dos agentes
  5. O formato da saída pode ser um pouco flexível - Alguma variação na estrutura do resultado é aceitável
# Example: Research Crew for market analysis
from crewai import Agent, Crew, Process, Task


# Create specialized agents
researcher = Agent(
    role="Market Research Specialist",
    goal="Find comprehensive market data on emerging technologies",
    backstory="You are an expert at discovering market trends and gathering data."
)


analyst = Agent(
    role="Market Analyst",
    goal="Analyze market data and identify key opportunities",
    backstory="You excel at interpreting market data and spotting valuable insights."
)


# Define their tasks
research_task = Task(
    description="Research the current market landscape for AI-powered healthcare solutions",
    expected_output="Comprehensive market data including key players, market size, and growth trends",
    agent=researcher
)


analysis_task = Task(
    description="Analyze the market data and identify the top 3 investment opportunities",
    expected_output="Analysis report with 3 recommended investment opportunities and rationale",
    agent=analyst,
    context=[research_task]
)


# Create the crew
market_analysis_crew = Crew(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    process=Process.sequential,
    verbose=True
)


# Run the crew
result = market_analysis_crew.kickoff()

Quando Escolher Flows

Seção intitulada “Quando Escolher Flows”

Flows são ideais quando:

  1. Você precisa de controle preciso da execução - O fluxo de trabalho exige sequenciamento exato e gerenciamento de estado
  2. A aplicação tem requisitos complexos de estado - Você precisa manter e transformar estado ao longo de múltiplas etapas
  3. Você precisa de saídas estruturadas e previsíveis - A aplicação exige resultados consistentes e formatados
  4. O fluxo de trabalho envolve lógica condicional - Caminhos diferentes precisam ser seguidos com base em resultados intermediários
  5. Você precisa combinar IA com código procedural - A solução demanda tanto capacidades de IA quanto programação tradicional
# Example: Customer Support Flow with structured processing
from crewai.flow.flow import Flow, listen, router, start
from pydantic import BaseModel
from typing import List, Dict


# Define structured state
class SupportTicketState(BaseModel):
    ticket_id: str = ""
    customer_name: str = ""
    issue_description: str = ""
    category: str = ""
    priority: str = "medium"
    resolution: str = ""
    satisfaction_score: int = 0


class CustomerSupportFlow(Flow[SupportTicketState]):
    @start()
    def receive_ticket(self):
        # In a real app, this might come from an API
        self.state.ticket_id = "TKT-12345"
        self.state.customer_name = "Alex Johnson"
        self.state.issue_description = "Unable to access premium features after payment"
        return "Ticket received"


    @listen(receive_ticket)
    def categorize_ticket(self, _):
        # Use a direct LLM call for categorization
        from crewai import LLM
        llm = LLM(model="openai/gpt-4o-mini")


        prompt = f"""
        Categorize the following customer support issue into one of these categories:
        - Billing
        - Account Access
        - Technical Issue
        - Feature Request
        - Other


        Issue: {self.state.issue_description}


        Return only the category name.
        """


        self.state.category = llm.call(prompt).strip()
        return self.state.category


    @router(categorize_ticket)
    def route_by_category(self, category):
        # Route to different handlers based on category
        return category.lower().replace(" ", "_")


    @listen("billing")
    def handle_billing_issue(self):
        # Handle billing-specific logic
        self.state.priority = "high"
        # More billing-specific processing...
        return "Billing issue handled"


    @listen("account_access")
    def handle_access_issue(self):
        # Handle access-specific logic
        self.state.priority = "high"
        # More access-specific processing...
        return "Access issue handled"


    # Additional category handlers...


    @listen("billing", "account_access", "technical_issue", "feature_request", "other")
    def resolve_ticket(self, resolution_info):
        # Final resolution step
        self.state.resolution = f"Issue resolved: {resolution_info}"
        return self.state.resolution


# Run the flow
support_flow = CustomerSupportFlow()
result = support_flow.kickoff()

Quando Combinar Crews e Flows

Seção intitulada “Quando Combinar Crews e Flows”

As aplicações mais sofisticadas frequentemente se beneficiam da combinação de Crews e Flows:

  1. Processos complexos em múltiplos estágios - Use Flows para orquestrar o processo geral e Crews para sub-tarefas complexas
  2. Aplicações que exigem criatividade e estrutura - Use Crews para tarefas criativas e Flows para processamento estruturado
  3. Aplicações corporativas de IA - Use Flows para gerenciar estado e fluxo de processo enquanto aproveita Crews para tarefas especializadas
# Example: Content Production Pipeline combining Crews and Flows
from crewai.flow.flow import Flow, listen, start
from crewai import Agent, Crew, Process, Task
from pydantic import BaseModel
from typing import List, Dict


class ContentState(BaseModel):
    topic: str = ""
    target_audience: str = ""
    content_type: str = ""
    outline: Dict = {}
    draft_content: str = ""
    final_content: str = ""
    seo_score: int = 0


class ContentProductionFlow(Flow[ContentState]):
    @start()
    def initialize_project(self):
        # Set initial parameters
        self.state.topic = "Sustainable Investing"
        self.state.target_audience = "Millennial Investors"
        self.state.content_type = "Blog Post"
        return "Project initialized"


    @listen(initialize_project)
    def create_outline(self, _):
        # Use a research crew to create an outline
        researcher = Agent(
            role="Content Researcher",
            goal=f"Research {self.state.topic} for {self.state.target_audience}",
            backstory="You are an expert researcher with deep knowledge of content creation."
        )


        outliner = Agent(
            role="Content Strategist",
            goal=f"Create an engaging outline for a {self.state.content_type}",
            backstory="You excel at structuring content for maximum engagement."
        )


        research_task = Task(
            description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}",
            expected_output="Comprehensive research notes with key points and statistics",
            agent=researcher
        )


        outline_task = Task(
            description=f"Create an outline for a {self.state.content_type} about {self.state.topic}",
            expected_output="Detailed content outline with sections and key points",
            agent=outliner,
            context=[research_task]
        )


        outline_crew = Crew(
            agents=[researcher, outliner],
            tasks=[research_task, outline_task],
            process=Process.sequential,
            verbose=True
        )


        # Run the crew and store the result
        result = outline_crew.kickoff()


        # Parse the outline (in a real app, you might use a more robust parsing approach)
        import json
        try:
            self.state.outline = json.loads(result.raw)
        except:
            # Fallback if not valid JSON
            self.state.outline = {"sections": result.raw}


        return "Outline created"


    @listen(create_outline)
    def write_content(self, _):
        # Use a writing crew to create the content
        writer = Agent(
            role="Content Writer",
            goal=f"Write engaging content for {self.state.target_audience}",
            backstory="You are a skilled writer who creates compelling content."
        )


        editor = Agent(
            role="Content Editor",
            goal="Ensure content is polished, accurate, and engaging",
            backstory="You have a keen eye for detail and a talent for improving content."
        )


        writing_task = Task(
            description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}",
            expected_output="Complete draft content in markdown format",
            agent=writer
        )


        editing_task = Task(
            description="Edit and improve the draft content for clarity, engagement, and accuracy",
            expected_output="Polished final content in markdown format",
            agent=editor,
            context=[writing_task]
        )


        writing_crew = Crew(
            agents=[writer, editor],
            tasks=[writing_task, editing_task],
            process=Process.sequential,
            verbose=True
        )


        # Run the crew and store the result
        result = writing_crew.kickoff()
        self.state.final_content = result.raw


        return "Content created"


    @listen(write_content)
    def optimize_for_seo(self, _):
        # Use a direct LLM call for SEO optimization
        from crewai import LLM
        llm = LLM(model="openai/gpt-4o-mini")


        prompt = f"""
        Analyze this content for SEO effectiveness for the keyword "{self.state.topic}".
        Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement.


        Content: {self.state.final_content[:1000]}... (truncated for brevity)


        Format your response as JSON with the following structure:
        {{
            "score": 85,
            "recommendations": [
                "Recommendation 1",
                "Recommendation 2",
                "Recommendation 3"
            ]
        }}
        """


        seo_analysis = llm.call(prompt)


        # Parse the SEO analysis
        import json
        try:
            analysis = json.loads(seo_analysis)
            self.state.seo_score = analysis.get("score", 0)
            return analysis
        except:
            self.state.seo_score = 50
            return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]}


# Run the flow
content_flow = ContentProductionFlow()
result = content_flow.kickoff()

Framework Prático de Avaliação

Seção intitulada “Framework Prático de Avaliação”

Para determinar a abordagem certa para seu caso de uso específico, siga este framework passo a passo:

Passo 1: Avalie a Complexidade

Seção intitulada “Passo 1: Avalie a Complexidade”

Classifique a complexidade do seu aplicativo numa escala de 1-10 considerando:

  1. Número de etapas: Quantas operações distintas são necessárias?

    • 1-3 etapas: Baixa complexidade (1-3)
    • 4-7 etapas: Média complexidade (4-7)
    • 8+ etapas: Alta complexidade (8-10)

  2. Interdependências: Quão interligadas estão as partes diferentes?

    • Poucas dependências: Baixa complexidade (1-3)
    • Algumas dependências: Média complexidade (4-7)
    • Muitas dependências complexas: Alta complexidade (8-10)

  3. Lógica condicional: Quanto de ramificação e tomada de decisão é necessário?

    • Processo linear: Baixa complexidade (1-3)
    • Alguma ramificação: Média complexidade (4-7)
    • Árvores de decisão complexas: Alta complexidade (8-10)

  4. Conhecimento de domínio: Quão especializado deve ser o conhecimento requerido?

    • Conhecimento geral: Baixa complexidade (1-3)
    • Algum conhecimento especializado: Média complexidade (4-7)
    • Grande especialização em múltiplos domínios: Alta complexidade (8-10)

Calcule a média das pontuações para determinar sua complexidade geral.

Passo 2: Avalie os Requisitos de Precisão

Seção intitulada “Passo 2: Avalie os Requisitos de Precisão”

Classifique seus requisitos de precisão numa escala de 1-10 considerando:

  1. Estrutura da saída: Quão estruturado o resultado deve ser?

    • Texto livre: Baixa precisão (1-3)
    • Semi-estruturado: Média precisão (4-7)
    • Estritamente formatado (JSON, XML): Alta precisão (8-10)

  2. Necessidade de exatidão: Qual a importância da precisão factual?

    • Conteúdo criativo: Baixa precisão (1-3)
    • Conteúdo informacional: Média precisão (4-7)
    • Informação crítica: Alta precisão (8-10)

  3. Reprodutibilidade: Quão consistentes devem ser os resultados entre execuções?

    • Variação aceitável: Baixa precisão (1-3)
    • Alguma consistência necessária: Média precisão (4-7)
    • Exata reprodutibilidade: Alta precisão (8-10)

  4. Tolerância a erros: Qual o impacto de erros?

    • Baixo impacto: Baixa precisão (1-3)
    • Impacto moderado: Média precisão (4-7)
    • Alto impacto: Alta precisão (8-10)

Calcule a média das pontuações para determinar seu requisito geral de precisão.

Passo 3: Mapeie na Matriz

Seção intitulada “Passo 3: Mapeie na Matriz”

Plote as pontuações de complexidade e precisão na matriz:

  • Baixa Complexidade (1-4), Baixa Precisão (1-4): Crews simples
  • Baixa Complexidade (1-4), Alta Precisão (5-10): Flows com chamadas diretas a LLM
  • Alta Complexidade (5-10), Baixa Precisão (1-4): Crews complexas
  • Alta Complexidade (5-10), Alta Precisão (5-10): Flows orquestrando Crews

Passo 4: Considere Fatores Adicionais

Seção intitulada “Passo 4: Considere Fatores Adicionais”

Além de complexidade e precisão, considere:

  1. Tempo de desenvolvimento: Crews costumam ser mais rápidas para prototipar
  2. Necessidades de manutenção: Flows proporcionam melhor manutenção a longo prazo
  3. Expertise do time: Considere a familiaridade de sua equipe com as abordagens
  4. Requisitos de escalabilidade: Flows normalmente escalam melhor para aplicações complexas
  5. Necessidades de integração: Considere como a solução se integrará aos sistemas existentes

Conclusão

Seção intitulada “Conclusão”

Escolher entre Crews e Flows — ou combiná-los — é uma decisão arquitetônica crítica que impacta a efetividade, manutenibilidade e escalabilidade da sua aplicação CrewAI. Ao avaliar seu caso de uso nas dimensões de complexidade e precisão, você toma decisões inteligentes que alinham-se aos seus requisitos.

Lembre-se de que a melhor abordagem geralmente evolui na medida em que sua aplicação amadurece. Comece com a solução mais simples que atenda às suas necessidades e esteja preparado para refinar sua arquitetura conforme for ganhando experiência e seus requisitos se tornarem mais claros.

Próximos Passos

Seção intitulada “Próximos Passos”