이 글에서는 다음을 살펴보겠습니다:

AWS 클라우드 개발 키트(CDK)란 무엇이며, 이를 통해 클라우드 인프라를 정의하고 배포하는 방법.
AWS CDK로 구축된 AWS Bedrock AI 에이전트에 Bright Data의 SERP API와 같은 AI 지원 도구를 활용해 웹 검색 결과에 접근 권한을 부여해야 하는 이유.
Python에서 AWS CDK를 사용하여 SERP API와 통합된 AWS Bedrock 에이전트를 구축하는 방법.

자, 시작해 보겠습니다!

AWS 클라우드 개발 키트(CDK)란 무엇인가요?

AWS CDK( AWS Cloud Development Kit) 는 현대적인 프로그래밍 언어를 사용하여 클라우드 인프라를 코드로 구축하기 위한 오픈 소스 프레임워크입니다. TypeScript, Python, Java, C#, Go와 같은 프로그래밍 언어를 사용하여 AWS 리소스를 프로비저닝하고 AWS CloudFormation을 통해 애플리케이션을 배포하는 데 필요한 기능을 제공합니다.

AWS CDK 덕분에 Amazon Bedrock용 AI 에이전트를 프로그래밍 방식으로 구축할 수도 있습니다. 바로 이 튜토리얼에서 수행할 작업입니다!

AWS CDK로 구축된 Amazon Bedrock AI 에이전트에 웹 검색이 필요한 이유

대규모 언어 모델은 특정 시점까지의 지식만을 반영한 데이터셋으로 훈련됩니다. 그 결과 부정확하거나 허구적인 응답을 생성하는 경향이 있습니다. 이는 최신 정보가 필요한 AI 에이전트에게 특히 문제가 됩니다.

이 문제는 RAG(검색 강화 생성) 환경에서 AI 에이전트에게 최신 신뢰할 수 있는 데이터를 가져올 수 있는 능력을 부여함으로써 해결할 수 있습니다. 예를 들어, AI 에이전트가 웹 검색을 수행하여 검증 가능한 정보를 수집함으로써 지식을 확장하고 정확도를 향상시킬 수 있습니다.

검색 엔진을 스크래핑하는 맞춤형 AWS Lambda 함수를 구축하는 것은 가능하지만 상당히 까다롭습니다. 자바스크립트 렌더링, CAPTCHA, 변화하는 사이트 구조, IP 차단 등을 처리해야 합니다.

더 나은 접근 방식은 Bright Data의 SERP API와 같은 기능이 풍부한 SERP API를 사용하는 것입니다. 이 API는 프록시 처리, 차단 해제, 확장성, 데이터 포맷팅 등을 자동으로 처리합니다. Lambda 함수를 통해 AWS Bedrock과 통합하면 AWS CDK로 구축한 AI 에이전트가 실시간 검색 결과를 활용하여 더 신뢰할 수 있는 응답을 제공할 수 있습니다.

Python으로 AWS CDK를 활용해 SERP API 통합 AI 에이전트 개발하기

이 단계별 섹션에서는 Python을 사용한 AWS CDK로 AWS Bedrock AI 에이전트를 구축하는 방법을 배웁니다. 이 에이전트는 Bright Data SERP API를 통해 검색 엔진에서 데이터를 가져올 수 있습니다.

통합은 에이전트가 도구로 호출할 수 있는 Lambda 함수(SERP API 호출)를 통해 구현됩니다. 구체적으로 Amazon Bedrock 에이전트를 생성하기 위한 주요 구성 요소는 다음과 같습니다:

액션 그룹: 에이전트가 확인하고 호출할 수 있는 함수를 정의합니다.
Lambda 함수: Bright Data SERP API를 쿼리하는 로직을 구현합니다.
AI 에이전트: 파운데이션 모델, 함수, 사용자 요청 간의 상호작용을 조정합니다.

이 설정은 Python 기반 AWS CDK로 완전히 구현됩니다. 시각적 AWS Bedrock 콘솔을 사용해 동일한 결과를 얻으려면 Amazon Bedrock + Bright Data 가이드를 참조하세요.

아래 단계를 따라 AWS CDK를 사용하여 AWS Bedrock AI 에이전트를 구축하고, SERP API를 통해 실시간 웹 검색 기능으로 강화하세요!

필수 사항

이 튜토리얼을 따라하려면 다음이 필요합니다:

AWS CDK CLI 사용을 위해 로컬에 설치된Node.js 22.x 이상
AWS CDK를 Python에서 사용하기 위해 로컬에 설치된Python 3.11 이상.
활성 AWS 계정 (무료 체험판도 가능).
Amazon Bedrock Agents 필수 구성 요소 설정 완료 (현재 일부 AWS 리전에서만이용 가능 ).
API 키가 준비된 Bright Data 계정.
기본적인 Python 프로그래밍 기술.

1단계: AWS CLI 설치 및 인증

AWS CDK를 진행하기 전에 AWS CLI를 설치하고 터미널이 AWS 계정으로 인증할 수 있도록 구성해야 합니다.

참고: 이미 AWS CLI가 설치되어 있고 인증이 구성된 경우, 이 단계를 건너뛰고 다음 단계로 진행하십시오.

운영 체제에 맞는 공식 설치 가이드를 따라 AWS CLI를 설치하세요. 설치 후 다음 명령어로 설치 여부를 확인하세요:

aws --version

다음과 유사한 출력이 표시되어야 합니다:

aws-cli/2.31.32 Python/3.13.9 Windows/11 exe/AMD64

그런 다음 구성 명령을 실행하여 자격 증명을 설정하세요:

aws configure

다음 항목을 입력하라는 메시지가 표시됩니다:

AWS Access Key ID
AWS 비밀 액세스 키
기본 리전 이름 (예: us-east-1)
기본 출력 형식 (선택 사항, 예: json)

CDK 개발 및 배포에 필수적이므로 처음 세 필드를 입력하세요. 해당 정보를 어디서 얻을 수 있는지 궁금하다면:

AWS에 접속하여 로그인하세요.
오른쪽 상단에서 계정 이름을 클릭하여 계정 메뉴를 열고 “보안 자격 증명” 옵션을 선택하세요.
“액세스 키” 섹션에서 새 키를 생성하세요. “액세스 키 ID”와 “비밀 액세스 키”를 안전한 곳에 모두 저장하세요.

완료! 이제 CLI를 통해 AWS 계정에 연결할 수 있습니다. AWS CDK 개발을 진행할 준비가 되었습니다.

2단계: AWS CDK 설치

aws-cdk npm 패키지를 사용하여시스템에 AWS CDK를 전역으로 설치하세요:

npm install -g aws-cdk

설치된 버전을 확인하려면 다음 명령을 실행하세요:

cdk --version

다음과 유사한 출력이 표시됩니다:

2.1031.2 (build 779352d)

참고: Python을 사용한 AWS CDK 기반 AI 에이전트 개발 및 배포에는 버전 2.174.3 이상이 필요합니다.

훌륭합니다! 이제 AWS CDK CLI가 로컬에 설치되었습니다.

3단계: AWS CDK Python 프로젝트 설정

AWS CDK + Bright Data SERP API AI 에이전트를 위한 새 프로젝트 폴더를 생성하세요.
예를 들어, aws-cdk-bright-data-web-search-agent로 이름을 지정할 수 있습니다:

mkdir aws-cdk-bright-data-web-search-agent

폴더로 이동합니다:

cd aws-cdk-bright-data-web-search-agent

그런 다음 init 명령어를 통해 Python 기반의 새로운 AWS CDK 애플리케이션을 초기화합니다:

cdk init app --language python

프로젝트 구조 설정을 위해 CDK CLI가 잠시 시간이 소요될 수 있으니 기다려 주세요.

초기화가 완료되면 프로젝트 폴더 구조는 다음과 같아야 합니다:

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.bat

주목해야 할 두 파일은 다음과 같습니다:

app.py: AWS CDK 애플리케이션의 최상위 정의를 포함합니다.
aws_cdk_bright_data_web_search_agent/aws_cdk_bright_data_web_search_agent_stack.py: 웹 검색 에이전트용 스택을 정의합니다(AI 에이전트 로직을 구현할 위치입니다).

자세한 내용은 Python에서 CDK 작업에 관한 공식 AWS 가이드를 참조하세요.

이제 PyCharm이나 Python 확장 프로그램이 설치된 Visual Studio Code 등 선호하는 Python IDE에서 프로젝트를 로드하세요.

cdk init 명령어가 프로젝트 내에 Python 가상 환경을 자동으로 생성한다는 점에 유의하세요. Linux 또는 macOS에서는 다음 명령어로 활성화합니다:

source .venv/bin/activate

또는 Windows에서는 다음 명령을 실행하세요:

.venvScriptsactivate

그런 다음 활성화된 가상 환경 내에서 필요한 모든 종속성을 설치하세요:

python -m pip install -r requirements.txt

훌륭합니다! 이제 AI 에이전트 개발을 위한 AWS CDK Python 환경이 설정되었습니다.

단계 #4: AWS CDK 부트스트래핑 실행

부트스트래핑은 AWS Cloud Development Kit 사용을 위해 AWS 환경을 준비하는 과정입니다. CDK 스택을 배포하기 전에 환경을 부트스트래핑해야 합니다.

간단히 말해, 이 프로세스는 AWS 계정에 다음 리소스를 설정합니다:

Amazon S3 버킷: AWS Lambda 함수 코드 및 기타 자산과 같은 CDK 프로젝트 파일을 저장합니다.
Amazon ECR 리포지토리: Docker 이미지를 저장합니다.
AWS IAM 역할: AWS CDK가 배포를 수행하는 데 필요한 권한을 부여합니다. (자세한 내용은 부트스트랩 중에 생성되는 IAM 역할에 대한 AWS 문서를 참조하십시오.)

CDK 부트스트랩 프로세스를 시작하려면 프로젝트 폴더에서 다음 명령을 실행하세요:

cdk bootstrap

이 명령은 AWS CloudFormation 서비스에서 CDK 애플리케이션 배포에 필요한 모든 리소스를 포함하는 “CDKToolkit”이라는 스택을 생성합니다.

CloudFormation 콘솔에 접속하여 “스택” 페이지를 확인하여 이를 검증하십시오:
Note the “CDKToolkit” stack in CloudFormation

“CDKToolkit” 스택이 표시됩니다. 해당 링크를 따라가면 다음과 유사한 내용을 확인할 수 있습니다:
The “CDKToolkit” stack generated by the bootstrapping process
부트스트랩 프로세스의 작동 방식, 필요성 및 백엔드에서 발생하는 작업에 대한 자세한 내용은 공식 AWS CDK 문서를 참조하십시오.

5단계: Bright Data의 SERP API 준비

이제 AWS CDK 환경이 개발 및 배포를 위해 설정되었으므로, Bright Data 계정을 준비하고 SERP API 서비스를 구성하여 사전 단계를 완료하세요. 공식 Bright Data 문서를 따르거나 아래 단계를 수행할 수 있습니다.

계정이 없는 경우 Bright Data 계정을 생성하세요. 또는 기존 계정으로 로그인하세요. Bright Data 계정에서 “프록시 및 스크래핑(Proxies & Scraping)” 페이지로 이동합니다. “내 영역(My Zones)” 섹션의 테이블에서 “SERP API” 행이 있는지 확인하세요:
Note the “serp_api” row in the table
“SERP API” 라벨이 있는 행이 보이지 않는다면, 아직 존을 설정하지 않았다는 의미입니다. 아래로 스크롤하여 “SERP API” 섹션으로 이동한 후 “존 생성”을 클릭하여 추가하세요:
Configuring the SERP API zone
SERP API 존을 생성하고 serp_api (또는 원하는 이름)과 같은 이름을 지정하세요. API를 통해 서비스에 접근할 때 필요하므로 선택한 존 이름을 기억해 두세요.

SERP API 제품 페이지에서 “활성화” 스위치를 토글하여 존을 활성화하세요:
Activating the SERP API zone
마지막으로 공식 가이드에 따라 Bright Data API 키를 생성하세요. 곧 필요할 수 있으니 안전한 곳에 보관하십시오.

훌륭합니다! 이제 AWS CDK로 개발한 AWS Bedrock AI 에이전트에서 Bright Data의 SERP API를 사용할 모든 준비가 완료되었습니다.

6단계: CDK 애플리케이션 시크릿을 AWS Secrets Manager에 저장하기

방금 민감한 정보(예: Bright Data API 키 및 SERP API 영역 이름)를 획득했습니다. 이러한 값을 Lambda 함수 코드에 하드코딩하는 대신 AWS Secrets Manager에서 안전하게 읽어와야 합니다.

다음 Bash 명령어를 실행하여 Bright Data API 키와 SERP API 영역을 포함하는 BRIGHT_DATA라는 시크릿을 생성하세요:

aws secretsmanager create-secret 
  --name "BRIGHT_DATA" 
  --description "Bright Data SERP API 통합용 API 자격 증명" 
  --secret-string '{
    "BRIGHT_DATA_API_KEY": "<YOUR_BRIGHT_DATA_API_KEY>",
    "BRIGHT_DATA_SERP_API_ZONE": "<YOUR_BRIGHT_DATA_SERP_API_ZONE>"
  }'

또는, 동등하게 PowerShell에서:

aws secretsmanager create-secret `
  --name "BRIGHT_DATA" `
  --description "Bright Data SERP API 통합용 API 자격 증명" `
  --secret-string '{"BRIGHT_DATA_API_KEY":"<YOUR_BRIGHT_DATA_API_KEY>","BRIGHT_DATA_SERP_API_ZONE":"<YOUR_BRIGHT_DATA_SERP_API_ZONE>"}'

<YOUR_BRIGHT_DATA_API_KEY> 와 <YOUR_BRIGHT_DATA_SERP_API_ZONE> 을 앞서 확인한 실제 값으로 반드시 교체하세요.

해당 명령어는 BRIGHT_DATA 시크릿을 설정합니다. AWS Secrets Manager 콘솔의 “시크릿” 페이지에서 확인할 수 있습니다:
Note the “BRIGHT_DATA” secret in AWS Secrets Manager

“비밀값 가져오기” 버튼을 클릭하면 BRIGHT_DATA_API_KEY 및 BRIGHT_DATA_SERP_API_ZONE 비밀값을 확인할 수 있습니다:
Note the "BRIGHT_DATA_API_KEY” and “BRIGHT_DATA_SERP_API_ZONE” secrets
대단합니다! 이 시크릿들은 곧 정의할 Lambda 함수에서 SERP API 요청을 인증하는 데 사용될 것입니다.

7단계: AWS CDK 스택 구현

이제 AI 에이전트 구축에 필요한 모든 설정이 완료되었으므로, 다음 단계는 Python으로 AWS CDK 스택을 구현하는 것입니다. 먼저 AWS CDK 스택이 무엇인지 이해하는 것이 중요합니다.

스택은 CDK에서 배포 가능한 가장 작은 단위입니다. CDK 구성을 사용하여 정의된 AWS 리소스 모음을 나타냅니다. CDK 앱을 배포할 때 스택 내 모든 리소스는 단일 CloudFormation 스택으로 함께 배포됩니다.

기본 스택 파일 위치:

aws_cdk_bright_data_web_search_agent/aws_cdk_bright_data_web_search_agent_stack.py

Visual Studio Code에서 확인해 보세요:
The CDK stack script in Visual Studio Code
이 파일에는 여러분의 로직을 정의할 일반적인 스택 템플릿이 포함되어 있습니다. 여러분의 임무는 Bright Data SERP API 통합이 적용된 AI 에이전트를 구축하기 위한 전체 AWS CDK 스택을 구현하는 것입니다. 여기에는 Lambda 함수, IAM 역할, 액션 그룹, Bedrock AI 에이전트가 포함됩니다.

다음과 같이 구현하세요:

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

# 필요한 상수 정의
AI_MODEL_ID = "amazon.nova-lite-v1:0" # 에이전트 구동에 사용되는 LLM의 이름
ACTION_GROUP_NAME = "action_group_web_search"
LAMBDA_FUNCTION_NAME = "serp_api_lambda"
AGENT_NAME = "web_search_agent"

# Bright Data 기반 웹 검색 에이전트 배포용 CDK 스택 정의
class AwsCdkBrightDataWebSearchAgentStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # 로깅 및 시크릿 읽기 권한 부여용 Lambda 정책
        lambda_policy = iam.Policy(
            self,
            "LambdaPolicy",
            statements=[
                # CloudWatch 로그 그룹 생성 권한
                iam.PolicyStatement(
                    sid="CreateLogGroup",
                    effect=iam.Effect.ALLOW,
                    actions=["logs:CreateLogGroup"],
                    resources=[f"arn:aws:logs:{Aws.REGION}:{Aws.ACCOUNT_ID}:*"],
                ),
                # 로그 스트림 생성 및 로그 이벤트 저장 권한
                iam.PolicyStatement(
                    sid="CreateLogStreamAndPutLogEvents",
                    effect=iam.Effect.ALLOW,
                    actions=["logs:CreateLogStream", "logs:PutLogEvents"],
                    resources=[
                        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:*",
                    ],
                ),
                # Secrets Manager에서 BRIGHT_DATA 시크릿 읽기 권한
                iam.PolicyStatement(
                    sid="GetSecretsManagerSecret",
                    effect=iam.Effect.ALLOW,
                    actions=["secretsmanager:GetSecretValue"],
                    resources=[
                        f"arn:aws:secretsmanager:{Aws.REGION}:{Aws.ACCOUNT_ID}:secret:BRIGHT_DATA*",
                    ],
                ),
            ],
        )

        # Lambda 함수를 위한 IAM 역할 정의
        lambda_role = iam.Role(
            self,
            "LambdaRole",
            role_name=f"{LAMBDA_FUNCTION_NAME}_role",
            assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
        )

        # Lambda 역할에 정책 연결
        lambda_role.attach_inline_policy(lambda_policy)

        # Lambda 함수 정의
        lambda_function = _lambda.Function(
            self,
            LAMBDA_FUNCTION_NAME,
            function_name=LAMBDA_FUNCTION_NAME,
            runtime=_lambda.Runtime.PYTHON_3_12,  # Python 런타임
            architecture=_lambda.Architecture.ARM_64,
            code=_lambda.Code.from_asset("lambda"),  # "lambda/" 폴더에서 Lambda 코드 읽기
            handler=f"{LAMBDA_FUNCTION_NAME}.lambda_handler",
            timeout=Duration.seconds(120),
            role=lambda_role,  # IAM 역할 연결
            environment={"LOG_LEVEL": "DEBUG", "ACTION_GROUP": f"{ACTION_GROUP_NAME}"},
        )

        # Bedrock 서비스가 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",
        )

        # Bedrock 에이전트용 IAM 정책 정의
        agent_policy = iam.Policy(
            self,
            "AgentPolicy",
            statements=[
                iam.PolicyStatement(
                    sid="AmazonBedrockAgentBedrockFoundationModelPolicy",
                    effect=iam.Effect.ALLOW,
                    actions=["bedrock:InvokeModel"],  # 파운데이션 모델 호출 권한 부여
                    resources=[f"arn:aws:bedrock:{Aws.REGION}::foundation-model/{AI_MODEL_ID}"],
                ),
            ],
        )

        # 에이전트 역할에 대한 신뢰 관계 설정 (Bedrock이 역할을 인수할 수 있도록 허용)
        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/*"},
            },
        )

        # Bedrock 에이전트용 IAM 역할 정의
        agent_role = iam.Role(
            self,
            "AmazonBedrockExecutionRoleForAgents",
            role_name=f"AmazonBedrockExecutionRoleForAgents_{AGENT_NAME}",
            assumed_by=agent_role_trust,
        )
        agent_role.attach_inline_policy(agent_policy)

        # AI 에이전트용 액션 그룹 정의
        action_group = bedrock.CfnAgent.AgentActionGroupProperty(
            action_group_name=ACTION_GROUP_NAME,
            description="Bright Data의 SERP API를 호출하여 웹 검색을 수행하고 검색 엔진에서 최신 정보를 가져옵니다.",
            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="Bright Data의 SERP API와 통합하여 웹 검색을 수행합니다.",
                        parameters={
                            "search_query": bedrock.CfnAgent.ParameterDetailProperty(
                                type="string",
                                description="Google 웹 검색을 위한 검색어.",
                                required=True,
                            )
                        },
                    ),
                ]
            ),
        )

        # Bedrock AI 에이전트 생성 및 지정
        agent_description = """
            Bright Data의 SERP API에 연결하여 검색 엔진에서 최신 웹 검색 컨텍스트를 가져올 수 있는 AI 에이전트입니다.
        """

        agent_instruction = """
            당신은 최신 정보를 검색하고 처리해야 하는 사용 사례를 처리하도록 설계된 에이전트입니다.
            Bright Data의 SERP API를 기반으로 한 웹 검색을 통해 뉴스 및 검색 엔진 결과를 포함한 최신 데이터에 접근할 수 있습니다.
        """

        agent = 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,
        )

        # 배포를 위한 주요 출력값 내보내기
        CfnOutput(self, "agent_id", value=agent.attr_agent_id)
        CfnOutput(self, "agent_version", value=agent.attr_agent_version)

위 코드는 웹 검색 AI 에이전트를 위한 공식 AWS CDK 스택 구현을 수정한 버전입니다.

150줄 이상의 코드에서 수행되는 작업은 가이드 초반에 설명된 단계, 즉 “Bright Data SERP API를 AWS Bedrock AI 에이전트와 통합하는 방법” 문서의 단계 #1, 단계 #2, 단계 #3을 반영합니다.

해당 파일에서 진행되는 작업을 더 잘 이해하기 위해 코드를 다섯 가지 기능 블록으로 나누어 살펴보겠습니다:

Lambda IAM 정책 및 역할: Lambda 함수에 대한 권한을 설정합니다. Lambda는 실행 세부 정보를 기록하기 위해 CloudWatch 로그에 접근해야 하며, Bright Data API 키와 영역을 안전하게 읽기 위해 AWS Secrets Manager에 접근해야 합니다. Lambda를 위한 IAM 역할이 생성되고 적절한 정책이 연결되어 필요한 권한만 가지고 안전하게 작동하도록 보장합니다.
Lambda 함수 정의: 여기서 Lambda 함수 자체를 정의하고 구성합니다. Python 런타임과 아키텍처를 지정하고, Lambda 코드가 포함된 폴더(다음 단계에서 구현될 예정)를 가리키며, 로그 수준 및 액션 그룹 이름과 같은 환경 변수를 설정합니다. AWS Bedrock이 Lambda를 호출할 수 있도록 권한이 부여되어 AI 에이전트가 Bright Data의 SERP API를 통해 웹 검색을 트리거할 수 있습니다.
Bedrock 에이전트 IAM 역할: Bedrock AI 에이전트의 실행 역할을 생성합니다. 에이전트는 지원되는 모델 (이 경우amazon.nova-lite-v1:0) 중 선택된 파운데이션 AI 모델을 호출할 권한이 필요합니다. 신뢰 관계가 정의되어 계정 내에서 Bedrock만 이 역할을 인수할 수 있습니다. 모델 접근 권한을 부여하는 정책이 연결됩니다.
액션 그룹 정의: 액션 그룹은 AI 에이전트가 수행할 수 있는 구체적인 작업을 정의합니다. 에이전트를 Bright Data의 SERP API를 통해 웹 검색을 실행할 수 있게 하는 Lambda 함수와 연결합니다. 액션 그룹에는 입력 매개변수에 대한 메타데이터도 포함되어 있어, 에이전트가 함수와 상호작용하는 방법과 각 검색에 필요한 정보를 이해할 수 있습니다.
Bedrock AI 에이전트 정의: AI 에이전트 자체를 정의합니다. 에이전트를 액션 그룹 및 실행 역할에 연결하고, 사용 방법에 대한 명확한 설명과 지침을 제공합니다.

CDK 스택 배포 후 AWS 콘솔에 AI 에이전트가 생성됩니다. 해당 에이전트는 Lambda 함수 내 Bright Data SERP API 통합을 활용하여 자율적으로 웹 검색을 수행하고 최신 정보를 검색할 수 있습니다. 훌륭합니다!

8단계: SERP API 통합을 위한 Lambda 구현

이전 코드의 다음 스니펫을 살펴보세요:

lambda_function = _lambda.Function(
    self,
    LAMBDA_FUNCTION_NAME,
    function_name=LAMBDA_FUNCTION_NAME,
    runtime=_lambda.Runtime.PYTHON_3_12,  # Python 런타임
    architecture=_lambda.Architecture.ARM_64,
    code=_lambda.Code.from_asset("lambda"),  # "lambda/" 폴더에서 Lambda 코드 읽기
    handler=f"{LAMBDA_FUNCTION_NAME}.lambda_handler",
    timeout=Duration.seconds(120),
    role=lambda_role,  # IAM 역할 연결
    environment={"LOG_LEVEL": "DEBUG", "ACTION_GROUP": f"{ACTION_GROUP_NAME}"},
)

code=_lambda.Code.from_asset("lambda") 라인은 Lambda 함수 코드가 lambda/ 폴더에서 로드될 것임을 지정합니다. 따라서 프로젝트에 lambda/ 폴더를 생성하고 그 안에 serp_api_lambda.py라는 파일을 추가하세요:
The serp_api_lambda.py file inside the lambda/ folder
serp_api_lambda.py 파일에는 앞서 정의한 AI 에이전트가 사용하는 Lambda 함수의 구현이 포함되어야 합니다. Bright Data SERP API와의 통합을 처리하기 위해 이 함수를 다음과 같이 구현하세요:

import json
import logging
import os
import urllib.parse
import urllib.request

import boto3

# ----------------------------
# 로깅 구성
# ----------------------------
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)

# ----------------------------
# 환경 변수에서 AWS 리전 가져오기
# ----------------------------
AWS_REGION = os.environ.get("AWS_REGION")
if not AWS_REGION:
    logger.warning("AWS_REGION 환경 변수가 설정되지 않았습니다; boto3는 기본 리전을 사용합니다")

# ----------------------------
# AWS Secrets Manager에서 시크릿 객체 가져오기
# ----------------------------
def get_secret_object(key: str) -> str:
    """
    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"Secrets Manager에서 비밀 '{key}'를 가져올 수 없습니다: {e}")
        raise e

    secret = json.loads(get_secret_value_response["SecretString"])

    return secret


# 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"]

# ----------------------------
# SERP API 웹 검색
# ----------------------------
def serp_api_web_search(search_query: str) -> str:
    """
    Bright Data SERP API를 호출하여 Google 검색 결과를 가져옵니다.
    """
    logger.info(f"search_query='{search_query}'에 대한 Bright Data SERP API 검색 실행 중")

    # URL용 쿼리 인코딩
    encoded_query = urllib.parse.quote(search_query)
    # SERP 스크래핑을 위한 Google URL 생성
    search_engine_url = f"https://www.google.com/search?q={encoded_query}"

    # Bright Data API 요청 (문서: 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" # AI가 처리 가능한 마크다운 문서 형태로 SERP를 가져오기 위해
    }

    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"SERP API 응답: {response_data}")
        return response_data
    except urllib.error.HTTPError as e:
        logger.error(f"Bright Data SERP API 호출 실패. HTTP 오류 {e.code}: {e.reason}")
    except urllib.error.URLError as e:
        logger.error(f"Bright Data SERP API 호출 실패. URL 오류: {e.reason}")

    return ""


# ----------------------------
# Lambda 핸들러
# ----------------------------
def lambda_handler(event, _):
    """
    AWS Lambda 핸들러.
    actionGroup, function 및 선택적 매개변수(search_query 포함)가 포함된 이벤트를 기대합니다.
    """
    logger.debug(f"lambda_handler 호출됨: {event}")

    action_group = event.get("actionGroup")
    function = event.get("function")
    parameters = event.get("parameters", [])

    # 매개변수에서 search_query 추출
    search_query = next(
        (param["value"] for param in parameters if param.get("name") == "search_query"),
        None,
    )
    logger.debug(f"입력 검색어: {search_query}")

    serp_page = serp_api_web_search(search_query) if search_query else ""
    logger.debug(f"검색어 결과: {serp_page}")

    # 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"lambda_handler 응답: {response}")

    return response

이 Lambda 함수는 세 가지 주요 작업을 처리합니다:

API 자격 증명을 안전하게 검색: AWS Secrets Manager에서 Bright Data API 키와 SERP API 영역을 가져와 민감한 정보가 하드코딩되지 않도록 합니다.
SERP API를 통한 웹 검색 수행: 검색 쿼리를 인코딩하고 Google 검색 URL을 생성한 후 Bright Data SERP API로 요청을 전송합니다. API는 AI가 활용하기에 이상적인 데이터 형식인 Markdown으로 포맷된 검색 결과를 반환합니다.
AWS Bedrock 응답: AI 에이전트가 활용할 수 있는 구조화된 응답 형식으로 결과를 반환합니다.

자, 이제 시작합니다! Bright Data SERP API에 연결하는 AWS Lambda 함수가 성공적으로 정의되었습니다.

9단계: AWS CDK 애플리케이션 배포

CDK 스택과 관련 Lambda 함수가 구현되었으므로, 마지막 단계는 스택을 AWS에 배포하는 것입니다. 프로젝트 폴더에서 다음 deploy 명령어를 실행하세요:

cdk deploy

IAM 역할 생성 권한을 요청하는 메시지가 표시되면 y를 입력하여 승인하세요.

잠시 후, 모든 것이 예상대로 진행되면 다음과 같은 출력이 표시됩니다:
The output of the “deploy” command

다음으로 Amazon Bedrock 콘솔로 이동합니다. “에이전트(Agents)” 페이지에서 “web_search_agent” 항목이 표시됩니다:
Note the “web_search_agent” entry

에이전트를 열면 배포된 에이전트 세부 정보를 확인할 수 있습니다:
The details page for the “web_search_agent”
“편집 및 에이전트 빌더” 버튼을 눌러 확인하면, “Bright Data SERP API를 AWS Bedrock에 통합하는 방법“에서 구현한 것과 정확히 동일한 AI 에이전트를 볼 수 있습니다.

마지막으로, 오른쪽 모서리의 채팅 인터페이스를 통해 에이전트를 직접 테스트할 수 있습니다. 다음이자 마지막 단계에서 바로 이 작업을 수행하게 됩니다!

단계 #10: AI 에이전트 테스트

AI 에이전트의 웹 검색 및 실시간 데이터 검색 기능을 테스트하려면 다음과 같은 프롬프트를 시도해 보세요:

"미국 정부 셧다운 관련 최신 뉴스 기사 상위 3개를 알려주세요"

(참고: 이는 예시일 뿐입니다. 따라서 웹 검색 결과가 필요한 모든 프롬프트로 테스트할 수 있습니다.)

이 프롬프트는 파운데이션 모델만으로는 알 수 없는 최신 정보를 요청하기 때문에 이상적입니다. 에이전트는 SERP API와 통합된 람다 함수를 호출하여 결과를 가져오고, 데이터를 처리하여 일관된 응답을 생성합니다.

에이전트의 “에이전트 테스트” 섹션에서 이 프롬프트를 실행하면 다음과 유사한 출력이 표시됩니다:
Running the prompt in the AWS Amazon Bedrock console
배경에서 에이전트는 SERP API 람다 함수를 호출하여 “미국 정부 셧다운” 쿼리에 대한 최신 구글 검색 결과를 가져오고, 가장 관련성 높은 기사(해당 URL 포함)를 추출합니다. 이는 설정된 Nova Lite와 같은 표준 LLM이 단독으로 수행할 수 없는 작업입니다.

자세한 내용은 에이전트가 생성한 응답입니다:

The agent’s response
선택된 뉴스 기사(및 해당 URL)는 “미국 정부 셧다운” 쿼리에 대해 구글에서 수동으로 찾을 수 있는 내용과 일치합니다(적어도 에이전트 테스트 시점 기준):
The SERP for the “US government shutdown” search query
구글 검색 결과 스크래핑을 시도해 본 사람이라면 봇 탐지, IP 차단, 자바스크립트 렌더링 등 다양한 문제로 인해 얼마나 어려운지 잘 알 것입니다. Bright Data SERP API는 이러한 모든 문제를 처리하여 AI 최적화 마크다운(또는 HTML, JSON 등) 형식으로 스크래핑된 SERP를 반환합니다.

에이전트가 실제로 SERP API 람다 함수를 호출했는지 확인하려면 응답 상자의 “추적 보기” 버튼을 클릭하세요. “추적 단계 1” 섹션에서 그룹 호출 로그까지 스크롤하여 람다 호출 결과를 확인합니다:
The output of the SERP API Lambda function
이를 통해 람다 함수가 성공적으로 실행되었으며 에이전트가 의도한 대로 SERP API와 상호작용했음을 확인할 수 있습니다. 람다 함수의 AWS CloudWatch 로그를 확인하여 실행 여부를 추가로 검증할 수도 있습니다.

이제 에이전트를 한 단계 발전시켜 보세요! 사실 확인, 브랜드 모니터링, 시장 동향 분석 또는 기타 시나리오와 관련된 프롬프트를 테스트하여 다양한 에이전트 및 RAG 사용 사례에서 어떻게 작동하는지 확인해 보세요.

자, 이제 완성되었습니다! Python과 AWS CDK 라이브러리를 사용하여 Bright Data의 SERP API와 통합된 AWS Bedrock 에이전트를 성공적으로 구축했습니다. 이 AI 에이전트는 최신, 신뢰할 수 있고 맥락에 맞는 웹 검색 데이터를 필요에 따라 검색할 수 있습니다.

결론

이 블로그 포스트에서는 AWS CDK Python 프로젝트를 사용하여 Bright Data의 SERP API를 AWS Bedrock AI 에이전트에 통합하는 방법을 배웠습니다. 이 워크플로는 AWS에서 더 많은 컨텍스트 인식 AI 에이전트를 구축하려는 개발자에게 완벽합니다.

더 정교한 AI 에이전트를 구축하려면 Bright Data의 AI 인프라를 살펴보세요. 실시간 웹 데이터를 수집, 검증, 변환하는 도구 모음을 제공합니다.

지금 바로 Bright Data 계정을 무료로 생성하고 AI 활용이 가능한 웹 데이터 솔루션으로 실험을 시작해 보세요!

문의하기 무료 체험 시작하기

Bright Data의 SERP API를 활용한 AWS CDK 기반 Python의 Bedrock Agent