Oracle Cloud Infrastructure-Dokumentation

Richtlinien für API-Endpunktaufruf-Tools für Generative AI Agents

Definieren Sie ein API-Endpunktaufruftool in Generative AI Agents für die Interaktion mit und den Aufruf externer Anwendungsprogrammierschnittstellen (APIs) und OCI-APIs.

Bei den Informationen in diesem Thema wird davon ausgegangen, dass Sie mit virtuellen OCI-Cloud-Netzwerken (VCNs), Subnetzen und Sicherheitsregeln, dem Deployment von Anwendungen auf OCI-Compute-Instanzen und den Grundlagen der Arbeit mit der REST-API (REpresentational State Transfer Application Programming Interface) vertraut sind.

Hier finden Sie einen Überblick über die ersten Schritte:

  1. Erstellen Sie ein OpenAPI-Schema, das die Anforderungs- und Antwortformate und verfügbaren Vorgänge definiert. Fügen Sie gegebenenfalls den x-requires-approval-Header in das Schema ein.
  2. Konfigurieren Sie eine Authentifizierungsmethode. Erstellen Sie je nach verwendetem Authentifizierungstyp ein Vault Secret für die Zugangsdaten, die Sie angeben müssen.
  3. OCI-Netzwerkressourcen einrichten. Ein virtuelles Cloud-Netz (VCN) ist erforderlich.
  4. Prüfen Sie die IAM-Policys, und fügen Sie die erforderlichen Policys hinzu. Beispiel: Networking und Vault.

API-Schema

Struktur und Verhalten der API-Vorgänge müssen in einem OpenAPI-Schema definiert sein, das in JSON oder YAML geschrieben ist.

Wenn Sie mit der Konsole ein API-Endpunktaufruftool in Generative AI Agents erstellen, können Sie das Schema manuell hochladen, indem Sie es kopieren und in ein Textfeld einfügen, oder Sie können das Schema auswählen, das in Object Storage hochgeladen wurde.

Die maximale Dateigröße und unterstützte Versionen sind:

  • Versionen:
    • OpenAPI: 3.0 und höher
    • JSON: Standard-JSON-Schema wie in RFC 8259 definiert
    • YAML: Version 1.2 und höher
  • Maximale Dateigröße:
    • Inline-Pasten: 1.000.000 Zeichen
    • Datei in Object Storage: 20 MB
Beispiel für ein API-Schema in JSON
{
  "openapi": "3.0.0",
  "info": {
    "title": "Object Storage API",
    "version": "1.0.0",
    "description": "API to create an Object Storage bucket in Oracle Cloud."
  },
  "servers": [
    {
      "url": "https://objectstorage.<region>.oraclecloud.com"
    }
  ],
  "paths": {
    "/n/yourNamespace/b": {
      "post": {
        "summary": "Create a Bucket",
        "operationId": "createBucket",
        "parameters": [
          {
            "name": "namespaceName",
            "in": "path",
            "required": true,
            "description": "The Object Storage namespace used for the request.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bucket_name": {
                    "type": "string",
                    "description": "The name of the bucket to create."
                  },
                  "compartment_ocid": {
                    "type": "string",
                    "description": "The OCID of the compartment where the bucket will be created."
                  },
                  "storage_tier": {
                    "type": "string",
                    "enum": [
                      "Standard",
                      "Archive"
                    ],
                    "description": "The storage tier for the bucket."
                  }
                },
                "required": [
                  "bucket_name",
                  "compartment_ocid"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bucket created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bucket_name": {
                      "type": "string"
                    },
                    "namespace": {
                      "type": "string"
                    },
                    "time_created": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input."
          },
          "500": {
            "description": "Internal server error."
          }
        }
      }
    }
  }
}
Beispiel für ein API-Schema in YAML
openapi: "3.0.0"
info:
	title: "Object Storage API"
	version: "1.0.0"
	description: "API to create an Object Storage bucket in Oracle Cloud."

servers:
	- url: "https://objectstorage.<region>.oraclecloud.com"

paths:
	/n/yourNamespace/b:
		post:
			summary: "Create a Bucket"
			operationId: "createBucket"
			parameters:
				- name: namespaceName
					in: path
					required: true
					description: "The Object Storage namespace used for the request."
					schema:
						type: string
			requestBody:
				required: true
				content:
					application/json:
						schema:
							type: object
							properties:
								bucket_name:
									type: string
									description: "The name of the bucket to create."
								compartment_ocid:
									type: string
									description: "The OCID of the compartment where the bucket will be created."
								storage_tier:
									type: string
									enum:
										- Standard
										- Archive
									description: "The storage tier for the bucket."
							required:
								- bucket_name
								- compartment_ocid
							additionalProperties: false
			responses:
				"200":
					description: "Bucket created successfully."
					content:
						application/json:
							schema:
								type: object
								properties:
									bucket_name:
										type: string
									namespace:
										type: string
									time_created:
										type: string
										format: date-time
				"400":
					description: "Invalid input."
				"500":
					description: "Internal server error."

Human-in-the-Loop-Genehmigung

Für API-Vorgänge, die einen Status ändern können, wird empfohlen, den x-requires-approval-Header in das Schema aufzunehmen, um anzugeben, dass eine Toolaktion eine Human-in-the-Loop-(HITL-)Genehmigung erfordert. Die Einbeziehung von Menschen in kritische Operationen wird in der Regel für die folgenden Operationstypen empfohlen, da sie möglicherweise zu ungerechtfertigten Änderungen führen können:

  • POST
  • PUT
  • PATCH
  • DELETE

Beispiel für die Aufnahme von x-requires-approval in ein YAML AI-Schema:

parameters:
  - in: header
    name: x-requires-approval
    required: false
    schema:
      type: string
    description: 
      Indicates that this operation requires human approval before execution.

Wenn Sie den x-requires-approval-Header einfügen, wird an Generative AI Agents signalisiert, dass eine Bestätigung von einem Benutzer angefordert werden muss, bevor der API-Endpunkt im Agent-Toolaufruf ausgeführt wird.

Wenn der Genehmigungsheader im Schema enthalten ist, führt der Header folgende Schritte aus:

  • Löst die erforderliche Aktion HumanApprovalRequiredAction im Trajektorienschritt aus
  • Verhindert unbeabsichtigte Nebenwirkungen ohne menschliche Aufsicht
  • Ermöglicht die sichere Verwendung von Tools, die Vorgänge zum Schreiben, Aktualisieren oder Löschen ausführen.

Authentifizierung

In Generative AI Agents kann ein API-Endpunktaufruftool so konfiguriert werden, dass Authentifizierung verwendet wird oder keine Authentifizierung verwendet wird, wenn eine Anforderung zum Ausführen eines API-Vorgangs gestellt wird.

In den folgenden Abschnitten finden Sie Informationen zu den unterstützten Authentifizierungsverfahren und den erforderlichen Aufgaben für einen Authentifizierungstyp.

API-Schlüsselauthentifizierung

Für öffentliche und private API-Endpunkte, für die ein API-Schlüssel erforderlich ist.

Ein API-Schlüssel ist eine eindeutige ID, die von der Plattform des API-Providers abgerufen wird. Wenn ein Client, wie eine Anwendung oder ein Service, eine Anforderung an die API sendet, wird der API-Schlüssel zur Authentifizierung des Clients verwendet.

In Generative AI Agents wird die API-Schlüsselauthentifizierung von den folgenden Typen unterstützt:

  • Header: Übergeben Sie den API-Schlüssel im Header einer HTTP-Anforderung.

    API-Headerparameter sind Schlüssel/Wert-Paare, die in einer HTTP-Anforderung oder -Antwort enthalten sind, um zusätzliche Metadaten über die Anforderung oder Antwort bereitzustellen.

  • Abfrageparameter: Übergeben Sie den API-Schlüssel direkt in der URL als Abfrageparameter.

    Abfrageparameter sind eine definierte Gruppe von Parametern (Schlüssel/Wert-Paaren), die an das Ende einer URL angehängt sind, um einem Webserver zusätzliche Informationen bei Anforderungen bereitzustellen.

Erstellen Sie ein Secret in OCI Vault, um den API-Schlüssel zu speichern. Wenn Sie Hilfe beim Erstellen eines Secrets benötigen, lesen Sie Secret erstellen in der Vault-Servicedokumentation.

Wenn Sie ein API-Endpunktaufruf-Tool mit API-Schlüsselauthentifizierung konfigurieren, geben Sie den Speicherort des Schlüssels (Header- oder Abfrageparameter), den Schlüsselnamen und das Vault Secret mit dem API-Schlüssel an.

Siehe auch Policys für Vault Secret.

Basisauthentifizierung

Zum Aufrufen öffentlicher und privater API-Endpunkte mit einem Benutzernamen und einem Kennwort.

Die Basisauthentifizierung verwendet Ihren Benutzernamen und Ihr Kennwort im folgenden erforderlichen Format:

<your-username>:<your-password>

Erstellen Sie ein Secret in OCI Vault, um die Zugangsdaten im erforderlichen Format zu speichern. Wenn Sie Hilfe beim Erstellen eines Secrets benötigen, lesen Sie Secret erstellen in der Vault-Servicedokumentation.

Wenn Sie ein API-Endpunktaufruftool mit Basisauthentifizierung konfigurieren, geben Sie das Vault Secret an.

Siehe auch Policys für Vault Secret.

Bearer-Authentifizierung

Zum Aufrufen privater API-Endpunkte mit einem Bearer-Token.

Ein Bearer-Token ist ein Zugriffstoken, das in der OAuth 2.0-Authentifizierung verwendet wird, um geschützte Ressourcen zu autorisieren oder ihnen Zugriff zu erteilen. Die Bearer-Authentifizierung ist eine Authentifizierungsmethode, bei der der Client ein Bearer-Token als Teil der Anforderung im Autorisierungsheader sendet, die zur Authentifizierung der Anforderung validiert wird. Es wird empfohlen, langlebige Token wie API-Schlüssel zu verwenden.

Erstellen Sie ein Secret in OCI Vault, um das Token zu speichern. Wenn Sie Hilfe beim Erstellen eines Secrets benötigen, lesen Sie Secret erstellen in der Vault-Servicedokumentation.

Wenn Sie ein API-Endpunktaufruf-Tool mit Bearer-Authentifizierung konfigurieren, geben Sie das Vault Secret an.

Siehe auch Policys für Vault Secret.

IDCS-Authentifizierung

Zum Aufrufen privater API-Endpunkte mit vertraulichen Oracle Identity Cloud Service-(IDCS-)Anwendungsclientzugangsdaten.

Eine vertrauliche Anwendung dient zur sicheren Authentifizierung und Autorisierung von Clientanwendungen unter Verwendung von OAuth 2.0. Clientzugangsdaten sind die Client-ID und das Client Secret einer vertraulichen Anwendung, die für eine Clientanwendung registriert ist.

Mit OCI IAM mit Identitätsdomains können Sie eine vertrauliche Anwendung erstellen. Beachten Sie, dass Sie die Rolle "Identitätsdomainadministrator" oder die Rolle "Anwendungsadministrator" haben müssen, um vertrauliche Anwendungen in einer Identitätsdomain zu erstellen.

So erstellen Sie eine vertrauliche Anwendung:

  1. Öffnen sie das Navigationsmenü , und wählen Sie Identität und Sicherheit aus. Wählen Sie unter Identität die Option Domains aus.
  2. Wählen Sie in der Liste der Domains in einem Compartment die Domain aus, in der Sie die vertrauliche Anwendung erstellen möchten.
  3. Erstellen und Aktivieren Sie eine vertrauliche Anwendung.

    Wählen Sie für die OAuth-Konfiguration die Clientkonfiguration aus, und verwenden Sie die Clientzugangsdaten.

    Weitere Informationen finden Sie unter Vertrauliche Anwendung erstellen in der Dokumentation für OCI IAM mit Identitätsdomains.

  4. Kopieren Sie die Client-ID und die Client Secret-Werte, die in der vertraulichen Anwendung generiert werden. Speichern Sie die Werte an einem sicheren Ort.
  5. Erstellen Sie in OCI Vault ein Secret, um das Client Secret der vertraulichen Anwendung zu speichern. Sie müssen das Vault Secret angeben, wenn Sie ein API-Endpunktaufruftool mit IDCS-Authentifizierung konfigurieren.
    Hinweis

    Regionsübergreifende Aufrufe aus dem Agent-Servicemandanten werden nicht unterstützt. Beispiel: Wenn sich das API-Endpunktaufruftool, das mit IDCS-Authentifizierung konfiguriert ist, in Region A befindet, sollten Sie keinen Vault mit Masterregion B auswählen.

    Wenn Sie Hilfe beim Erstellen eines Secrets benötigen, lesen Sie Secret erstellen in der Vault-Servicedokumentation.

    Siehe auch Policys für Vault Secret.

OCI Resource-Principal-Authentifizierung

Nur zum Aufrufen von OCI-APIs wie Object Storage und Networking.

Mit einem Resource Principal können sich Services sicher mit OCI- und OCI-Serviceressourcen authentifizieren, ohne dass explizite Zugangsdaten erforderlich sind. OCI-IAM-Policys werden zur Authentifizierung des Zugriffs verwendet. Beispiel:

// To enable Object Storage access in all compartments in the tenancy
allow any-user to manage object-family in tenancy where any {request.principal.type='genaiagent'}

Die von Ihnen erstellten IAM-Policys hängen von den OCI-Service-APIs ab, die Sie aufrufen, und davon, ob Sie eine dynamische Gruppe verwenden. Siehe Policys für OCI-Services.

Netzwerkressourcen

Wenn Sie ein API-Endpunktaufruftool in Generative AI Agents erstellen, müssen Sie ein virtuelles Cloud-Netzwerk (VCN) und ein Subnetz auswählen.

Unabhängig davon, ob die Ziel-URL privat oder öffentlich ist, werden alle Anforderungen von API-Endpunktaufruf-Tools über Ihr Subnetz weitergeleitet. Dazu gehören REST-Aufrufe an Drittanbieter, interne Services, die in Ihrem VCN gehostet werden, und öffentliche OCI-APIs.

Richten Sie die erforderlichen Netzwerkressourcen in OCI ein.

VCN und Subnetz

  • Ein virtuelles Cloud-Netz (VCN) ist erforderlich.

  • Sie können ein privates oder öffentliches Subnetz verwenden. Ein privates Subnetz wird empfohlen.

  • Ein privates Subnetz erfordert ein NAT-Gateway.

  • Ein öffentliches Subnetz erfordert ein Internetgateway. Je nach Umgebungssetup erfordert ein öffentliches Subnetz möglicherweise ein Internetgateway und ein NAT-Gateway.

    Stellen Sie zum Aufrufen öffentlicher APIs ohne Authentifizierung sicher, dass das öffentliche Subnetz für ein NAT-Gateway eingerichtet ist, bei dem der gesamte Porttraffic für Egress aktiviert ist.

API-Gateway für privates DNS

Ein API-Gateway kann für den Traffic zu Anwendungen auf privaten Instanzen erstellt werden.

Wählen Sie den privaten Typ aus, wenn Sie das API-Gateway für ein privates DNS erstellen.

Stellen Sie im privaten Subnetz sicher, dass diese beiden Egress-Regeln verfügbar sind:

  • Port 443 wird vom API-Gateway für die Kommunikation verwendet.
  • Der Port, an dem die private Anwendung gehostet wird. Das API-Gateway sendet eine Anforderung an diesen Port (Beispiel: 9090).

Wenn Sie die IDCS-Authentifizierung mit privaten Endpunkten verwenden, müssen Sie die Basis-URL durch die API-Gateway-Service-URL im Schema OpenAPI ersetzen. Das API-Gateway muss auf die Instanz verweisen, die in einem privaten Subnetz ausgeführt wird.

Setup von privatem Netzwerk
VCN:

  • Erstellen Sie ein VCN in der gewünschten Region und im gewünschten Compartment.

  • Geben Sie den CIDR-Block für das VCN an (Beispiel: 10.0.0.0/16).

  • Sie können die DNS-Auflösung für das VCN aktivieren.

Privates Subnetz:

  • Erstellen Sie ein privates Subnetz in dem von Ihnen erstellten VCN, und wählen Sie dasselbe Compartment wie das VCN aus.

  • Geben Sie den CIDR-Block für das Subnetz an (Beispiel: 10.0.1.0/24).

  • Sie können die DNS-Auflösung für das Subnetz aktivieren.

Private Compute-Instanz:

  • Erstellen Sie im selben Compartment wie das VCN und Subnetz eine private Compute-Instanz, und wählen Sie das von Ihnen erstellte VCN und private Subnetz aus.

  • Wenn Sie über SSH auf die Instanz zugreifen möchten, geben Sie den SSH-Public Key an.

Egress-Regeln:

  • Ausgehende Verbindungen zu erforderlichen Services zulassen (z.B. Object Storage, externe APIs, falls erforderlich).

  • Öffnen Sie den TCP-Port 443 für HTTPS.

Ingress-Regeln:

  • Lassen Sie eingehenden Traffic nur aus den OCI-Plattform-IP-Bereichen zu.

  • Begrenzen Sie die Ports (in der Regel TCP 443).

Ingress-UDP-Regel:

  • Fügen Sie eine Ingress-Regel für den UDP-Port 53 hinzu.

    Fügen Sie die UDP-Regel zur Standardsicherheitsliste des Agent-Service und Ihrer (Kunden-)VCN-Subnetze hinzu, um DNS-Umleitung und -Auflösung zu ermöglichen.

Setup für öffentliches Netzwerk

Richten Sie ähnliche Ingress- und Egress-Einschränkungen ein, die jedoch dem Internet ausgesetzt sind. Verwenden Sie strenge Access Control-Listen (ACLs).

DNS-Auflösung

So vereinfachen Sie die DNS-Auflösung für private Anwendungen:

  • Lassen Sie den UDP-Port 53 in Ihren Firewall-/Sicherheitslisten für DNS-Traffic zu.

  • Konfigurieren Sie die DNS-Weiterleitung/Regeln, um Traffic an Ihre privaten Anwendungsendpunkte zu leiten.

  • Stellen Sie sicher, dass der Ingress-UDP-Port 53 sowohl im Agent-Service als auch in den Sicherheitslisten des (Kunden-)VCN-Subnetzes geöffnet ist.

Stellen Sie sicher, dass die OCI-Plattform die Domainnamen auflösen kann, die mit Ihren privaten Anwendungen verknüpft sind.

Netzwerkreferenzdokumentation

Wenn Sie Hilfe benötigen, lesen Sie die folgende Servicedokumentation:

IAM-Policys

Stellen Sie sicher, dass Sie Benutzern Zugriff auf alle Generative AI Agents-Ressourcen erteilen, wie unter Policys hinzufügen, bevor Sie den Service verwenden können beschrieben.

Prüfen Sie auch die folgenden Abschnitte, und schreiben Sie die erforderlichen Policys.

Policys für Networking

Die Policy für den aggregierten Ressourcentyp virtual-network-family ist erforderlich.

Mit den folgenden Policys können Sie den Zugriff auf Networking in allen Compartments im Mandanten aktivieren oder den Zugriff auf ein bestimmtes Compartment einschränken. 

// To enable access to all compartments in the tenancy
allow group <group-name> to manage virtual-network-family in tenancy 

// To enable access to a specific compartment in the tenancy
allow group <group-name> to manage virtual-network-family in compartment <compartment-name>
Richtlinien für OCI Services

Wenn Sie ein API-Endpunktaufruftool erstellen und das Tool für die Verwendung der OCI-Resource-Principal-Authentifizierung konfigurieren, müssen Sie Policys hinzufügen, um die entsprechenden Berechtigungen für den Zugriff auf die API-Vorgänge des OCI-Service zu erteilen, die der Agent aufrufen soll.

Referenz: Detaillierte Service-Policy-Referenz in IAM mit Identitätsdomains

Die erforderlichen OCI-IAM-Policys hängen von den OCI-Service-APIs ab, die Sie aufrufen, und davon, ob Sie eine dynamische Gruppe verwenden.

Dynamische Gruppe verwenden

  1. Erstellen Sie eine dynamische Gruppe, und fügen Sie die folgende Vergleichsregel hinzu.

    ALL {resource.type='genaiagent'}

    Weitere Informationen finden Sie unter Dynamische Gruppe erstellen.

  2. Fügen Sie eine Policy hinzu, um der dynamischen Gruppe die entsprechende Zugriffsebene für einen Ressourcentyp zu erteilen. Beispiel: Um die Object Storage-Service-APIs aufzurufen, können Sie manage object-family oder read objects verwenden.

    • Die folgenden Policys können mit der Standardidentitätsdomain verwendet werden:

      allow dynamic-group <dynamic-group-name> 
to <verb> <resource type> in compartment <compartment-name>

allow dynamic-group <dynamic-group-name> 
to <verb> <resource type> in tenancy

    • Verwenden Sie die folgenden Policys mit einer Identitätsdomain, die nicht der Standard ist und den Oracle Identity Cloud Service-(IDCS-)Domainnamen und den Namen der dynamischen Gruppe angibt: 

      allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to <verb> <resource type> in compartment <compartment-name>

allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to <verb> <resource type> in tenancy

Ohne dynamische Gruppe

Fügen Sie eine Policy hinzu, um die entsprechende Zugriffsebene für einen Ressourcentyp zu erteilen. Beispiel: Um die Object Storage-Service-APIs aufzurufen, können Sie manage object-family oder read objects verwenden.

allow any-user to <verb> <resource type> in tenancy where any {request.principal.type='genaiagent'}

Policys für Vault Secret

Bei der verwendeten Authentifizierungsmethode müssen Sie möglicherweise Zugangsdaten angeben, die in einem OCI Vault Secret gespeichert sind.

Die IAM-Policy für den Zugriff auf Vault Secrets hängt davon ab, ob Sie eine dynamische Gruppe verwenden.

Dynamische Gruppe verwenden

  1. Erstellen Sie eine dynamische Gruppe, und fügen Sie die folgende Vergleichsregel hinzu.

    ALL {resource.type='genaiagent'}

    Weitere Informationen finden Sie unter Dynamische Gruppe erstellen.

  2. Die folgenden Policys können mit der Standardidentitätsdomain verwendet werden:

    • allow dynamic-group <dynamic-group-name> 
to read secret-family in compartment <compartment-name>

allow dynamic-group <dynamic-group-name> 
to read secret-family in tenancy

    • Verwenden Sie die folgenden Policys mit einer Identitätsdomain, die nicht der Standard ist und den Oracle Identity Cloud Service-(IDCS-)Domainnamen und den Namen der dynamischen Gruppe angibt: 

      allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to read secret-family in compartment <compartment-name>

allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to read secret-family in tenancy

Ohne dynamische Gruppe

Die folgende Policy kann verwendet werden.

allow any-user to read secret-family in tenancy where any {request.principal.type='genaiagent'}