Neste tutorial, você aprenderá:
- O que é o CrewAI e como ele difere de outras bibliotecas de agentes de IA.
- Suas maiores limitações e como superá-las com um fluxo de trabalho RAG.
- Como integrá-lo a uma API de raspagem para fornecer aos agentes de IA dados SERP para obter respostas mais precisas.
Vamos mergulhar de cabeça!
O que é a CrewAI?
O CrewAI é uma estrutura Python de código aberto para orquestrar e gerenciar agentes autônomos de IA que colaboram para concluir tarefas complexas. Ao contrário dos sistemas de agente único, como o Browser Use, o CrewAI é construído em torno de “equipes”, que são um conjunto de agentes.
Em uma equipe, cada agente tem uma função, um objetivo e um conjunto de ferramentas definidos. Em detalhes, você pode equipar os agentes de IA com ferramentas personalizadas para tarefas especializadas, como raspagem da Web, conexão de banco de dados e muito mais. Essa abordagem abre as portas para a solução especializada de problemas com base em IA e para a tomada de decisões eficazes.
A arquitetura multiagente do CrewAI promove a eficiência e o dimensionamento. Novos recursos são adicionados regularmente, como suporte para modelos Qwen e chamadas de funções paralelas, tornando-o um ecossistema em rápida evolução.
Limitações da CrewAI e como superá-las com dados atualizados da Web
O CrewAI é uma estrutura rica em recursos para a criação de sistemas multiagentes. No entanto, ele herda algumas limitações importantes dos LLMs nos quais se baseia. Como os LLMs geralmente são pré-treinados em conjuntos de dados estáticos, eles não têm conhecimento em tempo real e não podem acessar as últimas notícias ou o conteúdo ao vivo da Web.
Isso pode resultar em respostas desatualizadas – ou pior, em alucinações. Esses problemas são especialmente prováveis se os agentes não forem limitados ou não receberem dados atualizados e confiáveis em uma configuração de Geração Aumentada por Recuperação.
Para resolver essas limitações, você deve fornecer aos agentes (e, por extensão, aos LLMs deles) dados externos confiáveis. A Web é a fonte de dados mais abrangente e dinâmica disponível, o que a torna um alvo ideal. Portanto, uma abordagem eficaz é permitir que os agentes da CrewAI realizem consultas de pesquisa ao vivo em plataformas como o Google ou outros mecanismos de pesquisa.
Isso pode ser feito com a criação de uma ferramenta CrewAI personalizada que permite que os agentes recuperem páginas da Web relevantes para aprender. No entanto, a raspagem de SERPs (Search Engine Results Pages) é tecnicamente desafiadora, devido à necessidade de renderização de JavaScript, resolução de CAPTCHA, rotação de IP e estruturas de sites em constante mudança.
Gerenciar tudo isso internamente pode ser mais complexo do que desenvolver a própria lógica do CrewAI. Uma solução melhor é contar com APIs de raspagem SERP de alto nível, como a API SERP da Bright Data. Esses serviços lidam com o trabalho pesado de extrair dados limpos e estruturados da Web.
Ao integrar essas APIs ao seu fluxo de trabalho CrewAI, seus agentes obtêm acesso a informações atualizadas e precisas sem a sobrecarga operacional. A mesma estratégia também pode ser aplicada a outros domínios, conectando os agentes a APIs de raspagem específicas do domínio.
Como integrar o CrewAI às APIs SERP para acesso a dados em tempo real
Nesta seção guiada, você verá como dar ao seu agente de IA criado com o CrewAI a capacidade de buscar dados diretamente dos mecanismos SERP por meio da API SERP da Bright Data.
Essa integração do RAG permite que seus agentes da CrewAI forneçam resultados mais contextuais e atualizados, completos com links reais para leitura adicional.
Siga as etapas abaixo para criar uma equipe superalimentada com a integração da API SERP da Bright Data!
Pré-requisitos
Para acompanhar este tutorial, certifique-se de que você tenha:
- Uma chave de API da Bright Data.
- Uma chave de API para se conectar a um LLM (usaremos o Gemini neste tutorial).
- Python 3.10 ou superior instalado localmente.
Para obter mais detalhes, consulte a página de instalação da documentação do CrewAI, que contém pré-requisitos atualizados.
Não se preocupe se ainda não tiver uma chave de API da Bright Data, pois você será orientado a criar uma nas próximas etapas. Quanto à chave de API do LLM, se você não tiver uma, recomendamos configurar uma chave de API Gemini seguindo o guia oficial do Google.
Etapa 1: Instalar o CrewAI
Comece instalando o CrewAI globalmente executando o seguinte comando em seu terminal:
pip install crewaiObservação: isso fará o download e a configuração de vários pacotes, portanto, pode demorar um pouco.
Se encontrar problemas durante a instalação ou o uso, consulte a seção de solução de problemas na documentação oficial.
Depois de instalado, você terá acesso ao comando CLI do crewai. Verifique-o executando o seguinte em seu terminal:
crewaiVocê deverá ver um resultado semelhante a:
Usage: crewai [OPTIONS] COMMAND [ARGS]...
Top-level command group for crewai.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
chat Start a conversation with the Crew, collecting...
create Create a new crew, or flow.
deploy Deploy the Crew CLI group.
flow Flow related commands.
install Install the Crew.
log-tasks-outputs Retrieve your latest crew.kickoff() task outputs.
login Sign Up/Login to CrewAI+.
replay Replay the crew execution from a specific task.
reset-memories Reset the crew memories (long, short, entity,...
run Run the Crew.
signup Sign Up/Login to CrewAI+.
test Test the crew and evaluate the results.
tool Tool Repository related commands.
train Train the crew.
update Update the pyproject.toml of the Crew project to use...
version Show the installed version of crewai.Ótimo! Agora você tem a CLI do CrewAI pronta para inicializar seu projeto.
Etapa 2: Configuração do projeto
Execute o seguinte comando para criar um novo projeto CrewAI chamado serp_agent:
crewai create crew serp_agentDurante a configuração, você será solicitado a selecionar o provedor de LLM de sua preferência:
Select a provider to set up:
1. openai
2. anthropic
3. gemini
4. nvidia_nim
5. groq
6. huggingface
7. ollama
8. watson
9. bedrock
10. azure
11. cerebras
12. sambanova
13. other
q. Quit
Enter the number of your choice or 'q' to quit:Nesse caso, selecionaremos a opção “3” para o Gemini, pois sua integração via API é gratuita.
Em seguida, selecione o modelo Gemini específico que você gostaria de usar:
Select a model to use for Gemini:
1. gemini/gemini-1.5-flash
2. gemini/gemini-1.5-pro
3. gemini/gemini-2.0-flash-lite-001
4. gemini/gemini-2.0-flash-001
5. gemini/gemini-2.0-flash-thinking-exp-01-21
6. gemini/gemini-2.5-flash-preview-04-17
7. gemini/gemini-2.5-pro-exp-03-25
8. gemini/gemini-gemma-2-9b-it
9. gemini/gemini-gemma-2-27b-it
10. gemini/gemma-3-1b-it
11. gemini/gemma-3-4b-it
12. gemini/gemma-3-12b-it
13. gemini/gemma-3-27b-it
q. QuitNeste exemplo, o modelo gratuito gemini/gemini-1.5-flash é suficiente. Portanto, você pode selecionar a opção “1”.
Em seguida, você será solicitado a inserir sua chave de API do Gemini:
Enter your GEMINI API key from https://ai.dev/apikey (press Enter to skip):Cole-o e, se tudo correr como esperado, você verá um resultado como este:
API keys and model saved to .env file
Selected model: gemini/gemini-1.5-flash
- Created serp_agent.gitignore
- Created serp_agentpyproject.toml
- Created serp_agentREADME.md
- Created serp_agentknowledgeuser_preference.txt
- Created serp_agentsrcserp_agent__init__.py
- Created serp_agentsrcserp_agentmain.py
- Created serp_agentsrcserp_agentcrew.py
- Created serp_agentsrcserp_agenttoolscustom_tool.py
- Created serp_agentsrcserp_agenttools__init__.py
- Created serp_agentsrcserp_agentconfigagents.yaml
- Created serp_agentsrcserp_agentconfigtasks.yaml
Crew serp_agent created successfully!Esse procedimento gerará a seguinte estrutura de projeto:
serp_agent/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
├── knowledge/
├── tests/
└── src/
└── serp_agent/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yamlAqui:
main.pyé o ponto de entrada principal do seu projeto.crew.pyé onde você define a lógica da sua equipe.config/agents.yamldefine seus agentes de IA.config/tasks.yamldefine as tarefas com as quais seus agentes lidarão.tools/custom_tool.pypermitirá que você adicione ferramentas personalizadas que seus agentes possam usar..envarmazenam chaves de API e outras variáveis de ambiente.
Navegue até a pasta do projeto e instale as dependências do CrewAI:
cd serp_agent
crewai installO último comando criará uma pasta .venv de ambiente virtual local dentro do diretório do projeto. Isso permitirá que você execute sua CrewAI localmente.
Perfeito! Agora você tem um projeto CrewAI totalmente inicializado usando a API Gemini. Você está pronto para criar e executar seu agente SERP inteligente.
Etapa nº 3: comece a usar a API SERP
Conforme mencionado anteriormente, usaremos a API SERP da Bright Data para obter conteúdo das páginas de resultados dos mecanismos de pesquisa e enviá-lo aos nossos agentes da CrewAI. Especificamente, faremos pesquisas precisas no Google com base na entrada do usuário e utilizaremos os dados extraídos ao vivo para melhorar as respostas do agente.
Para configurar a API SERP, você pode consultar a documentação oficial. Como alternativa, siga as etapas abaixo.
Se ainda não o fez, inscreva-se em uma conta na Bright Data. Caso contrário, basta fazer login. Depois de fazer o login, acesse a seção “My Zones” (Minhas zonas) e clique na linha “SERP API” (API SERP):
Se você não vir essa linha na tabela, isso significa que ainda não configurou uma zona de API SERP. Nesse caso, role a tela para baixo e clique em “Create zone” (Criar zona) na seção “SERP API”:
Na página do produto SERP API, ative o botão “Activate” (Ativar) para ativar o produto:
Em seguida, siga o guia oficial para gerar sua chave de API da Bright Data. Em seguida, adicione-a ao seu arquivo .env conforme abaixo:
BRIGHT_DATA_API_KEY=<YOUR_BRIGHT_DATA_API_KEY>Substitua o pelo valor real de sua chave da API da Bright Data.
É isso aí! Agora você pode usar a API SERP da Bright Data em sua integração com o CrewAI.
Etapa 4: Criar uma ferramenta de pesquisa SERP da CrewAI
É hora de definir uma ferramenta de pesquisa SERP que seus agentes possam usar para interagir com a API SERP da Bright Data e recuperar dados de resultados de pesquisa.
Para isso, abra o arquivo custom_tool.py dentro da pasta tools/ e substitua seu conteúdo pelo seguinte:
# src/search_agent/tools/custom_tool.py
import os
import json
from typing import Type
import requests
from pydantic import BaseModel, PrivateAttr
from crewai.tools import BaseTool
class SerpSearchToolInput(BaseModel):
query: str
class SerpSearchTool(BaseTool):
_api_key: str = PrivateAttr()
name: str = "Bright Data SERP Search Tool"
description: str = """
Uses Bright Data's SERP API to retrieve real-time Google search results based on the user's query.
This tool fetches organic search listings to support agent responses with live data.
"""
args_schema: Type[BaseModel] = SerpSearchToolInput
def __init__(self, **kwargs):
super().__init__(**kwargs)
# Read the Bright Data API key from the envs
self._api_key = os.environ.get("BRIGHT_DATA_API_KEY")
if not self._api_key:
raise ValueError("Missing Bright Data API key. Please set BRIGHT_DATA_API_KEY in your .env file")
def _run(self, query: str) -> str:
url = "https://api.brightdata.com/request"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {self._api_key}"
}
payload = {
"zone": "serp", # Replace with the name of your actual Bright Data SERP API zone
"format": "json",
"url": f"https://www.google.com/search?q={query}&brd_json=1"
}
try:
response = requests.post(url, json=payload, headers=headers)
# Raise exceptions in case of errors
response.raise_for_status()
# Parse the JSON response
json_response = response.json()
response_body = json.loads(json_response.get("body", "{}"))
if "organic" not in response_body:
return "The response did not include organic search results."
# Return the SERP data as a JSON string
return json.dumps(response_body["organic"], indent=4)
except requests.exceptions.HTTPError as http_err:
return f"HTTP error occurred while querying Bright Data SERP API: {http_err}"
except requests.exceptions.RequestException as req_err:
return f"Network error occurred while connecting to Bright Data: {req_err}"
except (json.JSONDecodeError, KeyError) as parse_err:
return f"Error parsing Bright Data SERP API response: {parse_err}"Essa ferramenta CrewAI define uma função que recebe uma consulta do usuário e obtém resultados SERP da API SERP da Bright Data por meio de solicitações.
Observe que quando o parâmetro de consulta brd_json=1 é usado e o formato é definido como json, a API SERP responde com essa estrutura:
{
"status_code": 200,
"headers": {
"content-type": "application/json",
// omitted for brevity...
},
"body": "{"general":{"search_engine":"google","query":"pizza","results_cnt":1980000000, ...}}"
}Em particular, após analisar o campo body, que contém uma cadeia de caracteres JSON, você obterá a seguinte estrutura de dados:
{
"general": {
"search_engine": "google",
"query": "pizza",
"results_cnt": 1980000000,
"search_time": 0.57,
"language": "en",
"mobile": false,
"basic_view": false,
"search_type": "text",
"page_title": "pizza - Google Search",
"timestamp": "2023-06-30T08:58:41.786Z"
},
"input": {
"original_url": "https://www.google.com/search?q=pizza&brd_json=1",
"request_id": "hl_1a1be908_i00lwqqxt1"
},
"organic": [
{
"link": "https://www.pizzahut.com/",
"display_link": "https://www.pizzahut.com",
"title": "Pizza Hut | Delivery & Carryout - No One OutPizzas The Hut!",
"rank": 1,
"global_rank": 1
},
{
"link": "https://www.dominos.com/en/",
"display_link": "https://www.dominos.com",
"title": "Domino's: Pizza Delivery & Carryout, Pasta, Chicken & More",
"description": "Order pizza, pasta, sandwiches & more online...",
"rank": 2,
"global_rank": 3
},
// ...additional organic results omitted for brevity
]
}Portanto, você está interessado principalmente no campo orgânico. Esse é o campo acessado no código, analisado em uma cadeia de caracteres JSON e, em seguida, retornado pela ferramenta.
Fantástico! Seu agente da CrewAI agora pode usar essa ferramenta para recuperar dados SERP novos.
Etapa nº 5: Definir os agentes
Para realizar essa tarefa, você precisará de dois agentes CrewAI, cada um com uma finalidade distinta:
- Pesquisador: Reúne resultados de pesquisa do Google e filtra insights úteis.
- Analista de relatórios: Reúne as descobertas em um resumo estruturado e legível.
Você pode defini-los em seu arquivo agents.yml preenchendo-o da seguinte forma:
# src/search_agent/configs/agents.yml
researcher:
role: >
Online Research Specialist
goal: >
Conduct smart Google searches and collect relevant, trustworthy details from the top results.
backstory: >
You have a knack for phrasing search queries that deliver the most accurate and insightful content.
Your expertise lies in quickly identifying high-quality information from reputable sources.
reporting_analyst:
role: >
Strategic Report Creator
goal: >
Organize collected data into a clear, informative narrative that’s easy to understand and act on.
backstory: >
You excel at digesting raw information and turning it into meaningful analysis. Your work helps
teams make sense of data by presenting it in a well-structured and strategic format.Observe como essa configuração captura o que cada agente deve fazer – nada mais, nada menos. Basta definir a função, o objetivo e a história de fundo deles. Muito bom!
Etapa#6: Especificar as tarefas para cada agente
Prepare-se para definir tarefas específicas que descrevam claramente a função de cada agente no fluxo de trabalho. De acordo com a documentação do CrewAI, para obter resultados precisos, adefinição da tarefa é mais importante do que a definição do agente.
Portanto, no tasks.yml, você precisa informar aos seus agentes exatamente o que eles precisam fazer, conforme abaixo:
# src/search_agent/configs/tasks.yml
research_task:
description: >
Leverage SerpSearchTool to perform a targeted search based on the user's {query}.
Build API parameters like:
- 'query': develop a short, Google-like, keyword-optimized search phrase for search engines.
From the returned data, identify the most relevant and factual content.
expected_output: >
A file containing well-structured raw JSON content with the data from search results.
Avoid rewriting, summarizing, or modifying any content.
agent: researcher
output_file: output/serp_data.json
report_task:
description: >
Turn the collected data into a digestible, insight-rich report.
Address the user's {query} with fact-based findings. Add links for further reading. Do not fabricate or guess any information.
expected_output: >
A Markdown report with key takeaways and meaningful insights.
Keep the content brief and clearly, visually structured.
agent: reporting_analyst
context: [research_task]
output_file: output/report.mdNessa configuração, você está definindo duas tarefas – uma para cada agente:
research_task (tarefa de pesquisa): Informa ao pesquisador como usar a API SERP da Bright Data por meio da ferramenta, inclusive como criar parâmetros de API dinamicamente com base na consulta.report_task: Especifica que o resultado final deve ser um relatório legível e informativo criado estritamente com base nos dados coletados.
Essa definição tasks.yml é tudo de que seus agentes da CrewAI precisam para coletar dados de SERP e produzir um relatório baseado em resultados de pesquisa reais.
É hora de integrar seus agentes CrewAI em seu código e deixá-los trabalhar!
Etapa nº 7: Crie sua equipe
Agora que todos os componentes estão no lugar, conecte tudo no arquivo crew.py para criar uma equipe totalmente funcional. Especificamente, é assim que você pode definir seu crew.py:
# src/search_agent/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from .tools.custom_tool import SerpSearchTool
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class SerpAgent():
"""SerpAgent crew"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config["researcher"],
tools=[SerpSearchTool()],
verbose=True
)
@agent
def reporting_analyst(self) -> Agent:
return Agent(
config=self.agents_config["reporting_analyst"],
verbose=True
)
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config["research_task"],
output_file="output/serp_data.json"
)
@task
def report_task(self) -> Task:
return Task(
config=self.tasks_config["report_task"],
output_file="output/report.md"
)
@crew
def crew(self) -> Crew:
"""Creates the SerpAgent crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)No crew.py, você precisa usar os decoradores do CrewAI(@agent, @task, @crew, neste caso) para vincular a lógica dos seus arquivos YAML e conectar a funcionalidade real.
Neste exemplo:
- O agente
pesquisadorrecebe acesso aoSerpSearchTool, o que lhe permite realizar consultas reais de pesquisa no Google usando a API SERP da Bright Data. - O agente
reporting_analystestá configurado para gerar o relatório final, usando a saída do pesquisador. - Cada tarefa corresponde ao que foi definido em seu
tasks.ymle está explicitamente vinculada ao arquivo de saída apropriado. - O processo é definido como
sequencial, garantindo queo pesquisadorseja executado primeiro e depois passe seus dados para oreporting_analyst.
Aqui vamos nós! Sua equipe do SerpAgent agora está pronta para executar.
Etapa 8: Criar o loop principal
No main.py, acione a equipe passando a consulta do usuário como entrada:
# src/search_crew/main.py
import os
from serp_agent.crew import SerpAgent
# Create the output/ folder if it doesn"t already exist
os.makedirs("output", exist_ok=True)
def run():
try:
# Read the user's input and pass it to the crew
inputs = {"query": input("nSearch for: ").strip()}
# Start the SERP agent crew
result = SerpAgent().crew().kickoff(
inputs=inputs
)
return result
except Exception as e:
print(f"An error occurred: {str(e)}")
if __name__ == "__main__":
run()Missão concluída! Sua integração CrewAI + API SERP (usando o Gemini como LLM) agora está totalmente funcional. Basta executar main.py, inserir uma consulta de pesquisa e observar a equipe coletar e analisar os dados SERP para produzir um relatório.
Etapa 9: execute seu agente de IA
Na pasta do seu projeto, execute o aplicativo CrewAI com o seguinte comando:
crewai runAgora, insira uma consulta como, por exemplo:
"What are the new AI protocols?"Esse é o tipo de pergunta que um LLM típico pode ter dificuldade para responder com precisão. O motivo é que a maioria dos protocolos de IA mais recentes, como CMP, A2A, AGP e ACP, não existia quando o modelo foi originalmente treinado.
Veja a seguir o que acontecerá em detalhes:
Como você pode observar acima, a CrewAI trata a solicitação dessa forma:
- O agente
de pesquisaé executado, o que:- Transforma a entrada do usuário em uma consulta estruturada
"novos protocolos de IA" - Envia a consulta para a API SERP da Bright Data por meio da
SerpSearchTool. - Recebe os resultados da API e os salva no arquivo
output/serp_data.json.
- Transforma a entrada do usuário em uma consulta estruturada
- Em seguida, é acionado o agente
reporting_analyst, que:- Lê os dados estruturados do arquivo
serp_data.json. - Usa essas novas informações para gerar um relatório com reconhecimento de contexto em Markdown.
- Salva o relatório estruturado final em
output/report.md.
- Lê os dados estruturados do arquivo
Se você abrir o report.md usando um visualizador Markdown, verá algo parecido com isto:
O relatório inclui informações contextuais relevantes e até mesmo links para ajudá-lo a se aprofundar.
E pronto! Você acabou de implementar um fluxo de trabalho RAG no CrewAI com base na integração com uma API SERP.
Próximas etapas
A ferramenta API SERP da Bright Data integrada ao Crew permite que os agentes recebam novos resultados de mecanismos de pesquisa. Com os URLs dessas SERPs, você poderia usá-los para chamar outras APIs de raspagem para extrair o conteúdo bruto das páginas vinculadas, seja na forma não processada(para converter em Markdown e alimentar o agente) ou já analisado em JSON.
Essa ideia permite que os agentes descubram automaticamente algumas fontes confiáveis e recuperem informações atualizadas a partir delas. Além disso, você pode integrar uma solução como o Agent Browser para permitir que os agentes interajam dinamicamente com qualquer página da Web ativa.
Esses são apenas alguns exemplos, mas os cenários potenciais e os casos de uso são praticamente ilimitados.
Conclusão
Nesta publicação do blog, você aprendeu como tornar seus agentes CrewAI mais conscientes do contexto integrando uma configuração RAG usando a API SERP da Bright Data.
Conforme explicado, essa é apenas uma das muitas possibilidades que você pode explorar ao conectar seus agentes com APIs de raspagem externas ou ferramentas de automação. Em particular, as soluções da Bright Data podem servir como blocos de construção poderosos para fluxos de trabalho de IA inteligentes.
Aumente o nível de sua infraestrutura de IA com as ferramentas da Bright Data:
- Agentes autônomos de IA: Pesquise, acesse e interaja com qualquer site em tempo real usando um conjunto avançado de APIs.
- Aplicativos de IA verticais: crie pipelines de dados confiáveis e personalizados para extrair dados da Web de fontes específicas do setor.
- Modelos básicos: Acesse conjuntos de dados compatíveis e em escala da Web para potencializar o pré-treinamento, a avaliação e o ajuste fino.
- IA multimodal: aproveite o maior repositório do mundo de imagens, vídeos e áudio otimizados para IA.
- Provedores de dados: Conecte-se com provedores confiáveis para obter conjuntos de dados de alta qualidade e prontos para IA em escala.
- Pacotes de dados: Obtenha conjuntos de dados com curadoria, prontos para uso, estruturados, enriquecidos e anotados.
Para obter mais informações, explore nosso hub de IA.
Crie uma conta na Bright Data e experimente todos os nossos produtos e serviços para o desenvolvimento de agentes de IA!
