Executando CrewAI com Entradas Dinâmicas em Python: Guia Completo para Iniciar Fluxos

Se você é desenvolvedor e está começando a explorar o CrewAI, esta biblioteca Python poderosa para orquestração de múltiplos agentes inteligentes, este artigo é feito para você. Aqui, você aprenderá, de forma didática e prática, como iniciar um fluxo de trabalho do CrewAI usando o método crew.kickoff(), passando um dicionário de inputs para preencher variáveis dinâmicas em suas tarefas definidas em YAML. Assim, você poderá construir automações flexíveis e altamente customizáveis, simplificando a execução de fluxos complexos.

O que é CrewAI?

CrewAI é uma biblioteca em Python que permite orquestrar um conjunto de agentes (conhecidos como “crew”) que colaboram para realizar tarefas complexas definidas em arquivos YAML ou diretamente em código. Essa arquitetura possibilita definir agentes com funções específicas, tarefas com descrições dinâmicas, e processos de execução sofisticados, tudo isso alimentado por dados de entrada que podem variar a cada execução, tornando seu fluxo altamente reutilizável e adaptável.

1. Conceito Central: kickoff() e Inputs Dinâmicos

O método kickoff() é o ponto de partida para iniciar qualquer fluxo de trabalho no CrewAI. Ele aceita um parâmetro inputs, que é um dicionário Python. Este dicionário é fundamental para popular placeholders (variáveis dinâmicas) em suas definições de tarefas no YAML, como {topic}, {user}, entre outros. Com isso, você pode alterar o comportamento da execução sem a necessidade de modificar seu código ou os arquivos de definição, apenas manipulando esses inputs.

Por exemplo, considere uma tarefa definida como “Pesquise sobre {topic}”. Ao passar {'topic': 'AI in Material Science'} no inputs, o CrewAI substitui automaticamente o placeholder, guiando o agente para trabalhar naquele tema específico.

2. Exemplo Prático Simples

Suponha que você já tenha uma crew implementada, como LatestAiDevelopmentCrew, que agrupa os agentes e tarefas. Veja como iniciar o fluxo:

#!/usr/bin/env python
from latest_ai_development.crew import LatestAiDevelopmentCrew

def run():
  # Definindo o dicionário de entradas dinâmicas
  inputs = {
      'topic': 'AI Agents'  # Tema que será substituído nas tarefas
  }

  # Inicializando o fluxo com os inputs definidos
  LatestAiDevelopmentCrew().crew().kickoff(inputs=inputs)

if __name__ == '__main__':
  run()

Explicação:

- Criamos um dicionário inputs contendo a chave "topic" e o valor "AI Agents".

- O método kickoff() usa esse dicionário para preencher qualquer ocorrência de {topic} nas definições YAML.

- O fluxo é iniciado automaticamente, executando as tarefas com o tema especificado.

3. Entendendo o que acontece dentro do kickoff()

Ao chamar kickoff():

- O fluxo constrói a sequência de tarefas e associa os agentes de acordo com a configuração da crew.

- Variáveis dinâmicas presentes nas descrições das tarefas são preenchidas pelos valores passados no inputs.

- As tarefas são executadas de forma sequencial ou conforme o processo configurado, com comunicação entre agentes se necessário.

- O resultado final é consolidado em um objeto CrewOutput, contendo todas as respostas e outputs gerados.

4. Exemplo Avançado: Criando agentes, tarefas e fluxo com placeholders

Aqui você tem um exemplo completo, demonstrando como criar um agente, definir tarefas com placeholders, configurar uma crew, e executar o fluxo passando inputs dinâmicos:

from crewai import Agent, Task, Crew, Process

# Definição do agente com papel, objetivo e contexto (backstory)
researcher = Agent(
  role='Research Analyst',
  goal='Find and analyze the best investment opportunities',
  backstory='Expert in financial analysis',
  verbose=True  # Exibe logs detalhados para melhor debug
)

# Definição da tarefa usando placeholder para o tópico de pesquisa
research_task = Task(
  description='Deep research on the {topic}',  # Placeholder {topic} será substituído
  expected_output='Comprehensive report on {topic}',  # Resultado esperado dinâmico
  agent=researcher
)

# Criação do crew especificando agentes, tarefas e processo sequencial
crew = Crew(
  agents=[researcher],
  tasks=[research_task],
  process=Process.sequential,  # Executa tarefas em sequência
  verbose=True
)

# Execução do crew com inputs para preencher {topic}
result = crew.kickoff(inputs={'topic': 'Quantum Computing'})

# Exibindo o output bruto do fluxo (relatório gerado)
print(result.raw)

Passo a passo detalhado:

- Instanciamos um agente chamado "researcher" com papel, meta e experiência.

- Criamos uma tarefa cujo texto contém "{topic}" para ser dinamicamente substituído.

- Inicializamos o crew com o agente e a tarefa, definindo que o processo será sequencial.

- Executamos kickoff passando o input 'Quantum Computing' para popular as variáveis.

- Impressão do resultado final para análise.

5. YAML e Variáveis Dinâmicas no CrewAI

A força do CrewAI está no uso de arquivos YAML para definir agentes e tarefas, nos quais você pode inserir placeholders entre chaves para personalizar o conteúdo conforme os inputs recebidos. Veja um exemplo de task YAML:

description: "Faça uma pesquisa detalhada sobre {topic} e resuma os pontos-chave."
expected_output: "Resumo das informações encontradas sobre {topic}."
agent: researcher

Ao executar o fluxo com inputs = {"topic": "Medicina Digital"}, o placeholder {topic} será substituído automaticamente, permitindo reutilização e versatilidade das definições sem precisar editar arquivos.

6. Casos de Uso Reais e Benefícios

- Geração automatizada e atualizada de relatórios temáticos, ajustando o conteúdo conforme o input.

- Prototipagem rápida de linhas de investigação científica ou de mercado com temas variados.

- Ferramenta acessível para operadores não técnicos, que podem alterar comportamentos simplesmente ajustando dicionários de entrada.

7. Próximos Passos para Seu Aprendizado

- Explore configurações avançadas de agentes, tarefas e processos oferecidos pelo CrewAI.

- Utilize kickoff_for_each(inputs=[]) para executar múltiplas instâncias de fluxo simultâneamente com diferentes parâmetros.

- Aproveite os hooks @before_kickoff e @after_kickoff para pré-processamento e pós-processamento automatizados.

- Combine CrewAI com outras ferramentas Python para construir pipelines ainda mais robustos e personalizados.

Conclusão

Iniciar um fluxo de trabalho no CrewAI com entradas dinâmicas em Python é uma prática simples, porém poderosa, que eleva o nível da automação e personalização de suas soluções. O método kickoff(), ao receber um dicionário de inputs, torna seu fluxo mais adaptável e fácil de manter, sem necessidade de alterar arquivos YAML ou código principal a cada mudança de contexto.

Para avançar em seu domínio do CrewAI, experimente criar seus próprios agentes, definir tarefas com placeholders, e explorar as funcionalidades avançadas conforme seus desafios profissionais evoluem.

Conheça o novo curso da DIO de CrewAI: https://www.dio.me/courses/instalacao-e-configuracao-do-crewai