Documentación de Oracle Cloud Infrastructure

Directrices de la herramienta de llamadas de punto final de API para agentes de IA generativa

Defina una herramienta de llamada de punto final de API en agentes de IA generativa para interactuar y llamar a interfaces de programación de aplicaciones (API) externas y API de OCI.

La información proporcionada en este tema supone que está familiarizado con las redes virtuales en la nube (VCN), las subredes y las reglas de seguridad de OCI, cómo desplegar aplicaciones en instancias informáticas de OCI y los conceptos fundamentales de trabajar con la interfaz de programación de aplicaciones (API de REST) de REpresentational State Transfer.

A continuación, se muestra una descripción general de cómo empezar:

  1. Cree un esquema OpenAPI que defina los formatos de solicitud y respuesta y las operaciones disponibles. Incluya la cabecera x-requires-approval en el esquema, si es necesario.
  2. Configurar un método de autenticación. Según el tipo de autenticación que utilice, cree un secreto de almacén para las credenciales que necesite proporcionar.
  3. Configurar recursos de red de OCI. Se necesita una red virtual en La nube (VCN).
  4. Revise las políticas de IAM y agregue las que sean necesarias. Por ejemplo, Networking y Vault.

Esquema de API

La estructura y el comportamiento de las operaciones de API se deben definir en un esquema OpenAPI que esté escrito en JSON o en YAML.

Al utilizar la consola para crear una herramienta de llamada de punto final de API en agentes de IA generativa, puede cargar el esquema manualmente copiando y pegando en un cuadro de texto, o bien puede seleccionar el esquema que se ha cargado en Object Storage.

El tamaño máximo de archivo y las versiones soportadas son:

  • Versiones:
    • OpenAPI: 3.0 y posterior
    • JSON: esquema JSON estándar según se define en RFC 8259
    • YAML: versión 1.2 y posterior
  • Tamaño máximo de archivo:
    • Pegado en línea: 1.000.000 caracteres
    • Archivo en Object Storage: 20 MB
Ejemplo de un esquema de API en 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."
          }
        }
      }
    }
  }
}
Ejemplo de esquema de API en 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."

Aprobación Human-in-the-Loop

Para las operaciones de API que pueden cambiar un estado, se recomienda incluir la cabecera x-requires-approval en el esquema para indicar que una acción de herramienta requiere la aprobación de Human-in-the-loop (HITL). Por lo general, se recomienda la participación de personas en operaciones críticas para los siguientes tipos de operaciones, ya que podrían causar cambios injustificados:

  • POST
  • PUT
  • PATCH
  • DELETE

Ejemplo de inclusión de x-requires-approval en un esquema AI de YAML:

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

Al incluir la cabecera x-requires-approval, se indica a los agentes de IA generativa que se debe solicitar una confirmación a un humano antes de ejecutar el punto final de API en la llamada a la herramienta del agente.

Cuando la cabecera de aprobación se incluye en el esquema, la cabecera:

  • Dispara la acción necesaria HumanApprovalRequiredAction en el paso de trayectoria
  • Evita los efectos secundarios no deseados sin supervisión humana
  • Permite el uso seguro de herramientas que realizan operaciones de escritura, actualización o supresión.

Autenticación

En los agentes de IA generativa, se puede configurar una herramienta de llamada de punto final de API para que utilice la autenticación o no utilice la autenticación al realizar una solicitud para ejecutar una operación de API.

Consulte las siguientes secciones para obtener información sobre los mecanismos de autenticación admitidos y las tareas previas necesarias que debe realizar para un tipo de autenticación.

Autenticación de clave de API

Para puntos finales de API públicos y privados que requieren una clave de API.

Una clave de API es un identificador único obtenido de la plataforma del proveedor de API. Cuando un cliente, como una aplicación o un servicio, realiza una solicitud a la API, la clave de API se utiliza para autenticar el cliente.

En los agentes de IA generativa, la autenticación de claves de API está soportada por los siguientes tipos:

  • Encabezado: transfiera la clave de API en la cabecera de una solicitud HTTP.

    Los parámetros de cabecera de API son pares clave-valor incluidos en una solicitud o respuesta HTTP para proporcionar metadatos adicionales sobre la solicitud o respuesta.

  • Parámetro de consulta: transfiera la clave de API directamente en la URL como parámetro de consulta.

    Los parámetros de consulta son un juego definido de parámetros (pares clave-valor) asociados al final de una URL que se utiliza para proporcionar información adicional a un servidor web al realizar solicitudes.

Cree un secreto en OCI Vault para almacenar la clave de API. Si necesita ayuda para crear un secreto, consulte Creación de un secreto en la documentación del servicio Vault.

Al configurar una herramienta de llamada de punto final de API con autenticación de clave de API, se especifica la ubicación de la clave (parámetro de cabecera o consulta), el nombre de la clave y el secreto de almacén que tiene la clave de API.

Consulte también Políticas para secreto de almacén.

Autenticación Básica

Para llamar a puntos finales de API públicos y privados mediante un nombre de usuario y una contraseña.

La autenticación básica utiliza sus credenciales de nombre de usuario y contraseña en el siguiente formato necesario:

<your-username>:<your-password>

Cree un secreto en OCI Vault para almacenar las credenciales en el formato necesario. Si necesita ayuda para crear un secreto, consulte Creación de un secreto en la documentación del servicio Vault.

Cuando configura una herramienta de llamada de punto final de API con autenticación básica, proporciona el secreto de almacén.

Consulte también Políticas para secreto de almacén.

Autenticación del portador

Para llamar a puntos finales de API privados mediante un token de portador.

Un token de portador es un token de acceso utilizado en la autenticación OAuth 2.0 para autorizar u otorgar acceso a recursos protegidos. La autenticación de portador es un método de autenticación en el que el cliente envía un token de portador como parte de la solicitud en el encabezado Autorización, que se valida para autenticar la solicitud. Recomendamos utilizar tokens de larga duración, como claves de API.

Cree un secreto en OCI Vault para almacenar el token. Si necesita ayuda para crear un secreto, consulte Creación de un secreto en la documentación del servicio Vault.

Cuando configura una herramienta de llamada de punto final de API con autenticación de portador, proporciona el secreto de almacén.

Consulte también Políticas para secreto de almacén.

Autenticación IDCS

Para llamar a puntos finales de API privados mediante las credenciales confidenciales de cliente de aplicación de Oracle Identity Cloud Service (IDCS).

Una aplicación confidencial está diseñada para autenticar y autorizar de forma segura las aplicaciones cliente mediante OAuth 2.0. Las credenciales de cliente son el ID de cliente y el secreto de cliente de una aplicación confidencial que está registrada para una aplicación cliente.

Utilice OCI IAM con dominios de identidad para crear una aplicación confidencial. Tenga en cuenta que debe tener el rol de administrador de dominio de identidad o el rol de administrador de aplicaciones para crear aplicaciones confidenciales en un dominio de identidad.

Para crear una aplicación confidencial:

  1. Abra el menú de navegación y seleccione Identidad y seguridad. En Identidad, seleccione Dominios.
  2. En la lista de dominios de un compartimento, seleccione el dominio en el que desea crear la aplicación confidencial.
  3. Cree y active una aplicación confidencial.

    Para la configuración OAuth, seleccione Configuración de cliente y utilice credenciales de cliente.

    Si necesita ayuda, consulte Creación de una aplicación confidencial en la documentación de OCI IAM con dominios de identidad.

  4. Copie los valores de ID de cliente y secreto de cliente que se generan en la aplicación confidencial. Almacene los valores en un lugar seguro.
  5. En OCI Vault, cree un secreto para almacenar el secreto de cliente de la aplicación confidencial. Debe proporcionar el secreto de almacén al configurar una herramienta de llamada de punto final de API con autenticación de IDCS.
    Nota

    Las llamadas entre regiones desde el arrendamiento del servicio de agente no están soportadas. Por ejemplo, si la herramienta de llamada de punto final de API que está configurada con autenticación de IDCS está en la región A, no debe seleccionar un almacén con la región maestra B.

    Si necesita ayuda para crear un secreto, consulte Creación de un secreto en la documentación del servicio Vault.

    Consulte también Políticas para secreto de almacén.

Autenticación de entidad de recurso de OCI

Solo para llamar a API de OCI como Object Storage y Networking.

Una entidad de recurso permite a los servicios autenticarse de forma segura con los recursos de servicio de OCI y OCI sin necesidad de credenciales explícitas. Las políticas de OCI IAM se utilizan para autenticar el acceso. Por ejemplo:

// 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'}

Las políticas de IAM que escriba dependen de las API del servicio OCI que esté llamando y de si está utilizando un grupo dinámico. Consulte Políticas de servicios de OCI.

Recursos de red

Al crear una herramienta de llamada de punto final de API en agentes de IA generativa, debe seleccionar una red virtual en la nube (VCN) y una subred.

Independientemente de si la URL de destino es privada o pública, todas las solicitudes realizadas por las herramientas de llamada de punto final de API se enrutan a través de la subred. Esto incluye llamadas REST a proveedores de terceros, servicios internos alojados en la VCN y API públicas de OCI.

Configure los recursos de red que necesita en OCI.

VCN y subred

  • Se necesita una red virtual en La nube (VCN).

  • Puede tener una subred privada o pública. Se recomienda una subred privada.

  • Una subred privada necesita un gateway de NAT.

  • Una subred pública necesita un gateway de Internet. En función de la configuración del entorno, una subred pública puede necesitar un gateway de Internet y un gateway de NAT.

    Para llamar a las API públicas sin autenticación, asegúrese de que la subred pública esté configurada para un gateway de NAT con todo el tráfico de puerto activado para la salida.

Gateway de API para DNS privado

Se puede crear un gateway de API para el tráfico a aplicaciones en instancias privadas.

Seleccione el tipo Privado al crear el gateway de API para un DNS privado.

En la subred privada, asegúrese de que estas dos reglas de salida están disponibles:

  • El gateway de API utiliza el puerto 443 para la comunicación.
  • Puerto donde se aloja la aplicación privada. El gateway de API envía la solicitud a este puerto (por ejemplo, 9090).

Al utilizar la autenticación de IDCS con puntos finales privados, asegúrese de sustituir la URL base por la URL del servicio API Gateway en el esquema OpenAPI. El gateway de API debe apuntar a la instancia que se ejecuta en una subred privada.

Configuración de red privada
VCN:

  • Cree una VCN en la región y el compartimento que desee.

  • Especifique el bloque de CIDR para la VCN (por ejemplo, 10.0.0.0/16).

  • Puede activar la resolución de DNS para la VCN.

Subred privada:

  • Cree una subred privada en la VCN que ha creado y seleccione el mismo compartimento que la VCN.

  • Especifique el bloque de CIDR para la subred (por ejemplo, 10.0.1.0/24).

  • Puede activar la resolución de DNS para la subred.

Instancia informática privada:

  • En el mismo compartimento que la VCN y la subred, cree una instancia informática privada, seleccionando la VCN y la subred privada que ha creado.

  • Si desea acceder a la instancia mediante SSH, proporcione la clave pública SSH.

Reglas de salida:

  • Permitir conexiones salientes a los servicios necesarios (por ejemplo, Object Storage, API externas, si es necesario).

  • Abra el puerto TCP 443 para HTTPS.

Reglas de entrada:

  • Permitir el tráfico entrante solo desde los rangos de IP de la plataforma OCI.

  • Restrinja a los puertos necesarios (normalmente TCP 443).

Regla UDP de entrada:

  • Agregue una regla de entrada para el puerto UDP 53.

    Agregue la regla UDP a la lista de seguridad por defecto del servicio de agente y sus subredes de VCN (cliente) para permitir la redirección y resolución de DNS.

Configuración de red pública

Establezca restricciones similares de entrada y salida, pero expuestas a Internet. Utilización de listas de control de accesos (ACL) estrictas.

Resolución de DNS

Para facilitar la resolución de DNS para aplicaciones privadas:

  • Permitir el puerto UDP 53 en las listas de firewall/seguridad para el tráfico DNS.

  • Configure el reenvío/reglas de DNS para dirigir el tráfico a los puntos finales de la aplicación privada.

  • Asegúrese de que el puerto UDP de entrada 53 esté abierto tanto en el servicio de agente como en las listas de seguridad de la subred de la VCN (cliente).

Asegúrese de que la plataforma OCI pueda resolver los nombres de dominio asociados a sus aplicaciones privadas.

Documentación de referencia de red

Si necesita ayuda, consulte la siguiente documentación de servicio:

Políticas de IAM

Asegúrese de otorgar a los usuarios acceso a todos los recursos de agentes de IA generativa, como se describe en Adición de políticas antes de que pueda utilizar el servicio.

Revise también las siguientes secciones y escriba las políticas que necesita.

Políticas para Networking

Se necesita la política para el tipo de recurso agregado virtual-network-family.

Puede utilizar las siguientes políticas para activar el acceso a las redes en todos los compartimentos del arrendamiento o restringir el acceso a un compartimento específico. 

// 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>
Políticas para servicios de OCI

Al crear una herramienta de llamada de punto final de API y configurar la herramienta para utilizar la autenticación de entidad de recurso de OCI, debe agregar políticas para otorgar los permisos adecuados para acceder a las operaciones de API del servicio de OCI a las que desea que llame el agente.

Referencia: Referencia detallada de políticas de servicio en IAM con dominios de identidad

Las políticas de OCI IAM que necesita dependen de las API de servicio de OCI que está llamando y de si está utilizando un grupo dinámico.

Usar grupo dinámico

  1. Cree un grupo dinámico y agregue la siguiente regla de coincidencia.

    ALL {resource.type='genaiagent'}

    Si necesita ayuda, consulte Creación de un grupo dinámico.

  2. Agregue una política para proporcionar al grupo dinámico el nivel adecuado de acceso a un tipo de recurso. Por ejemplo, para llamar a las API del servicio Object Storage, puede utilizar manage object-family o read objects.

    • Las siguientes políticas se pueden utilizar con el dominio de identidad por defecto:

      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

    • Utilice las siguientes políticas con un dominio de identidad no por defecto, que proporciona el nombre de dominio de Oracle Identity Cloud Service (IDCS) y el nombre de grupo dinámico: 

      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

Sin usar grupo dinámico

Agregue una política para proporcionar el nivel adecuado de acceso a un tipo de recurso. Por ejemplo, para llamar a las API del servicio Object Storage, puede utilizar manage object-family o read objects.

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

Políticas para secreto de almacén

El método de autenticación que utilice puede requerir que proporcione una credencial almacenada en un secreto de OCI Vault.

La política de IAM para acceder a los secretos del almacén depende de si está utilizando un grupo dinámico.

Usar grupo dinámico

  1. Cree un grupo dinámico y agregue la siguiente regla de coincidencia.

    ALL {resource.type='genaiagent'}

    Si necesita ayuda, consulte Creación de un grupo dinámico.

  2. Las siguientes políticas se pueden utilizar con el dominio de identidad por defecto:

    • 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

    • Utilice las siguientes políticas con un dominio de identidad no por defecto, que proporciona el nombre de dominio de Oracle Identity Cloud Service (IDCS) y el nombre de grupo dinámico: 

      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

Sin usar grupo dinámico

Se puede utilizar la siguiente política.

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