Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
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 opérations d'API que l'agent peut invoquer à l'aide de ces paramètres. Pour définir les opérations de l'API, créez un OpenAPI schéma au format JSON ou YAML. 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'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'appel de l'agent.
Pour plus d'informations sur les schémas d'API, 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 schémas d'API, consultez la section Meilleures pratiques en matière de conception d'API
sur le 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 faitDISABLEDsi ce champ n'est pas spécifié.
Au minimum, chaque méthode nécessite les champs suivants :
-
description: description de l’opération d’API. Utilisez ce champ pour indiquer à l'agent quand appeler cette opération d'API et à quoi elle sert. -
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 créer des invites, traiter avec précision les résultats d'un appel d'API 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éthodesGETetDELETE.
Pour en savoir plus sur une structure, sélectionnez l'un des onglets suivants.
"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édiassur 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’itemsdans 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.
-
Pour savoir comment ajouter le 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 schémas d'API
L'exemple suivant fournit une solution simple OpenAPI schéma au format YAML 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: stringL'exemple de schéma d'API suivant définit un groupe d'opérations d'API qui aident à traiter les réclamations d'assurance. Trois d' APIs entre elles sont définies comme suit :
-
getAllOpenClaims— Votre agent peut utiliser ledescriptionchamp pour déterminer s'il doit appeler cette opération d'API si une liste de réclamations ouvertes est nécessaire. L’objetpropertiesdansresponsesindique 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— Votre agent peut utiliser ledescriptionchamp pour déterminer s'il doit appeler cette opération API si des documents manquants doivent être identifiés pour une réclamation d'assurance. Les champsname,descriptionetrequiredindiquent à l’agent qu’il doit obtenir l’identifiant unique de la réclamation en cours auprès du client. Lepropertiesdans leresponsesspé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 appels d'API suivants. -
sendReminders— Votre agent peut utiliser ledescriptionchamp 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 suspens dont ils disposent pour les demandes en cours. Lepropertiesin therequestBodyindique à l'agent qu'il doit trouver la réclamation IDs et les documents en suspens. Entrezpropertiesdans leresponseschamp 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 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 d'autres exemples de OpenAPI schémas, voir les exemples de descriptions d'API
