Definire schemi OpenAPI per i gruppi di operazioni dell’agente in Amazon Bedrock - Amazon Bedrock
Esempi di schemi API

Definire schemi OpenAPI per i gruppi di operazioni dell’agente in Amazon Bedrock

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

L’agente utilizza lo schema per determinare l’operazione API da invocare 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 all’invocazione dell’agente.

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

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

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

Nell’elenco seguente vengono descritti i campi presenti nello schema OpenAPI:

  • openapi: (obbligatorio) la versione di OpenAPI in uso. Affinché il gruppo di operazioni funzioni, questo valore deve essere "3.0.0".

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

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

  • x-requireConfirmation: (facoltativo) specifica se è richiesta la conferma dell’utente prima di invocare l’azione. Abilita questo campo per richiedere la conferma all’utente prima che l’azione venga invocata. Richiedere la conferma dell’utente prima di invocare l’azione può impedire all’applicazione di intraprendere azioni causate da iniezioni di prompt dannose. Se questo campo non viene specificato, per impostazione predefinita la conferma dell’utente è DISABLED.

Ogni metodo richiede almeno i seguenti campi:

  • description: una descrizione dell'operazione API. Utilizza questo campo per indicare all’agente quando chiamare questa operazione API e cosa fa l’operazione.

  • operationId: una stringa univoca che identifica un’operazione in un’API, ad esempio il nome di una funzione. Questo è un campo obbligatorio per tutti i nuovi modelli basati su toolUse come Anthropic, Claude 3.5 Sonnet e Meta Llama. Assicurati che l’identificatore (Id) che fornisci sia univoco per tutte le operazioni e segua un semplice pattern alfanumerico in cui i separatori sono solo trattini o trattini bassi.

  • responses: contiene le proprietà che l’agente restituisce nella risposta dell’API. L’agente utilizza le proprietà di risposta per creare prompt, elaborare accuratamente i risultati di una chiamata API e determinare una serie di fasi corrette per eseguire 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. Imposta il valore dei campi required su true se obbligatori e su false se facoltativi.

  • 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’oggetto responses è 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 contenuti multimediali sul sito web di Swagger.

  • 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 quelle da 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 operazioni.

  • 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 è necessario per la richiesta API. Utilizza questo campo per indicare all’agente se questo parametro è necessario per ogni invocazione o se è opzionale.

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

requestBody

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

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

Nell’elenco seguente è descritto ciascun campo:

  • required: (facoltativo) se il corpo della richiesta è necessario 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 contenuti multimediali sul sito web di Swagger.

  • 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 schema OpenAPI creato durante la creazione del gruppo di operazioni, consulta Aggiunta di un gruppo di operazioni all’agente in Amazon Bedrock.

Esempi di schemi API

L’esempio seguente fornisce uno schema OpenAPI semplice in formato YAML che ottiene informazioni sul meteo di 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

Il seguente esempio di schema API definisce un gruppo di operazioni API che semplificano la gestione delle richieste di indennizzo assicurativo. Le tre API sono definite come segue:

  • getAllOpenClaims: il tuo agente può utilizzare il campo description per stabilire se chiamare questa operazione API nel caso in cui sia necessario un elenco di richieste di indennizzo aperte. 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 campo description per stabilire che deve chiamare questa operazione API se è necessario identificare i documenti mancanti per una richiesta di indennizzo. 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 oppure utilizza alcune o tutte le risposte come input per le chiamate API successive.

  • sendReminders: l’agente può utilizzare il campo description per stabilire che deve chiamare questa operazione API se è necessario inviare dei promemoria al cliente, ad esempio su documenti in sospeso per le richieste di indennizzo aperte. Le properties nel requestBody comunicano all’agente che deve trovare gli ID delle richieste di indennizzo e i documenti in sospeso. Le properties nelle responses specificano di restituire un ID di un promemoria e il relativo stato. L’agente restituisce queste informazioni all’utente finale oppure utilizza alcune o tutte le risposte come input per le chiamate API successive.

{
    "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 schemi OpenAPI, consulta Descrizioni di API di esempio sul sito web di OpenAPI.