Documentação do Oracle Cloud Infrastructure

Chamadas de Função com SDKs em Agentes de IA Generativa

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

Criando uma ferramenta de chamada de função

As etapas a seguir mostram como usar o OCI Java SDK para criar uma ferramenta de chamada de função para um agente.

  1. Configure o cliente. Por exemplo: 
    GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
       .endpoint(endpoint)
       .configuration(clientConfiguration)
       .build(provider);
  2. Defina uma função e incorpore-a em ToolConfig. Por exemplo, aqui está uma função que cria um bucket do OCI Object Storage: 
    private static Function prepareFunction() throws JsonProcessingException {

        String payload="{\n" +
        "                \"type\": \"object\",\n" +
        "                \"properties\": {\n" +
        "                    \"bucket_name\": {\n" +
        "                        \"type\": \"string\",\n" +
        "                        \"description\": \"The name of the bucket to create.\"\n" +
        "                    },\n" +
        "                    \"compartment_ocid\": {\n" +
        "                        \"type\": \"string\",\n" +
        "                        \"description\": \"The OCID of the compartment where the bucket will be created.\"\n" +
        "                    },\n" +
        "                    \"storage_tier\": {\n" +
        "                        \"type\": \"string\",\n" +
        "                        \"enum\": [\"Standard\", \"Archive\"],\n" +
        "                        \"description\": \"The storage tier for the bucket.\"\n" +
        "                    }\n" +
        "                },\n" +
        "                \"required\": [\"bucket_name\", \"compartment_ocid\"],\n" +
        "                \"additionalProperties\": \"false\" \n" +
        "            }\n";

        ObjectMapper objectMapper = new ObjectMapper();
        
        Map<String,String> parameters = objectMapper.readValue(payload, HashMap.class);

        for (Map.Entry entry : parameters.entrySet()) {
                String jsonString = objectMapper.writeValueAsString(entry.getValue());
                entry.setValue(jsonString);
        }
        return Function.builder()
                .name("object_storage")
                .description("A function to create object storage bucket")
                .parameters(parameters)
                .build();            
}
 
private static ToolConfig createFunctionToolConfig() {
        return FunctionCallingToolConfig.builder()
                .function(prepareFunction())
                .build();
}
  3. Crie uma solicitação de ferramenta e, em seguida, crie a ferramenta usando o cliente. Por exemplo: 
    CreateToolDetails createToolDetails = CreateToolDetails.builder()
                .agentId(agentId)
                .compartmentId(COMPARTMENT_ID)
                .toolConfig(toolConfig)
                .displayName("tool-sdk")
                .description("tool description")
                .build();
 CreateToolRequest toolRequest = CreateToolRequest.builder()
                 .createToolDetails(createToolDetails)
                 .build();
client.createTool(toolRequest);

Conversando com um Agente

Para conversar com um agente que tenha uma ferramenta de chamada de função, primeiro crie uma sessão e, na sessão, chame a função. Veja alguns exemplos dessas etapas.
  1. Criar uma sessão. Por exemplo: 
    GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
        .endpoint(endpoint)
        .configuration(clientConfiguration)
        .build(provider);
 
// 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();

    Substitua <agentEndpointId> pelo OCID do ponto final do agente na seção de pré-requisito.

  2. Use a sessão para fazer uma chamada de chat que chame a função. Este exemplo envia uma mensagem ao agente e espera uma resposta que inclua uma chamada de função 
    String message = "Create an Object Store.";
 
// Create Chat request
final ChatDetails chatDetails = ChatDetails.builder()
        .shouldStream(shouldStream)
        .userMessage(message)
        .sessionId(sessionId)
        .build();
final ChatRequest chatRequest = ChatRequest.builder()
        .chatDetails(chatDetails)
        .agentEndpointId(agentEndpointId)
        .build();
 
final ChatResult chatResult = agentClient.chat(chatRequest);

    A resposta do agente inclui um campo required-actions, que contém os detalhes da função a ser chamada.

    chatResult(message=null, traces=[], usageDetails=null, 
requiredActions=[FunctionCallingRequiredAction(super=RequiredAction(super=BmcModel
(__explicitlySet__=[functionCall, actionId])
actionId=<some-action-id>),
functionCall=FunctionCall(super=BmcModel(__explicitlySet__=[name, arguments])name=object_storage,
arguments=
{"bucket_name": "my_object_store", 
"compartment_ocid": "ocid1.compartment.oc1..xxx",
"storage_tier": "Standard"
}))], 
toolResults=null)

    Na resposta, extraia o action-id associado à chamada de função. Esse ID é usado na próxima etapa para executar a ação.

    String actionId = "<some-action-id>";
  3. Execute a ação. A resposta contém a resposta final do agente, que inclui o resultado da chamada de função. Por exemplo: 
    String actionId = chatResponse.getChatResult().getRequiredActions().get(0).getActionId();
String functionCallOutput = "{"bucket_name": "test_bucket", "compartment_ocid": "<compartment_OCID>",
"storage_tier":"Standard"}";
 
PerformedAction performedAction = FunctionCallingPerformedAction.builder()
    .actionId(actionId)
    .functionCallOutput(functionCallOutput)
    .build();
 
// Execute the chat session with the performed action
final ChatDetails chatDetails = ChatDetails.builder()
        .shouldStream(shouldStream)
        .userMessage(userMessage)
        .performedActions(List.of(performedAction))
        .sessionId(sessionId)
        .build();
final ChatRequest chatRequest = ChatRequest.builder()
        .chatDetails(chatDetails)
        .agentEndpointId(agentEndpointId)
        .build();
ChatResult chatResult = agentClient.chat(chatRequest);
 
# Chat Result:
# ChatResult(message=The object store 'my_object_store' has been successfully created 
in the specified compartment with the 'Standard' storage tier., 
traces=[], usageDetails=null, toolResults=null)