Documentación de Oracle Cloud Infrastructure

Llamadas de punto final de API con SDK en agentes de IA generativa

Utilice esta guía para familiarizarse con el uso del SDK de Java de OCI para integrar la llamada de punto final de API en una aplicación. En los siguientes pasos se muestra un ejemplo de SDK de Java de OCI para crear una herramienta de llamada de punto final de API y, a continuación, utilizar el chat para llamar a la herramienta.

Políticas de IAM

Asegúrese de agregar políticas para otorgar los permisos adecuados para acceder a las operaciones de API del servicio OCI a las que desea que llame el agente.

En el ejemplo, la herramienta de llamada de punto final de API interactúa con cubos de Object Storage. Puede utilizar las siguientes políticas para activar el acceso a Object Storage en todos los compartimentos del arrendamiento o restringir el acceso a un compartimento específico.

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

Sustituya <compartment-name> por el compartimento que desea utilizar.

Creación de una herramienta de llamada de punto final de API

En los siguientes pasos se muestra cómo utilizar el SDK de Java de OCI para crear una herramienta de llamada de punto final de API para un agente.

  1. Configure un cliente para interactuar con los agentes de IA generativa. Por ejemplo: 
    // Configure your client
GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
       .endpoint(endpoint)
       .configuration(clientConfiguration)
       .build(provider);

    En el código, sustituya endpoint y clientConfiguration por los valores adecuados para la configuración.

  2. Cree HttpEndpointToolConfig para la herramienta. Por ejemplo: 
    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();
}

    En el código:

    • apiSchema define la especificación OpenAPI para la API HTTP con la que desea interactuar.
    • httpEndpointAuthConfig especifica la configuración de autenticación para el punto final HTTP. En el ejemplo, llamamos a un servicio de OCI, por lo que la autenticación se define en la entidad de recurso de OCI y <namespace> es el espacio de nombres de Object Storage del arrendamiento.
    • subnetId es el ID de la subred que queremos utilizar para realizar llamadas de punto final de API.
  3. Cree una solicitud CreateToolDetails para definir la herramienta. 
    // 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);

    En el código:

    • Sustituya agentId y COMPARTMENT_ID por los valores adecuados para la configuración.
    • Para toolConfig, transfiera el HttpEndpointToolConfig que ha creado en el paso 2.

Chat con un agente

Para iniciar una conversación con el agente y utilizar la herramienta de punto final HTTP, siga estos pasos:

  1. Cree una sesión para iniciar una conversación. Por ejemplo: 
    // 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();

    En el código, sustituya agentEndpointId por el OCID del punto final del agente que desea utilizar.

  2. Llame a la herramienta de punto final HTTP enviando una solicitud de chat. 
    // 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);

    En este ejemplo, el mensaje "List all the objects under mydepartment bucket dispara la herramienta de punto final HTTP para interactuar con la API y recupera la lista de objetos.