Definir OpenAPI esquemas para os grupos de ação do seu agente no Amazon Bedrock - Amazon Bedrock
Exemplo de esquemas de API

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Definir OpenAPI esquemas para os grupos de ação do seu agente no Amazon Bedrock

Ao criar um grupo de ação no Amazon Bedrock, defina os parâmetros que o agente precisa invocar do usuário. Também é possível definir operações de API que o agente pode invocar usando esses parâmetros. Para definir as operações da API, crie um OpenAPI esquema no formato JSON ou YAML. Você pode criar OpenAPI esquema arquivos e faça o upload deles para o Amazon Simple Storage Service (Amazon S3). Como alternativa, você pode usar o OpenAPI editor de texto no console, que validará seu esquema. Após a criação de um agente, é possível usar o editor de texto ao adicionar um grupo de ação ao agente ou ao editar um grupo de ação existente. Para obter mais informações, consulte Modificar um agente.

O agente usa o esquema para determinar a operação de API que ele precisa invocar e os parâmetros necessários para fazer a solicitação de API. Esses detalhes são enviados por meio de uma função do Lambda que você define para executar a ação ou são exibidos na resposta da invocação do agente.

Para obter mais informações sobre os esquemas da API, consulte os seguintes recursos:

A seguir está o formato geral de um OpenAPI esquema para um grupo de ação.

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

A lista a seguir descreve os campos no OpenAPI esquema

  • openapi— (Obrigatório) A versão do OpenAPI que está sendo usado. Esse valor deve ser "3.0.0" para que o grupo de ação funcione.

  • paths: (obrigatório) contém os caminhos relativos para endpoints individuais. Cada caminho deve começar com uma barra (/).

  • method: (obrigatório) define o método a ser usado.

  • x-requireConfirmation: (opcional) especifica se a confirmação do usuário é necessária antes de invocar a ação. Ative esse campo para solicitar a confirmação do usuário antes que a ação seja invocada. Solicitar a confirmação do usuário antes de invocar a ação pode impedir que a aplicação execute ações devido a injeções de prompt maliciosas. Por padrão, a confirmação do usuário será DISABLED se esse campo não for especificado.

Cada método exige pelo menos os seguintes campos:

  • description: uma descrição da operação de API. Use esse campo para informar ao agente quando chamar essa operação de API e o que ela faz.

  • operationId: uma string exclusiva que identifica uma operação em uma API, como o nome de uma função. Esse é um campo obrigatório para todos os novos modelos habilitados para ToolUse, como Anthropic Claude 3.5 Sonnet, Meta Llama, etc. Verifique se o identificador (ID) fornecido é exclusivo em todas as operações e siga um padrão alfanumérico simples com apenas hifens ou sublinhados como separadores.

  • responses: contém as propriedades que o agente exibe na resposta da API. O agente usa as propriedades de resposta para construir prompts, processar com precisão os resultados de uma chamada de API e determinar um conjunto correto de etapas para a execução de uma tarefa. O agente pode usar os valores de resposta de uma operação como entradas para as etapas subsequentes da orquestração.

Os campos nos dois objetos a seguir fornecem mais informações para que o agente aproveite o grupo de ação de forma eficaz. Para cada campo, defina o valor do campo required como true se necessário e false se opcional.

  • parameters: contém informações sobre os parâmetros que podem ser incluídos na solicitação.

  • requestBody: contém os campos no corpo da solicitação para a operação. Não inclua esse campo para os métodos GET e DELETE.

Para saber mais sobre uma estrutura, selecione nas guias a seguir.

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

Cada chave no objeto responses é um código de resposta, que descreve o status da resposta. O código de resposta é associado a um objeto que contém as seguintes informações para a resposta:

  • content: (obrigatório para cada resposta) o conteúdo da resposta.

  • <media type>— O formato do corpo da resposta. Para obter mais informações, consulte Tipos de mídia no Swagger site.

  • schema: (obrigatório para cada tipo de mídia) define o tipo de dados do corpo da resposta e os respectivos campos.

  • properties: (obrigatório se houver items no esquema) o agente usa as propriedades que você define no esquema para determinar as informações que precisa exibir ao usuário final para executar uma tarefa. Cada propriedade contém os seguintes campos:

    • (Obrigatório para cada propriedade) type: o tipo de dados do campo de resposta.

    • description: (opcional) descreve a propriedade. O agente pode usar essas informações para determinar as informações que precisa exibir ao usuário final.

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

O agente usa os campos a seguir para determinar as informações que precisa obter do usuário final para executar os requisitos do grupo de ação.

  • name: (obrigatório) o nome do parâmetro.

  • description: (obrigatório) uma descrição do parâmetro. Use esse campo para ajudar o agente a compreender como obter esse parâmetro do usuário do agente ou determinar se ele já tem esse valor de parâmetro de ações anteriores ou da solicitação do usuário ao agente.

  • required: (opcional) se o parâmetro é necessário ou não para a solicitação da API. Use esse campo para informar ao agente se esse parâmetro é necessário para cada invocação ou se é opcional.

  • schema: (opcional) a definição dos tipos de dados de entrada e de saída. Para obter mais informações, consulte Modelos de dados (esquemas) no Swagger site.

requestBody

Veja a estrutura geral de um campo requestBody:

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

A seguinte lista descreve cada campo:

  • required: (opcional) se o corpo da solicitação é necessário ou não para a solicitação da API.

  • content: (obrigatório) o conteúdo do corpo da solicitação.

  • <media type>— (Opcional) O formato do corpo da solicitação. Para obter mais informações, consulte Tipos de mídia no Swagger site.

  • schema: (opcional) define o tipo de dados do corpo da solicitação e os respectivos campos.

  • properties: (opcional) o agente usa as propriedades que você define no esquema para determinar as informações que ele precisa obter do usuário final para executar a solicitação de API. Cada propriedade contém os seguintes campos:

    • (Opcional) type: o tipo de dados do campo de solicitação.

    • (Opcional) description: descreve a propriedade. O agente pode usar essas informações para determinar as informações que precisam ser exibidas ao usuário final.

Para saber como adicionar o OpenAPI esquema que você criou ao criar o grupo de ação, consulteAdicionar um grupo de ação ao agente no Amazon Bedrock.

Exemplo de esquemas de API

O exemplo a seguir fornece uma simples OpenAPI esquema no formato YAML que obtém o clima de um determinado local em 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

O exemplo do esquema de API a seguir define um grupo de operações de API que ajudam a tratar reivindicações de seguro. Três APIs são definidos da seguinte forma:

  • getAllOpenClaims: o agente pode usar o campo description para determinar se deve chamar essa operação de API se uma lista das reivindicações em aberto for necessária. As properties em responses estabelecem a devolução do ID e do titular da apólice e o status do pedido. O agente retorna essas informações ao usuário do agente ou usa parte ou toda a resposta como entrada para chamadas de API subsequentes.

  • identifyMissingDocuments: o agente pode usar o campo description para determinar se deve chamar essa operação de API se os documentos ausentes precisarem ser identificados para uma reivindicação de seguro. Os campos name, description e required informam ao agente que ele deve obter o identificador exclusivo de reivindicação em aberto do cliente. propertiesEm seguida, responses especifique para devolver os pedidos IDs de seguro abertos. O agente apresenta essas informações ao usuário final ou usa parte ou toda a resposta como entrada para chamadas de API subsequentes.

  • sendReminders: o agente pode usar o campo description para determinar se deve chamar essa operação de API se houver necessidade de enviar lembretes ao cliente. Por exemplo, um lembrete sobre documentos pendentes que têm para reivindicações abertas. propertiesEm seguida, requestBody informe ao agente que ele deve encontrar a reclamação IDs e os documentos pendentes. properties em responses especifica que um ID do lembrete e seu status devem ser apresentados. O agente apresenta essas informações ao usuário final ou usa parte ou toda a resposta como entrada para chamadas de API subsequentes.

{
    "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 mais exemplos de OpenAPI esquemas, consulte exemplos de descrições de API no OpenAPI site.