Définition de schémas OpenAPI pour les groupes d’actions de l’agent dans Amazon Bedrock

Lorsque vous créez un groupe d’actions dans Amazon Bedrock, vous devez définir les paramètres que l’agent doit invoquer auprès de l’utilisateur. Vous pouvez également définir les opérations d’API que l’agent peut invoquer à l’aide de ces paramètres. Pour définir les opérations d’API, créez un schéma OpenAPI au format JSON ou YAML. Vous pouvez créer des fichiers de schéma OpenAPI et les charger dans Amazon Simple Storage Service (Amazon S3). Vous pouvez également utiliser l’éditeur de texte OpenAPI dans la console, ce qui validera votre schéma. Après avoir créé un agent, vous pouvez utiliser l’éditeur de texte lorsque vous ajoutez un groupe d’actions à l’agent ou que vous modifiez un groupe d’actions existant. Pour plus d’informations, consultez Modifier un agent.

L’agent utilise le schéma pour déterminer l’opération d’API qu’il doit invoquer et les paramètres requis pour effectuer la demande d’API. Ces informations sont ensuite envoyées via une fonction Lambda que vous définissez pour exécuter l’action ou renvoyées en réponse à l’invocation de l’agent.

Pour plus d’informations sur les schémas d’API, consultez les ressources suivantes :

Pour plus de détails sur les schémas OpenAPI, consultez la spécification OpenAPI sur le site Web Swagger.
Pour connaître les bonnes pratiques en matière d’écriture de schémas d’API, consultez Bonnes pratiques en matière de conception d’API sur le site Web Swagger.

Voici le format général d’un schéma OpenAPI pour un groupe d’actions.


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

La liste suivante décrit les champs figurant dans le schéma OpenAPI :

openapi : (obligatoire) version d’OpenAPI utilisée. Cette valeur doit être "3.0.0" pour que le groupe d’actions fonctionne.
paths : (obligatoire) contient les chemins relatifs vers les points de terminaison individuels. Chaque chemin doit commencer par une barre oblique (/).
method : (obligatoire) définit la méthode à utiliser.
x-requireConfirmation : (facultatif) spécifie si la confirmation de l’utilisateur est requise avant d’invoquer l’action. Activez ce champ pour demander une confirmation de l’utilisateur avant que l’action ne soit invoquée. Le fait de demander la confirmation de l’utilisateur avant d’invoquer l’action peut empêcher votre application de prendre des mesures en raison d’injections d’invite malveillantes. Par défaut, la confirmation de l’utilisateur est désactivée (DISABLED) si ce champ n’est pas spécifié.

Chaque méthode nécessite au minimum les champs suivants :

description : description de l’opération d’API. Utilisez ce champ pour indiquer à l’agent quand cette opération d’API doit être appelée et ce que fait l’opération.
operationId : chaîne unique qui identifie une opération dans une API, comme le nom d’une fonction. Ce champ est obligatoire pour tous les nouveaux modèles compatibles toolUse tels que Anthropic, Claude 3.5 Sonnet, Meta Llama, etc. Assurez-vous que l’identifiant (ID) que vous fournissez est unique pour toutes les opérations et qu’il suit un schéma alphanumérique simple avec uniquement des traits d’union ou des traits de soulignement comme séparateurs.
responses : contient les propriétés que l’agent renvoie dans la réponse de l’API. L’agent utilise les propriétés de réponse pour construire des invites, traiter avec précision les résultats d’un appel d’API et déterminer un ensemble correct d’étapes à suivre pour effectuer une tâche. L’agent peut utiliser les valeurs de réponse d’une opération comme entrées pour les étapes suivantes de l’orchestration.

Les champs des deux objets suivants fournissent des informations supplémentaires permettant à l’agent de tirer efficacement parti du groupe d’actions. Pour chaque champ, définissez la valeur du champ required sur true s’il est obligatoire et sur false s’il est facultatif.

parameters : contient des informations sur les paramètres qui peuvent être inclus dans la demande.
requestBody : contient les champs du corps de la demande pour l’opération. N’incluez pas ce champ pour les méthodes GET et DELETE.

Pour plus d’informations sur une structure, sélectionnez l’un des onglets suivants.

responses


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

Chaque clé de l’objet responses est un code de réponse, qui décrit le statut de la réponse. Le code de réponse est mappé à un objet qui contient les informations suivantes pour la réponse :

content : (obligatoire pour chaque réponse) contenu de la réponse.
<type_multimédia> : format du corps de la réponse. Pour plus d’informations, consultez Media Types sur le site Web Swagger.
schema : (obligatoire pour chaque type multimédia) définit le type de données dans le corps de la réponse et ses champs.
properties : (obligatoire en cas de présence d’items dans le schéma) l’agent utilise les propriétés que vous définissez dans le schéma pour déterminer les informations qu’il doit renvoyer à l’utilisateur final afin d’exécuter une tâche. Chaque propriété contient les champs suivants :
- type : (obligatoire pour chaque propriété) type de données du champ de réponse.
- description : (facultatif) décrit la propriété. L’agent peut utiliser ces informations pour déterminer les informations qu’il doit renvoyer à l’utilisateur final.

parameters


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

L’agent utilise les champs suivants pour déterminer les informations qu’il doit obtenir de l’utilisateur pour exécuter les exigences relatives au groupe d’actions.

name : (obligatoire) nom du paramètre.
description : (obligatoire) description du paramètre. Utilisez ce champ pour aider l’agent à comprendre comment obtenir ce paramètre de l’utilisateur de l’agent ou pour l’aider à déterminer s’il possède déjà cette valeur de paramètre à la suite d’actions antérieures ou de la demande de l’utilisateur à l’agent.
required : (facultatif) définit si le paramètre est obligatoire pour la demande d’API. Utilisez ce champ pour indiquer à l’agent si ce paramètre est nécessaire pour chaque invocation ou s’il est facultatif.
schema : (facultatif) définition des types de données d’entrée et de sortie. Pour plus d’informations, consultez Data Models (Schemas) sur le site Web Swagger.

requestBody

Voici la structure générale d’un champ requestBody :


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

La liste suivante décrit chaque champ :

required : (facultatif) définit si le corps de la demande est obligatoire pour la demande d’API.
content : (obligatoire) contenu du corps de la demande.
<type_multimédia> : (facultatif) format du corps de la demande. Pour plus d’informations, consultez Media Types sur le site Web Swagger.
schema : (facultatif) définit le type de données du corps de la demande et de ses champs.
properties : (facultatif) l’agent utilise les propriétés que vous définissez dans le schéma pour déterminer les informations qu’il doit obtenir de l’utilisateur final pour exécuter la demande d’API. Chaque propriété contient les champs suivants :
- type : (facultatif) type de données du champ de la demande.
- description : (facultatif) décrit la propriété. L’agent peut utiliser ces informations pour déterminer les informations qu’il doit renvoyer à l’utilisateur final.

Pour découvrir comment ajouter le schéma OpenAPI que vous avez créé lors de la création du groupe d’actions, consultez Ajout d’un groupe d’actions à votre agent dans Amazon Bedrock.

Exemple de schémas d’API

L’exemple suivant fournit un schéma OpenAPI simple au format YAML qui permet d’obtenir la météo d’un endroit donné en degrés Celsius.


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

L’exemple de schéma d’API suivant définit un groupe d’opérations d’API qui permettent de traiter des réclamations d’assurance. Trois API sont définies comme suit :

getAllOpenClaims : l’agent peut utiliser le champ description pour déterminer s’il doit appeler cette opération d’API si une liste des réclamations en cours est nécessaire. L’élément properties dans responses indique que la pièce d’identité, le titulaire de la police et le statut de la réclamation doivent être renvoyés. L’agent renvoie ces informations à l’utilisateur de l’agent ou utilise une partie ou la totalité de la réponse comme entrée pour les appels d’API suivants.
identifyMissingDocuments : l’agent peut utiliser le champ description pour déterminer s’il doit appeler cette opération d’API si des documents manquants doivent être identifiés dans le cadre d’une réclamation d’assurance. Les champs name, description et required indiquent à l’agent qu’il doit obtenir l’identifiant unique de la réclamation en cours auprès du client. L’élément properties dans responses indique que les identifiants des réclamations d’assurance en cours doivent être renvoyés. L’agent renvoie ces informations à l’utilisateur final ou utilise une partie ou la totalité de la réponse comme entrée pour les appels d’API suivants.
sendReminders : l’agent peut utiliser le champ description pour déterminer s’il doit appeler cette opération d’API s’il est nécessaire d’envoyer des rappels au client. Par exemple, un rappel concernant les documents en attente pour les réclamations en cours. L’élément properties dans requestBody indique à l’agent qu’il doit trouver les numéros de réclamation et les documents en attente. L’élément properties dans responses indique qu’un ID du rappel et son statut doivent être renvoyés. L’agent renvoie ces informations à l’utilisateur final ou utilise une partie ou la totalité de la réponse comme entrée pour les appels d’API suivants.


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

Pour plus d’exemples de schémas OpenAPI, consultez Example API Descriptions sur le site Web OpenAPI.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Définition des détails des fonctions

Gestion de l’exécution de l’action