기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
Amazon Bedrock에서 작업 그룹을 만들 때 에이전트가 사용자로부터 간접 호출해야 하는 파라미터를 정의해야 합니다. 에이전트가 이러한 파라미터를 사용하여 간접 호출할 수 있는 API 작업을 정의할 수도 있습니다. API 작업을 정의하려면 JSON 또는 YAML 형식으로 OpenAPI 스키마를 만듭니다. OpenAPI 스키마 파일을 만들고 이를 Amazon Simple Storage Service(Amazon S3)에 업로드할 수 있습니다. 또는 콘솔에서 OpenAPI 텍스트 편집기를 사용하여 스키마를 검증할 수 있습니다. 에이전트를 만든 후 에이전트에 작업 그룹을 추가하거나 기존 작업 그룹을 편집할 때 텍스트 편집기를 사용할 수 있습니다. 자세한 내용은 에이전트 수정 섹션을 참조하세요.
에이전트는 간접 호출이 필요한 API 작업 및 API 요청을 수행하는 데 필요한 파라미터를 결정할 때 스키마를 사용합니다. 이러한 세부 정보는 작업을 수행하기 위해 정의한 Lambda 함수를 통해 전송되거나 에이전트 간접 호출의 응답으로 반환됩니다.
API 스키마에 대한 자세한 내용은 다음 리소스를 참조하세요.
-
OpenAPI 스키마에 대한 자세한 내용은 Swagger 웹 사이트의 OpenAPI specification
을 참조하세요. -
API 스키마 작성 모범 사례는 Swagger 웹사이트의 Best practices in API design
을 참조하세요.
다음은 작업 그룹에 대한 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 작업을 언제 직접적으로 호출해야 하는지, 어떤 작업을 수행해야 하는지 알려줍니다. -
operationId- 함수 이름과 같이 API에서 작업을 식별하는 고유한 문자열입니다. 이 필드는 Anthropic Claude 3.5 Sonnet, Meta Llama 등과 같은 모든 새 toolUse 지원 모델에 필요한 필드입니다. 제공하는 식별자(Id)가 모든 작업에서 고유한지, 하이픈 또는 밑줄만 구분자로 사용하고 간단한 영숫자 패턴을 따르는지 확인합니다. -
responses- 에이전트가 API 응답에서 반환하는 속성을 포함합니다. 에이전트는 응답 속성을 사용하여 프롬프트를 구성하고, API 직접 호출 결과를 정확하게 처리하고, 작업을 수행하기 위한 올바른 단계 세트를 결정합니다. 에이전트는 한 작업의 응답 값을 오케스트레이션의 후속 단계에 대한 입력으로 사용할 수 있습니다.
다음 두 객체의 필드는 에이전트가 작업 그룹을 효과적으로 활용할 수 있도록 자세한 정보를 제공합니다. 각 필드에 대해 required 필드 값이 필수인 경우 true로 설정하고 선택 사항인 경우 false로 설정합니다.
-
parameters- 요청에 포함할 수 있는 파라미터에 대한 정보가 들어 있습니다. -
requestBody- 요청 본문의 작업에 대한 필드를 포함합니다.GET및DELETE메서드에 이 필드를 포함하지 않습니다.
구조에 대해 자세히 알아보려면 다음 탭 중에서 선택하세요.
"responses": {
"200": {
"content": {
"<media type>": {
"schema": {
"properties": {
"<property>": {
"type": "string",
"description": "string"
},
...
}
}
}
},
},
...
}responses 객체의 각 키는 응답의 상태를 설명하는 응답 코드입니다. 응답 코드는 응답에 대한 다음 정보가 포함된 객체에 매핑됩니다.
-
content- (각 응답에서 필수) 응답 내용. -
<media type>- 응답 본문의 형식. 자세한 내용은 Swagger 웹사이트의 Media types를 참조하세요. -
schema- (각 미디어 유형에서 필수) 응답 본문의 데이터 유형과 해당 필드를 정의합니다. -
properties- (스키마에items가 있는 경우 필수) 에이전트는 스키마에 정의한 속성을 사용하여 작업을 수행하기 위해 최종 사용자에게 반환하는 데 필요한 정보를 결정합니다. 각 속성에는 다음 필드가 포함됩니다.-
type- (각 속성에서 필수) 응답 필드의 데이터 유형. -
description- (선택 사항) 속성의 설명. 에이전트는 이 정보를 사용하여 최종 사용자에게 반환하는 데 필요한 정보를 결정할 수 있습니다.
-
작업 그룹을 만드는 동안 이전에 만든 OpenAPI 스키마를 추가하는 방법을 알아보려면 Amazon Bedrock에서 에이전트에 작업 그룹 추가 섹션을 참조하세요.
API 스키마 예제
다음 예제에서는 지정된 위치의 날씨를 섭씨로 가져오는 YAML 형식의 간단한 OpenAPI 스키마를 제공합니다.
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 작업 그룹을 정의합니다. 세 가지 API는 다음과 같이 정의됩니다.
-
getAllOpenClaims- 에이전트는description필드를 사용하여 미해결 청구 목록이 필요한 경우 이 API 작업을 직접적으로 호출해야 한다고 결정할 수 있습니다.responses의properties는 ID와 보험 계약자 및 청구 상태를 반환하도록 지정합니다. 에이전트는 이 정보를 에이전트 사용자에게 반환하거나 응답의 일부 또는 전체를 후속 API 직접 호출에 대한 입력으로 사용합니다. -
identifyMissingDocuments- 에이전트는description필드를 사용하여 보험 청구 시 누락된 문서를 식별해야 하는 경우 이 API 작업을 직접적으로 호출해야 한다고 결정할 수 있습니다.name,description,required필드는 에이전트가 고객으로부터 미해결 청구의 고유 식별자를 얻어야 한다고 알려줍니다.responses의properties는 미해결 보험 청구의 ID를 반환하도록 지정합니다. 에이전트는 이 정보를 최종 사용자에게 반환하거나 응답의 일부 또는 전체를 후속 API 직접 호출에 대한 입력으로 사용합니다. -
sendReminders- 에이전트는description필드를 사용하여 고객에게 알림을 보내야 하는 경우 이 API 작업을 직접적으로 호출해야 한다고 결정할 수 있습니다. 예를 들어 미해결 청구 건에 대해 보류 중인 문서에 대한 알림을 보내야 할 수 있습니다.requestBody의properties는 에이전트에게 청구 ID와 보류 중인 문서를 찾아야 한다고 알립니다.responses의properties는 알림의 ID와 상태를 반환하도록 지정합니다. 에이전트는 이 정보를 최종 사용자에게 반환하거나 응답의 일부 또는 전체를 후속 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 스키마의 자세한 예는 OpenAPI 웹 사이트의 예제 API 설명을 참조하세요
