Appel de fonction avec des kits SDK dans des agents d'IA générative

Utilisez ce guide pour vous familiariser avec l'utilisation du kit SDK Java OCI et intégrer des appels de fonction à une application. Les étapes suivantes présentent un exemple de kit SDK Java OCI permettant de créer un outil d'appel de fonction, puis d'utiliser la discussion pour appeler l'outil d'appel de fonction.

Prérequis

Avant de commencer, assurez-vous d'avoir configuré les ressources suivantes :

Un agent. Reportez-vous à Création d'un agent dans des agents Generative AI.
Adresse d'agent. Reportez-vous à Création d'une adresse dans les agents Generative AI.
Le kit SDK OCI et les dépendances nécessaires installés dans votre environnement de développement. Reportez-vous à Configuration et prérequis.

Créer un outil d'appel de fonction

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

Configurez le client. Exemple :

GenerativeAiAgentRuntimeClient agentClient = GenerativeAiAgentRuntimeClient.builder()
       .endpoint(endpoint)
       .configuration(clientConfiguration)
       .build(provider);

Définissez une fonction, puis incorporez-la dans ToolConfig. Par exemple, voici une fonction qui crée un bucket 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();
}

Créez une demande d'outil, puis créez l'outil à l'aide du client. 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);

Discuter avec un agent

Pour discuter 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 de ces étapes.

Créer une session. 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 de l'adresse d'agent dans la section de prérequis.

Utilisez la session pour effectuer un appel de discussion 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)

A partir de la réponse, extrayez le fichier action-id associé à l'appel de fonction. Cet ID est utilisé à l'étape suivante pour exécuter l'action.

String actionId = "<some-action-id>";

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. 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)

Documentation Oracle Cloud Infrastructure

Appel de fonction avec des kits SDK dans des agents d'IA générative

Prérequis

Créer un outil d'appel de fonction

Discuter avec un agent