Neste artigo, você verá:
- O que é o AWS Cloud Development Kit (CDK) e como ele pode ser usado para definir e implantar infraestrutura em nuvem.
- Por que você deve dar aos agentes AWS Bedrock IA, criados com o AWS CDK, acesso aos resultados de pesquisa na web usando uma ferramenta pronta para IA, como a API SERP da Bright Data.
- Como criar um agente AWS Bedrock integrado à API SERP usando o AWS CDK em Python.
Vamos começar!
O que é o AWS Cloud Development Kit (CDK)?
O AWS Cloud Development Kit, também conhecido como AWS CDK, é uma estrutura de código aberto para construir infraestrutura em nuvem como código usando linguagens de programação modernas. Ele fornece o que você precisa para provisionar recursos da AWS e implantar aplicativos por meio do AWS CloudFormation usando linguagens de programação como TypeScript, Python, Java, C# e Go.
Graças ao AWS CDK, você também pode criar agentes de IA para o Amazon Bedrock programaticamente — exatamente o que você fará neste tutorial!
Por que os agentes de IA do Amazon Bedrock criados com o AWS CDK precisam de pesquisa na web
Grandes modelos de linguagem são treinados em Conjuntos de dados que representam conhecimento apenas até um determinado momento. Como resultado, eles tendem a produzir respostas imprecisas ou alucinadas. Isso é especialmente problemático para agentes de IA que exigem informações atualizadas.
Isso pode ser resolvido dando ao seu agente de IA a capacidade de buscar dados novos e confiáveis em uma configuração RAG (Retrieval-Augmented Generation, ougeração aumentada por recuperação). Por exemplo, o agente de IA poderia realizar pesquisas na web para reunir informações verificáveis, expandindo seu conhecimento e melhorando a precisão.
É possível criar uma função AWS Lambda personalizada para rastrear mecanismos de pesquisa, mas isso é bastante desafiador. Você teria que lidar com renderização JavaScript, CAPTCHAs, mudanças na estrutura do site e bloqueios de IP.
Uma abordagem melhor é usar uma API SERP rica em recursos, como a API SERP da Bright Data. Ela lida com proxies, desbloqueio, escalabilidade, formatação de dados e muito mais para você. Ao integrá-la ao AWS Bedrock usando uma função Lambda, seu agente de IA criado via AWS CDK poderá acessar resultados de pesquisa em tempo real para respostas mais confiáveis.
Como desenvolver um agente de IA com integração da API SERP usando AWS CDK em Python
Nesta seção passo a passo, você aprenderá como usar o AWS CDK com Python para criar um agente de IA AWS Bedrock. Ele será capaz de buscar dados de mecanismos de pesquisa por meio da API SERP da Bright Data.
A integração será implementada por meio de uma função Lambda (que chama a API SERP) que o agente pode invocar como uma ferramenta. Especificamente, para criar um agente Amazon Bedrock, os principais componentes são:
- Grupo de ações: define as funções que o agente pode ver e chamar.
- Função Lambda: implementa a lógica para consultar a API SERP da Bright Data.
- Agente de IA: coordena as interações entre os modelos básicos, as funções e as solicitações do usuário.
Essa configuração será implementada inteiramente com AWS CDK em Python. Para obter os mesmos resultados usando o console visual AWS Bedrock, consulte nosso guia Amazon Bedrock + Bright Data.
Siga as etapas abaixo para criar um agente AWS Bedrock IA usando AWS CDK, aprimorado com recursos de pesquisa na web em tempo real por meio da API SERP!
Pré-requisitos
Para acompanhar este tutorial, você precisa de:
- Node.js 22.x+ instalado localmente para usar a CLI do AWS CDK.
- Python 3.11+ instalado localmente para empregar o AWS CDK em Python.
- Uma conta AWS ativa (mesmo em uma avaliação gratuita).
- Pré-requisitos do Amazon Bedrock Agents configurados. (O Amazon Bedrock Agents está disponível atualmente apenas em algumas regiões da AWS.)
- Uma conta Bright Data com uma chave API pronta.
- Conhecimentos básicos de programação em Python.
Etapa 1: Instalar e autorizar a AWS CLI
Antes de prosseguir com o AWS CDK, você precisa instalar o AWS CLI e configurá-lo para que seu terminal possa se autenticar com sua conta AWS.
Observação: se você já tem a AWS CLI instalada e configurada para autenticação, pule esta etapa e passe para a próxima.
Instale a AWS CLI seguindo o guia de instalação oficial para o seu sistema operacional. Após a instalação, verifique a instalação executando:
aws --versionVocê deverá ver um resultado semelhante a:
aws-cli/2.31.32 Python/3.13.9 Windows/11 exe/AMD64Em seguida, execute o comando configure para definir suas credenciais:
aws configureVocê será solicitado a inserir:
- ID da chave de acesso da AWS
- Chave secreta de acesso da AWS
- Nome da região padrão (por exemplo,
us-east-1) - Formato de saída padrão (opcional, por exemplo,
json)
Preencha os três primeiros campos, pois eles são necessários para o desenvolvimento e a implantação do CDK. Se você não souber onde obter essas informações:
- Acesse a AWS e faça login.
- No canto superior direito, clique no nome da sua conta para abrir o menu da conta e selecione a opção “Credenciais de segurança”.
- Na seção “Chaves de acesso”, crie uma nova chave. Salve a “ID da chave de acesso” e a “Chave de acesso secreta” em um local seguro.
Pronto! Sua máquina pode se conectar à sua conta AWS por meio da CLI. Você está pronto para prosseguir com o desenvolvimento do AWS CDK.
Etapa 2: instale o AWS CDK
Instale o AWS CDK globalmente em seu sistema usando o pacote npm aws-cdk:
npm install -g aws-cdkEm seguida, verifique a versão instalada executando:
cdk --versionVocê deverá ver um resultado semelhante a:
2.1031.2 (build 779352d)Observação: a versão 2.174.3 ou posterior é necessária para o desenvolvimento e a implantação de agentes de IA usando o AWS CDK com Python.
Ótimo! Agora você tem o AWS CDK CLI instalado localmente.
Etapa 3: Configure seu projeto AWS CDK Python
Comece criando uma nova pasta de projeto para seu agente de IA AWS CDK + Bright Data API SERP.
Por exemplo, você pode nomeá-la aws-cdk-bright-data-web-search-agent:
mkdir aws-cdk-bright-data-web-search-agentNavegue até a pasta:
cd aws-cdk-bright-data-web-search-agentEm seguida, inicialize um novo aplicativo AWS CDK baseado em Python por meio do comando init:
cdk init app --language pythonIsso pode demorar um pouco, então seja paciente enquanto a CLI do CDK configura a estrutura do seu projeto.
Depois de inicializada, sua pasta de projeto deve ficar assim:
aws-cdk-bright-data-web-search-agent
├── .git/
├── venv/
├── aws_cdk_bright_data_web_search_agent/
│ ├── __init__.py
│ └── aws_cdk_bright_data_web_search_agent_stack.py
├── tests/
│ ├── __init__.py
│ └── unit/
│ ├── __init__.py
│ └── test_aws_cdk_bright_data_web_search_agent_stack.py
├── .gitignore
├── app.py
├── cdk.json
├── README.md
├── requirements.txt
├── requirements-dev.txt
└── source.batVocê precisa se concentrar nestes dois arquivos:
app.py: contém a definição de nível superior do aplicativo AWS CDK.aws_cdk_bright_data_web_search_agent/aws_cdk_bright_data_web_search_agent_stack.py: define a pilha para o agente de pesquisa na web (é aqui que você implementará a lógica do seu agente de IA).
Para obter mais detalhes, consulte o guia oficial da AWS sobre como trabalhar com CDK em Python.
Agora, carregue seu projeto em seu IDE Python favorito, como PyCharm ou Visual Studio Code com a extensão Python.
Observe que o comando cdk init cria automaticamente um ambiente virtual Python no projeto. No Linux ou macOS, ative-o com:
source .venv/bin/activateOu, de forma equivalente, no Windows, execute:
.venvScriptsactivateEm seguida, dentro do ambiente virtual ativado, instale todas as dependências necessárias:
python -m pip install -r requirements.txtÓtimo! Agora você tem um ambiente Python AWS CDK configurado para o desenvolvimento de agentes de IA.
Etapa 4: execute o AWS CDK Bootstrapping
Bootstrapping é o processo de preparar seu ambiente AWS para uso com o AWS Cloud Development Kit. Antes de implantar uma pilha CDK, seu ambiente deve ser inicializado.
Em termos mais simples, esse processo configura os seguintes recursos em sua conta AWS:
- Um bucket Amazon S3: armazena seus arquivos de projeto CDK, como código de função AWS Lambda e outros ativos.
- Um repositório Amazon ECR: armazena imagens Docker.
- Funções do AWS IAM: concedem as permissões necessárias para que o AWS CDK execute implantações. (Para obter mais detalhes, consulte a documentação da AWS sobre funções do IAM criadas durante o bootstrapping.)
Para iniciar o processo de inicialização do CDK, execute o seguinte comando na pasta do seu projeto:
cdk bootstrapNo serviço AWS CloudFormation, esse comando cria uma pilha chamada “CDKToolkit” que contém todos os recursos necessários para implantar aplicativos CDK.
Verifique isso acessando o console do CloudFormation e verificando a página “Stacks”:
Você verá uma pilha “CDKToolkit”. Siga o link e você verá algo como:
Para obter mais informações sobre como funciona o processo de inicialização, por que ele é necessário e o que acontece nos bastidores, consulte a documentação oficial do AWS CDK.
Etapa 5: Prepare-se com a API SERP da Bright Data
Agora que seu ambiente AWS CDK está configurado para desenvolvimento e implantação, conclua as etapas preliminares preparando sua conta Bright Data e configurando o serviço API SERP. Você pode seguir a documentação oficial da Bright Data ou seguir as etapas abaixo.
Se você ainda não tem uma conta, crie uma conta Bright Data. Como alternativa, basta fazer login. Na sua conta Bright Data, acesse a página “Proxy & Scraping”. Na seção “My Zones”, verifique se há uma linha “API SERP” na tabela:
Se você não vir uma linha com a etiqueta “API SERP”, isso significa que você ainda não configurou uma zona. Role para baixo até a seção “API SERP” e clique em “Create zone” (Criar zona) para adicionar uma:
Crie uma zona API SERP e dê a ela um nome como serp_api (ou qualquer nome de sua preferência). Lembre-se do nome da zona que você escolheu, pois você precisará dele para acessar o serviço via API.
Na página do produto API SERP, alterne a opção “Ativar” para habilitar a zona:
Por último, siga o guia oficial para gerar sua chave API Bright Data. Guarde-a em um local seguro, pois você precisará dela em breve.
Ótimo! Agora você tem tudo configurado para usar a API SERP da Bright Data em seu agente AWS Bedrock IA desenvolvido com AWS CDK.
Etapa 6: armazene os segredos do seu aplicativo CDK no AWS Secrets Manager
Você acabou de obter informações confidenciais (por exemplo, sua chave API da Bright Data e o nome da zona da API SERP). Em vez de codificar esses valores no código da sua função Lambda, você deve lê-los com segurança no AWS Secrets Manager.
Execute o seguinte comando Bash para criar um segredo chamado BRIGHT_DATA contendo sua chave API Bright Data e zona API SERP:
aws secretsmanager create-secret --name "BRIGHT_DATA" --description "Credenciais da API para integração da API SERP da Bright Data" --secret-string '{
"BRIGHT_DATA_API_KEY": "<SUA_CHAVE_API_BRIGHT_DATA>",
"BRIGHT_DATA_SERP_API_ZONE": "<SUA_ZONA_API_BRIGHT_DATA_SERP>"
}'Ou, de forma equivalente, no PowerShell:
aws secretsmanager create-secret `
--name "BRIGHT_DATA" `
--description "Credenciais da API para integração com a API SERP da Bright Data" `
--secret-string '{"BRIGHT_DATA_API_KEY":"<SUA_CHAVE_DE_API_BRIGHT_DATA>","BRIGHT_DATA_SERP_API_ZONE":"<SUA_ZONA_DE_API_SERP_BRIGHT_DATA>"}'Certifique-se de substituir <SUA_CHAVE_DE_API_BRIGHT_DATA> e <SUA_ZONA_DE_API_SERP_BRIGHT_DATA> pelos valores reais que você recuperou anteriormente.
Esse comando configurará o segredo BRIGHT_DATA, como você pode confirmar no console do AWS Secrets Manager na página “Segredos”:
Se você clicar no botão “Recuperar valor secreto”, deverá ver os segredos BRIGHT_DATA_API_KEY e BRIGHT_DATA_SERP_API_ZONE:
Incrível! Esses segredos serão usados para autenticar solicitações à API SERP em uma função Lambda que você definirá em breve.
Etapa 7: Implemente sua pilha AWS CDK
Agora que você configurou tudo o que é necessário para criar seu agente de IA, a próxima etapa é implementar a pilha AWS CDK em Python. Primeiro, é importante entender o que é uma pilha AWS CDK.
Uma pilha é a menor unidade implantável no CDK. Ela representa uma coleção de recursos da AWS definidos usando construções CDK. Quando você implanta um aplicativo CDK, todos os recursos da pilha são implantados juntos como uma única pilha CloudFormation.
O arquivo de pilha padrão está localizado em:
aws_cdk_bright_data_web_search_agent/aws_cdk_bright_data_web_search_agent_stack.pyInspecione-o no Visual Studio Code:
Ele contém um modelo de pilha genérico onde você definirá sua lógica. Sua tarefa é implementar a pilha AWS CDK completa para construir o agente de IA com integração da API SERP da Bright Data, incluindo funções Lambda, funções IAM, grupos de ação e o agente Bedrock AI.
Faça tudo isso com:
import aws_cdk.aws_iam as iam
from aws_cdk import (
Aws,
CfnOutput,
Duration,
Stack)
from aws_cdk import aws_bedrock as bedrock
from aws_cdk import aws_lambda as _lambda
from constructs import Construct
# Defina as constantes necessárias
AI_MODEL_ID = "amazon.nova-lite-v1:0" # O nome do LLM usado para alimentar o agente
ACTION_GROUP_NAME = "action_group_web_search"
LAMBDA_FUNCTION_NAME = "serp_api_lambda"
AGENT_NAME = "web_search_agent"
# Defina a pilha CDK para implantar o agente de pesquisa na web com tecnologia Bright Data
class AwsCdkBrightDataWebSearchAgentStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Concede permissões Lambda para registrar e ler segredos
lambda_policy = iam.Policy(
self,
"LambdaPolicy",
statements=[
# Permissão para criar grupos de log do CloudWatch
iam.PolicyStatement(
sid="CreateLogGroup",
efeito=iam.Effect.ALLOW,
ações=["logs:CreateLogGroup"],
recursos=[f"arn:aws:logs:{Aws.REGION}:{Aws.ACCOUNT_ID}:*"],
),
# Permissão para criar fluxos de log e inserir eventos de log
iam.PolicyStatement(
sid="CreateLogStreamAndPutLogEvents",
efeito=iam.Effect.ALLOW,
ações=["logs:CreateLogStream", "logs:PutLogEvents"],
recursos=[
f"arn:aws:logs:{Aws.REGION}:{Aws.ACCOUNT_ID}:log-group:/aws/lambda/{LAMBDA_FUNCTION_NAME}",
f"arn:aws:logs:{Aws.REGION}:{Aws.ACCOUNT_ID}:log-group:/aws/lambda/{LAMBDA_FUNCTION_NAME}:log-stream:*",
],
),
# Permissão para ler segredos BRIGHT_DATA do Secrets Manager
iam.PolicyStatement(
sid="GetSecretsManagerSecret",
effect=iam.Effect.ALLOW,
actions=["secretsmanager:GetSecretValue"],
resources=[
f"arn:aws:secretsmanager:{Aws.REGION}:{Aws.ACCOUNT_ID}:secret:BRIGHT_DATA*",
],),
],
)
# Defina a função IAM para as funções Lambda
lambda_role = iam.Role(
self,
"LambdaRole",
role_name=f"{LAMBDA_FUNCTION_NAME}_role",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
)
# Anexe a política à função Lambda
lambda_role.attach_inline_policy(lambda_policy)
# Definição da função Lambda
lambda_function = _lambda.Function(
self,
LAMBDA_FUNCTION_NAME,
function_name=LAMBDA_FUNCTION_NAME,
runtime=_lambda.Runtime.PYTHON_3_12, # Tempo de execução Python
architecture=_lambda.Architecture.ARM_64,
code=_lambda.Code.from_asset("lambda"), # Ler o código Lambda da pasta "lambda/"
handler=f"{LAMBDA_FUNCTION_NAME}.lambda_handler",
timeout=Duration.seconds(120),
role=lambda_role, # Anexar função IAM
environment={"LOG_LEVEL": "DEBUG", "ACTION_GROUP": f"{ACTION_GROUP_NAME}"},
)
# Permita que o serviço Bedrock invoque funções Lambda
bedrock_account_principal = iam.PrincipalWithConditions(
iam.ServicePrincipal("bedrock.amazonaws.com"),
conditions={
"StringEquals": {"aws:SourceAccount": f"{Aws.ACCOUNT_ID}"},
},
)
lambda_function.add_permission(
id="LambdaResourcePolicyAgentsInvokeFunction",
principal=bedrock_account_principal,
action="lambda:invokeFunction",
)
# Defina a política IAM para o agente Bedrock
agent_policy = iam.Policy(
self,
"AgentPolicy",
statements=[
iam.PolicyStatement(
sid="AmazonBedrockAgentBedrockFoundationModelPolicy",
effect=iam.Effect.ALLOW,
actions=["bedrock:InvokeModel"], # Dê a ele permissão para chamar o modelo básico
resources=[f"arn:aws:bedrock:{Aws.REGION}::foundation-model/{AI_MODEL_ID}"],
),
],
)
# Relação de confiança para a função do agente para permitir que o Bedrock a assuma
agent_role_trust = iam.PrincipalWithConditions(
iam.ServicePrincipal("bedrock.amazonaws.com"),
conditions={
"StringLike": {"aws:SourceAccount": f"{Aws.ACCOUNT_ID}"},
"ArnLike": {"aws:SourceArn": f"arn:aws:bedrock:{Aws.REGION}:{Aws.ACCOUNT_ID}:agent/*"},
},
)
# Defina a função IAM para o agente Bedrock
agent_role = iam.Role(
self,
"AmazonBedrockExecutionRoleForAgents",
role_name=f"AmazonBedrockExecutionRoleForAgents_{AGENT_NAME}",
assumed_by=agent_role_trust,
)
agent_role.attach_inline_policy(agent_policy)
# Definir o grupo de ações para o agente de IA
action_group = bedrock.CfnAgent.AgentActionGroupProperty(
action_group_name=ACTION_GROUP_NAME,
description="Chamar a API SERP da Bright Data para realizar pesquisas na web e recuperar informações atualizadas dos mecanismos de pesquisa.",
action_group_executor=bedrock.CfnAgent.ActionGroupExecutorProperty(lambda_=lambda_function.function_arn),
function_schema=bedrock.CfnAgent.FunctionSchemaProperty(
functions=[
bedrock.CfnAgent.FunctionProperty(
name=LAMBDA_FUNCTION_NAME,
description="Integra-se com a API SERP da Bright Data para realizar pesquisas na web.",
parameters={
"search_query": bedrock.CfnAgent.ParameterDetailProperty(
type="string",
description="A consulta de pesquisa para a pesquisa na web do Google.",
required=True,
)
},
),
]
),
)
# Crie e especifique o agente Bedrock AI
agent_description = """
Um agente de IA que pode se conectar à API SERP da Bright Data para recuperar o contexto de pesquisa recente na web dos mecanismos de pesquisa.
"""
agent_instruction = """
Você é um agente projetado para lidar com casos de uso que exigem a recuperação e o processamento de informações atualizadas.
Você pode acessar dados atuais, incluindo notícias e resultados de mecanismos de pesquisa, por meio de pesquisas na web alimentadas pela API SERP da Bright Data.
"""
agente = bedrock.CfnAgent(
self,
AGENT_NAME,
description=agent_description,
agent_name=AGENT_NAME,
foundation_model=AI_MODEL_ID,
action_groups=[action_group],
auto_prepare=True,
instruction=agent_instruction,
agent_resource_role_arn=agent_role.role_arn,
)
# Exportar as principais saídas para implantação
CfnOutput(self, "agent_id", value=agent.attr_agent_id)
CfnOutput(self, "agent_version", value=agent.attr_agent_version)O código acima é uma versão modificada da implementação oficial da pilha AWS CDK para um agente de IA de pesquisa na web.
O que acontece nessas mais de 150 linhas de código reflete as etapas descritas anteriormente no guia: Etapa nº 1, Etapa nº 2 e Etapa nº 3 do nosso artigo“Como integrar a API SERP da Bright Data com os agentes de IA do AWS Bedrock”.
Para entender melhor o que está acontecendo nesse arquivo, vamos dividir o código em cinco blocos funcionais:
- Política e função IAM do Lambda: configura as permissões para a função Lambda. O Lambda requer acesso aos logs do CloudWatch para registrar detalhes de execução e ao AWS Secrets Manager para ler com segurança a chave e a zona da API da Bright Data. Uma função IAM é criada para o Lambda e a política apropriada é anexada, garantindo que ele opere com segurança, apenas com as permissões necessárias.
- Definição da função Lambda: aqui, a própria função Lambda é definida e configurada. Ela especifica o tempo de execução e a arquitetura do Python, aponta para a pasta que contém o código Lambda (que será implementado na próxima etapa) e configura variáveis de ambiente, como nível de log e nome do grupo de ação. As permissões são concedidas para que o AWS Bedrock possa invocar o Lambda, permitindo que o agente de IA acione pesquisas na web por meio da API SERP da Bright Data.
- Função IAM do agente Bedrock: cria a função de execução para o agente de IA Bedrock. O agente precisa de permissões para invocar o modelo de IA básico selecionado entre os suportados (
amazon.nova-lite-v1:0, neste caso). Uma relação de confiança é definida para que apenas o Bedrock possa assumir a função dentro da sua conta. Uma política é anexada concedendo acesso ao modelo. - Definição do grupo de ações: um grupo de ações define as ações específicas que o agente de IA pode realizar. Ele vincula o agente à função Lambda que permite que ele execute pesquisas na web por meio da API SERP da Bright Data. O grupo de ações também inclui metadados para parâmetros de entrada, para que o agente entenda como interagir com a função e quais informações são necessárias para cada pesquisa.
- Definição do agente IA Bedrock: define o próprio agente IA. Ele vincula o agente ao grupo de ações e à função de execução e fornece uma descrição clara e instruções para seu uso.
Após implantar a pilha CDK, um agente de IA aparecerá no seu console AWS. Esse agente pode realizar pesquisas na web de forma autônoma e recuperar informações atualizadas, aproveitando a integração da API SERP da Bright Data na função Lambda. Fantástico!
Etapa 8: Implemente o Lambda para integração com a API SERP
Dê uma olhada neste trecho do código anterior:
lambda_function = _lambda.Function(
self,
LAMBDA_FUNCTION_NAME,
function_name=LAMBDA_FUNCTION_NAME,
runtime=_lambda.Runtime.PYTHON_3_12, # Python runtime
architecture=_lambda.Architecture.ARM_64,
code=_lambda.Code.from_asset("lambda"), # Leia o código Lambda da pasta "lambda/"
handler=f"{LAMBDA_FUNCTION_NAME}.lambda_handler",
timeout=Duration.seconds(120),
role=lambda_role, # Anexar função IAM
environment={"LOG_LEVEL": "DEBUG", "ACTION_GROUP": f"{ACTION_GROUP_NAME}"},
)A linha code=_lambda.Code.from_asset("lambda") especifica que o código da função Lambda será carregado da pasta lambda/. Portanto, crie uma pasta lambda/ em seu projeto e adicione um arquivo chamado serp_api_lambda.py dentro dela:
O arquivo serp_api_lambda.py precisa conter a implementação da função Lambda usada pelo agente de IA definido anteriormente. Implemente esta função para lidar com a integração com a API SERP da Bright Data da seguinte maneira:
import json
import logging
import os
import urllib.parse
import urllib.request
import boto3
# ----------------------------
# Configuração de registro
# ----------------------------
log_level = os.environ.get("LOG_LEVEL", "INFO").strip().upper()
logging.basicConfig(
format="[%(asctime)s] p%(process)s {%(filename)s:%(lineno)d} %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)
logger.setLevel(log_level)
# ----------------------------
# Região AWS do ambiente
# ----------------------------
AWS_REGION = os.environ.get("AWS_REGION")
if not AWS_REGION:
logger.warning("Variável de ambiente AWS_REGION não definida; boto3 usará a região padrão")
# ----------------------------
# Recuperar o objeto secreto do AWS Secrets Manager
# ----------------------------
def get_secret_object(key: str) -> str:
"""
Obter um valor secreto do AWS Secrets Manager.
"""
session = boto3.session.Session()
client = session.client(
service_name='secretsmanager',
region_name=AWS_REGION
)
try:
get_secret_value_response = client.get_secret_value(
SecretId=key
)
except Exception as e:
logger.error(f"Não foi possível obter o segredo '{key}' do Secrets Manager: {e}")
raise e
secret = json.loads(get_secret_value_response["SecretString"])
return secret
# Recuperar credenciais do Bright Data
bright_data_secret = get_secret_object("BRIGHT_DATA")
BRIGHT_DATA_API_KEY = bright_data_secret["BRIGHT_DATA_API_KEY"]
BRIGHT_DATA_SERP_API_ZONE = bright_data_secret["BRIGHT_DATA_SERP_API_ZONE"]
# ----------------------------
# Pesquisa na Web da API SERP
# ----------------------------
def serp_api_web_search(search_query: str) -> str:
"""
Chama a API SERP da Bright Data para recuperar os resultados da pesquisa do Google.
"""
logger.info(f"Executando pesquisa da API SERP da Bright Data para search_query='{search_query}'")
# Codifica a consulta para URL
encoded_query = urllib.parse.quote(search_query)
# Cria a URL do Google para extrair o SERP de
search_engine_url = f"https://www.google.com/search?q={encoded_query}"
# Solicitação da API Bright Data (documentação: https://docs.brightdata.com/scraping-automation/serp-api/send-your-first-request)
url = "https://api.brightdata.com/request"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {BRIGHT_DATA_API_KEY}"
}
data = {
"zone": BRIGHT_DATA_SERP_API_ZONE,
"url": search_engine_url,
"format": "raw",
"data_format": "markdown" # Para obter o SERP como um documento Markdown pronto para IA
}
payload = json.dumps(data).encode("utf-8")
request = urllib.request.Request(url, data=payload, headers=headers)
try:
response = urllib.request.urlopen(request)
response_data: str = response.read().decode("utf-8")
logger.debug(f"Resposta da API SERP: {response_data}")
return response_data
except urllib.error.HTTPError as e:
logger.error(f"Falha ao chamar a API SERP da Bright Data. Erro HTTP {e.code}: {e.reason}")
exceto urllib.error.URLError como e:
logger.error(f"Falha ao chamar a API SERP da Bright Data. Erro de URL: {e.reason}")
retornar ""
# ----------------------------
# Manipulador Lambda
# ----------------------------
def lambda_handler(event, _):
"""
Manipulador AWS Lambda.
Espera evento com actionGroup, função e parâmetros opcionais (incluindo search_query).
"""
logger.debug(f"lambda_handler chamado com evento: {event}")
action_group = event.get("actionGroup")
function = event.get("function")
parameters = event.get("parameters", [])
# Extrair search_query dos parâmetros
search_query = next(
(param["value"] for param in parameters if param.get("name") == "search_query"),
None,
)
logger.debug(f"Entrada da consulta de pesquisa: {search_query}")
serp_page = serp_api_web_search(search_query) se search_query for diferente de ""
logger.debug(f"Resultados da consulta de pesquisa: {serp_page}")
# Prepare a resposta Lambda
function_response_body = {"TEXT": {"body": serp_page}}
action_response = {
"actionGroup": action_group,
"function": function,
"functionResponse": {"responseBody": function_response_body},
}
response = {"response": action_response, "messageVersion": event.get("messageVersion")}
logger.debug(f"resposta do lambda_handler: {response}")
return responseEsta função Lambda lida com três tarefas principais:
- Recupera credenciais de API com segurança: busca a chave da API Bright Data e a zona da API SERP no AWS Secrets Manager, para que informações confidenciais nunca sejam codificadas.
- Realizar pesquisas na web por meio da API SERP: codifica a consulta de pesquisa, constrói a URL de pesquisa do Google e envia uma solicitação para a API SERP da Bright Data. A API retorna os resultados da pesquisa formatados como Markdown, que é um formato de dados ideal para consumo de IA.
- Responder ao AWS Bedrock: retorna os resultados em uma resposta estruturada que o agente de IA pode usar.
Pronto! Sua função AWS Lambda para se conectar à API SERP da Bright Data foi definida com sucesso.
Etapa 9: Implante sua aplicação AWS CDK
Agora que sua pilha CDK e sua função Lambda relacionada foram implementadas, a etapa final é implantar sua pilha na AWS. Para fazer isso, na pasta do seu projeto, execute o comando de implantação:
cdk deployQuando solicitado a dar permissão para criar a função IAM, digite y para aprovar.
Após alguns instantes, se tudo funcionar conforme o esperado, você deverá ver uma saída como esta:
Em seguida, acesse o console Amazon Bedrock. Na página “Agentes”, você verá uma entrada chamada “web_search_agent”:
Abra o agente e você verá os detalhes do agente implantado:
Inspecione-o pressionando o botão “Editar e criador de agente” e você verá exatamente o mesmo agente de IA implementado em“Como integrar a API SERP da Bright Data com o AWS Bedrock”.
Por fim, observe que você pode testar o agente diretamente usando a interface de bate-papo no canto direito. É isso que você fará na próxima e última etapa!
Etapa 10: Teste o agente de IA
Para testar os recursos de pesquisa na web e recuperação de dados em tempo real do seu agente de IA, tente um prompt como:
“Mostre-me as três últimas notícias sobre a paralisação do governo dos EUA”(Observação: este é apenas um exemplo. Portanto, você pode testar qualquer prompt que exija resultados de pesquisa na web).
Essa é uma solicitação ideal, pois pede informações atualizadas que o modelo básico por si só não conhece. O agente chamará a função Lambda integrada à API SERP, recuperará os resultados e processará os dados para gerar uma resposta coerente.
Execute esta solicitação na seção “Testar agente” do seu agente e você deverá ver um resultado semelhante a este:
Nos bastidores, o agente invoca a função Lambda da API SERP, recupera os resultados de pesquisa mais recentes do Google para a consulta “paralisação do governo dos EUA” e extrai os artigos mais relevantes (junto com suas URLs). Isso é algo que um LLM padrão, como o Nova Lite configurado, não pode fazer sozinho.
Em detalhes, esta é a resposta gerada pelo agente:
Os artigos de notícias selecionados (e seus URLs) correspondem ao que você encontraria manualmente no Google para a consulta “paralisação do governo dos EUA” (pelo menos na data em que o agente foi testado):
Agora, qualquer pessoa que já tentou extrair resultados de pesquisa do Google sabe como isso pode ser desafiador devido à detecção de bots, proibições de IP, renderização de JavaScript e outros desafios. A API SERP da Bright Data lida com todas essas questões para você, retornando SERPs extraídos no formato Markdown (ou HTML, JSON, etc.) otimizado por IA.
Para confirmar que seu agente realmente chamou a função Lambda da API SERP, clique no botão “Mostrar rastreamento” na caixa de resposta. Na seção “Rastreamento etapa 1”, role para baixo até o log de invocação do grupo para inspecionar a saída da chamada Lambda:
Isso verifica se a função Lambda foi executada com sucesso e se o agente interagiu com a API SERP conforme o esperado. Você também pode verificar os logs do AWS CloudWatch para sua função Lambda para confirmar a execução.
É hora de levar seu agente adiante! Teste prompts relacionados à verificação de fatos, monitoramento de marcas, análise de tendências de mercado ou outros cenários para ver como ele se sai em diferentes casos de uso de agentes e RAG.
Et voilà! Você criou com sucesso um agente AWS Bedrock integrado à API SERP da Bright Data usando Python e a biblioteca AWS CDK. Este agente de IA é capaz de recuperar dados de pesquisa na web atualizados, confiáveis e contextuais sob demanda.
Conclusão
Nesta postagem do blog, você aprendeu como integrar a API SERP da Bright Data a um agente de IA AWS Bedrock usando um projeto AWS CDK Python. Esse fluxo de trabalho é perfeito para desenvolvedores que desejam criar agentes de IA mais sensíveis ao contexto na AWS.
Para criar agentes de IA ainda mais sofisticados, explore a infraestrutura da Bright Data para IA. Ela oferece um conjunto de ferramentas para recuperar, validar e transformar dados da web em tempo real.
Crie uma conta Bright Data hoje gratuitamente e comece a experimentar nossas soluções de dados da web prontas para IA!
