AWS는 메시지를 지원하는 Bedrock 모델에서 Converse가 모델 간 요청 형식을 통일하고 멀티턴 대화를 쉽게 관리할 수 있기 때문에, InvokeModel보다 Converse 사용을 권장합니다.
1. Converse API란?
Converse API는 Amazon Bedrock의 여러 생성형 AI 모델을 공통된 메시지 형식으로 호출하기 위한 대화형 API 입니다.
핵심 구조는 다음과 같습니다.
사용자
│
│ "AWS Bedrock이 뭐야?"
▼
Python 프로그램
│
│ boto3
▼
Bedrock Runtime
│
│ converse()
▼
Foundation Model
│
│ Nova / Claude / Llama / Mistral ...
▼
AI 답변
Plain Text
복사
InvokeModel에서는 모델별 native JSON 형식을 알아야 하는 경우가 있지만, Converse는 메시지를 지원하는 모델에 대해 공통 인터페이스를 제공합니다. 그래서 모델을 바꾸더라도 애플리케이션 코드의 상당 부분을 그대로 유지할 수 있습니다.
2. Converse API의 주요 사용 목적
사용 목적 | 설명 |
챗봇 개발 | 사용자와 AI가 대화하는 서비스 |
멀티턴 대화 | 이전 질문/답변을 포함하여 연속 대화 |
모델 교체 | 공통 메시지 구조를 사용하여 모델 변경을 단순화 |
System Prompt | AI의 역할과 행동 방식 지정 |
Tool Use | Lambda, API, DB 등의 외부 기능 연결 |
Guardrails | 입력/출력에 Bedrock Guardrails 적용 |
Streaming | ConverseStream으로 실시간 답변 출력 |
AI Agent 기반 기능 | 모델이 필요한 Tool을 판단하는 구조 구현 |
특히 Converse는 system, messages, inferenceConfig, toolConfig, guardrailConfig 등을 지원합니다.
3. InvokeModel과 Converse의 핵심 차이
앞에서 공부한 내용을 연결하면 이렇게 이해하면 됩니다.
InvokeModel
Python
↓
모델 고유 Request 형식
↓
Foundation Model
↓
모델 고유 Response 형식
Plain Text
복사
Converse
Python
↓
공통 Messages 형식
↓
Bedrock Converse API
↓
Foundation Model
↓
공통된 대화형 Response 구조
Plain Text
복사
따라서 대표적인 차이는 다음과 같습니다. AWS는 Converse를 멀티턴 채팅/표준화에, Invoke를 직접 모델 접근과 요청·응답 제어가 필요한 경우에 적합한 API로 설명합니다.
구분 | InvokeModel | Converse |
호출 | invoke_model() | converse() |
주요 목적 | 모델 직접 추론 | 대화형 AI |
입력 형식 | 모델별 차이 가능 | 공통 메시지 구조 |
모델 교체 | 상대적으로 코드 변경 가능성 큼 | 상대적으로 간단 |
멀티턴 | 직접 관리 가능 | 메시지 기반으로 편리 |
System Prompt | 모델별 구조 확인 | system |
Tool Use | 가능 | toolConfig로 표준화 |
Guardrail | 가능 | guardrailConfig 지원 |
챗봇 개발 | 가능 | 특히 적합 |
4. 가장 간단한 Converse Python 코드
먼저 Tool 없이 질문 → Bedrock → 답변만 테스트해 보겠습니다.
파일 이름:
converse_basic.py
Plain Text
복사
전체 코드는 다음과 같습니다.
# ============================================================
# Amazon Bedrock Converse API 기본 실습
# Amazon Nova Lite 사용
# ============================================================
import boto3
from botocore.exceptions import ClientError
# ------------------------------------------------------------
# 1. Amazon Bedrock Runtime Client 생성
# ------------------------------------------------------------
#
# 실제 Foundation Model을 호출하기 때문에
# "bedrock-runtime" 서비스를 사용합니다.
# ------------------------------------------------------------
bedrock = boto3.client(
service_name="bedrock-runtime",
region_name="us-east-1"
)
# ------------------------------------------------------------
# 2. 사용할 모델 ID
# ------------------------------------------------------------
MODEL_ID = "amazon.nova-lite-v1:0"
# ------------------------------------------------------------
# 3. 사용자 질문
# ------------------------------------------------------------
user_message = "Amazon Bedrock이 무엇인지 초보자에게 쉽게 설명해주세요."
# ------------------------------------------------------------
# 4. Converse API에서 사용할 messages 생성
# ------------------------------------------------------------
#
# role
# user : 사용자의 메시지
# assistant : AI의 메시지
#
# content
# 실제 질문 또는 답변
# ------------------------------------------------------------
messages = [
{
"role": "user",
"content": [
{
"text": user_message
}
]
}
]
# ------------------------------------------------------------
# 5. Converse API 호출
# ------------------------------------------------------------
try:
response = bedrock.converse(
# 사용할 Foundation Model
modelId=MODEL_ID,
# 대화 내용
messages=messages,
# AI 응답 생성 설정
inferenceConfig={
"maxTokens": 512,
"temperature": 0.5,
"topP": 0.9
}
)
# --------------------------------------------------------
# 6. AI 답변 추출
# --------------------------------------------------------
answer = response[
"output"
][
"message"
][
"content"
][0][
"text"
]
# --------------------------------------------------------
# 7. 결과 출력
# --------------------------------------------------------
print("\n========== 사용자 질문 ==========\n")
print(user_message)
print("\n========== Bedrock 답변 ==========\n")
print(answer)
except ClientError as error:
print("\nBedrock API 호출 오류")
print(error)
except Exception as error:
print("\n프로그램 실행 오류")
print(error)
Plain Text
복사
AWS 공식 Python 예제도 boto3.client("bedrock-runtime") → messages 생성 → client.converse() → response["output"]["message"]["content"][0]["text"]의 흐름을 사용합니다.
5. 실행 방법
이미 boto3가 설치되어 있다면 바로 실행할 수 있습니다.
설치되지 않았다면:
pip install boto3
Plain Text
복사
AWS 인증 확인:
aws sts get-caller-identity
Plain Text
복사
그리고 실행합니다.
python converse_basic.py
Plain Text
복사
정상 실행되면:
========== 사용자 질문 ==========
Amazon Bedrock이 무엇인지 초보자에게 쉽게 설명해주세요.
========== Bedrock 답변 ==========
Amazon Bedrock은 AWS에서 제공하는 생성형 AI 서비스입니다.
다양한 Foundation Model을 API를 통해 사용할 수 있으며...
Plain Text
복사
처럼 출력됩니다.
6. messages가 Converse에서 가장 중요합니다
Converse API를 공부할 때 가장 먼저 이해해야 하는 것이 messages입니다.
messages = [
{
"role": "user",
"content": [
{
"text": "안녕하세요."
}
]
}
]
Plain Text
복사
쉽게 보면:
messages
│
└─ 사용자 메시지
│
├─ role = user
│
└─ content
│
└─ text = "안녕하세요."
Plain Text
복사
즉,
"role": "user"
Plain Text
복사
이 메시지는 사용자가 입력한 것입니다.
라는 뜻이고,
"content": [ {"text": "안녕하세요."}]
Plain Text
복사
실제 메시지 내용입니다.
7. System Prompt도 사용할 수 있습니다
예를 들어 AI를 AWS 강사로 만들고 싶다면 다음처럼 할 수 있습니다.
response = bedrock.converse(
modelId=MODEL_ID,
system=[
{
"text": """
당신은 AWS 초보자를 교육하는 전문 강사입니다.
어려운 용어는 쉽게 설명하세요.
가능하면 예제를 사용하세요.
모든 답변은 한국어로 작성하세요.
"""
}
],
messages=[
{
"role": "user",
"content": [
{
"text": "Amazon Bedrock을 설명해주세요."
}
]
}
],
inferenceConfig={
"maxTokens": 512,
"temperature": 0.5
}
)
Plain Text
복사
구조적으로 보면:
System
│
└─ "너는 AWS 강사야."
↓
Messages
│
└─ "Bedrock을 설명해줘."
↓
Converse
↓
Foundation Model
↓
AWS 강사 스타일 답변
Plain Text
복사
AWS 공식 문서에서도 system은 모델에 지침이나 컨텍스트를 제공하는 시스템 프롬프트 용도로 정의되어 있습니다.
8. 이번에는 진짜 대화가 이어지도록 만들어보기
Converse의 장점을 보려면 한 번 질문하고 끝내는 것보다 멀티턴 대화를 만들어보는 것이 좋습니다.
파일:
converse_chat.py
Plain Text
복사
# ============================================================
# Amazon Bedrock Converse API
# 멀티턴 대화 예제
# ============================================================
import boto3
from botocore.exceptions import ClientError
# Bedrock Runtime Client
bedrock = boto3.client(
"bedrock-runtime",
region_name="us-east-1"
)
# 사용할 모델
MODEL_ID = "amazon.nova-lite-v1:0"
# ------------------------------------------------------------
# 대화 내용을 저장하는 리스트
# ------------------------------------------------------------
messages = []
print("======================================")
print(" Amazon Bedrock Converse Chat")
print("======================================")
print("종료하려면 exit를 입력하세요.")
print()
while True:
# --------------------------------------------------------
# 사용자 입력
# --------------------------------------------------------
user_input = input("사용자: ")
# 프로그램 종료
if user_input.lower() == "exit":
print("대화를 종료합니다.")
break
# --------------------------------------------------------
# 사용자 메시지를 대화 기록에 추가
# --------------------------------------------------------
messages.append(
{
"role": "user",
"content": [
{
"text": user_input
}
]
}
)
try:
# ----------------------------------------------------
# Converse API 호출
# ----------------------------------------------------
response = bedrock.converse(
modelId=MODEL_ID,
system=[
{
"text":
"당신은 AWS 초보자를 교육하는 강사입니다. "
"모든 답변은 한국어로 쉽게 설명하세요."
}
],
messages=messages,
inferenceConfig={
"maxTokens": 512,
"temperature": 0.5,
"topP": 0.9
}
)
# ----------------------------------------------------
# Assistant Message 전체 가져오기
# ----------------------------------------------------
assistant_message = response["output"]["message"]
# ----------------------------------------------------
# 답변 출력
# ----------------------------------------------------
answer = assistant_message["content"][0]["text"]
print()
print("AI:", answer)
print()
# ----------------------------------------------------
# AI 답변도 messages에 저장
# ----------------------------------------------------
#
# 이 부분이 중요합니다.
#
# 다음 Converse 호출에서 이전 대화를 함께 전달하기
# 때문에 AI가 앞의 대화를 참고할 수 있습니다.
# ----------------------------------------------------
messages.append(assistant_message)
except ClientError as error:
print("Bedrock API 오류:")
print(error)
except Exception as error:
print("프로그램 오류:")
print(error)
Plain Text
복사
이제 실행합니다.
python converse_chat.py
Plain Text
복사
예를 들어:
사용자: Amazon Bedrock이 뭐야?
AI: Amazon Bedrock은 AWS의 생성형 AI 서비스입니다.
사용자: 방금 설명한 서비스의 장점 3개만 알려줘.
AI: Amazon Bedrock의 주요 장점은...
Plain Text
복사
두 번째 질문에 "Amazon Bedrock"이라는 단어를 넣지 않았는데도 이전 대화를 함께 전달했기 때문에 문맥을 이어갈 수 있습니다. Converse는 이런 멀티턴 대화형 애플리케이션 구축을 주요 사용 사례로 제공한다.
9. 첨부하신 화면 오른쪽의 Tool은 무엇인가?
첨부하신 슬라이드에서 중요한 부분이 이것입니다.
tools = [
{
"toolSpec": {
"name": "get_weather",
...
}
}
]
Plain Text
복사
이것은 AI에게
get_weather라는 외부 기능을 사용할 수 있어. 라고 도구의 존재와 입력 형식을 알려주는 것입니다.
예를 들어:
사용자
"서울 날씨 어때?"
↓
Converse API
↓
Foundation Model
↓
"날씨 정보가 필요하다"
↓
get_weather Tool 사용 요청
↓
Python 프로그램
↓
날씨 API / Lambda 실행
↓
결과 반환
↓
Foundation Model
↓
"현재 서울 날씨는..."
Plain Text
복사
여기서 매우 중요한 점이 있습니다.
일반적인 Converse의 client-side Tool Use에서는 모델이 Python 함수나 Lambda를 직접 실행하는 것이 아닙니다.
모델은
get_weather Tool을 이런 파라미터로 사용하고 싶다. 라는 Tool Use 요청을 반환합니다.
그러면 애플리케이션 코드가 실제 API/Lambda/DB 등을 실행하고 결과를 다시 모델에 전달합니다.
10. Tool 정의 형태
첨부 화면의 Tool을 조금 정리하면 다음과 같습니다.
tools = [
{
"toolSpec": {
"name": "get_weather",
"description": "지정한 도시의 현재 날씨를 조회합니다.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "조회할 도시 이름"
}
},
"required": [
"location"
]
}
}
}
}
]
Plain Text
복사
그리고 Converse에 연결합니다.
response = bedrock.converse(
modelId=MODEL_ID,
messages=[
{
"role": "user",
"content": [
{
"text": "서울 날씨 어때?"
}
]
}
],
toolConfig={
"tools": tools
}
)
Plain Text
복사
AWS Converse API에서는 toolConfig에 모델이 사용할 수 있는 Tool 정의를 전달할 수 있습니다.
단, 이것만 작성한다고 실제 날씨가 조회되는 것은 아닙니다. Tool 요청 감지 → 실제 함수/Lambda 실행 → toolResult 반환 → Converse 재호출 단계가 추가로 필요합니다.
11. Converse API 전체 구조
최종적으로 구조를 이렇게 기억하시면 됩니다.
Amazon Bedrock
Converse API
│
├── modelId
│ └── 어떤 모델을 사용할 것인가?
│
├── system
│ └── AI에게 어떤 역할을 줄 것인가?
│
├── messages
│ ├── user
│ └── assistant
│
├── inferenceConfig
│ ├── maxTokens
│ ├── temperature
│ └── topP
│
├── toolConfig
│ └── 외부 Tool 정의
│
├── guardrailConfig
│ └── Bedrock Guardrail
│
└── response
│
└── output
└── message
└── content
Plain Text
복사
12. InvokeModel → Converse → AI Agent 관계
지금까지 공부하신 내용을 하나로 연결하면 다음 구조가 중요하다.
[1단계]
InvokeModel
─────────────────────────
모델을 직접 호출하는 방법 학습
↓
[2단계]
Converse
─────────────────────────
공통 Messages 형식
멀티턴 대화
System Prompt
↓
[3단계]
Converse + Tool Use
─────────────────────────
AI가 Tool 필요성 판단
↓
[4단계]
Python Function / Lambda
─────────────────────────
날씨 조회
상품 조회
재고 조회
DB 조회
예산 계산
↓
[5단계]
AI Agent
─────────────────────────
LLM
+ Prompt
+ Conversation
+ Tools
+ 외부 API
+ Lambda
Plain Text
복사
그래서 앞서 진행하셨던 Pet Store AI Agent나 Travel Planner Agent도 이 개념을 이해하고 나면 훨씬 쉽게 보입니다. 단순히 LLM에게 질문하는 단계에서 끝나는 것이 아니라, Converse + Tool Use + Lambda까지 연결하면서 Agent 형태로 발전시킬 수 있기 때문입니다.
다음 실습으로는 서울 날씨 알려줘 → Converse가 Tool 사용 판단 → Python이 Lambda 호출 → Lambda 결과를 Converse에 반환 → Nova가 최종 한국어 답변 생성까지 한 번에 동작하는 전체 Python 코드를 만들어보는 것이 가장 자연스럽습니다.
Converse API의 Tool Use와 AWS Lambda를 실제로 연결하는 완성형 코드
전체동작 프로세스
사용자: "서울 날씨 알려줘"
↓
Amazon Bedrock Converse
↓
Nova가 get_weather Tool 필요 판단
↓
Python이 toolUse 요청 확인
↓
AWS Lambda 호출
↓
Lambda가 날씨 데이터 반환
↓
Python이 toolResult를 Nova에 전달
↓
Nova가 결과를 자연어로 정리
↓
"현재 서울은 23.5°C이고..."
JavaScript
복사
AWS 공식 문서에서도 Converse의 client-side tool use는 모델이 Tool을 직접 실행하는 것이 아니라, Tool 이름과 입력값을 반환하면 애플리케이션이 Lambda/API/DB 등을 실행하고 그 결과를 toolResult로 모델에 다시 전달하는 구조라고 설명한다.
1. 이번 실습 구성 : 파일은 2개라고 생각하면 됩니다.
AWS
│
├── Lambda
│ └── travel-weather-function
│ └── lambda_function.py
│
└── 내 Windows PC
│
└── weather_agent.py
JavaScript
복사
역할
구성 | 역할 |
Nova | 질문 분석 + Tool 사용 판단 + 최종 답변 |
Converse API | Nova와 대화 |
get_weather | Nova에게 알려주는 Tool 이름 |
Python | Nova와 Lambda 사이를 연결 |
Lambda | 실제 날씨 조회 |
toolUse | Nova → Python의 Tool 실행 요청 |
toolResult | Python → Nova의 실행 결과 |
기존에 사용했던 travel-weather-function Lambda가 있다면 그대로 활용할 수 있는 구조입니다.
2. 먼저 Lambda 코드 만들기
travel-weather-function
JavaScript
복사
Lambda의 lambda_function.py를 다음처럼 작성합니다.
이 예제에서는 외부 Python 패키지 설치 없이 실행할 수 있도록 Python 표준 라이브러리 urllib을 사용하고, Open-Meteo API에서 현재 기온·강수량·날씨 코드를 가져오도록 구성했습니다.
# ============================================================
# AWS Lambda
# 서울 / 제주 / 부산 등의 현재 날씨 조회
# ============================================================
import json
import urllib.request
import urllib.parse
# ------------------------------------------------------------
# 도시별 좌표
# ------------------------------------------------------------
CITY_COORDINATES = {
"서울": {
"latitude": 37.5665,
"longitude": 126.9780
},
"부산": {
"latitude": 35.1796,
"longitude": 129.0756
},
"제주": {
"latitude": 33.4996,
"longitude": 126.5312
},
"인천": {
"latitude": 37.4563,
"longitude": 126.7052
}
}
# ------------------------------------------------------------
# 날씨 코드 설명
# ------------------------------------------------------------
def weather_description(code):
weather_codes = {
0: "맑음",
1: "대체로 맑음",
2: "부분적으로 흐림",
3: "흐림",
45: "안개",
48: "서리 안개",
51: "약한 이슬비",
53: "이슬비",
55: "강한 이슬비",
61: "약한 비",
63: "비",
65: "강한 비",
71: "약한 눈",
73: "눈",
75: "강한 눈",
80: "약한 소나기",
81: "소나기",
82: "강한 소나기",
95: "뇌우"
}
return weather_codes.get(
code,
"알 수 없는 날씨"
)
# ------------------------------------------------------------
# Lambda Handler
# ------------------------------------------------------------
def lambda_handler(event, context):
print("입력 Event:", event)
# --------------------------------------------------------
# 도시 이름 가져오기
# --------------------------------------------------------
city = event.get("city")
if not city:
return {
"success": False,
"message": "city 값이 필요합니다."
}
# --------------------------------------------------------
# 지원 도시 확인
# --------------------------------------------------------
if city not in CITY_COORDINATES:
return {
"success": False,
"city": city,
"message": "현재 지원하지 않는 도시입니다."
}
# --------------------------------------------------------
# 위도 / 경도 가져오기
# --------------------------------------------------------
latitude = CITY_COORDINATES[city]["latitude"]
longitude = CITY_COORDINATES[city]["longitude"]
# --------------------------------------------------------
# Open-Meteo API URL 생성
# --------------------------------------------------------
params = urllib.parse.urlencode({
"latitude": latitude,
"longitude": longitude,
"current":
"temperature_2m,"
"precipitation,"
"weather_code",
"timezone": "Asia/Seoul"
})
url = (
"https://api.open-meteo.com/v1/forecast?"
+ params
)
print("Weather API URL:", url)
try:
# ----------------------------------------------------
# 날씨 API 호출
# ----------------------------------------------------
with urllib.request.urlopen(
url,
timeout=10
) as response:
weather_data = json.loads(
response.read().decode("utf-8")
)
# ----------------------------------------------------
# 현재 날씨 데이터
# ----------------------------------------------------
current = weather_data["current"]
temperature = current["temperature_2m"]
precipitation = current["precipitation"]
weather_code = current["weather_code"]
# ----------------------------------------------------
# Lambda 결과
# ----------------------------------------------------
result = {
"success": True,
"city": city,
"temperature": temperature,
"precipitation": precipitation,
"weather_code": weather_code,
"weather":
weather_description(weather_code),
"unit": "C"
}
print("Lambda 결과:", result)
return result
except Exception as error:
print("날씨 API 오류:", str(error))
return {
"success": False,
"city": city,
"message": str(error)
}
JavaScript
복사
3. Lambda부터 단독 테스트
Agent에 연결하기 전에 Lambda가 정상인지 반드시 확인하는 것이 좋습니다.
Lambda Console에서 테스트 이벤트를 다음처럼 만듭니다.
{
"city": "서울"
}
JavaScript
복사
정상적인 경우 대략 다음 구조가 반환됩니다.
{
"success": true,
"city": "서울",
"temperature": 23.5,
"precipitation": 0.0,
"weather_code": 1,
"weather": "대체로 맑음",
"unit": "C"
}
JavaScript
복사
4. 로컬 PC에서 Lambda 호출 권한 확인
이번에는 Python이 Lambda를 호출해야 합니다.
따라서 Python을 실행하는 AWS IAM 사용자 또는 Role에 최소한 다음과 같은 권한이 필요합니다
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": "*"
}
]
}
JavaScript
복사
실습용 예제이므로 Resource: "*"로 단순화했습니다. 실제 운영에서는 사용할 모델/추론 프로파일과 Lambda ARN으로 범위를 제한하는 것이 좋다.
5. Python 패키지 설치
Windows PowerShell에서:
pip install --upgrade boto3 botocore
JavaScript
복사
설치 확인:
python -c "import boto3; print(boto3.__version__)"
JavaScript
복사
AWS 인증 확인:
aws sts get-caller-identity
JavaScript
복사
6. 핵심: weather_agent.py
이제 Converse → Tool Use → Lambda → Tool Result → Converse 전체를 하나로 연결합니다.
파일:
weather_agent.py
JavaScript
복사
전체 코드는 다음과 같다.
# ============================================================
# Amazon Bedrock Converse API + Tool Use + AWS Lambda
#
# 동작 과정
#
# 사용자
# ↓
# Amazon Nova
# ↓
# Tool 사용 판단
# ↓
# Python
# ↓
# AWS Lambda
# ↓
# 날씨 결과
# ↓
# Python
# ↓
# Nova
# ↓
# 최종 한국어 답변
# ============================================================
import json
import boto3
from botocore.exceptions import ClientError
# ============================================================
# 1. 기본 설정
# ============================================================
BEDROCK_REGION = "us-east-1"
LAMBDA_REGION = "ap-northeast-2"
MODEL_ID = "amazon.nova-lite-v1:0"
LAMBDA_FUNCTION_NAME = "travel-weather-function"
# ============================================================
# 2. Bedrock Runtime Client
# ============================================================
bedrock = boto3.client(
service_name="bedrock-runtime",
region_name=BEDROCK_REGION
)
# ============================================================
# 3. Lambda Client
# ============================================================
lambda_client = boto3.client(
service_name="lambda",
region_name=LAMBDA_REGION
)
# ============================================================
# 4. Nova에게 사용할 수 있는 Tool 정의
# ============================================================
#
# 중요한 점:
#
# 여기서 Lambda를 직접 등록하는 것이 아닙니다.
#
# Nova에게
#
# "get_weather라는 Tool이 있고
# city라는 값을 전달해야 한다."
#
# 라고 알려주는 JSON Schema입니다.
#
# ============================================================
weather_tool = {
"toolSpec": {
"name": "get_weather",
"description":
"대한민국 도시의 현재 날씨를 조회합니다. "
"사용자가 서울, 부산, 제주, 인천 등의 "
"현재 날씨를 질문하면 이 도구를 사용하세요.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description":
"날씨를 조회할 대한민국 도시 이름. "
"예: 서울, 부산, 제주, 인천"
}
},
"required": [
"city"
]
}
}
}
}
# ============================================================
# 5. Tool Configuration
# ============================================================
tool_config = {
"tools": [
weather_tool
]
}
# ============================================================
# 6. AWS Lambda 호출 함수
# ============================================================
def call_weather_lambda(city):
print()
print("========================================")
print("[Python] AWS Lambda 호출")
print("========================================")
print("도시:", city)
# --------------------------------------------------------
# Lambda에게 전달할 데이터
# --------------------------------------------------------
payload = {
"city": city
}
try:
# ----------------------------------------------------
# AWS Lambda 호출
# ----------------------------------------------------
response = lambda_client.invoke(
FunctionName=LAMBDA_FUNCTION_NAME,
InvocationType="RequestResponse",
Payload=json.dumps(
payload,
ensure_ascii=False
).encode("utf-8")
)
# ----------------------------------------------------
# Lambda 응답 읽기
# ----------------------------------------------------
response_payload = response[
"Payload"
].read()
# ----------------------------------------------------
# JSON → Python Dictionary
# ----------------------------------------------------
result = json.loads(
response_payload.decode("utf-8")
)
print()
print("Lambda 응답:")
print(
json.dumps(
result,
ensure_ascii=False,
indent=2
)
)
return result
except ClientError as error:
print("Lambda 호출 오류:")
print(error)
return {
"success": False,
"message": str(error)
}
except Exception as error:
print("프로그램 오류:")
print(error)
return {
"success": False,
"message": str(error)
}
# ============================================================
# 7. Weather Agent 함수
# ============================================================
def weather_agent(user_question):
print()
print("========================================")
print("[사용자 질문]")
print("========================================")
print(user_question)
# --------------------------------------------------------
# 첫 번째 대화
# --------------------------------------------------------
messages = [
{
"role": "user",
"content": [
{
"text": user_question
}
]
}
]
# ========================================================
# 8. 첫 번째 Converse 호출
# ========================================================
#
# 여기에서는 아직 Lambda를 호출하지 않습니다.
#
# Nova에게
#
# "사용자의 질문을 보고
# Tool이 필요한지 판단해라."
#
# 라고 요청합니다.
#
# ========================================================
print()
print("========================================")
print("[1단계] Nova에게 질문 전달")
print("========================================")
response = bedrock.converse(
modelId=MODEL_ID,
system=[
{
"text":
"당신은 날씨 안내 AI Assistant입니다. "
"사용자가 현재 날씨를 질문하면 "
"추측하지 말고 get_weather 도구를 사용하세요. "
"도구 결과를 받은 후 "
"최종 답변은 반드시 한국어로 "
"쉽고 간결하게 작성하세요."
}
],
messages=messages,
toolConfig=tool_config,
inferenceConfig={
"maxTokens": 512,
"temperature": 0
}
)
# --------------------------------------------------------
# Nova 응답 확인
# --------------------------------------------------------
assistant_message = response[
"output"
][
"message"
]
stop_reason = response[
"stopReason"
]
print()
print("Nova stopReason:", stop_reason)
# --------------------------------------------------------
# Nova 응답을 대화 기록에 추가
# --------------------------------------------------------
messages.append(
assistant_message
)
# ========================================================
# 9. Tool 사용 여부 확인
# ========================================================
if stop_reason != "tool_use":
# Tool이 필요하지 않은 질문이면
# Nova의 일반 답변을 출력합니다.
for content in assistant_message["content"]:
if "text" in content:
return content["text"]
print()
print("========================================")
print("[2단계] Nova가 Tool 사용을 요청했습니다.")
print("========================================")
# ========================================================
# 10. toolUse 찾기
# ========================================================
tool_uses = [
content["toolUse"]
for content in assistant_message["content"]
if "toolUse" in content
]
if not tool_uses:
return "Tool 요청 정보를 찾지 못했습니다."
# ========================================================
# 11. Tool 결과를 저장할 리스트
# ========================================================
tool_results = []
# ========================================================
# 12. Nova가 요청한 Tool 처리
# ========================================================
for tool_use in tool_uses:
tool_name = tool_use[
"name"
]
tool_use_id = tool_use[
"toolUseId"
]
tool_input = tool_use[
"input"
]
print()
print("Tool 이름:", tool_name)
print(
"Tool 입력:",
json.dumps(
tool_input,
ensure_ascii=False
)
)
# ----------------------------------------------------
# 허용된 Tool인지 반드시 확인
# ----------------------------------------------------
if tool_name == "get_weather":
city = tool_input.get(
"city"
)
# ------------------------------------------------
# city 입력 검증
# ------------------------------------------------
if not city:
tool_results.append({
"toolResult": {
"toolUseId":
tool_use_id,
"content": [
{
"json": {
"success": False,
"message":
"city 값이 없습니다."
}
}
],
"status": "error"
}
})
continue
# =================================================
# 13. 실제 AWS Lambda 호출
# =================================================
weather_result = call_weather_lambda(
city
)
# ------------------------------------------------
# Lambda 성공 / 실패 확인
# ------------------------------------------------
status = (
"success"
if weather_result.get("success")
else "error"
)
# =================================================
# 14. Tool Result 생성
# =================================================
tool_results.append({
"toolResult": {
"toolUseId":
tool_use_id,
"content": [
{
"json":
weather_result
}
],
"status":
status
}
})
# ----------------------------------------------------
# 허용되지 않은 Tool
# ----------------------------------------------------
else:
tool_results.append({
"toolResult": {
"toolUseId":
tool_use_id,
"content": [
{
"json": {
"success": False,
"message":
f"허용되지 않은 Tool: {tool_name}"
}
}
],
"status": "error"
}
})
# ========================================================
# 15. Tool Result를 messages에 추가
# ========================================================
messages.append({
"role": "user",
"content": tool_results
})
print()
print("========================================")
print("[3단계] Lambda 결과를 Nova에게 전달")
print("========================================")
# ========================================================
# 16. 두 번째 Converse 호출
# ========================================================
#
# 이번에는 Nova가
#
# 사용자 질문
# +
# toolUse
# +
# Lambda 결과
#
# 를 모두 보고 최종 답변을 작성합니다.
#
# ========================================================
final_response = bedrock.converse(
modelId=MODEL_ID,
system=[
{
"text":
"당신은 날씨 안내 AI Assistant입니다. "
"도구에서 반환된 실제 날씨 정보를 기준으로 "
"사용자에게 한국어로 자연스럽게 설명하세요. "
"도구 결과에 없는 날씨 정보는 추측하지 마세요."
}
],
messages=messages,
toolConfig=tool_config,
inferenceConfig={
"maxTokens": 512,
"temperature": 0
}
)
# ========================================================
# 17. 최종 답변 추출
# ========================================================
final_message = final_response[
"output"
][
"message"
]
final_texts = [
content["text"]
for content in final_message["content"]
if "text" in content
]
if final_texts:
return "\n".join(
final_texts
)
return "최종 답변을 생성하지 못했습니다."
# ============================================================
# 18. 프로그램 시작
# ============================================================
if __name__ == "__main__":
try:
question = "서울 날씨 알려줘"
answer = weather_agent(
question
)
print()
print("========================================")
print("[Nova 최종 답변]")
print("========================================")
print(answer)
except ClientError as error:
print()
print("AWS API 호출 오류가 발생했습니다.")
print(error)
except Exception as error:
print()
print("프로그램 실행 중 오류가 발생했습니다.")
print(error)
JavaScript
복사
AWS 문서에서도 모델의 응답 stopReason이 tool_use이면 toolUse의 name, input, toolUseId를 꺼내 실제 Tool을 실행하고, 동일한 toolUseId를 포함한 toolResult를 다시 대화에 넣어 Converse를 재호출하는 구조를 사용합니다
7. 실행명령어
python weather_agent.py
JavaScript
복사
정상결과값
========================================
[사용자 질문]
========================================
서울 날씨 알려줘
========================================
[1단계] Nova에게 질문 전달
========================================
Nova stopReason: tool_use
========================================
[2단계] Nova가 Tool 사용을 요청했습니다.
========================================
Tool 이름: get_weather
Tool 입력: {"city": "서울"}
========================================
[Python] AWS Lambda 호출
========================================
도시: 서울
Lambda 응답:
{
"success": true,
"city": "서울",
"temperature": 23.5,
"precipitation": 0.0,
"weather_code": 1,
"weather": "대체로 맑음",
"unit": "C"
}
========================================
[3단계] Lambda 결과를 Nova에게 전달
========================================
========================================
[Nova 최종 답변]
========================================
현재 서울의 기온은 23.5°C이며,
날씨는 대체로 맑습니다.
현재 강수량은 0mm입니다.
JavaScript
복사
여기서 마지막 문장은 Python이 직접 만든 것이 아닙니다.
Lambda가 반환한 JSON 데이터를 Nova가 읽어서 자연스러운 한국어 문장으로 만들어 준 것입니다.
8. 가장 중요한 부분 ① — Tool 정의
이 부분은 실제 Lambda 호출 코드가 아닙니다.
weather_tool = {
"toolSpec": {
"name": "get_weather",
"description":
"대한민국 도시의 현재 날씨를 조회합니다.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
}
}
Plain Text
복사
Nova에게 일종의 Tool 사용설명서를 제공하는 것입니다.
Nova에게 알려주는 내용
Tool 이름
↓
get_weather
무슨 기능?
↓
현재 날씨 조회
어떤 값을 줘야 함?
↓
city
city 자료형?
↓
string
Plain Text
복사
Nova의 Tool schema 최상위 객체는 type, properties, required 구조를 사용하며, AWS는 Tool calling의 정확도를 위해 temperature=0 사용을 권장합니다. AWS 문서
9. 가장 중요한 부분 ② — Nova가 Tool을 선택
사용자가:
서울 날씨 알려줘
Plain Text
복사
라고 질문합니다.
첫 번째 Converse:
response = bedrock.converse(
modelId=MODEL_ID,
messages=messages,
toolConfig=tool_config
)
Plain Text
복사
Nova는 질문과 Tool 설명을 보고 판단합니다.
사용자가 현재 날씨를 물었다.
↓
내가 가진 일반 지식으로
현재 날씨를 추측하면 안 된다.
↓
get_weather라는 적절한 Tool이 있다.
↓
get_weather를 사용하자.
Plain Text
복사
그러면 대략 다음 구조의 요청을 돌려줍니다.
{
"toolUse": {
"toolUseId":
"tooluse_abc123",
"name":
"get_weather",
"input": {
"city": "서울"
}
}
}
Plain Text
복사
그리고:
response["stopReason"]
Plain Text
복사
은:
tool_use
Plain Text
복사
가 됩니다. AWS 문서도 Nova가 Tool을 선택하면 stopReason="tool_use"와 Tool 이름·입력값을 반환한다고 설명합니다.
10. 가장 중요한 부분 ③ — Python이 Lambda 실행
Nova가 Lambda를 직접 실행한 것이 아닙니다.
Python이:
if tool_name == "get_weather":
Plain Text
복사
를 확인한 후:
weather_result = call_weather_lambda(city)
Plain Text
복사
를 실행합니다.
그 안에서 실제 AWS Lambda API를 호출합니다.
response = lambda_client.invoke(
FunctionName="travel-weather-function",
InvocationType="RequestResponse",
Payload=json.dumps(
{"city": city},
ensure_ascii=False
).encode("utf-8")
)
Plain Text
복사
따라서 관계는:
Nova
│
│ toolUse
▼
Python
│
│ lambda.invoke()
▼
AWS Lambda
Plain Text
복사
입니다.
이 차이가 Tool Use를 이해할 때 가장 중요합니다.
11. 가장 중요한 부분 ④ — toolUseId
Nova가 이런 값을 줍니다.
toolUseId
Plain Text
복사
예:
tooluse_abc123
Plain Text
복사
Python은 결과를 돌려줄 때 같은 ID를 그대로 사용해야 합니다.
{
"toolResult": {
"toolUseId":
tool_use_id,
"content": [
{
"json":
weather_result
}
]
}
}
Plain Text
복사
그래야 Nova가:
내가 요청했던 get_weather 실행 결과구나.
Plain Text
복사
12. 가장 중요한 부분 ⑤ — Nova에게 결과 반환
Lambda가:
{
"city": "서울",
"temperature": 23.5,
"precipitation": 0,
"weather": "대체로 맑음"
}
Plain Text
복사
을 반환했다고 가정합니다.
Python은 이것을:
toolResult
Plain Text
복사
형태로 Nova에게 다시 전달합니다.
Lambda
{
temperature: 23.5,
weather: "대체로 맑음"
}
↓
Python
toolResult 생성
↓
Converse
↓
Nova
↓
"현재 서울은 23.5°C이고
대체로 맑은 날씨입니다."
Plain Text
복사
즉 Lambda는 데이터 담당, Nova는 판단과 자연어 생성 담당 입니다.
13. 전체 구조를 한 장으로 정리
이 구조를 이해하시면 Bedrock Agent의 기본 원리를 상당 부분 이해한 것입니다.
┌─────────────────────┐
│ 사용자 │
│ "서울 날씨 알려줘" │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Python Program │
│ weather_agent.py │
└──────────┬──────────┘
│
│ converse()
▼
┌─────────────────────┐
│ Amazon Bedrock │
│ Nova │
└──────────┬──────────┘
│
│ Tool 필요 판단
▼
get_weather
city="서울"
│
▼
┌─────────────────────┐
│ Python │
│ Tool 요청 검사 │
└──────────┬──────────┘
│
│ lambda.invoke()
▼
┌─────────────────────┐
│ AWS Lambda │
│ travel-weather- │
│ function │
└──────────┬──────────┘
│
│ 날씨 API
▼
┌─────────────────────┐
│ Weather API │
└──────────┬──────────┘
│
│ JSON
▼
┌─────────────────────┐
│ Lambda │
│ 온도 / 강수량 / 날씨 │
└──────────┬──────────┘
│
▼
Python
│
│ toolResult
▼
┌─────────────────────┐
│ Amazon Bedrock │
│ Nova │
└──────────┬──────────┘
│
│ 자연어 생성
▼
┌─────────────────────┐
│ 사용자 │
│ "현재 서울은..." │
└─────────────────────┘
Plain Text
복사
이것이 바로 Converse Tool Use 기반의 간단한 AI Agent 패턴입니다. 모델은 Tool의 필요성을 판단하고, 애플리케이션은 실제 Tool을 실행하며, 결과를 다시 모델에 넣어 최종 응답을 생성합니다.
다음 단계
여기까지 정상 동작하면 다음에는 이 코드를 확장해서
Streamlit 화면
↓
사용자 질문
↓
Amazon Nova
↓
┌───────────────┬────────────────┐
│ get_weather │ calculate_budget│
└───────┬───────┴────────┬───────┘
↓ ↓
Weather Lambda Budget Lambda
└────────┬───────┘
↓
Nova
↓
제주 2박3일 여행계획
Plain Text
복사
처럼 **날씨 Lambda + 여행예산 Lambda + Converse Tool 2개 + Streamlit 채팅 화면**으로 확장할 수 있습니다. 이 단계까지 만들면 앞서 진행했던 Travel Planner를 AgentCore/Gateway 없이도 순수 Python + Bedrock Converse + Lambda 구조로 구현할 수 있습니다.



