Oracle Cloud Infrastructure Documentation

Creating an API Endpoint Calling Tool in Generative AI Agents

In Generative AI Agents, each agent must have one or more tools. You can create an agent's tool during or after creating the agent. For both options, creating a tool has the same steps. This section shows you the steps to create an API endpoint calling tool.

Before you begin, review the API Endpoint Calling Tool Guidelines for Generative AI Agents and complete any tasks that are required. For example, you might have to create an OCI Vault secret, and add policies to access vault secrets.

Creating an API Endpoint Calling Tool

  1. Select Create tool and then Custom tool.
  2. Enter a name and a description for this tool.
  3. In Tool configuration, select API endpoint calling (agent execution).
  4. (Optional) Select an example, if applicable.

    If you select an example, the example is copied into the API schema box for Inline importing. Skip ahead to step 6.

  5. For Import API schema, select one of the following options to provide the API schema for this tool. An API schema describes the API endpoint operations and methods.
    • Inline: For a small schema, you can enter a string that contains the API endpoint operations and methods.
    • Choose from Object Storage: For a large schema or schema that has frequent updates, select a compartment and a bucket. Then select the file that contains the API schema.
  6. For Authentication type, select one of the following options and complete the tool configuration as needed.
    • None: For calling public or private API endpoints that don't require authentication. When selected, no authentication header is added to a call request.
    • API key: An API key is a token that a client provides when making API calls. The API key must be stored in an OCI Vault secret.
      • Key location: Specify the location of the API key in a call request.
        • Select Header to send the key in the request header.
        • Select Query parameter to pass the key as a query parameter in the request.
      • Key name: Enter the name of a header key (for example, Authorization) or the key name of a query parameter (for example, appid).
      • Select vault secret: In the appropriate compartment, select the OCI Vault secret that has the API key.
    • Basic: HTTP basic authentication using a username and a password. The credentials must be specified in the format <your-username>:<your-password>, and stored in an OCI Vault secret.
      • Select vault secret: In the appropriate compartment, select the OCI Vault secret that has the credentials in the required format.
    • Bearer : OAuth 2.0 authentication using a bearer token. The token must be stored in an OCI Vault secret.
      • Select vault secret: In the appropriate compartment, select the OCI Vault secret that has the token.
    • IDCS: OAuth 2.0 authentication using the client ID and client secret obtained from an Oracle Identity Cloud Service (IDCS) confidential application. The client secret must be stored in an OCI Vault secret.
      • Identity domain: In the appropriate compartment, select the identity domain in which to create this tool.
      • Client ID: Enter the client ID of the confidential application.
      • Client secret: In the appropriate compartment, select the OCI Vault secret that has the client secret for the confidential application.
      • Scope URL: Enter the scope URL that defines a specific set of resources and operations that can be accessed.
    • OCI resource principal: Only for calling OCI service APIs such as Object Storage, Compute, and Networking (VCN and subnet).
  7. In the appropriate compartment, select the VCN and the subnet that you want to use.
  8. Select Create tool.
Tip

Perform one of the following actions:

  • If you're creating an agent, go back to Creating an Agent in Generative AI Agents to create another tool or an agent endpoint.
  • If you added the tool to an existing agent, after the tool is active, from the agent's detail page, select Launch chat to chat with the agent using this tool.
  • If you created the agent without an agent endpoint, when you're ready to use the agent, create an endpoint for this agent.
Note

To let a human reviewer monitor and edit a response before sending it to the user, select the optional feature Enable human in the loop in the agent endpoint.