定义 OpenAPI Amazon Bedrock 中代理人行动小组的架构

在 Amazon Bedrock 中创建操作组时，必须定义代理需要从用户那里调用的参数。您也可以使用这些参数定义代理可以调用的API操作。要定义API操作，请创建一个 OpenAPI JSON或YAML格式的架构。你可以创建 OpenAPI 架构文件并将其上传到亚马逊简单存储服务 (Amazon S3) Semple Service。或者，你可以使用 OpenAPI 控制台中的文本编辑器，它将验证您的架构。创建代理后，您可以使用文本编辑器向代理添加操作组或编辑现有操作组。有关更多信息，请参阅修改代理。

代理使用架构来确定需要调用的API操作以及API发出请求所需的参数。然后，这些详细信息将通过您为执行操作而定义的 Lambda 函数发送，或者在代理调用的响应中返回。

有关API架构的更多信息，请参阅以下资源：

有关以下内容的更多详细信息 OpenAPI 架构，请参阅 OpenAPI上面的规格 Swagger 网站。
有关编写API架构的最佳实践，请参阅上的 “API设计最佳实践” Swagger 网站。

以下是 a 的一般格式 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，例如函数名称。这是所有新 toolUse 启用的模型的必填字段，例如 Anthropic Claude 3.5 Sonnet, Meta Llama、等确保您提供的标识符 (Id) 在所有操作中都是唯一的，并且遵循简单的字母数字模式，仅使用连字符或下划线作为分隔符。
responses— 包含代理在API响应中返回的属性。代理使用响应属性来构造提示，准确处理API呼叫结果，并确定执行任务的正确步骤集。代理可以使用来自一个操作的响应值作为编排中后续步骤的输入。

以下两个对象中的字段可为代理提供更多信息，让其有效利用操作组。对于每个字段，true如果需要，将该required字段的值设置为，如果可选，false则设置为。

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中responses指定要返回未IDs结保险索赔的。代理将此信息返回给最终用户，或者使用部分或全部响应作为后续API调用的输入。
sendReminders— 如果需要向客户发送提醒，您的代理可以使用该description字段来确定是否应调用此API操作。例如，提醒他们有待处理的未决索赔文件。然后requestBody告诉代理人必须找到索赔IDs和待处理的文件。propertiesproperties中的responses指定返回提醒的 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 架构，参见网站上的 Open API-s https://github.com/OAI/ pecification/Tree/main/examples/v3.0。 GitHub

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

定义函数细节

处理操作的履行