Definieren OpenAPI Schemas für die Aktionsgruppen Ihres Agenten in Amazon Bedrock - Amazon Bedrock
Beispiel für API-Schemas

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Definieren OpenAPI Schemas für die Aktionsgruppen Ihres Agenten in Amazon Bedrock

Wenn Sie eine Aktionsgruppe in Amazon Bedrock erstellen, müssen Sie die Parameter definieren, die der Agent vom Benutzer aufrufen muss. Sie können auch API-Operationen definieren, die der Agent mithilfe dieser Parameter aufrufen kann. Um die API-Operationen zu definieren, erstellen Sie eine OpenAPI Schema im JSON- oder YAML-Format. Sie können erstellen OpenAPI Schemadateien und laden Sie sie auf Amazon Simple Storage Service (Amazon S3) hoch. Alternativ können Sie den OpenAPI Texteditor in der Konsole, der Ihr Schema validiert. Nachdem Sie einen Agenten erstellt haben, können Sie den Texteditor verwenden, um dem Agenten eine Aktionsgruppe hinzuzufügen oder eine bestehende Aktionsgruppe zu bearbeiten. Weitere Informationen finden Sie unter Einen Agenten ändern.

Der Agent bestimmt anhand des Schemas den API-Vorgang, den er aufrufen muss, und die Parameter, die für die API-Anfrage erforderlich sind. Diese Details werden dann über eine Lambda-Funktion gesendet, die Sie für die Ausführung der Aktion definieren, oder als Antwort auf den Agentenaufruf zurückgegeben.

Weitere Informationen zu API-Schemas finden Sie in den folgenden Ressourcen:

Das Folgende ist das allgemeine Format einer OpenAPI Schema für eine Aktionsgruppe.

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

Die folgende Liste beschreibt Felder in OpenAPI schema

  • openapi— (Erforderlich) Die Version von OpenAPI das wird benutzt. Dieser Wert muss sein, "3.0.0" damit die Aktionsgruppe funktioniert.

  • paths: (Erforderlich) Enthält relative Pfade zu einzelnen Endpunkten. Jeder Pfad muss mit einem Schrägstrich (/) beginnen.

  • method: (Erforderlich) Definiert die zu verwendende Methode.

  • x-requireConfirmation— (Optional) Gibt an, ob die Benutzerbestätigung erforderlich ist, bevor die Aktion aufgerufen wird. Aktivieren Sie dieses Feld, um eine Bestätigung vom Benutzer anzufordern, bevor die Aktion aufgerufen wird. Das Anfordern einer Benutzerbestätigung vor dem Aufrufen der Aktion kann Ihre Anwendung davor schützen, aufgrund böswilliger Eingabeaufforderungen Maßnahmen zu ergreifen. Standardmäßig erfolgt die Benutzerbestätigung, DISABLED wenn dieses Feld nicht angegeben ist.

Für jede Methode sind mindestens die folgenden Felder erforderlich:

  • description: Eine Beschreibung der API-Operation. Verwenden Sie dieses Feld, um den Agenten darüber zu informieren, wann dieser API-Vorgang aufgerufen werden soll und was der Vorgang bewirkt.

  • operationId— Eine eindeutige Zeichenfolge, die eine Operation in einer API identifiziert, z. B. ein Funktionsname. Dies ist ein Pflichtfeld für alle neuen ToolUse-fähigen Modelle wie Anthropic Claude 3.5 Sonnet, Meta Llama, usw. Stellen Sie sicher, dass der von Ihnen angegebene Bezeichner (ID) bei allen Vorgängen eindeutig ist und einem einfachen alphanumerischen Muster folgt, das nur Bindestriche oder Unterstriche als Trennzeichen enthält.

  • responses— Enthält Eigenschaften, die der Agent in der API-Antwort zurückgibt. Der Agent verwendet die Antworteigenschaften, um Eingabeaufforderungen zu erstellen, die Ergebnisse eines API-Aufrufs genau zu verarbeiten und die richtigen Schritte für die Ausführung einer Aufgabe festzulegen. Der Agent kann Antwortwerte aus einem Vorgang als Eingaben für nachfolgende Orchestrierungsschritte verwenden.

Die Felder in den folgenden beiden Objekten bieten Ihrem Agenten weitere Informationen, damit er Ihre Aktionsgruppe effektiv nutzen kann. Legen Sie für jedes Feld den Wert des required Felds auf true falls erforderlich und auf false falls optional fest.

  • parameters: Enthält Informationen über Parameter, die in die Anforderung aufgenommen werden können.

  • requestBody: Enthält die Felder im Anforderungstext für die Operation. Schließen Sie dieses Feld nicht für die GET- und DELETE-Methoden ein.

Um mehr über eine Struktur zu erfahren, wählen Sie eine der folgenden Registerkarten aus.

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

Jeder Schlüssel im responses Objekt ist ein Antwortcode, der den Status der Antwort beschreibt. Der Antwortcode ist einem Objekt zugeordnet, das die folgenden Informationen für die Antwort enthält:

  • content: (Für jede Antwort erforderlich) Der Inhalt der Antwort.

  • <media type>— Das Format des Antworttextes. Weitere Informationen finden Sie unter Medientypen auf der Swagger Website.

  • schema: (Für jeden Medientyp erforderlich) Definiert den Datentyp des Antworttextes und seiner Felder.

  • properties: (Erforderlich, wenn items im Schema enthalten sind) Ihr Agent verwendet Eigenschaften, die Sie im Schema definieren, um zu bestimmen, welche Informationen er an die Endbenutzer zurückgeben muss, um eine Aufgabe auszuführen. Alle Eigenschaften enthalten die folgenden Felder:

    • type: (Für jede Eigenschaft erforderlich) Der Datentyp des Antwortfeldes.

    • description: (Optional) Beschreibt die Eigenschaft. Der Agent kann anhand dieser Informationen ermitteln, welche Informationen er an den Endbenutzer zurückgeben muss.

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

Ihr Agent bestimmt anhand der folgenden Felder, welche Informationen er vom Endbenutzer erhalten muss, um die Anforderungen der Aktionsgruppe zu erfüllen.

  • name: (Erforderlich) Der Name des Parameters.

  • description: (Erforderlich) Eine Beschreibung des Parameters. Verwenden Sie dieses Feld, um dem Agenten zu vermitteln, wie dieser Parameter vom Benutzer des Agenten abgefragt wird, oder um festzustellen, ob dieser Parameterwert bereits aus früheren Aktionen oder aus der Anforderung des Benutzers an den Agenten vorliegt.

  • required— (Optional) Ob der Parameter für die API-Anfrage erforderlich ist. Verwenden Sie dieses Feld, um dem Agenten mitzuteilen, ob dieser Parameter für jeden Aufruf benötigt wird oder ob er optional ist.

  • schema: (Optional) Die Definition von Eingabe- und Ausgabedatentypen. Weitere Informationen finden Sie unter Datenmodelle (Schemas) auf der Swagger Webseite.

requestBody

Es folgt die allgemeine Struktur eines requestBody Feldes:

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

In der folgenden Liste werden die einzelnen Felder beschrieben:

  • required— (Optional) Ob der Anfragetext für die API-Anfrage erforderlich ist.

  • content: (Erforderlich) Der Inhalt des Anforderungstextes.

  • <media type>— (Optional) Das Format des Hauptteils der Anfrage. Weitere Informationen finden Sie unter Medientypen auf der Swagger Website.

  • schema: (Optional) Definiert den Datentyp des Anforderungstextes und seiner Felder.

  • properties— (Optional) Ihr Agent verwendet Eigenschaften, die Sie im Schema definieren, um die Informationen zu ermitteln, die er vom Endbenutzer erhalten muss, um die API-Anfrage zu stellen. Alle Eigenschaften enthalten die folgenden Felder:

    • type: (Optional) Der Datentyp des Anforderungsfeldes.

    • description: (Optional) Beschreibt die Eigenschaft. Der Agent kann anhand dieser Informationen ermitteln, welche Informationen er an die Endbenutzer zurückgeben muss.

Um zu erfahren, wie Sie das hinzufügen OpenAPI Schema, das Sie beim Erstellen der Aktionsgruppe erstellt haben, finden Sie unterFügen Sie Ihrem Agenten in Amazon Bedrock eine Aktionsgruppe hinzu.

Beispiel für API-Schemas

Das folgende Beispiel bietet ein einfaches OpenAPI Schema im YAML-Format, das das Wetter für einen bestimmten Ort in Celsius abruft.

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

Das folgende API-Beispielschema definiert eine Gruppe von API-Vorgängen, die bei der Bearbeitung von Versicherungsansprüchen helfen. Drei APIs sind wie folgt definiert:

  • getAllOpenClaims— Ihr Agent kann anhand des description Felds festlegen, dass er diesen API-Vorgang aufrufen soll, falls eine Liste mit offenen Ansprüchen benötigt wird. Die properties in den responses geben an, ob die ID, der Versicherungsnehmer und der Status des Anspruchs zurückgegeben werden sollen. Der Agent gibt diese Informationen an den Benutzer des Agenten zurück oder verwendet die gesamte oder einen Teil der Antwort als Eingabe für nachfolgende API-Aufrufe.

  • identifyMissingDocuments— Ihr Agent kann anhand des description Felds festlegen, dass er diesen API-Vorgang aufrufen soll, wenn fehlende Dokumente für einen Versicherungsanspruch identifiziert werden müssen. Die Felder name, description und required teilen dem Agenten mit, dass er die eindeutige Kennung des offenen Anspruchs des Kunden ermitteln muss. responsesGeben Sie an, welche IDs der offenen Versicherungsansprüche zurückgegeben werden sollen. properties Der Agent gibt diese Informationen an den Endbenutzer zurück oder verwendet die Antwort ganz oder teilweise als Eingabe für nachfolgende API-Aufrufe.

  • sendReminders— Ihr Agent kann anhand des description Felds festlegen, dass er diesen API-Vorgang aufrufen soll, wenn Erinnerungen an den Kunden gesendet werden müssen. Zum Beispiel eine Erinnerung an ausstehende Dokumente, die ihnen für offene Anträge vorliegen. requestBodySie teilen properties dem Agenten mit, dass er den Antrag IDs und die ausstehenden Dokumente finden muss. responsesGeben Sie properties an, ob Sie eine ID der Erinnerung und deren Status zurücksenden möchten. Der Agent gibt diese Informationen an den Endbenutzer zurück oder verwendet die Antwort ganz oder teilweise als Eingabe für nachfolgende API-Aufrufe.

{
    "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."
                    }
                }
            }
        }
    }
}

Weitere Beispiele für OpenAPI Schemas finden Sie unter API-Beispielbeschreibungen auf der OpenAPI Webseite.