Documentação do Oracle Cloud Infrastructure

Diretrizes da Ferramenta de Chamada do Ponto Final da API para Agentes de IA Generativa

Defina uma ferramenta de chamada de ponto final de API em Generative AI Agents para interagir e chamar interfaces de programação de aplicativos (APIs) externas e APIs do OCI.

As informações fornecidas neste tópico pressupõem que você esteja familiarizado com as redes virtuais na nuvem (VCNs), sub-redes e regras de segurança do OCI, como implantar aplicativos em instâncias de computação do OCI e os fundamentos do trabalho com a API REST (REpresentational State Transfer Application Programming Interface).

Veja uma visão geral de como começar:

  1. Crie um esquema OpenAPI que defina os formatos de solicitação e resposta e as operações disponíveis. Inclua o cabeçalho x-requires-approval no esquema, se necessário.
  2. Configure um método de autenticação. Dependendo do tipo de autenticação usado, crie um segredo do vault para as credenciais que você precisa fornecer.
  3. Configurar recursos de rede do OCI. É necessária uma VCN (Rede Virtual Na Nuvem).
  4. Verifique as políticas do IAM e adicione as necessárias. Por exemplo, Rede e Vault.

Esquema da API

A estrutura e o comportamento das operações de API devem ser definidos em um esquema OpenAPI que seja gravado em JSON ou YAML.

Ao usar a Console para criar uma ferramenta de chamada de ponto final de API em Agentes de IA Generativa, você pode fazer upload do esquema manualmente copiando e colando em uma caixa de texto ou pode selecionar o esquema que foi submetido a upload para o Object Storage.

O tamanho máximo do arquivo e as versões suportadas são:

  • Versões:
    • OpenAPI: 3.0 e posterior
    • JSON: Esquema JSON padrão conforme definido na RFC 8259
    • YAML: versão 1.2 e posterior
  • Tamanho máximo do arquivo:
    • Colagem em linha: 1.000.000 caracteres
    • Arquivo no Object Storage: 20 MB
Exemplo de um esquema de API no 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."
          }
        }
      }
    }
  }
}
Exemplo de um esquema de API no 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."

Aprovação Human-in-the-Loop

Para operações de API que podem alterar um estado, recomendamos incluir o cabeçalho x-requires-approval no esquema para indicar que uma ação de ferramenta requer aprovação HITL (human-in-the-loop). Envolver seres humanos em operações críticas é geralmente recomendado para os seguintes tipos de operação, porque eles podem potencialmente causar mudanças injustificadas:

  • POST
  • PUT
  • PATCH
  • DELETE

Exemplo de inclusão de x-requires-approval em um esquema de IA YAML:

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

Incluindo os sinais de cabeçalho x-requires-approval para Agentes de IA Generativa de que uma confirmação deve ser solicitada a um ser humano antes de executar o ponto final da API na chamada de ferramenta do agente.

Quando o cabeçalho de aprovação é incluído no esquema, o cabeçalho:

  • Triggers a ação necessária HumanApprovalRequiredAction na etapa da trajetória
  • Evita efeitos colaterais não intencionais sem supervisão humana
  • Permite o uso seguro de ferramentas que executam operações que gravam, atualizam ou excluem.

Autenticação

Em Generative AI Agents, uma ferramenta de chamada de ponto final de API pode ser configurada para usar autenticação ou não usar autenticação ao fazer uma solicitação para executar uma operação de API.

Consulte as seções a seguir para obter informações sobre os mecanismos de autenticação suportados e as tarefas de pré-requisito que você deve executar para um tipo de autenticação.

Autenticação de Chave de API

Para pontos finais de API públicos e privados que exigem uma chave de API.

Uma chave de API é um identificador exclusivo obtido da plataforma do provedor de API. Quando um cliente, como um aplicativo ou serviço, faz uma solicitação à API, a chave da API é usada para autenticar o cliente.

Em Generative AI Agents, a autenticação de chave de API é suportada pelos seguintes tipos:

  • Cabeçalho: Informe a chave de API no cabeçalho de uma solicitação HTTP.

    Os parâmetros de cabeçalho da API são pares de chave/valor incluídos em uma solicitação ou resposta HTTP para fornecer metadados adicionais sobre a solicitação ou resposta.

  • Parâmetro de consulta: passe a chave de API diretamente no URL como um parâmetro de consulta.

    Parâmetros de consulta são um conjunto definido de parâmetros (pares de chave/valor) anexados ao final de um URL usado para fornecer informações adicionais a um servidor Web ao fazer solicitações.

Criar um segredo no OCI Vault para armazenar a chave de API. Se precisar de ajuda para criar um segredo, consulte Criando um Segredo na documentação do serviço Vault.

Ao configurar uma ferramenta de chamada de ponto final de API com autenticação de chave de API, você especifica a localização da chave (parâmetro de cabeçalho ou consulta), o nome da chave e o segredo do vault que tem a chave de API.

Consulte também Políticas para o Segredo do Vault.

Autenticação Básica

Para chamar pontos finais de API públicos e privados usando um nome de usuário e uma senha.

A autenticação básica usa suas credenciais de nome de usuário e senha no seguinte formato obrigatório:

<your-username>:<your-password>

Crie um segredo no OCI Vault para armazenar as credenciais no formato necessário. Se precisar de ajuda para criar um segredo, consulte Criando um Segredo na documentação do serviço Vault.

Ao configurar uma ferramenta de chamada de ponto final de API com autenticação básica, você fornece o segredo do vault.

Consulte também Políticas para o Segredo do Vault.

Autenticação do portador

Para chamar pontos finais de API privados usando um token do portador.

Um token de portador é um token de acesso usado na autenticação do OAuth 2.0 para autorizar ou conceder acesso a recursos protegidos. A autenticação do portador é um método de autenticação em que o cliente envia um token do portador como parte da solicitação no cabeçalho Autorização, que é validado para autenticar a solicitação. Recomendamos o uso de tokens de longa duração, como chaves de API.

Criar um segredo no OCI Vault para armazenar o token. Se precisar de ajuda para criar um segredo, consulte Criando um Segredo na documentação do serviço Vault.

Ao configurar uma ferramenta de chamada de ponto final de API com autenticação de portador, você fornece o segredo do vault.

Consulte também Políticas para o Segredo do Vault.

Autenticação IDCS

Para chamar pontos finais de API privados usando credenciais de cliente de aplicativo confidencial do Oracle Identity Cloud Service (IDCS).

Um aplicativo confidencial foi projetado para autenticar e autorizar com segurança aplicativos cliente usando o OAuth 2.0. As credenciais do cliente são o ID do cliente e o segredo do cliente de um aplicativo confidencial registrado para um aplicativo cliente.

Usar o OCI IAM com Domínios de Identidade para criar um aplicativo confidencial. Observe que você deve ter a atribuição Administrador do Domínio de Identidades ou Administrador do Aplicativo para criar aplicativos confidenciais em um domínio de identidades.

Para criar um aplicativo confidencial:

  1. Abra o menu de navegação e selecione Identidade e Segurança. Em Identidade, selecione Domínios.
  2. Na lista de domínios em um compartimento, selecione o domínio no qual você deseja criar o aplicativo confidencial.
  3. Crie e ative um aplicativo confidencial.

    Para a configuração OAuth, selecione a configuração do Cliente e use as credenciais do Cliente.

    Se precisar de ajuda, consulte Criando um Aplicativo Confidencial na documentação do OCI IAM com Domínios de Identidade.

  4. Copie o ID do cliente e os valores de segredo do cliente que são gerados no aplicativo confidencial. Armazene os valores em um local seguro.
  5. No OCI Vault, crie um segredo para armazenar o segredo do cliente do aplicativo confidencial. Você deve fornecer o segredo do vault ao configurar uma ferramenta de chamada de ponto final de API com autenticação IDCS.
    Observação

    Não há suporte para chamadas entre regiões da tenancy do serviço do agente. Por exemplo, se a ferramenta de chamada de ponto final de API configurada com autenticação do IDCS estiver na região A, você não deverá selecionar um vault com a região mestre B.

    Se precisar de ajuda para criar um segredo, consulte Criando um Segredo na documentação do serviço Vault.

    Consulte também Políticas para o Segredo do Vault.

Autenticação do Controlador de Recursos do OCI

Somente para chamar APIs do OCI, como Armazenamento de Objetos e Rede.

Um controlador de recursos permite que os serviços sejam autenticados com segurança com recursos de serviço do OCI e do OCI sem exigir credenciais explícitas. As políticas do OCI IAM são usadas para autenticar o acesso. Por exemplo:

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

As políticas do IAM que você escreve dependem das APIs de serviço do OCI que você está chamando e se você está usando um grupo dinâmico. Consulte Políticas para Serviços OCI.

Recursos de Rede

Ao criar uma ferramenta de chamada de ponto final de API em Agentes de IA Generativa, você deve selecionar uma rede virtual na nuvem (VCN) e uma sub-rede.

Independentemente de o URL de destino ser privado ou público, todas as solicitações feitas pelas ferramentas de chamada do ponto final da API são roteadas por meio da sua sub-rede. Isso inclui chamadas REST para provedores de terceiros, serviços internos hospedados na sua VCN e APIs públicas do OCI.

Configure os recursos de rede necessários no OCI.

VCN e Sub-rede

  • É necessária uma VCN (Rede Virtual Na Nuvem).

  • Você pode ter uma sub-rede privada ou pública. É recomendável uma sub-rede privada.

  • Uma sub-rede privada requer um gateway NAT.

  • Uma sub-rede pública requer um gateway de Internet. Dependendo da configuração do seu ambiente, uma sub-rede pública poderá exigir um gateway de Internet e um gateway NAT.

    Para chamar APIs públicas sem autenticação, certifique-se de que a sub-rede pública esteja configurada para um gateway NAT com todo o tráfego de porta ativado para saída.

Gateway de API para DNS Privado

Um gateway de API pode ser criado para tráfego para aplicativos em instâncias privadas.

Selecione o tipo Privado ao criar o gateway de API para um DNS privado.

Na sub-rede privada, certifique-se de que estas duas regras de saída estejam disponíveis:

  • A porta 443 é usada pelo gateway de API para comunicação.
  • A porta na qual o aplicativo privado está hospedado. O gateway de API envia a solicitação para essa porta (por exemplo, 9090).

Ao usar a autenticação do IDCS com pontos finais privados, certifique-se de substituir o URL base pelo URL do serviço API Gateway no esquema OpenAPI. O gateway de API deve apontar para a instância em execução em uma sub-rede privada.

Configuração de Rede Privada
VCN:

  • Crie uma VCN na região e no compartimento desejados.

  • Especifique o bloco CIDR da VCN (por exemplo, 10.0.0.0/16).

  • Você pode optar por ativar a resolução de DNS para a VCN.

Sub-rede privada:

  • Crie uma sub-rede privada na VCN que você criou, selecionando o mesmo compartimento da VCN.

  • Especifique o bloco CIDR da sub-rede (por exemplo, 10.0.1.0/24).

  • Você pode optar por ativar a resolução de DNS para a sub-rede.

Instância de Computação Privada:

  • No mesmo compartimento da VCN e da sub-rede, crie uma instância privada do serviço Compute, selecionando a VCN e a sub-rede privada que você criou.

  • Se quiser acessar a instância por SSH, forneça sua chave pública SSH.

Regras de saída:

  • Permita conexões de saída com serviços necessários (por exemplo, Object Storage, APIs externas, se necessário).

  • Abra a porta TCP 443 para HTTPS.

Regras de entrada:

  • Permitir tráfego de entrada somente dos intervalos de IPs da plataforma OCI.

  • Restrinja às portas necessárias (geralmente TCP 443).

Regra UDP de entrada:

  • Adicione uma regra de entrada para a porta UDP 53.

    Adicione a regra UDP à lista de segurança padrão do serviço do agente e suas sub-redes de VCN (cliente) para permitir o redirecionamento e a resolução de DNS.

Configuração de Rede Pública

Configure restrições de Entrada e Saída semelhantes, mas expostas à Internet. Use listas de controle de acesso estrito (ACLs).

Resolução de DNS

Para facilitar a resolução de DNS para aplicativos privados:

  • Permita a porta UDP 53 em suas listas de firewall/segurança para tráfego de DNS.

  • Configure o encaminhamento/regras de DNS para direcionar o tráfego para seus pontos finais de aplicativos privados.

  • Certifique-se de que a porta UDP de Entrada 53 esteja aberta nas listas de segurança de sub-rede da VCN do serviço do agente e do cliente.

Certifique-se de que a plataforma OCI possa resolver os nomes de domínio associados aos seus aplicativos privados.

Documentação de referência de rede

Se precisar de ajuda, consulte a seguinte documentação de serviço:

Políticas de IAM

Certifique-se de conceder aos usuários acesso a todos os recursos do Generative AI Agents, conforme descrito em Adicionando Políticas Antes de Usar o Serviço.

Verifique também as seções a seguir e crie as políticas necessárias.

Políticas para Rede

A política para o resource-type agregado virtual-network-family é obrigatória.

Você pode usar as políticas a seguir para permitir o acesso ao serviço Networking em todos os compartimentos da tenancy ou restringir o acesso a um 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 Serviços OCI

Ao criar uma ferramenta de chamada de ponto final de API e configurar a ferramenta para usar a autenticação do controlador de recursos do OCI, você deve adicionar políticas para conceder as permissões apropriadas para acessar as operações de API do serviço do OCI que deseja que o agente chame.

Referência: Referência de Política de Serviço Detalhada no Serviço IAM com Domínios de Identidade

As políticas do OCI IAM necessárias dependem das APIs de serviço do OCI que você está chamando e se você está usando um grupo dinâmico.

Usar Grupo Dinâmico

  1. Crie um grupo dinâmico e adicione a seguinte regra de correspondência.

    ALL {resource.type='genaiagent'}

    Se precisar de ajuda, consulte Criando um Grupo Dinâmico.

  2. Adicione uma política para fornecer ao grupo dinâmico o nível apropriado de acesso a um tipo de recurso. Por exemplo, para chamar as APIs do serviço Object Storage, você pode usar manage object-family ou read objects.

    • As seguintes políticas podem ser usadas com o domínio de identidades Padrão:

      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

    • Use as seguintes políticas com um domínio de identidades não Padrão, fornecendo o nome do domínio do IDCS (Oracle Identity Cloud Service) e o nome do 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

Sem usar grupo dinâmico

Adicione uma política para fornecer o nível apropriado de acesso a um tipo de recurso. Por exemplo, para chamar as APIs do serviço Object Storage, você pode usar manage object-family ou read objects.

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

Políticas para Segredo do Vault

O método de autenticação que você usa pode exigir que você forneça uma credencial armazenada em um segredo do OCI Vault.

A política do serviço IAM para acessar segredos do vault depende se você está usando um grupo dinâmico.

Usar Grupo Dinâmico

  1. Crie um grupo dinâmico e adicione a seguinte regra de correspondência.

    ALL {resource.type='genaiagent'}

    Se precisar de ajuda, consulte Criando um Grupo Dinâmico.

  2. As seguintes políticas podem ser usadas com o domínio de identidades Padrão:

    • 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

    • Use as seguintes políticas com um domínio de identidades não Padrão, fornecendo o nome do domínio do IDCS (Oracle Identity Cloud Service) e o nome do 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

Sem usar grupo dinâmico

A política a seguir pode ser usada.

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