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

Definieren von 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. Zum Definieren der API-Operationen erstellen Sie ein OpenAPI-Schema im JSON- oder YAML-Format. Sie können OpenAPI-Schemadateien erstellen und sie in Amazon Simple Storage Service (Amazon S3) hochladen. Alternativ können Sie den OpenAPI-Texteditor in der Konsole verwenden, der Ihr Schema validiert. Nachdem Sie einen Agenten erstellt haben, können Sie den Texteditor verwenden, wenn Sie dem Agenten eine Aktionsgruppe hinzufügen oder eine bestehende Aktionsgruppe bearbeiten. Weitere Informationen finden Sie unter Ändern eines Agenten.

Der Agent bestimmt anhand des Schemas die API-Operation, die 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:

Nachstehend sehen Sie das allgemeine Format eines OpenAPI-Schemas 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 im OpenAPI-Schema.

  • openapi – (Erforderlich) Die Version der verwendeten OpenAPI. Dieser Wert muss "3.0.0" betragen, damit die Aktionsgruppe funktioniert.

  • paths: (Erforderlich) Enthält relative Pfade zu einzelnen Endpunkten. Pfadnamen müssen mit einem Schrägstrich (/) beginnen und enden. (/).

  • 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, bevor die Aktion aufgerufen wird, kann Ihre Anwendung davor schützen, aufgrund bösartiger Promptinjektionen Maßnahmen zu ergreifen. Wenn dieses Feld nicht angegeben wird, ist die Benutzerbestätigung standardmäßig DISABLED.

Für jede Methode müssen mindestens die folgenden Felder angegeben werden:

  • description: Eine Beschreibung der API-Operation. Verwenden Sie dieses Feld, um den Agenten darüber zu informieren, wann diese API‑Operation aufgerufen werden soll und welche Funktion sie hat.

  • 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 Operationen 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 Prompts zu erstellen, die Ergebnisse eines API-Aufrufs genau zu verarbeiten und die richtigen Schritte zur Ausführung einer Aufgabe zu ermitteln. Der Agent kann Antwortwerte aus einer Operation 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.

Wenn Sie mehr über eine Struktur erfahren möchten, 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 die Endbenutzer zurückgeben muss.

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

Ihr Agent ermittelt anhand der folgenden Felder, welche Informationen er vom Endbenutzer erhalten muss, um die Anforderungen der Aktionsgruppe auszuführen.

  • 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-Website.

requestBody

Es folgt die allgemeine Struktur eines requestBody-Felds:

"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 Anforderungstext für die API-Anfrage erforderlich ist.

  • content: (Erforderlich) Der Inhalt des Anforderungstextes.

  • <media type>: (Optional) Das Format des Anforderungstextes. 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 abfragen muss, um die API-Anfrage auszuführen. 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.

Informationen zum Hinzufügen des OpenAPI-Schemas, das Sie beim Erstellen der Aktionsgruppe erstellt haben, finden Sie unter Hinzufügen einer Aktionsgruppe zu Ihrem Agenten in Amazon Bedrock.

Beispiele 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 Beispiel für ein API-Schema definiert eine Gruppe von API-Operationen, die die Bearbeitung von Versicherungsansprüchen erleichtern. Drei APIs sind wie folgt definiert:

  • getAllOpenClaims – Ihr Agent kann im Feld description festlegen, dass er diese API-Operation aufrufen soll, wenn eine Liste mit offenen Ansprüchen gefordert 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 im Feld description festlegen, dass er diese API-Operation 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. Die properties in den responses legen fest, dass die IDs der offenen Versicherungsansprüche zurückgegeben werden sollen. Der Agent gibt diese Informationen an den Endbenutzer zurück oder verwendet die gesamte oder einen Teil der Antwort als Eingabe für nachfolgende API-Aufrufe.

  • sendReminders – Ihr Agent kann im Feld description festlegen, dass er diese API-Operation aufrufen soll, wenn Erinnerungen an den Kunden gesendet werden sollen. Zum Beispiel eine Erinnerung an ausstehende Dokumente im Zusammenhang mit offenen Ansprüchen. Die properties im requestBody teilen dem Agenten mit, dass er die Anspruchsnummern und die ausstehenden Dokumente suchen muss. Die properties in den responses geben an, dass eine ID der Erinnerung und ihr Status zurückgegeben werden sollen. Der Agent gibt diese Informationen an den Endbenutzer zurück oder verwendet die gesamte oder einen Teil der Antwort 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 Beispiele für API-Beschreibungen auf der OpenAPI-Website.