Oracle Cloud Infrastructure-Dokumentation

API-Endpunktaufruf mit SDKs in Generative AI Agents

In dieser Dokumentation machen Sie sich mit dem OCI-Java-SDK vertraut, um API-Endpunktaufrufe in eine Anwendung zu integrieren. Die folgenden Schritte zeigen ein OCI-Java-SDK-Beispiel zum Erstellen eines API-Endpunktaufrufstools und dann zum Aufrufen des Tools mit Chat.

IAM-Policys

Stellen Sie sicher, dass 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.

In diesem Beispiel interagiert das API-Endpunktaufruf-Tool mit Object Storage-Buckets. Sie können die folgenden Policys verwenden, um den Zugriff auf Object Storage in allen Compartments im Mandanten zu aktivieren oder den Zugriff auf ein bestimmtes Compartment einzuschränken.

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

// To enable access to a specific compartment in the tenancy
allow any-user to manage object-family in compartment <compartment-name> where any {request.principal.type='genaiagent'}

Ersetzen Sie <compartment-name> durch das Compartment, das Sie verwenden möchten.

API-Endpunktaufruf-Tool erstellen

Die folgenden Schritte zeigen, wie Sie mit dem OCI-Java-SDK ein API-Endpunktaufruftool für einen Agent erstellen.

  1. Konfigurieren Sie einen Client für die Interaktion mit Generative AI Agents. Beispiel: 
    // Configure your client
GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
       .endpoint(endpoint)
       .configuration(clientConfiguration)
       .build(provider);

    Ersetzen Sie im Code endpoint und clientConfiguration durch die entsprechenden Werte für Ihr Setup.

  2. Erstellen Sie die HttpEndpointToolConfig für Ihr Tool. Beispiel: 
    private static ToolConfig createHttpEndpointToolConfig() {
    return HttpEndpointToolConfig.builder()
            .apiSchema(ApiSchemaInlineInputLocation.builder()
                    .content("{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"OCIObjectStorageAPI\",\"version\":\"1.0.0\",\"description\":\"API for interacting with Oracle Cloud Infrastructure (OCI) Object Storage.\"},\"servers\":[{\"url\":\"https://<namespace>.objectstorage.us-chicago-1.oci.customer-oci.com\"}],\"paths\":{\"/n/<namespace>/b/{bucketName}/o\":{\"get\":{\"summary\":\"List objects in a bucket\",\"description\":\"Retrieves a list of objects stored in the specified bucket.\",\"operationId\":\"listObjects\",\"parameters\":[{\"name\":\"bucketName\",\"in\":\"path\",\"required\":true,\"description\":\"The name of the bucket.\",\"schema\":{\"type\":\"string\"}},{\"name\":\"prefix\",\"in\":\"query\",\"required\":false,\"description\":\"Filter objects by prefix.\",\"schema\":{\"type\":\"string\"}},{\"name\":\"limit\",\"in\":\"query\",\"required\":false,\"description\":\"Maximum number of objects to return.\",\"schema\":{\"type\":\"integer\",\"format\":\"int32\"}},{\"name\":\"start\",\"in\":\"query\",\"required\":false,\"description\":\"Pagination token to start listing from.\",\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"description\":\"A list of objects in the bucket.\",\"content\":{\"application/json\":{\"schema\":{\"type\":\"object\",\"properties\":{\"objects\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"size\":{\"type\":\"integer\",\"format\":\"int64\"},\"md5\":{\"type\":\"string\"},\"timeCreated\":{\"type\":\"string\",\"format\":\"date-time\"},\"etag\":{\"type\":\"string\"}}}}}}}}},\"400\":{\"description\":\"Bad request.\"},\"401\":{\"description\":\"Unauthorized request.\"},\"404\":{\"description\":\"Bucket not found.\"},\"500\":{\"description\":\"Internal server error.\"}}},\"/n/<namespace>/b/{bucketName}/o/{objectName}\":{\"delete\":{\"summary\":\"Delete an object from a bucket\",\"description\":\"Deletes a specified object from the given bucket.\",\"operationId\":\"deleteObject\",\"parameters\":[{\"name\":\"bucketName\",\"in\":\"path\",\"required\":true,\"description\":\"The name of the bucket.\",\"schema\":{\"type\":\"string\"}},{\"name\":\"objectName\",\"in\":\"path\",\"required\":true,\"description\":\"The name of the object to delete.\",\"schema\":{\"type\":\"string\"}},{\"name\":\"versionId\",\"in\":\"query\",\"required\":false,\"description\":\"The version ID of the object (if versioning is enabled).\",\"schema\":{\"type\":\"string\"}}],\"responses\":{\"204\":{\"description\":\"Object deleted successfully.\"},\"400\":{\"description\":\"Bad request.\"},\"401\":{\"description\":\"Unauthorized request.\"},\"404\":{\"description\":\"Object not found.\"},\"500\":{\"description\":\"Internal server error.\"}}}}}}")
                    .build())
            .httpEndpointAuthConfig(HttpEndpointAuthConfig.builder()
        .httpEndpointAuthSources(
                Collections.singletonList(
                        HttpEndpointAuthSource.builder()
                                .httpEndpointAuthScope(
                                        HttpEndpointAuthSource.HttpEndpointAuthScope.Agent)
                                .httpEndpointAuthScopeConfig(
                                        HttpEndpointOciAuthScopeConfig.builder().build())
                                .build()))
        .build());
            .subnetId("ocid1.subnet.oc1.us-chicago-1.aaaaaaaal7lmb2rnugbljkchadorxub7463ggill2onyt74v3l5dqhgsojcq")
            .build();
}

    In dem Code:

    • apiSchema definiert die OpenAPI-Spezifikation für die HTTP-API, mit der Sie interagieren möchten.
    • httpEndpointAuthConfig gibt die Authentifizierungskonfiguration für den HTTP-Endpunkt an. Im Beispiel wird ein OCI-Service aufgerufen. Daher wird die Authentifizierung auf OCI Resource Principal gesetzt, und <namespace> ist der Object Storage-Namespace des Mandanten.
    • subnetId ist die ID des Subnetzes, mit dem wir API-Endpunktaufrufe durchführen möchten.
  3. Erstellen Sie eine CreateToolDetails-Anforderung, um Ihr Tool zu definieren. 
    // Create a CreateToolDetails request
CreateToolDetails createToolDetails = CreateToolDetails.builder()
                .agentId(agentId)
                .compartmentId(COMPARTMENT_ID)
                .toolConfig(createHttpEndpointToolConfig())
                .displayName("tool-sdk")
                .description("tool description")
                .build();

// Build the CreateToolRequest
CreateToolRequest toolRequest = CreateToolRequest.builder()
                 .createToolDetails(createToolDetails)
                 .build();

// Create the tool
client.createTool(toolRequest);

    Der Code enthält:

    • Ersetzen Sie agentId und COMPARTMENT_ID durch die entsprechenden Werte für Ihr Setup.
    • Übergeben Sie für toolConfig die HttpEndpointToolConfig, die Sie in Schritt 2 erstellt haben.

Mit einem Agent chatten

Um eine Unterhaltung mit dem Agent zu initiieren und das HTTP-Endpunkttool zu verwenden, gehen Sie wie folgt vor:

  1. Erstellen Sie eine Session, um eine Unterhaltung zu starten. Beispiel: 
    // Create a new chat session request
CreateSessionRequest request = CreateSessionRequest.builder()
        .agentEndpointId(agentEndpointId)
        .createSessionDetails(CreateSessionDetails.builder()
                .description("description")
                .displayName("display_name")
                .build())
        .build();

String sessionId = agentClient.createSession(request)
        .getSession()
        .getId();

    Ersetzen Sie im Code agentEndpointId durch die OCID des zu verwendenden Agent-Endpunkts.

  2. Rufen Sie das HTTP-Endpunkttool auf, indem Sie eine Chatanfrage senden. 
    // Create a chat request
String message = "List all the objects under mydepartment bucket";
final ChatDetails chatDetails = ChatDetails.builder()
        .shouldStream(shouldStream)
        .userMessage(message)
        .sessionId(sessionId)
        .build();
final ChatRequest chatRequest = ChatRequest.builder()
        .chatDetails(chatDetails)
        .agentEndpointId(agentEndpointId)
        .build();

// Send the chat request
agentClient.chat(chatRequest);

    In diesem Beispiel löst die Nachricht "List all the objects under mydepartment bucket das HTTP-Endpunkttool aus, um mit der API zu interagieren, und ruft die Liste der Objekte ab.