Amazon Bedrock 에이전트와 Lambda 연동의 핵심: 표준 API 요청/응답 형식 완벽 가이드

Amazon Bedrock의 강력한 기능 중 하나인 에이전트(Agents)는 반복적인 작업을 자동화하고 사용자의 요청에 따라 동적인 액션을 수행할 수 있게 해줍니다. 이러한 액션을 실행하는 가장 일반적이고 강력한 방법은 바로 AWS Lambda 함수를 연동하는 것입니다.

Bedrock 에이전트가 Lambda 함수를 호출할 때, 둘 사이에는 미리 정해진 약속, 즉 표준 API 형식에 따라 데이터를 주고받습니다. 개발자는 이 형식을 정확히 이해하고 Lambda 함수를 작성해야만 에이전트가 원활하게 작동할 수 있습니다.

이번 글에서는 Bedrock이 Lambda에 보내는 요청(Request) 형식과 Lambda가 Bedrock에 반환해야 하는 응답(Response) 형식을 상세히 파헤쳐 보겠습니다.

Bedrock에서 Lambda로: 요청(Request) 형식 🗳️

사용자가 에이전트에게 특정 작업을 요청하면, Bedrock은 이 요청을 해석하여 미리 정의된 액션 그룹(Action Group)과 연결된 Lambda 함수를 트리거합니다. 이때 Lambda 함수는 event 파라미터로 다음과 같은 JSON 형식의 데이터를 전달받습니다.

{
    "messageVersion": "1.0",
    "agent": {
        "name": "MyWeatherAgent",
        "id": "AGENT123456",
        "alias": "TSTALIASID",
        "version": "2"
    },
    "actionGroup": {
        "actionGroupName": "WeatherActionGroup",
        "apiPath": "/getWeather",
        "httpMethod": "GET"
    },
    "parameters": [
        {
            "name": "city",
            "type": "string",
            "value": "Seoul"
        }
    ],
    "requestBody": {
        "content": {
            "application/json": {
                "properties": []
            }
        }
    },
    "sessionAttributes": {
        "userId": "user-001"
    },
    "promptSessionAttributes": {}
}

 

요청 데이터 상세 분석

각 필드는 중요한 정보를 담고 있습니다.

• messageVersion: 이벤트 스키마의 버전을 나타냅니다. 현재는 "1.0"입니다.
• agent: 호출을 시작한 에이전트의 정보를 담습니다. (이름, ID, 별칭, 버전)
• actionGroup: 에이전트가 호출한 액션 그룹의 상세 정보입니다.
  • actionGroupName: 액션 그룹의 이름입니다.
  • apiPath: 액션 그룹의 OpenAPI 스키마에 정의된 경로 중, 이번 요청과 매칭된 API 경로입니다.
  • httpMethod: 매칭된 API의 HTTP 메서드(GET, POST, PUT 등)입니다.
• parameters: 가장 중요한 부분 중 하나로, Bedrock의 파운데이션 모델(FM)이 사용자의 프롬프트에서 추출한 파라미터 값들의 배열입니다. Lambda 함수는 이 값을 사용하여 비즈니스 로직을 수행합니다. 위 예시에서는 사용자가 "서울 날씨 알려줘"라고 했을 때 city 파라미터에 Seoul이라는 값을 추출하여 전달한 것입니다.
• requestBody: POST나 PUT 요청과 같이 HTTP 요청 본문이 필요한 경우, 그 내용이 여기에 담깁니다. content 객체는 MIME 타입을 키로 가지며, 그 값으로 파싱된 요청 본문이 들어갑니다.
• sessionAttributes: 세션 동안 유지되는 속성 값입니다. 대화의 전체 맥락에서 사용자 정보나 상태를 유지해야 할 때 유용합니다.
• promptSessionAttributes: 단일 프롬프트(사용자의 한 번의 입력과 그에 대한 응답 과정) 내에서만 유지되는 속성입니다.

---

Lambda에서 Bedrock으로: 응답(Response) 형식 📤

Lambda 함수는 비즈니스 로직을 모두 수행한 후, 반드시 Bedrock이 이해할 수 있는 특정 JSON 형식으로 결과를 반환해야 합니다. 만약 이 형식을 따르지 않으면 Bedrock 에이전트는 오류를 발생시킵니다.

성공적인 응답의 기본 구조는 다음과 같습니다.

{
    "messageVersion": "1.0",
    "response": {
        "actionGroup": "WeatherActionGroup",
        "apiPath": "/getWeather",
        "httpMethod": "GET",
        "httpStatusCode": 200,
        "responseBody": {
            "application/json": {
                "body": "{\"city\":\"Seoul\",\"temperature\":25,\"condition\":\"맑음\"}"
            }
        }
    },
    "sessionAttributes": {
        "userId": "user-001"
    },
    "promptSessionAttributes": {}
}

 

응답 데이터 상세 분석

• messageVersion: 요청과 마찬가지로 스키마 버전을 명시합니다.
• response: 실제 응답 내용이 담기는 객체입니다.
  • actionGroup, apiPath, httpMethod: 어떤 요청에 대한 응답인지 명확히 하기 위해 요청에서 받은 값을 그대로 넣어주는 것이 좋습니다.
  • httpStatusCode: 매우 중요합니다. 함수의 실행 결과를 나타내는 HTTP 상태 코드입니다. 성공 시 200을 반환합니다.
  • responseBody: 가장 핵심적인 부분으로, 함수의 실행 결과를 담는 곳입니다.
    • 키는 application/json과 같은 MIME 타입이어야 합니다.
    • 값(body)은 문자열(String) 형태의 JSON 데이터여야 합니다. 즉, 실제 반환할 JSON 객체를 JSON.stringify()나 json.dumps()와 같은 함수로 직렬화하여 전달해야 합니다.
    • 이 responseBody의 내용은 액션 그룹을 정의할 때 사용한 OpenAPI 스키마의 응답 모델을 준수해야 합니다. Bedrock의 파운데이션 모델은 이 body의 내용을 해석하여 사용자에게 최종적인 자연어 답변을 생성합니다.
• sessionAttributes, promptSessionAttributes: 요청과 마찬가지로, 세션 속성을 업데이트하거나 추가해야 할 경우 이 필드에 포함하여 반환할 수 있습니다.

 

결론: 약속의 중요성 🤝

Bedrock 에이전트와 Lambda의 연동은 정해진 API 명세를 정확히 지키는 것이 핵심입니다. 특히 Lambda가 Bedrock으로 반환하는 응답 형식, 그중에서도 httpStatusCode와 responseBody를 OpenAPI 스키마에 맞게 올바르게 구성하는 것이 중요합니다.

이 구조를 완벽하게 이해하고 Lambda 함수를 작성한다면, 여러분의 Bedrock 에이전트는 마치 사람처럼 외부 도구를 자유자재로 활용하여 사용자에게 더욱 풍부하고 정확한 경험을 제공할 수 있을 것입니다.