Definir OpenAPI esquemas para los grupos de acción de su agente en Amazon Bedrock - Amazon Bedrock
Ejemplos de API esquemas

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Definir OpenAPI esquemas para los grupos de acción de su agente en Amazon Bedrock

Al crear un grupo de acciones en Amazon Bedrock, debe definir los parámetros que el agente debe invocar desde el usuario. También puede definir API las operaciones que el agente puede invocar con estos parámetros. Para definir las API operaciones, cree un OpenAPI esquema en JSON nuestro YAML formato. Puedes crear OpenAPI archivos de esquema y cárguelos en Amazon Simple Storage Service (Amazon S3). Como alternativa, puede utilizar el OpenAPI editor de texto de la consola, que validará el esquema. Tras crear un agente, puede utilizar el editor de texto para añadir un grupo de acciones al agente o editar un grupo de acciones existente. Para obtener más información, consulte Modificar un agente.

El agente usa el esquema para determinar la API operación que debe invocar y los parámetros necesarios para realizar la API solicitud. Luego, estos detalles se envían a través de una función Lambda que usted defina para llevar a cabo la acción o se devuelven en respuesta a la invocación del agente.

Para obtener más información sobre los API esquemas, consulte los siguientes recursos:

El siguiente es el formato general de un OpenAPI esquema de un grupo de acciones.

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

En la siguiente lista se describen los campos del OpenAPI Esquema

  • openapi— (Obligatorio) La versión de OpenAPI que se está utilizando. Este valor debe ser "3.0.0" para que el grupo de acción funcione.

  • paths: (obligatorio) contiene rutas relativas a puntos de conexión individuales. Cada ruta debe comenzar con una barra inclinada (/).

  • method: (obligatorio) define el método que se debe utilizar.

  • x-requireConfirmation— (Opcional) Especifica si se requiere la confirmación del usuario antes de invocar la acción. Active este campo para solicitar la confirmación del usuario antes de invocar la acción. Solicitar la confirmación del usuario antes de invocar la acción puede impedir que tu aplicación tome medidas debido a inyecciones rápidas malintencionadas. De forma predeterminada, la confirmación del usuario es DISABLED si no se especifica este campo.

Como mínimo, cada método requiere los siguientes campos:

  • description— Una descripción de la API operación. Utilice este campo para informar al agente de cuándo debe llamar a esta API operación y qué hace la operación.

  • operationId— Una cadena única que identifica una operación en unaAPI, por ejemplo, el nombre de una función. Este campo es obligatorio para todos los nuevos modelos toolUse habilitados, como Anthropic Claude 3.5 Sonnet, Meta Llama, , etc.: Asegúrese de que el identificador (ID) que proporcione sea único en todas las operaciones y siga un patrón alfanumérico simple con solo guiones o guiones bajos como separadores.

  • responses— Contiene las propiedades que el agente devuelve en la respuesta. API El agente utiliza las propiedades de respuesta para crear mensajes, procesar con precisión los resultados de una API llamada y determinar el conjunto correcto de pasos para realizar una tarea. El agente puede usar los valores de respuesta de una operación como entradas para los pasos posteriores de la orquestación.

Los campos de los dos objetos siguientes proporcionan más información para que el agente aproveche eficazmente el grupo de acciones. Para cada campo, defina el valor del required campo en true si es necesario y en false si es opcional.

  • parameters: contiene información sobre los parámetros que se pueden incluir en la solicitud.

  • requestBody: contiene los campos del cuerpo de la solicitud para la operación. No incluya este campo para los métodos GET o DELETE.

Para obtener más información sobre una estructura, seleccione una de las siguientes pestañas.

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

Cada clave del responses objeto es un código de respuesta que describe el estado de la respuesta. El código de respuesta se asigna a un objeto que contiene la siguiente información para la respuesta:

  • content: (obligatorio para cada respuesta) el contenido de la respuesta.

  • <media type> — El formato del cuerpo de la respuesta. Para obtener más información, consulte Tipos de medios en el Swagger sitio web.

  • schema: (obligatorio para cada tipo de medio) define el tipo de datos del cuerpo de la respuesta y sus campos.

  • properties: (obligatorio si hay items en el esquema) el agente usa las propiedades que usted defina en el esquema para determinar la información que debe devolver al usuario final para completar una tarea. Cada propiedad contiene los siguientes campos:

    • type: (obligatorio para cada propiedad) el tipo de datos del campo de respuesta.

    • description: (opcional) describe la propiedad. El agente puede usar esta información para determinar la información que necesita devolver al usuario final.

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

El agente utiliza los siguientes campos para determinar la información que debe obtener del usuario final para cumplir con los requisitos del grupo de acciones.

  • name: (obligatorio) el nombre del parámetro.

  • description: (obligatorio) una descripción del parámetro. Utilice este campo para ayudar al agente a entender cómo obtener este parámetro del usuario del agente o determinar si ya tiene ese valor de parámetro debido a acciones anteriores o a una solicitud del usuario al agente.

  • required— (Opcional) Si el parámetro es obligatorio para la API solicitud. Utilice este campo para indicar al agente si este parámetro es necesario para cada invocación o si es opcional.

  • schema: (opcional) la definición de los tipos de datos de entrada y salida. Para obtener más información, consulte Modelos de datos (esquemas) en el Swagger sitio web.

requestBody

A continuación se presenta la estructura general de un requestBody campo:

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

En la siguiente lista se describe cada campo:

  • required— (Opcional) Si el cuerpo de la solicitud es obligatorio para la API solicitud.

  • content: (obligatorio) el contenido del cuerpo de la solicitud.

  • <media type> — (Opcional) El formato del cuerpo de la solicitud. Para obtener más información, consulte Tipos de medios en la Swagger sitio web.

  • schema: (opcional) define el tipo de datos del cuerpo de la solicitud y sus campos.

  • properties— (Opcional) El agente utiliza las propiedades que usted defina en el esquema para determinar la información que debe obtener del usuario final para realizar la API solicitud. Cada propiedad contiene los siguientes campos:

    • type: (opcional) el tipo de datos del campo de la solicitud.

    • description: (opcional) describe la propiedad. El agente puede usar esta información para determinar la información que necesita devolver al usuario final.

Para obtener información sobre cómo añadir el OpenAPI esquema que creó al crear el grupo de acciones, consulteAñada un grupo de acción a su agente en Amazon Bedrock.

Ejemplos de API esquemas

El siguiente ejemplo proporciona un sencillo OpenAPI esquema en YAML formato que obtiene el clima de una ubicación determinada en grados 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

El siguiente API esquema de ejemplo define un grupo de API operaciones que ayudan a gestionar las reclamaciones de seguros. APIsLas tres se definen de la siguiente manera:

  • getAllOpenClaims— Su agente puede usar el description campo para determinar si debe llamar a esta API operación si necesita una lista de reclamaciones pendientes. El properties en las responses especifica que debe devolverse el ID, el titular de la póliza y el estado de la reclamación. El agente devuelve esta información al usuario del agente o utiliza una parte o la totalidad de la respuesta como entrada para las API llamadas posteriores.

  • identifyMissingDocuments— Su agente puede usar el description campo para determinar si debe cancelar esta API operación si es necesario identificar los documentos faltantes para una reclamación de seguro. Los campos name, description y required indican al agente que debe obtener del cliente el identificador único de la reclamación pendiente. El properties responses especificado para devolver las reclamaciones IDs de seguro pendientes. El agente devuelve esta información al usuario final o utiliza parte o la totalidad de la respuesta como entrada para las API llamadas posteriores.

  • sendReminders— Su agente puede usar el description campo para determinar si debe llamar a esta API operación si es necesario enviar recordatorios al cliente. Por ejemplo, un recordatorio sobre los documentos pendientes que tienen en relación con las reclamaciones pendientes. requestBodyLe dicen al agente que debe encontrar la reclamación IDs y los documentos pendientes. properties propertiesEn el responses especifican que se devolverá un identificador del recordatorio y su estado. El agente devuelve esta información al usuario final o utiliza parte o la totalidad de la respuesta como entrada para las API llamadas posteriores.

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

Para ver más ejemplos de OpenAPI consulte https://github.com/OAI/APIOpen-Specification/Tree/Main/Examples/v3.0 en el sitio web. GitHub