Agentes

​

Visão Geral de um Agente

No framework CrewAI, um Agent é uma unidade autônoma que pode:

• Executar tarefas específicas
• Tomar decisões com base em seu papel e objetivo
• Utilizar ferramentas para alcançar objetivos
• Comunicar e colaborar com outros agentes
• Manter a memória de interações
• Delegar tarefas, quando permitido

​

Atributos do Agente

​

Criando Agentes

Existem duas maneiras de criar agentes no CrewAI: usando configuração YAML (recomendado) ou definindo-os diretamente em código.

​

Configuração em YAML (Recomendado)

Usar configuração em YAML proporciona uma maneira mais limpa e fácil de manter para definir agentes. Recomendamos fortemente esse método em seus projetos CrewAI.

Depois de criar seu projeto CrewAI conforme descrito na seção de Instalação, navegue até o arquivo src/latest_ai_development/config/agents.yaml e edite o template para atender aos seus requisitos.

crew.kickoff(inputs={'topic': 'AI Agents'})

Veja um exemplo de como configurar agentes usando YAML:

# src/latest_ai_development/config/agents.yaml
researcher:
  role: >
    {topic} Senior Data Researcher
  goal: >
    Uncover cutting-edge developments in {topic}
  backstory: >
    You're a seasoned researcher with a knack for uncovering the latest
    developments in {topic}. Known for your ability to find the most relevant
    information and present it in a clear and concise manner.

reporting_analyst:
  role: >
    {topic} Reporting Analyst
  goal: >
    Create detailed reports based on {topic} data analysis and research findings
  backstory: >
    You're a meticulous analyst with a keen eye for detail. You're known for
    your ability to turn complex data into clear and concise reports, making
    it easy for others to understand and act on the information you provide.

Para usar essa configuração YAML no seu código, crie uma classe de crew que herda de CrewBase:

# src/latest_ai_development/crew.py
from crewai import Agent, Crew, Process
from crewai.project import CrewBase, agent, crew
from crewai_tools import SerperDevTool

@CrewBase
class LatestAiDevelopmentCrew():
  """LatestAiDevelopment crew"""

  agents_config = "config/agents.yaml"

  @agent
  def researcher(self) -> Agent:
    return Agent(
      config=self.agents_config['researcher'], # type: ignore[index]
      verbose=True,
      tools=[SerperDevTool()]
    )

  @agent
  def reporting_analyst(self) -> Agent:
    return Agent(
      config=self.agents_config['reporting_analyst'], # type: ignore[index]
      verbose=True
    )

​

Definição Direta em Código

Você pode criar agentes diretamente em código instanciando a classe Agent. Veja um exemplo abrangente mostrando todos os parâmetros disponíveis:

from crewai import Agent
from crewai_tools import SerperDevTool

# Crie um agente com todos os parâmetros disponíveis
agent = Agent(
    role="Senior Data Scientist",
    goal="Analyze and interpret complex datasets to provide actionable insights",
    backstory="With over 10 years of experience in data science and machine learning, "
              "you excel at finding patterns in complex datasets.",
    llm="gpt-4",  # Default: OPENAI_MODEL_NAME or "gpt-4"
    function_calling_llm=None,  # Optional: Separate LLM for tool calling
    verbose=False,  # Default: False
    allow_delegation=False,  # Default: False
    max_iter=20,  # Default: 20 iterations
    max_rpm=None,  # Optional: Rate limit for API calls
    max_execution_time=None,  # Optional: Maximum execution time in seconds
    max_retry_limit=2,  # Default: 2 retries on error
    allow_code_execution=False,  # Default: False
    code_execution_mode="safe",  # Default: "safe" (options: "safe", "unsafe")
    respect_context_window=True,  # Default: True
    use_system_prompt=True,  # Default: True
    multimodal=False,  # Default: False
    inject_date=False,  # Default: False
    date_format="%Y-%m-%d",  # Default: ISO format
    reasoning=False,  # Default: False
    max_reasoning_attempts=None,  # Default: None
    tools=[SerperDevTool()],  # Optional: List of tools
    knowledge_sources=None,  # Optional: List of knowledge sources
    embedder=None,  # Optional: Custom embedder configuration
    system_template=None,  # Optional: Custom system prompt template
    prompt_template=None,  # Optional: Custom prompt template
    response_template=None,  # Optional: Custom response template
    step_callback=None,  # Optional: Callback function for monitoring
)

Vamos detalhar algumas combinações de parâmetros-chave para casos de uso comuns:

​

Agente de Pesquisa Básico

research_agent = Agent(
    role="Research Analyst",
    goal="Find and summarize information about specific topics",
    backstory="You are an experienced researcher with attention to detail",
    tools=[SerperDevTool()],
    verbose=True  # Enable logging for debugging
)

​

Agente de Desenvolvimento de Código

dev_agent = Agent(
    role="Senior Python Developer",
    goal="Write and debug Python code",
    backstory="Expert Python developer with 10 years of experience",
    allow_code_execution=True,
    code_execution_mode="safe",  # Uses Docker for safety
    max_execution_time=300,  # 5-minute timeout
    max_retry_limit=3  # More retries for complex code tasks
)

​

Agente de Análise de Longa Duração

analysis_agent = Agent(
    role="Data Analyst",
    goal="Perform deep analysis of large datasets",
    backstory="Specialized in big data analysis and pattern recognition",
    memory=True,
    respect_context_window=True,
    max_rpm=10,  # Limit API calls
    function_calling_llm="gpt-4o-mini"  # Cheaper model for tool calls
)

​

Agente com Template Personalizado

custom_agent = Agent(
    role="Customer Service Representative",
    goal="Assist customers with their inquiries",
    backstory="Experienced in customer support with a focus on satisfaction",
    system_template="""<|start_header_id|>system<|end_header_id|>
                        {{ .System }}<|eot_id|>""",
    prompt_template="""<|start_header_id|>user<|end_header_id|>
                        {{ .Prompt }}<|eot_id|>""",
    response_template="""<|start_header_id|>assistant<|end_header_id|>
                        {{ .Response }}<|eot_id|>""",
)

​

Agente Ciente de Data, com Raciocínio

strategic_agent = Agent(
    role="Market Analyst",
    goal="Track market movements with precise date references and strategic planning",
    backstory="Expert in time-sensitive financial analysis and strategic reporting",
    inject_date=True,  # Automatically inject current date into tasks
    date_format="%B %d, %Y",  # Format as "May 21, 2025"
    reasoning=True,  # Enable strategic planning
    max_reasoning_attempts=2,  # Limit planning iterations
    verbose=True
)

​

Agente de Raciocínio

reasoning_agent = Agent(
    role="Strategic Planner",
    goal="Analyze complex problems and create detailed execution plans",
    backstory="Expert strategic planner who methodically breaks down complex challenges",
    reasoning=True,  # Enable reasoning and planning
    max_reasoning_attempts=3,  # Limit reasoning attempts
    max_iter=30,  # Allow more iterations for complex planning
    verbose=True
)

​

Agente Multimodal

multimodal_agent = Agent(
    role="Visual Content Analyst",
    goal="Analyze and process both text and visual content",
    backstory="Specialized in multimodal analysis combining text and image understanding",
    multimodal=True,  # Enable multimodal capabilities
    verbose=True
)

​

Detalhes dos Parâmetros

​

Parâmetros Críticos

• role, goal e backstory são obrigatórios e definem o comportamento do agente
• llm determina o modelo de linguagem utilizado (padrão: GPT-4 da OpenAI)

​

Memória e Contexto

• memory: Ative para manter o histórico de conversas
• respect_context_window: Evita problemas com limites de tokens
• knowledge_sources: Adicione bases de conhecimento específicas do domínio

​

Controle de Execução

• max_iter: Número máximo de tentativas antes da melhor resposta
• max_execution_time: Tempo limite em segundos
• max_rpm: Limite de requisições por minuto
• max_retry_limit: Tentativas de correção em erros

​

Execução de Código

• allow_code_execution: Deve ser True para permitir execução de código
• code_execution_mode:
  • "safe": Usa Docker (recomendado para produção)
  • "unsafe": Execução direta (apenas em ambientes confiáveis)

​

Funcionalidades Avançadas

• multimodal: Habilita capacidades multimodais para processar texto e conteúdo visual
• reasoning: Permite que o agente reflita e crie planos antes de executar tarefas
• inject_date: Injeta a data atual automaticamente nas descrições das tarefas

​

Templates

• system_template: Define o comportamento central do agente
• prompt_template: Estrutura o formato da entrada
• response_template: Formata as respostas do agente

​

Ferramentas do Agente

Agentes podem ser equipados com diversas ferramentas para ampliar suas capacidades. O CrewAI suporta ferramentas do:

• CrewAI Toolkit
• LangChain Tools

Veja como adicionar ferramentas a um agente:

from crewai import Agent
from crewai_tools import SerperDevTool, WikipediaTools

# Criar ferramentas
search_tool = SerperDevTool()
wiki_tool = WikipediaTools()

# Adicionar ferramentas ao agente
researcher = Agent(
    role="AI Technology Researcher",
    goal="Research the latest AI developments",
    tools=[search_tool, wiki_tool],
    verbose=True
)

​

Memória e Contexto do Agente

Agentes podem manter a memória de suas interações e usar contexto de tarefas anteriores. Isto é especialmente útil para fluxos de trabalho complexos onde é necessário reter informações ao longo de várias tarefas.

from crewai import Agent

analyst = Agent(
    role="Data Analyst",
    goal="Analyze and remember complex data patterns",
    memory=True,  # Enable memory
    verbose=True
)

​

Gerenciamento da Janela de Contexto

O CrewAI inclui um gerenciamento automático sofisticado de janela de contexto para lidar com situações onde as conversas excedem o limite de tokens do modelo de linguagem. Esse poderoso recurso é controlado pelo parâmetro respect_context_window.

​

Como Funciona o Gerenciamento de Janela de Contexto

Quando o histórico de conversas de um agente se torna muito grande para a janela de contexto do LLM, o CrewAI detecta essa situação automaticamente e pode:

1. Resumir o conteúdo automaticamente (com respect_context_window=True)
2. Parar a execução com erro (com respect_context_window=False)

​

Manipulação Automática de Contexto (respect_context_window=True)

Esta é a configuração padrão e recomendada para a maioria dos casos. Quando ativada, CrewAI irá:

# Agente com gerenciamento automático de contexto (padrão)
smart_agent = Agent(
    role="Research Analyst",
    goal="Analyze large documents and datasets",
    backstory="Expert at processing extensive information",
    respect_context_window=True,  # 🔑 Default: auto-handle context limits
    verbose=True
)

O que acontece quando os limites de contexto são excedidos:

• ⚠️ Mensagem de aviso: "Context length exceeded. Summarizing content to fit the model context window."
• 🔄 Resumir automaticamente: O CrewAI resume o histórico da conversa de forma inteligente
• ✅ Execução contínua: A execução da tarefa prossegue normalmente com o contexto resumido
• 📝 Informação preservada: Informações-chave são mantidas enquanto reduz a contagem de tokens

​

Limites Estritos de Contexto (respect_context_window=False)

Quando você precisa de controle total e prefere que a execução pare a perder qualquer informação:

# Agente com limites estritos de contexto
strict_agent = Agent(
    role="Legal Document Reviewer",
    goal="Provide precise legal analysis without information loss",
    backstory="Legal expert requiring complete context for accurate analysis",
    respect_context_window=False,  # ❌ Stop execution on context limit
    verbose=True
)

O que acontece quando os limites de contexto são excedidos:

• ❌ Mensagem de erro: "Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."
• 🛑 Execução interrompida: A execução da tarefa é parada imediatamente
• 🔧 Intervenção manual necessária: Você precisará modificar sua abordagem

​

Como Escolher a Melhor Configuração

​

Use respect_context_window=True (padrão) quando:

• Processar documentos grandes que podem ultrapassar os limites de contexto
• Conversas longas onde certo grau de resumo é aceitável
• Tarefas de pesquisa onde o contexto geral é mais importante que detalhes exatos
• Prototipagem e desenvolvimento quando se deseja execução robusta

# Ideal para processamento de documentos
document_processor = Agent(
    role="Document Analyst",
    goal="Extract insights from large research papers",
    backstory="Expert at analyzing extensive documentation",
    respect_context_window=True,  # Lida com documentos grandes sem problemas
    max_iter=50,  # Permite mais iterações para análises complexas
    verbose=True
)

​

Use respect_context_window=False quando:

• Precisão é crítica e perda de informação é inaceitável
• Tarefas jurídicas ou médicas que requerem contexto completo
• Revisão de código onde detalhes perdidos podem causar bugs
• Análise financeira onde precisão é fundamental

# Ideal para tarefas de precisão
precision_agent = Agent(
    role="Code Security Auditor",
    goal="Identify security vulnerabilities in code",
    backstory="Security expert requiring complete code context",
    respect_context_window=False,  # Prefere falhar do que análise incompleta
    max_retry_limit=1,  # Falha rápida em caso de problemas de contexto
    verbose=True
)

​

Abordagens Alternativas para Grandes Volumes de Dados

Ao lidar com conjuntos de dados muito grandes, considere as seguintes estratégias:

​

1. Use Ferramentas RAG

from crewai_tools import RagTool

# Crie uma ferramenta RAG para processamento de documentos grandes
rag_tool = RagTool()

rag_agent = Agent(
    role="Research Assistant",
    goal="Query large knowledge bases efficiently",
    backstory="Expert at using RAG tools for information retrieval",
    tools=[rag_tool],  # Usar RAG ao invés de grandes janelas de contexto
    respect_context_window=True,
    verbose=True
)

​

2. Use Fontes de Conhecimento

# Use fontes de conhecimento ao invés de prompts grandes
knowledge_agent = Agent(
    role="Knowledge Expert",
    goal="Answer questions using curated knowledge",
    backstory="Expert at leveraging structured knowledge sources",
    knowledge_sources=[your_knowledge_sources],  # Conhecimento pré-processado
    respect_context_window=True,
    verbose=True
)

​

Boas Práticas para Janela de Contexto

1. Monitore o uso de contexto: Ative verbose=True para visualizar o gerenciamento de contexto em ação
2. Otimize para eficiência: Estruture tarefas para minimizar o acúmulo de contexto
3. Use modelos apropriados: Escolha LLMs com janelas de contexto adequadas à sua tarefa
4. Teste ambos os modos: Experimente True e False para descobrir o que funciona melhor para seu caso
5. Combine com RAG: Utilize ferramentas RAG para grandes conjuntos de dados ao invés de depender apenas da janela de contexto

​

Solucionando Problemas de Contexto

Se você receber erros de limite de contexto:

# Solução rápida: Habilite manipulação automática
agent.respect_context_window = True

# Solução melhor: Use ferramentas RAG para dados volumosos
from crewai_tools import RagTool
agent.tools = [RagTool()]

# Alternativa: Divida as tarefas em partes menores
# Ou use fontes de conhecimento no lugar de prompts extensos

Se o resumo automático perder informações importantes:

# Desative o resumo automático e use RAG
agent = Agent(
    role="Detailed Analyst",
    goal="Maintain complete information accuracy",
    backstory="Expert requiring full context",
    respect_context_window=False,  # Sem resumo automático
    tools=[RagTool()],  # Use RAG para grandes volumes de dados
    verbose=True
)

​

Considerações e Boas Práticas Importantes

​

Segurança e Execução de Código

• Ao usar allow_code_execution, seja cauteloso com entradas do usuário e sempre as valide
• Use code_execution_mode: "safe" (Docker) em ambientes de produção
• Considere definir limites adequados de max_execution_time para evitar loops infinitos

​

Otimização de Performance

• Use respect_context_window: true para evitar problemas com limite de tokens
• Ajuste max_rpm para evitar rate limiting
• Ative cache: true para melhorar performance em tarefas repetitivas
• Ajuste max_iter e max_retry_limit conforme a complexidade da tarefa

​

Gerenciamento de Memória e Contexto

• Considere knowledge_sources para informações específicas de domínio
• Configure embedder ao usar modelos de embedding personalizados
• Use templates personalizados (system_template, prompt_template, response_template) para controle fino do comportamento do agente

​

Funcionalidades Avançadas

• Ative reasoning: true para agentes que precisam planejar e refletir antes de tarefas complexas
• Defina max_reasoning_attempts para controlar as iterações de planejamento (None para ilimitadas)
• Use inject_date: true para dar consciência temporal a agentes em tarefas que dependem de datas
• Personalize o formato de data com date_format usando códigos padrões do Python datetime
• Ative multimodal: true para agentes que precisam processar texto e imagem

​

Colaboração entre Agentes

• Ative allow_delegation: true quando agentes precisarem trabalhar juntos
• Use step_callback para monitorar e registrar interações dos agentes
• Considere usar LLMs diferentes para propósitos distintos:
  • llm principal para raciocínio complexo
  • function_calling_llm para uso eficiente de ferramentas

​

Consciência de Data e Raciocínio

• Use inject_date: true para fornecer consciência temporal aos agentes em tarefas sensíveis ao tempo
• Customize o formato de data com date_format usando códigos standards de datetime do Python
• Códigos válidos incluem: %Y (ano), %m (mês), %d (dia), %B (nome completo do mês), etc.
• Formatos de data inválidos serão registrados como avisos e não modificarão a descrição da tarefa
• Ative reasoning: true para tarefas complexas que se beneficiam de planejamento e reflexão antecipados

​

Compatibilidade de Modelos

• Defina use_system_prompt: false para modelos antigos que não suportam mensagens de sistema
• Certifique-se que o llm escolhido suporta as funcionalidades necessárias (como function calling)

​

Solução de Problemas Comuns

1. Limite de Taxa (Rate Limiting): Se atingir limites de API:

   • Implemente o max_rpm adequado
   • Use cache para operações repetitivas
   • Considere agrupar requisições em lote

2. Erros de Janela de Contexto: Se exceder limites de contexto:

   • Habilite respect_context_window
   • Otimize seus prompts
   • Limpe periodicamente a memória do agente

3. Problemas de Execução de Código: Se a execução de código falhar:

   • Verifique se o Docker está instalado para o modo seguro
   • Cheque permissões de execução
   • Revise as configurações do sandbox de código

4. Problemas de Memória: Se as respostas do agente parecerem inconsistentes:

   • Cheque a configuração das fontes de conhecimento
   • Analise o gerenciamento do histórico de conversas

Lembre-se de que agentes são mais eficientes quando configurados de acordo com o caso de uso específico. Reserve um tempo para entender seus requisitos e ajustar esses parâmetros conforme necessário.