Definire OpenAPI schemi per i gruppi di azioni del tuo agente in Amazon Bedrock - Amazon Bedrock
APISchemi di esempio

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Definire OpenAPI schemi per i gruppi di azioni 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 API operazioni che l'agente può richiamare utilizzando questi parametri. Per definire le API operazioni, create un OpenAPI schema nel JSON nostro YAML formato. È possibile creare OpenAPI file di schema e caricali su Amazon Simple Storage Service (Amazon S3). In alternativa, puoi usare il OpenAPI editor di testo nella console, che convaliderà lo schema. Dopo aver creato un agente, è possibile utilizzare l'editor di testo per aggiungere un gruppo di azioni all'agente o modificare un gruppo di azioni esistente. Per ulteriori informazioni, consulta Modificare un agente.

L'agente utilizza lo schema per determinare l'APIoperazione da richiamare e i parametri necessari per effettuare la API richiesta. 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 API schemi, consulta le seguenti risorse:

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

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

L'elenco seguente descrive i campi in OpenAPI schema

  • openapi— (Obbligatorio) La versione di OpenAPI che viene utilizzata. Questo valore deve essere necessario "3.0.0" affinché il gruppo d'azione funzioni.

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

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

  • x-requireConfirmation— (Facoltativo) Specificate se è richiesta la conferma dell'utente prima di richiamare l'azione. Abilita questo campo per richiedere la conferma all'utente prima che l'azione venga richiamata. Richiedere la conferma dell'utente prima di richiamare l'azione può proteggere l'applicazione dall'intraprendere azioni dovute a iniezioni tempestive dannose. Per impostazione predefinita, la conferma dell'utente avviene DISABLED se questo campo non è specificato.

Come minimo, ogni metodo richiede i seguenti campi:

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

  • operationId— Una stringa univoca che identifica un'operazione in un nomeAPI, come una funzione. Questo è un campo obbligatorio per tutti i nuovi modelli toolUse abilitati, ad esempio Anthropic Claude 3.5 Sonnet, Meta Llama, e così via. Assicurati che l'identificatore (Id) che fornisci sia unico per tutte le operazioni e segua un semplice schema alfanumerico con solo trattini o caratteri di sottolineatura come separatori.

  • responses— Contiene le proprietà che l'agente restituisce nella risposta. API L'agente utilizza le proprietà di risposta per creare prompt, elaborare con precisione i risultati di una API chiamata 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, consultate Tipi di file multimediali su 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 API richiesta. 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) su Swagger sito web.

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 API richiesta.

  • 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 su 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 API richiesta. 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 sapere come aggiungere OpenAPI schema creato durante la creazione del gruppo di azioni, vediAggiungi un gruppo d'azione al tuo agente in Amazon Bedrock.

APISchemi di esempio

L'esempio seguente fornisce un semplice OpenAPI schema in YAML formato che ottiene le condizioni meteorologiche 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

APILo schema di esempio seguente definisce un gruppo di API operazioni che aiutano a gestire i reclami assicurativi. Tre APIs sono definite come segue:

  • getAllOpenClaims— Il tuo agente può utilizzare il description campo per determinare che debba richiamare questa API operazione 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 agente o utilizza alcune o tutte le risposte come input per API le chiamate successive.

  • identifyMissingDocuments— L'agente può utilizzare il description campo per determinare che debba avviare questa API operazione 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. responsesSpecificare di restituire i IDs reclami assicurativi aperti. properties L'agente restituisce queste informazioni all'utente finale o utilizza una parte o tutta la risposta come input per API le chiamate successive.

  • sendReminders— L'agente può utilizzare il description campo per stabilire che debba richiamare questa API operazione 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 il reclamo IDs e i documenti pendenti. 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 API chiamate 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 OpenAPI schemi, vedi https://github.com/OAI/Open API -Specification/tree/main/examples/v3.0 sul sito web. GitHub