Oracle Cloud Infrastructure Documentation

API Endpoint Calling Tool Guidelines for Generative AI Agents

Define an API endpoint calling tool in Generative AI Agents for interacting with and calling external application programming interfaces (APIs) and OCI APIs.

The information provided in this topic assumes that you're familiar with OCI virtual cloud networks (VCNs), subnets, and security rules, how to deploy applications on OCI compute instances, and the fundamentals of working with REpresentational State Transfer Application Programming Interface (REST API).

Here's an overview of how to get started:

  1. Create an OpenAPI schema that defines the request and response formats and available operations. Include the x-requires-approval header in the schema, if necessary.
  2. Configure an authentication method. Depending on the authentication type you use, create a vault secret for the credentials that you need to provide.
  3. Set up OCI network resources. A virtual cloud network (VCN) is required.
  4. Review the IAM policies and add those that are required. For example, Networking and Vault.

API Schema

The structure and behavior of the API operations must be defined in an OpenAPI schema that's written in either JSON or YAML.

When using the Console to create an API endpoint calling tool in Generative AI Agents, you can upload the schema manually by copying and pasting into a text box, or you can select the schema that's been uploaded to Object Storage.

The maximum file size and supported versions are:

  • Versions:
    • OpenAPI: 3.0 and later
    • JSON: Standard JSON schema as defined in RFC 8259
    • YAML: version 1.2 and later
  • Maximum file size:
    • Inline pasting: 1,000,000 characters
    • File in Object Storage: 20 MB
Example of an 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."
          }
        }
      }
    }
  }
}
Example of an 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 Approval

For API operations that might change a state, we recommend including the x-requires-approval header in the schema to indicate that a tool action requires human-in-the-loop (HITL) approval. Involving humans in critical operations is generally recommended for the following operation types because they might potentially cause unwarranted changes:

  • POST
  • PUT
  • PATCH
  • DELETE

Example of including x-requires-approval in a 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.

Including the x-requires-approval header signals to Generative AI Agents that a confirmation must be requested from a human before executing the API endpoint in the agent tool call.

When the approval header is included in the schema, the header:

  • Triggers the required action HumanApprovalRequiredAction in the trajectory step
  • Prevents unintended side effects without human oversight
  • Enables safe usage of tools that perform operations that write, update, or delete.

Authentication

In Generative AI Agents, an API endpoint calling tool can be configured to use authentication or not use authentication when making a request to execute an API operation.

See the following sections for information about the supported authentication mechanisms, and the prerequisite tasks that you must perform for an authentication type.

API Key Authentication

For public and private API endpoints that require an API key.

An API key is a unique identifier obtained from the API provider's platform. When a client such as an application or service makes a request to the API, the API key is used to authenticate the client.

In Generative AI Agents, API key authentication is supported by the following types:

  • Header: Pass the API key in the header of an HTTP request.

    API header parameters are key-value pairs included in an HTTP request or response to provide additional metadata about the request or response.

  • Query parameter: Pass the API key directly in the URL as a query parameter.

    Query parameters are a defined set of parameters (key-value pairs) attached to the end of a URL used to provide additional information to a web server when making requests.

Create a secret in OCI Vault to store the API key. If you need help creating a secret, see Creating a Secret in the Vault service documentation.

When you configure an API endpoint calling tool with API key authentication, you specify the location of the key (header or query parameter), the key name, and the vault secret that has the API key.

See also Policies for Vault Secret.

Basic Authentication

For calling public and private API endpoints using a username and password.

Basic authentication uses your username and password credentials in the following required format:

<your-username>:<your-password>

Create a secret in OCI Vault to store the credentials in the required format. If you need help creating a secret, see Creating a Secret in the Vault service documentation.

When you configure an API endpoint calling tool with basic authentication, you provide the vault secret.

See also Policies for Vault Secret.

Bearer Authentication

For calling private API endpoints using a bearer token.

A bearer token is an access token used in OAuth 2.0 authentication to authorize or grant access to protected resources. Bearer authentication is an authentication method where the client sends a bearer token as part of the request in the Authorization header, which is validated to authenticate the request. We recommend using long-lived tokens such as API keys.

Create a secret in OCI Vault to store the token. If you need help creating a secret, see Creating a Secret in the Vault service documentation.

When you configure an API endpoint calling tool with bearer authentication, you provide the vault secret.

See also Policies for Vault Secret.

IDCS Authentication

For calling private API endpoints using Oracle Identity Cloud Service (IDCS) confidential application client credentials.

A confidential application is designed to securely authenticate and authorize client applications using OAuth 2.0. Client credentials are the client ID and client secret of a confidential application that's registered for a client application.

Use OCI IAM with Identity Domains to create a confidential application. Note that you must have the Identity Domain Administrator role or the Application Administrator role to create confidential applications in an identity domain.

To create a confidential application:

  1. Open the navigation menu  and select Identity & Security. Under Identity, select Domains.
  2. From the list of domains in a compartment, select the domain in which you want to create the confidential application.
  3. Create and activate a confidential application.

    For OAuth configuration, select Client configuration and use Client credentials.

    If you need help, see Creating a Confidential Application in the documentation for OCI IAM with Identity Domains.

  4. Copy the client ID and client secret values that are generated in the confidential application. Store the values in a safe place.
  5. In OCI Vault, create a secret to store the client secret of the confidential application. You must provide the vault secret when you configure an API endpoint calling tool with IDCS authentication.
    Note

    Cross-region calls from the agent service tenancy are not supported. For example, if the API endpoint calling tool that's configured with IDCS authentication is in region A, you should not select a vault with master region B.

    If you need help creating a secret, see Creating a Secret in the Vault service documentation.

    See also Policies for Vault Secret.

OCI Resource Principal Authentication

Only for calling OCI APIs such as Object Storage and Networking.

A resource principal lets services securely authenticate with OCI and OCI service resources without requiring explicit credentials. OCI IAM policies are used to authenticate access. For example:

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

The IAM policies that you write depends on the OCI service APIs you're calling, and whether you're using a dynamic group. See Policies for OCI Services.

Network Resources

When you create an API endpoint calling tool in Generative AI Agents, you must select a virtual cloud network (VCN) and a subnet.

Regardless of whether the target URL is private or public, all requests made by API endpoint calling tools route through your subnet. This includes REST calls to third-party providers, internal services hosted in your VCN, and OCI public APIs.

Set up the networking resources that you need in OCI.

VCN and Subnet

  • A virtual cloud network (VCN) is required.

  • You can have a private or public subnet. A private subnet is recommended.

  • A private subnet requires a NAT gateway.

  • A public subnet requires an Internet gateway. Depending on your environment setup, a public subnet might require an Internet gateway and a NAT gateway.

    For calling public APIs without authentication, ensure that the public subnet is set up for a NAT gateway with all port traffic enabled for egress.

API Gateway for Private DNS

An API gateway can be created for traffic to applications on private instances.

Select the Private type when you create the API gateway for a private DNS.

In the private subnet, ensure that these two egress rules are available:

  • Port 443 is used by the API gateway for communication.
  • The port where the private application is hosted. The API gateway sends request to this port (for example, 9090).

When using IDCS authentication with private endpoints, ensure that you replace the base URL with the API Gateway service URL in the OpenAPI schema. The API gateway must point to the instance running in a private subnet.

Private Network Setup
VCN:

  • Create a VCN in the region and compartment that you want.

  • Specify the CIDR block for the VCN (for example, 10.0.0.0/16).

  • You can choose to enable DNS resolution for the VCN.

Private subnet:

  • Create a private subnet in the VCN you created, selecting the same compartment as the VCN.

  • Specify the CIDR block for the subnet (for example, 10.0.1.0/24).

  • You can choose to enable DNS resolution for the subnet.

Private Compute instance:

  • In the same compartment as the VCN and subnet, create a private Compute instance, selecting the VCN and private subnet that you created.

  • If you want to access the instance by SSH, provide your SSH public key.

Egress rules:

  • Allow outbound connections to required services (for example, Object Storage, external APIs, if needed).

  • Open TCP port 443 for HTTPS.

Ingress rules:

  • Allow inbound traffic only from the OCI platform IP ranges.

  • Restrict to necessary ports (typically TCP 443).

Ingress UDP rule:

  • Add an ingress rule for UDP port 53.

    Add the UDP rule to the default security list of the agent service and your (customer) VCN subnets to allow DNS redirection and resolution.

Public Network Setup

Set up similar Ingress and Egress restrictions, but exposed to the internet. Use strict access control lists (ACLs).

DNS Resolution

To facilitate DNS resolution for private applications:

  • Allow UDP port 53 on your firewall/security lists for DNS traffic.

  • Configure DNS forwarding/rules to direct traffic to your private application endpoints.

  • Ensure that Ingress UDP port 53 is open in both the agent service and your (customer) VCN subnet security lists.

Ensure that the OCI platform can resolve the domain names associated with your private applications.

Network Reference Documentation

If you need help, see the following service documentation:

IAM Policies

Ensure that you give users access to all Generative AI Agents resources as described in Adding Policies Before You Can Use the Service.

Review also the following sections and write the policies that you need.

Policies for Networking

The policy for the aggregate resource-type virtual-network-family is required.

You can use the following policies to enable access to Networking in all compartments in the tenancy or restrict access to a specific compartment. 

// 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>
Policies for OCI Services

When you create an API endpoint calling tool and configure the tool to use OCI resource principal authentication, you must add policies to give the appropriate permissions to access the OCI service's API operations that you want the agent to call.

Reference: Detailed Service Policy Reference in IAM with Identity Domains

The OCI IAM policies that you need depends on the OCI service APIs you're calling, and whether you're using a dynamic group.

Use Dynamic Group

  1. Create a dynamic group, and add the following matching rule.

    ALL {resource.type='genaiagent'}

    If you need help, see Creating a Dynamic Group.

  2. Add a policy to give the dynamic group the appropriate level of access to a resource type. For example, to call the Object Storage service APIs, you might use manage object-family or read objects.

    • The following policies can be used with the Default identity domain:

      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 the following policies with an identity domain that's not Default, providing the Oracle Identity Cloud Service (IDCS) domain name and the dynamic group name: 

      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

Without Using Dynamic Group

Add a policy to give the appropriate level of access to a resource type. For example, to call the Object Storage service APIs, you might use manage object-family or read objects.

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

Policies for Vault Secret

The authentication method that you use might require you to provide a credential stored in an OCI Vault secret.

The IAM policy to access vault secrets depends on whether you're using a dynamic group.

Use Dynamic Group

  1. Create a dynamic group, and add the following matching rule.

    ALL {resource.type='genaiagent'}

    If you need help, see Creating a Dynamic Group.

  2. The following policies can be used with the Default identity domain:

    • 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 the following policies with an identity domain that's not Default, providing the Oracle Identity Cloud Service (IDCS) domain name and the dynamic group name: 

      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

Without Using Dynamic Group

The following policy can be used.

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