Definisci OpenAPI schemi per i gruppi d'azione del tuo agente in Amazon Bedrock

Quando crei un gruppo di azioni in Amazon Bedrock, devi definire i parametri che l'agente deve richiamare dall'utente. Puoi anche definire operazioni API che l'agente può richiamare utilizzando questi parametri. Per definire le operazioni API, crea uno OpenAPI schema in formato JSON o YAML. Puoi creare file di OpenAPI schema e caricarli su Amazon Simple Storage Service (Amazon S3). In alternativa, puoi utilizzare l'editor di OpenAPI testo nella console, che convaliderà lo schema. Dopo aver creato un agente, puoi utilizzare l'editor di testo quando aggiungi un gruppo di azioni all'agente o modifichi un gruppo di azioni esistente. Per ulteriori informazioni, consulta Modifica di un agente.

L'agente utilizza lo schema per determinare l'operazione API da richiamare e i parametri necessari per effettuare la richiesta API. Questi dettagli vengono quindi inviati tramite una funzione Lambda definita per eseguire l'azione o restituiti nella risposta alla chiamata dell'agente.

Per ulteriori informazioni sugli schemi API, consulta le seguenti risorse:

• Per ulteriori dettagli sugli OpenAPI schemi, vedere le OpenAPIspecifiche sul Swagger sito Web.

• Per le migliori pratiche nella scrittura di schemi API, consulta Best practice in materia di progettazione delle API sul Swagger sito Web.

Di seguito è riportato il formato generale di OpenAPI uno schema per un gruppo di azione.

{
    "openapi": "3.0.0",
    "paths": {
        "/path": {
            "method": {
                "description": "string",
                "operationId": "string",
                "parameters": [ ... ],
                "requestBody": { ... },
                "responses": { ... }
           }
       }
    }
}

L'elenco seguente descrive i campi dello OpenAPI schema

• openapi— (Obbligatorio) La versione in uso. OpenAPI Questo valore deve essere utilizzato "3.0.0" per consentire al gruppo di azione di funzionare.

• paths: (obbligatorio) contiene percorsi relativi ai singoli endpoint. Ogni percorso deve iniziare con una barra (/).

• method: (obbligatorio) definisce il metodo da utilizzare.

Come minimo, ogni metodo richiede i seguenti campi:

• description: una descrizione dell'operazione API. Utilizzate questo campo per informare l'agente quando chiamare questa operazione API e cosa fa l'operazione.

• responses— Contiene le proprietà che l'agente restituisce nella risposta dell'API. L'agente utilizza le proprietà di risposta per creare prompt, elaborare con precisione i risultati di una chiamata API e determinare una serie corretta di passaggi per l'esecuzione di un'attività. L'agente può utilizzare i valori di risposta di un'operazione come input per le fasi successive dell'orchestrazione.

I campi all'interno dei due oggetti seguenti forniscono ulteriori informazioni affinché l'agente possa sfruttare efficacemente il gruppo di operazioni. Per ogni campo, imposta il valore del required campo su true se obbligatorio e su se facoltativo. false

• parameters: contiene informazioni sui parametri che possono essere inclusi nella richiesta.

• requestBody: contiene i campi nel corpo della richiesta per l'operazione. Non includere questo campo per i metodi GET e DELETE.

Per ulteriori informazioni su una struttura, seleziona una delle seguenti schede.

responses

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

Ogni chiave dell'responsesoggetto è un codice di risposta che descrive lo stato della risposta. Il codice di risposta è mappato su un oggetto che contiene le seguenti informazioni per la risposta:

• content: (obbligatorio per ogni risposta) il contenuto della risposta.

• <media type>: il formato del corpo della risposta. Per ulteriori informazioni, consulta Tipi di file multimediali sul Swagger sito Web.

• schema: (obbligatorio per ogni tipo di supporto) definisce il tipo di dati del corpo della risposta e dei relativi campi.

• properties: (obbligatorio se nello schema sono presenti items) l'agente utilizza le proprietà definite nello schema per determinare le informazioni che deve restituire all'utente finale per eseguire un'attività. Ogni proprietà contiene i campi seguenti:

  • type: (obbligatorio per ogni proprietà) il tipo di dati del campo di risposta.

  • description: (facoltativo) descrive la proprietà. L'agente può utilizzare queste informazioni per determinare le informazioni che deve restituire all'utente finale.

parameters

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

L'agente utilizza i seguenti campi per determinare le informazioni che deve ottenere dall'utente finale per soddisfare i requisiti del gruppo di azione.

• name: (obbligatorio) il nome del parametro.

• description: (obbligatorio) una descrizione del parametro. Utilizza questo campo per aiutare l'agente a capire come ottenere questo parametro dall'utente dell'agente o per determinare che abbia già quel valore di parametro in base alle azioni precedenti o alla richiesta dell'utente all'agente.

• required— (Facoltativo) Se il parametro è obbligatorio per la richiesta API. Utilizzate questo campo per indicare all'agente se questo parametro è necessario per ogni chiamata o se è facoltativo.

• schema: (facoltativo) la definizione dei tipi di dati di input e output. Per ulteriori informazioni, consulta Modelli di dati (schemi) sul sito Web. Swagger

requestBody

Di seguito è riportata la struttura generale di un requestBody campo:

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

L'elenco seguente descrive ogni campo:

• required— (Facoltativo) Se il corpo della richiesta è obbligatorio per la richiesta API.

• content: (obbligatorio) il contenuto del corpo della richiesta.

• <media type>: (facoltativo) il formato del corpo della richiesta. Per ulteriori informazioni, consulta Tipi di file multimediali sul Swagger sito Web.

• schema: (facoltativo) definisce il tipo di dati del corpo della richiesta e dei relativi campi.

• properties— (Facoltativo) L'agente utilizza le proprietà definite nello schema per determinare le informazioni che deve ottenere dall'utente finale per effettuare la richiesta API. Ogni proprietà contiene i campi seguenti:

  • type: (facoltativo) il tipo di dati del campo della richiesta.

  • description: (facoltativo) descrive la proprietà. L'agente può utilizzare queste informazioni per determinare quelle da restituire all'utente finale.

Per informazioni su come aggiungere lo OpenAPI schema creato durante la creazione del gruppo di azioni, consultaAggiungi un gruppo d'azione al tuo agente in Amazon Bedrock.

Schemi API di esempio

L'esempio seguente fornisce uno OpenAPI schema semplice in formato YAML che ottiene il meteo per una determinata località in gradi 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

Lo schema API di esempio seguente definisce un gruppo di operazioni API che aiutano a gestire i reclami assicurativi. Le tre API sono definite come segue:

• getAllOpenClaims— Il tuo agente può utilizzare il description campo per determinare che debba chiamare questa operazione API se è necessario un elenco di reclami aperti. properties in responses specifica se restituire l'ID e l'intestatario della polizza e lo stato della richiesta di indennizzo. L'agente restituisce queste informazioni all'utente dell'agente o utilizza alcune o tutte le risposte come input per le successive chiamate API.

• identifyMissingDocuments— L'agente può utilizzare il description campo per determinare che debba richiamare questa operazione API se è necessario identificare i documenti mancanti per una richiesta di risarcimento assicurativo. I campi name, description e required indicano all'agente che deve richiedere al cliente l'identificativo univoco della richiesta di indennizzo aperta. properties in responses specificano di restituire gli ID delle richieste di indennizzo assicurativo aperte. L'agente restituisce queste informazioni all'utente finale o utilizza alcune o tutte le risposte come input per le successive chiamate API.

• sendReminders— L'agente può utilizzare il description campo per determinare che debba richiamare questa operazione API se è necessario inviare promemoria al cliente. Ad esempio, un promemoria sui documenti in sospeso di cui dispone per i reclami aperti. Quindi requestBody comunica properties all'agente che deve trovare gli ID dei reclami e i documenti in sospeso. Quindi responses specifica properties di restituire l'ID del promemoria e il relativo stato. L'agente restituisce queste informazioni all'utente finale o utilizza alcune o tutte le risposte come input per le successive chiamate API.

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

Per altri esempi di OpenAPI schemi, vedere https://github.com/OAI/OpenAPI-Specification/tree/main/examples/v3.0 sul GitHub sito Web.