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

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

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

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

에 대한 자세한 내용은 OpenAPI 스키마는 을 참조하십시오. OpenAPI에 대한 사양 Swagger 웹사이트.
API스키마 작성 모범 사례는 API설계 모범 사례를 참조하십시오.Swagger 웹 사이트.

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


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

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

openapi— (필수) 버전 OpenAPI 사용 중입니다. 이 값은 액션 그룹이 작동하기 "3.0.0" 위한 값이어야 합니다.
paths - (필수) 개별 엔드포인트에 대한 상대 경로를 포함합니다. 각 경로는 슬래시 (/) 로 시작해야 합니다.
method - (필수) 사용할 메서드를 정의합니다.
x-requireConfirmation— (선택 사항) 작업을 호출하기 전에 사용자 확인이 필요한지 여부를 지정합니다. 작업을 호출하기 전에 사용자에게 확인을 요청하려면 이 필드를 활성화합니다. 작업을 호출하기 전에 사용자 확인을 요청하면 애플리케이션이 악의적인 프롬프트 삽입으로 인한 조치를 취하지 않도록 보호할 수 있습니다. 이 필드를 DISABLED 지정하지 않으면 기본적으로 사용자 확인이 이루어집니다.

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

description— API 작업에 대한 설명. 이 필드를 사용하여 에이전트에게 이 작업을 호출할 시기와 API 작업이 수행하는 작업을 알릴 수 있습니다.
responses— 에이전트가 API 응답에서 반환하는 속성을 포함합니다. 에이전트는 응답 속성을 사용하여 프롬프트를 구성하고, API 통화 결과를 정확하게 처리하고, 작업 수행을 위한 올바른 단계를 결정합니다. 에이전트는 한 작업의 응답 값을 오케스트레이션의 후속 단계를 위한 입력으로 사용할 수 있습니다.

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

parameters - 요청에 포함할 수 있는 파라미터에 대한 정보가 들어 있습니다.
requestBody - 요청 본문의 작업에 대한 필드를 포함합니다. GET 및 DELETE 메서드에 이 필드를 포함하지 않습니다.

구조에 대해 자세히 알아보려면 다음 탭 중에서 선택하십시오.

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 - (선택 사항) 입력 및 출력 데이터 유형의 정의. 자세한 내용은 의 데이터 모델 (스키마) 을 참조하십시오.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 가지는 다음과 같이 정의됩니다.

getAllOpenClaims— 상담원은 이 description 필드를 사용하여 미해결 청구 목록이 필요한 경우 이 API 작업을 호출해야 한다고 결정할 수 있습니다. responses의 properties는 ID와 보험 계약자 및 청구 상태를 반환하도록 지정합니다. 상담원은 이 정보를 상담원 사용자에게 반환하거나 응답의 일부 또는 전체를 후속 API 통화에 대한 입력으로 사용합니다.
identifyMissingDocuments— 상담원은 이 description 필드를 사용하여 보험 청구 시 누락된 문서를 확인해야 하는 경우 이 API 작업을 호출해야 한다고 결정할 수 있습니다. name, description, required 필드는 에이전트가 고객으로부터 미해결 청구의 고유 식별자를 얻어야 한다고 알려줍니다. 미결 보험 청구의 반환 properties IDs 명세서에 responses 명시되어 있습니다. 상담원은 이 정보를 최종 사용자에게 반환하거나 응답의 일부 또는 API 전부를 후속 통화에 대한 입력으로 사용합니다.
sendReminders— 상담원은 이 description 필드를 사용하여 고객에게 알림을 보내야 하는 경우 이 API 작업을 호출해야 한다고 결정할 수 있습니다. 예를 들어 미해결 청구에 대해 가지고 있는 보류 중인 문서에 대한 알림. 이 properties 서류는 에이전트에게 IDs 청구서와 보류 중인 문서를 찾아야 한다고 requestBody 알려줍니다. 알림 ID와 상태를 반환하도록 responses 지정하십시오. properties 상담원은 이 정보를 최종 사용자에게 반환하거나 응답의 일부 또는 전체를 후속 API 통화에 대한 입력으로 사용합니다.


{
    "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 스키마는 웹 사이트의 https://github.com/OAI/공개 API 사양/트리/메인/예제/V3.0을 참조하십시오. GitHub

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

함수 세부 정보 정의

조치 이행 처리