View a markdown version of this page

AWS Lambda 함수 대상 - Amazon Bedrock AgentCore
주요 고려 사항 및 제한 사항Lambda 함수 도구 스키마Lambda 함수 입력 형식

AWS Lambda 함수 대상

Lambda 대상을 사용하면 게이트웨이를 도구를 구현하는 AWS Lambda 함수에 연결할 수 있습니다. 이는 도구 호출에 대한 응답으로 사용자 지정 코드를 실행하려는 경우에 유용합니다.

Lambda 서비스를 사용하여 AWS Lambda 함수를 생성합니다. 함수를 생성하려면 다음을 수행해야 합니다.

  • Lambda 함수가 호출할 수 있는 도구를 정의하는 도구 스키마를 생성합니다.

  • Lambda 입력 형식을 이해합니다. 그런 다음 원하는 언어로 빌드하기 위한 AWS Lambda 개발자 안내서의 단계를 따를 수 있습니다.

함수를 생성한 후 게이트웨이가 액세스할 수 있도록 권한을 구성합니다.

주요 고려 사항 및 제한 사항을 검토하여 Lambda 대상을 사용 사례에 적용할 수 있는지 여부를 결정하는 데 도움이 됩니다. 이 경우 도구 스키마와 Lambda 함수를 생성한 다음 게이트웨이가 대상에 액세스할 수 있도록 권한을 설정할 수 있습니다. 주제 영역을 선택하여 자세히 알아보세요.

주요 고려 사항 및 제한 사항

Lambda 대상을 사용할 때는 다음 제한 사항 및 고려 사항에 유의하세요.

  • 도구 이름 접두사는 AWS Lambda 함수의 도구 이름에서 수동으로 제거해야 합니다. 자세한 내용은 AgentCore Gateway 도구의 이름 지정 방법 이해를 참조하세요.

  • 기존 AWS Lambda 함수를 사용하고 게이트웨이로 도구로 가져오는 경우 이벤트 및 컨텍스트 객체에 대한 스키마 변경을 설명하도록 함수 코드를 변경해야 합니다.

  • Lambda 함수는 게이트웨이에서 구문 분석할 수 있는 유효한 JSON 응답을 반환해야 합니다.

  • Lambda 함수 제한 시간은 도구의 예상 처리 시간을 처리하도록 적절하게 구성해야 합니다.

  • 클라이언트에 의미 있는 오류 메시지를 제공하려면 LLambda 함수에서 오류 처리를 구현하는 것이 좋습니다.

Lambda 함수 도구 스키마

이 섹션에서는 Lambda 함수가 반환할 수 있는 도구를 정의하는 도구 스키마의 구조를 설명합니다. 도구 스키마를 정의한 후 다음 중 하나를 수행할 수 있습니다.

  • Amazon S3 버킷에 업로드하고 게이트웨이에 대상을 추가할 때 S3 위치를 참조합니다.

  • 게이트웨이에 대상을 추가할 때 정의를 인라인으로 붙여 넣습니다.

주제를 선택하여 도구 스키마의 세부 정보에 대해 자세히 알아보거나 예제를 확인합니다.

도구 정의

Lambda 함수를 게이트웨이 대상으로 추가할 때 대상 구성을 제공할 때 ToolDefinition을 제공합니다. 도구 정의의 구조는 다음과 같습니다.

{
    "name": "string",
    "description": "string",
    "inputSchema": {
        "type": "object",
        "description" "string",
        "properties": {
            "string": SchemaDefinition
        },
        "required": ["string"]
    },
    "outputSchema": {
        "type": "object",
        "description" "string",
        "properties": {
            "string": SchemaDefinition
        },
        "required": ["string"]
    }
}

도구 정의에는 다음 필드가 포함됩니다.

  • name(필수) - 도구의 이름입니다.

  • 설명(필수) - 도구 및 도구의 용도와 사용에 대한 설명입니다.

  • inputSchema(필수) - 도구가 수락하는 입력의 구조를 정의하는 JSON 객체입니다.

  • outputSchema(선택 사항) - 도구가 생성하는 출력의 구조를 정의하는 JSON 객체입니다.

inputSchema 및 outputSchema 필드는 모두 다음 섹션에 설명된 객체 유형 SchemaDefinition에 매핑됩니다.

입력 및 출력 스키마에 대한 최상위 스키마 정의

도구 정의의 최상위 수준에 있는 inputSchema 및 outputSchema 필드는 모두 다음 필드가 포함된 객체 유형 SchemaDefinition에 매핑됩니다.

{
    "type": "object",
    "description": "string",
    "properties": {
        "string": SchemaDefinition
    },
    "required": ["string"]
}

  • type(필수) - 이어야 합니다object.

  • 설명(선택 사항) - 스키마와 스키마의 용도 및 사용에 대한 설명입니다.

  • 속성(선택 사항) - 도구의 속성 또는 인수를 정의하는 JSON 객체입니다. 각 키는 속성의 이름이며 속성을 정의하는 SchemaDefinition 객체에 매핑됩니다.

  • 필수(선택 사항) - properties 객체에 필요한 속성을 열거하는 배열입니다.

도구에 대한 인수를 정의하는 properties 필드를 포함하는 경우 각 인수에 대한 스키마 정의를 제공합니다. 다양한 유형의 스키마 정의가 다음 섹션에 요약되어 있습니다.

속성 스키마 정의

최상위 수준의 각 속성은 최상위 스키마 정의와 요구 사항이 약간 다른 SchemaDefinition 객체에 SchemaDefinition 매핑됩니다. 사용 가능한 필드는 속성의 type에 따라 다릅니다. 유형에 SchemaDefinition 대한의 모양을 보려면 다음 탭에서 선택합니다.

예
String

  1. 문자열 속성에 SchemaDefinition 대한의 구조는 다음과 같습니다.

    {
    "type": "string",
    "description": "string"
}
Number

  1. 숫자 속성에 SchemaDefinition 대한의 구조는 다음과 같습니다.

    {
    "type": "number",
    "description": "string"
}
Integer

  1. 정수 속성에 SchemaDefinition 대한의 구조는 다음과 같습니다.

    {
    "type": "integer",
    "description": "string"
}
Boolean

  1. 부울 속성에 SchemaDefinition 대한의 구조는 다음과 같습니다.

    {
    "type": "boolean",
    "description": "string"
}
Array

  1. 배열 속성에 SchemaDefinition 대한의 구조는 다음과 같습니다.

    {
    "type": "array",
    "description": "string",
    "items": SchemaDefinition
}

    items 필드의 값은 배열에 SchemaDefinition 있는 각 항목의 구조를 정의하는 입니다.

Object

  1. 객체 속성SchemaDefinition의는 다음 구조를 가지며 최상위 속성 스키마 정의와 일치합니다.

    {
    "type": "object",
    "description": "string",
    "properties": {
        "string": SchemaDefinition
    },
    "required": ["string"]
}

다른 객체 유형 속성을 포함하는 경우 다른를 재귀적으로 추가합니다SchemaDefinition.

Lambda 도구 정의 예

탭을 선택하면 Lambda 함수에 포함할 수 있는 예제 도구 정의를 볼 수 있습니다.

예
Weather tool

  1. 다음 get_weather 도구는 location 문자열 인수가 필요하며 해당 위치의 날씨를 반환하는 데 사용할 수 있습니다.

    {
    "name": "get_weather",
    "description": "Get weather for a location",
    "inputSchema": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "the location e.g. seattle, wa"
            }
        },
        "required": [
            "location"
        ]
    }
}
Time tool

  1. 다음 get_time 도구는 timezone 문자열 인수가 필요하며 해당 시간대의 시간을 반환하는 데 사용할 수 있습니다.

    {
    "name": "get_time",
    "description": "Get time for a timezone",
    "inputSchema": {
        "type": "object",
        "properties": {
            "timezone": {
                "type": "string"
            }
        },
        "required": [
            "timezone"
        ]
    }
}

Lambda 함수 입력 형식

Amazon Bedrock AgentCore 게이트웨이는 Lambda 함수를 호출할 때 event 객체와 context 객체를 함수에 전달합니다. 작성하는 Lambda 이벤트 핸들러는 이러한 객체의 값에 액세스할 수 있습니다.

이벤트 객체

도구에서 반환되는 properties에서 inputSchema 해당 값으로의 맵입니다. 예를 들어 입력 스키마에 keywords 및 속성이 포함된 경우 이벤트 객체category는 다음과 같을 수 있습니다.

{
  "keywords": "wireless headphones",
  "category": "electronics"
}

컨텍스트 객체

다음 메타데이터를 포함합니다.

  • bedrockAgentCoreMessageVersion – 메시지의 버전입니다.

  • bedrockAgentCoreAwsRequestId - Amazon Bedrock AgentCore 서비스에 대한 요청의 ID입니다.

  • bedrockAgentCoreMcpMessageId - MCP 서버로 전송된 메시지의 ID입니다.

  • bedrockAgentCoreGatewayId - 호출된 게이트웨이의 ID입니다.

  • bedrockAgentCoreTargetId - 호출된 게이트웨이 대상의 ID입니다.

  • bedrockAgentCoreToolName - 호출된 도구의 이름입니다. 도구 이름은 ${target_name} _ 형식입니다${tool_name}.

컨텍스트 객체의 형식은 다음과 같습니다.

{
  "bedrockAgentCoreMessageVersion": "1.0",
  "bedrockAgentCoreAwsRequestId": "string",
  "bedrockAgentCoreMcpMessageId": "string",
  "bedrockAgentCoreGatewayId": "string",
  "bedrockAgentCoreTargetId": "string",
  "bedrockAgentCoreToolName": "string"
}

작성하는 Lambda 함수는 이벤트 및 컨텍스트 객체의 속성에 액세스할 수 있습니다. 다음 표준 문안 코드를 사용하여 시작할 수 있습니다.

# Access context properties in your Lambda function
def lambda_handler(event, context):
    # Since the visible tool name includes the target name as a prefix, we can use this delimiter to strip the prefix
    delimiter = "___"

    # Get the tool name from the context
    originalToolName = context.client_context.custom['bedrockAgentCoreToolName']
    toolName = originalToolName[originalToolName.index(delimiter) + len(delimiter):]

    # Get other context properties
    message_version = context.client_context.custom['bedrockAgentCoreMessageVersion']
    aws_request_id = context.client_context.custom['bedrockAgentCoreAwsRequestId']
    mcp_message_id = context.client_context.custom['bedrockAgentCoreMcpMessageId']
    gateway_id = context.client_context.custom['bedrockAgentCoreGatewayId']
    target_id = context.client_context.custom['bedrockAgentCoreTargetId']

    # Process the request based on the tool name
    if tool_name == 'searchProducts':
        # Handle searchProducts tool
        pass
    elif tool_name == 'getProductDetails':
        # Handle getProductDetails tool
        pass
    else:
        # Handle unknown tool
        pass