Documentação do Oracle Cloud Infrastructure

Chamada de Ponto Final de API com SDKs em Generative AI Agents

Use este guia para se familiarizar com o uso do OCI Java SDK para integrar a chamada de ponto final de API em um aplicativo. As etapas a seguir mostram um exemplo do OCI Java SDK para criar uma ferramenta de chamada de ponto final de API e, em seguida, usar o chat para chamar a ferramenta.

Políticas de IAM

Certifique-se de adicionar políticas para conceder as permissões apropriadas para acessar as operações de API do serviço OCI que você deseja que o agente chame.

No exemplo, a ferramenta de chamada de ponto final de API interage com buckets do serviço Object Storage. Você pode usar as políticas a seguir para permitir o acesso ao serviço Object Storage em todos os compartimentos da tenancy ou restringir o acesso a um 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'}

Substitua <compartment-name> pelo compartimento que você deseja usar.

Criando uma Ferramenta de Chamada de Ponto Final de API

As etapas a seguir mostram como usar o OCI Java SDK para criar uma ferramenta de chamada de ponto final de API para um agente.

  1. Configure um cliente para interagir com os Generative AI Agents. Por exemplo: 
    // Configure your client
GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
       .endpoint(endpoint)
       .configuration(clientConfiguration)
       .build(provider);

    No código, substitua endpoint e clientConfiguration pelos valores apropriados para sua configuração.

  2. Crie o HttpEndpointToolConfig para sua ferramenta. Por exemplo: 
    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();
}

    Em código:

    • apiSchema define a especificação OpenAPI da API HTTP com a qual você deseja interagir.
    • httpEndpointAuthConfig especifica a configuração de autenticação para o ponto final HTTP. No exemplo, estamos chamando um serviço do OCI, portanto, a autenticação é definida como Controlador de Recursos do OCI e o <namespace> é o namespace do serviço Object Storage da tenancy.
    • subnetId é o ID da sub-rede que queremos usar para fazer chamadas de ponto final de API.
  3. Crie uma solicitação CreateToolDetails para definir sua ferramenta. 
    // 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);

    No código: de

    • Substitua agentId e COMPARTMENT_ID pelos valores apropriados para sua configuração.
    • Para toolConfig, informe a HttpEndpointToolConfig criada na etapa 2.

Conversando com um agente

Para iniciar uma conversa com o agente e usar a ferramenta de ponto final HTTP, siga estas etapas:

  1. Crie uma sessão para iniciar uma conversa. Por exemplo: 
    // 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();

    No código, substitua agentEndpointId pelo OCID do ponto final do agente que você deseja usar.

  2. Chame a ferramenta de ponto final HTTP enviando uma solicitação 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);

    Neste exemplo, a mensagem "List all the objects under mydepartment bucket aciona a ferramenta de ponto final HTTP para interagir com a API e recupera a lista de objetos.