기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

정의 OpenAPI Amazon Bedrock에서 에이전트의 작업 그룹에 대한 스키마

Amazon Bedrock에서 작업 그룹을 생성할 때 에이전트가 사용자로부터 호출해야 하는 파라미터를 정의해야 합니다. 에이전트가 이러한 파라미터를 사용하여 호출할 수 있는 API 작업을 정의할 수도 있습니다. API 작업을 정의하려면 OpenAPI JSON 또는 YAML 형식의 스키마입니다. 를 생성할 수 있습니다.OpenAPI 스키마 파일을 Amazon Simple Storage Service(Amazon S3)에 업로드합니다. 또는 OpenAPI 스키마를 검증하는 콘솔의 텍스트 편집기입니다. 에이전트를 생성한 후 에이전트에 작업 그룹을 추가하거나 기존 작업 그룹을 편집할 때 텍스트 편집기를 사용할 수 있습니다. 자세한 내용은 에이전트 수정 단원을 참조하십시오.

에이전트는 스키마를 사용하여 호출해야 하는 API 작업과 API 요청에 필요한 파라미터를 결정합니다. 그런 다음 이러한 세부 정보는 작업을 수행하도록 정의한 Lambda 함수를 통해 전송되거나 에이전트 호출의 응답으로 반환됩니다.

API 스키마에 대한 자세한 내용은 다음 리소스를 참조하세요.

다음은 의 일반적인 형식입니다.OpenAPI 작업 그룹의 스키마입니다.

{
    "openapi": "3.0.0",
    "paths": {
        "/path": {
            "method": {
                "description": "string",
                "operationId": "string",
                "parameters": [ ... ],
                "requestBody": { ... },
                "responses": { ... }
                "x-requireConfirmation": ENABLED | DISABLED
           }
       }
    }
}

다음 목록은 의 필드를 설명합니다.OpenAPI 스키마

최소한 각 메서드에는 다음 필드가 필요합니다.

다음 두 객체의 필드는 에이전트가 작업 그룹을 효과적으로 활용할 수 있도록 자세한 정보를 제공합니다. 각 필드에 대해 required 필드 값을 필요한 true 경우 로 설정하고 선택 사항false인 경우 로 설정합니다.

구조에 대해 자세히 알아보려면 다음 탭에서 를 선택합니다.

responses

"responses": {
    "200": {
        "content": {
            "<media type>": {
                "schema": {
                    "properties": {
                        "<property>": {
                            "type": "string",
                            "description": "string"
                        },
                        ...
                    }
                }
            }
        },
    },
    ...
}

responses 객체의 각 키는 응답 상태를 설명하는 응답 코드입니다. 응답 코드는 응답에 대한 다음 정보가 포함된 객체에 매핑됩니다.

• content - (각 응답에서 필수) 응답 내용.

• <media type> - 응답 본문의 형식입니다. 자세한 내용은 의 미디어 유형을 참조하세요.Swagger 웹 사이트.

• schema - (각 미디어 유형에서 필수) 응답 본문의 데이터 유형과 해당 필드를 정의합니다.

• properties - (스키마에 items가 있는 경우 필수) 에이전트는 스키마에 정의한 속성을 사용하여 작업을 수행하기 위해 최종 사용자에게 반환하는 데 필요한 정보를 결정합니다. 각 속성에는 다음 필드가 포함됩니다.

  • type - (각 속성에서 필수) 응답 필드의 데이터 유형.

  • description - (선택 사항) 속성의 설명. 에이전트는 이 정보를 사용하여 최종 사용자에게 반환해야 하는 정보를 확인할 수 있습니다.

parameters

"parameters": [
    {
        "name": "string",
        "description": "string",
        "required": boolean,
        "schema": {
            ...
        }
    },
    ...
]

에이전트는 다음 필드를 사용하여 작업 그룹의 요구 사항을 수행하기 위해 최종 사용자로부터 얻어야 하는 정보를 결정합니다.

• name - (필수) 파라미터의 이름.

• description - (필수) 파라미터의 설명. 이 필드를 사용하면 에이전트가 에이전트 사용자로부터 이 파라미터를 이끌어내는 방법을 이해하거나 이전 작업 또는 에이전트에 대한 사용자의 요청에서 해당 파라미터 값이 이미 있는지 확인하는 데 도움이 됩니다.

• required – (선택 사항) API 요청에 파라미터가 필요한지 여부. 이 필드를 사용하여 모든 호출에 이 파라미터가 필요한지 아니면 선택 사항인지 에이전트에게 나타냅니다.

• schema - (선택 사항) 입력 및 출력 데이터 유형의 정의. 자세한 내용은 의 데이터 모델(Schemas)을 참조하세요.Swagger 웹 사이트.

requestBody

필드의 일반적인 구조는 다음과 같습니다requestBody.

"requestBody": {
    "required": boolean,
    "content": {
        "<media type>": {
            "schema": {
                "properties": {
                    "<property>": {
                        "type": "string",
                        "description": "string"
                    },
                    ...
                }
            }
        }
    }
}

다음 목록은 각 필드를 설명합니다.

• required – (선택 사항) 요청에 요청 본문이 필요한지 여부API.

• content - (필수) 요청 본문의 내용.

• <media type> – (선택 사항) 요청 본문의 형식입니다. 자세한 내용은 의 미디어 유형을 참조하세요.Swagger 웹 사이트.

• schema - (선택 사항) 요청 본문과 해당 필드의 데이터 유형을 정의합니다.

• properties – (선택 사항) 에이전트는 스키마에서 정의한 속성을 사용하여 API 최종 사용자로부터 요청해야 하는 정보를 결정합니다. 각 속성에는 다음 필드가 포함됩니다.

  • type - (선택 사항) 요청 필드의 데이터 유형.

  • description - (선택 사항) 속성의 설명. 에이전트는 이 정보를 사용하여 최종 사용자에게 반환하는 데 필요한 정보를 결정할 수 있습니다.

를 추가하는 방법을 알아보려면 OpenAPI 작업 그룹을 생성하는 동안 생성한 스키마는 섹션을 참조하세요Amazon Bedrock에서 에이전트에 작업 그룹 추가.

스키마 API 예제

다음 예제에서는 간단한 OpenAPI 지정된 위치의 날씨를 섭씨로 가져오는 YAML 형식의 스키마입니다.

openapi: 3.0.0
info:
  title: GetWeather API
  version: 1.0.0
  description: gets weather
paths:
  /getWeather/{location}/:
    get:
      summary: gets weather in Celsius
      description: gets weather in Celsius
      operationId: getWeather
      parameters:
        - name: location
          in: path
          description: location name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: weather in Celsius
          content:
            application/json:
              schema:
                type: string

다음 예제 스키마는 보험 청구를 처리하는 데 도움이 API 되는 API 작업 그룹을 정의합니다. 세 가지 정의APIs는 다음과 같습니다.

{
    "openapi": "3.0.0",
    "info": {
        "title": "Insurance Claims Automation API",
        "version": "1.0.0",
        "description": "APIs for managing insurance claims by pulling a list of open claims, identifying outstanding paperwork for each claim, and sending reminders to policy holders."
    },
    "paths": {
        "/claims": {
            "get": {
                "summary": "Get a list of all open claims",
                "description": "Get the list of all open insurance claims. Return all the open claimIds.",
                "operationId": "getAllOpenClaims",
                "responses": {
                    "200": {
                        "description": "Gets the list of all open insurance claims for policy holders",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "claimId": {
                                                "type": "string",
                                                "description": "Unique ID of the claim."
                                            },
                                            "policyHolderId": {
                                                "type": "string",
                                                "description": "Unique ID of the policy holder who has filed the claim."
                                            },
                                            "claimStatus": {
                                                "type": "string",
                                                "description": "The status of the claim. Claim can be in Open or Closed state"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/claims/{claimId}/identify-missing-documents": {
            "get": {
                "summary": "Identify missing documents for a specific claim",
                "description": "Get the list of pending documents that need to be uploaded by policy holder before the claim can be processed. The API takes in only one claim id and returns the list of documents that are pending to be uploaded by policy holder for that claim. This API should be called for each claim id",
                "operationId": "identifyMissingDocuments",
                "parameters": [{
                    "name": "claimId",
                    "in": "path",
                    "description": "Unique ID of the open insurance claim",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }],
                "responses": {
                    "200": {
                        "description": "List of documents that are pending to be uploaded by policy holder for insurance claim",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pendingDocuments": {
                                            "type": "string",
                                            "description": "The list of pending documents for the claim."
                                        }
                                    }
                                }
                            }
                        }

                    }
                }
            }
        },
        "/send-reminders": {
            "post": {
                "summary": "API to send reminder to the customer about pending documents for open claim",
                "description": "Send reminder to the customer about pending documents for open claim. The API takes in only one claim id and its pending documents at a time, sends the reminder and returns the tracking details for the reminder. This API should be called for each claim id you want to send reminders for.",
                "operationId": "sendReminders",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "claimId": {
                                        "type": "string",
                                        "description": "Unique ID of open claims to send reminders for."
                                    },
                                    "pendingDocuments": {
                                        "type": "string",
                                        "description": "The list of pending documents for the claim."
                                    }
                                },
                                "required": [
                                    "claimId",
                                    "pendingDocuments"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Reminders sent successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sendReminderTrackingId": {
                                            "type": "string",
                                            "description": "Unique Id to track the status of the send reminder Call"
                                        },
                                        "sendReminderStatus": {
                                            "type": "string",
                                            "description": "Status of send reminder notifications"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request. One or more required fields are missing or invalid."
                    }
                }
            }
        }
    }
}

의 추가 예제 OpenAPI 스키마, GitHub 웹 사이트의 https://github.com/OAI/Open API-Specification/tree/main/examples/v3.0을 참조하세요.