Appel de fonction 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 fonction dans une application. Les étapes suivantes présentent un exemple de trousse SDK Java pour OCI pour créer un outil d'appel de fonction, puis utiliser le clavardage pour appeler l'outil d'appel de fonction.

Créer un outil d'appel de fonction

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

  1. Configurez le client. Par exemple :
    GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
           .endpoint(endpoint)
           .configuration(clientConfiguration)
           .build(provider);
  2. Définissez une fonction, puis intégrez-la dans ToolConfig. Par exemple, voici une fonction qui crée un seau de stockage d'objets OCI :
    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. Créez une demande d'outil, puis créez l'outil à l'aide du client. Par exemple :
    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);

Clavardage avec un agent

Pour clavarder avec un agent doté d'un outil d'appel de fonction, créez d'abord une session et, dans la session, appelez la fonction. Voici quelques exemples pour ces étapes.
  1. Créer une session. Par exemple :
    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();
    

    Remplacez <agentEndpointId> par l'OCID du point d'extrémité de l'agent dans la section des préalables.

  2. Utilisez la session pour effectuer un appel de clavardage qui appelle la fonction. Cet exemple envoie un message à l'agent et attend une réponse qui inclut un appel de fonction
    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);
     

    La réponse de l'agent inclut un champ required-actions, qui contient les détails de la fonction à appeler.

    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)

    À partir de la réponse, extrayez action-id associé à l'appel de fonction. Ce code est utilisé à l'étape suivante pour exécuter l'action.

    String actionId = "<some-action-id>";
    
  3. Exécutez l'action. La réponse contient la réponse finale de l'agent, qui inclut le résultat de l'appel de fonction. Par exemple :
    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)