Documentation sur Oracle Cloud Infrastructure

Appel de point d'extrémité d'API avec des trousses SDK dans les agents d'intelligence artificielle générative

Utilisez ce guide pour vous familiariser avec l'utilisation de la trousse SDK Java pour OCI afin d'intégrer l'appel de point d'extrémité d'API dans une application. Les étapes suivantes présentent un exemple de trousse SDK Java pour OCI pour créer un outil d'appel de point d'extrémité d'API, puis utiliser le clavardage pour appeler l'outil.

Politiques GIA

Assurez-vous d'ajouter des politiques pour accorder les autorisations appropriées permettant d'accéder aux opérations d'API du service OCI que l'agent doit appeler.

Dans l'exemple, l'outil d'appel de point d'extrémité d'API interagit avec les seaux de stockage d'objets. Vous pouvez utiliser les politiques suivantes pour activer l'accès au service de stockage d'objets dans tous les compartiments de la location ou restreindre l'accès à un compartiment spécifique.

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

Remplacez <compartment-name> par le compartiment que vous voulez utiliser.

Création d'un outil d'appel de point d'extrémité d'API

Les étapes suivantes montrent comment utiliser la trousse SDK Java pour OCI pour créer un outil d'appel de point d'extrémité d'API pour un agent.

  1. Configurez un client pour interagir avec les agents d'IA générative. Par exemple : 
    // Configure your client
GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
       .endpoint(endpoint)
       .configuration(clientConfiguration)
       .build(provider);

    Dans le code, remplacez endpoint et clientConfiguration par les valeurs appropriées pour votre configuration.

  2. Créez HttpEndpointToolConfig pour votre outil. Par exemple : 
    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();
}

    Dans le code :

    • apiSchema définit la spécification OpenAPI de l'API HTTP avec laquelle vous souhaitez interagir.
    • httpEndpointAuthConfig indique la configuration d'authentification pour le point d'extrémité HTTP. Dans l'exemple, nous appelons un service OCI. L'authentification est donc réglée à Principal de ressource OCI et <namespace> est l'espace de noms de stockage d'objets de la location.
    • subnetId est l'ID du sous-réseau à utiliser pour effectuer des appels de point d'extrémité d'API.
  3. Créez une demande CreateToolDetails pour définir votre outil. 
    // 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);

    Dans le code :

    • Remplacez agentId et COMPARTMENT_ID par les valeurs appropriées pour votre configuration.
    • Pour toolConfig, transmettez la valeur HttpEndpointToolConfig que vous avez créée à l'étape 2.

Clavardage avec un agent

Pour lancer une conversation avec l'agent et utiliser l'outil de point d'extrémité HTTP, procédez comme suit :

  1. Créez une session pour démarrer une conversation. Par exemple : 
    // 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();

    Dans le code, remplacez agentEndpointId par l'OCID du point d'extrémité de l'agent à utiliser.

  2. Appelez l'outil de point d'extrémité HTTP en envoyant une demande de clavardage. 
    // 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);

    Dans cet exemple, le message "List all the objects under mydepartment bucket déclenche l'interaction de l'outil de point d'extrémité HTTP avec l'API et extrait la liste des objets.