Définir OpenAPI schémas pour les groupes d'action de votre agent dans Amazon Bedrock

Lorsque vous créez un groupe d'action 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 API opérations que l'agent peut invoquer à l'aide de ces paramètres. Pour définir les API opérations, créez un OpenAPI schéma dans JSON ou YAML format. Vous pouvez créer OpenAPI fichiers de schéma et chargez-les sur Amazon Simple Storage Service (Amazon S3). Vous pouvez également utiliser OpenAPI éditeur de texte dans la console, 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 de plus amples informations, veuillez consulter Modifier un agent.

L'agent utilise le schéma pour déterminer l'APIopération qu'il doit invoquer et les paramètres requis pour effectuer la API demande. 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'appel de l'agent.

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

• Pour plus de détails sur OpenAPI schémas, voir OpenAPI spécification sur le Swagger site Web.

• Pour connaître les meilleures pratiques en matière d'écriture de API schémas, consultez la section Meilleures pratiques en matière API de conception sur Swagger site Web.

Voici le format général d'un OpenAPI schéma d'un groupe d'action.

{
    "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 du OpenAPI schéma

• openapi— (Obligatoire) La version de OpenAPI qui est utilisé. Cette valeur doit être valide "3.0.0" pour que le groupe d'action fonctionne.

• paths : (obligatoire) contient des chemins relatifs vers des 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'appeler l'action. Activez ce champ pour demander une confirmation à 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 rapides malveillantes. Par défaut, la confirmation de l'utilisateur se fait DISABLED si ce champ n'est pas spécifié.

Au minimum, chaque méthode nécessite les champs suivants :

• description— Description de l'APIopération. Utilisez ce champ pour indiquer à l'agent à quel moment lancer cette API opération et à quoi elle sert.

• operationId— Chaîne unique qui identifie une opération dans unAPI, comme le nom d'une fonction. Ce champ est obligatoire pour tous les nouveaux modèles toolUse activés 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 API réponse. L'agent utilise les propriétés de réponse pour créer des instructions, traiter avec précision les résultats d'un API appel et déterminer un ensemble d'étapes correctes 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 parti efficacement du groupe d’actions. Pour chaque champ, définissez la valeur du required champ sur true false si nécessaire et sur 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 en savoir plus 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'responsesobjet est un code de réponse qui décrit l'état de la réponse. Le code de réponse correspond à un objet qui contient les informations suivantes pour la réponse :

• content : (obligatoire pour chaque réponse) contenu de la réponse.

• <media type> — Le format du corps de la réponse. Pour plus d'informations, consultez la section Types de médias sur le Swagger site Web.

• schema : (obligatoire pour chaque type de média) définit le type de données du corps de la réponse et de ses champs.

• properties : (obligatoire en cas 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": {
            ...
        }
    },
    ...
]

Votre agent utilise les champs suivants pour déterminer les informations qu'il doit obtenir de l'utilisateur final pour répondre aux exigences du 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 auprès 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) Si le paramètre est obligatoire pour la API demande. Utilisez ce champ pour indiquer à l'agent si ce paramètre est nécessaire pour chaque appel 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 la section Modèles de données (schémas) sur Swagger site Web.

requestBody

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

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

La liste suivante décrit chaque champ :

• required— (Facultatif) Si le corps de la demande est requis pour la API demande.

• content : (obligatoire) contenu du corps de la demande.

• <media type> — (Facultatif) Le format du corps de la demande. Pour plus d'informations, consultez la section Types de médias sur le Swagger site Web.

• schema : (facultatif) définit le type de données du corps de la demande et de ses champs.

• properties— (Facultatif) Votre 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 effectuer la API demande. 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 savoir comment ajouter OpenAPI schéma que vous avez créé lors de la création du groupe d'actions, voirAjoutez un groupe d'action à votre agent dans Amazon Bedrock.

Exemples de API schémas

L'exemple suivant fournit une solution simple OpenAPI schéma au YAML format qui obtient la météo pour 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 API schéma suivant définit un groupe d'APIopérations qui aident à traiter les réclamations d'assurance. Trois d'APIsentre elles sont définies comme suit :

• getAllOpenClaims— Votre agent peut utiliser le description champ pour déterminer s'il doit appeler cette API opération s'il a besoin d'une liste de réclamations ouvertes. L’objet 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 API appels suivants.

• identifyMissingDocuments— Votre agent peut utiliser le description champ pour déterminer s'il doit appeler cette API opération 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. Le properties dans le responses spécifiez pour renvoyer les IDs réclamations d'assurance ouvertes. L'agent renvoie ces informations à l'utilisateur final ou utilise une partie ou la totalité de la réponse comme entrée pour les API appels suivants.

• sendReminders— Votre agent peut utiliser le description champ pour déterminer s'il doit appeler cette API opération s'il est nécessaire d'envoyer des rappels au client. Par exemple, un rappel concernant les documents en suspens dont ils disposent pour les demandes en cours. Le properties in the requestBody indique à l'agent qu'il doit trouver la réclamation IDs et les documents en suspens. Entrez properties dans le responses champ pour renvoyer un identifiant du rappel et son statut. L'agent renvoie ces informations à l'utilisateur final ou utilise une partie ou la totalité de la réponse comme entrée pour les API appels 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 d'autres exemples de OpenAPI schémas, voir https://github.com/OAI/Open API -Specification/Tree/Main/Examples/v3.0 sur le site Web. GitHub