Agente con uno strumento funzione

Scopri come creare un agente con uno strumento di funzione personalizzato.

Esempio di agente meteo

In questo esempio, abbiamo un agente meteorologico dotato di uno strumento di funzione personalizzato. Questo è anche noto come agente chiamante funzione.

Con gli strumenti di funzione un agente può utilizzare funzioni scritte su misura e definite localmente come strumenti. Gli strumenti di funzione sono flessibili e particolarmente utili per i casi d'uso aziendali a causa dell'elaborazione locale, della facilità di autenticazione e della perfetta integrazione con le funzionalità esistenti.

---

Informazioni: gli strumenti di funzione vengono eseguiti localmente sul lato.

Ciò che viene inviato all'agente remoto sul lato server OCI è la definizione della funzione (nome della funzione, parametri della funzione e relative descrizioni). I server OCI non accedono all'implementazione delle funzioni.

---

Python

weather_agent.py

from typing import Dict, Any
from oci.addons.adk import Agent, AgentClient, tool

@tool
def get_weather(location: str) -> Dict[str, Any]:
    """Get the weather for a given location.

    Args:
      location(str): The location for which weather is queried
    """
    return {"location": location, "temperature": 72, "unit": "F"}


def main():
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="us-chicago-1"
    )

    agent = Agent(
        client=client,
        agent_endpoint_id="ocid1...",
        instructions="Perform weather queries using the given tools",
        tools=[get_weather]
    )

    agent.setup()

    input = "Is it cold in Seattle?"
    response = agent.run(input)

    response.pretty_print()

if __name__ == "__main__":
    main()

Java

WeatherAgent.java

package demos.singleTurnSingleTool.WeatherAgent;

import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.adk.agent.Agent;
import com.oracle.bmc.adk.agent.RunOptions;
import com.oracle.bmc.adk.client.AgentClient;
import com.oracle.bmc.adk.tools.FunctionTool;
import com.oracle.bmc.adk.run.RunResponse;
import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.SessionTokenAuthenticationDetailsProvider;

import java.lang.reflect.Method;
import java.util.Arrays;

public class WeatherAgent {
    @Tool(name = "getWeather", description = "Get weather of a given location")
    public static Map<String, String> getWeather(
            @Param(description = "The location") String location) {
        Map<String, String> weather = new HashMap<>();
        weather.put("location", location);
        weather.put("temperature", "72");
        weather.put("unit", "F");
        return weather;
    }

  public static void main(String[] args) throws Exception {
    final String configLocation = "~/.oci/config";
    final String configProfile = "DEFAULT";

    BasicAuthenticationDetailsProvider authProvider =
            new SessionTokenAuthenticationDetailsProvider(
                    ConfigFileReader.parse(configLocation, configProfile));

    AgentClient agentClient = AgentClient.builder()
        .authProvider(authProvider)
        .region("us-chicago-1")
        .build();

    FunctionTool getWeatherTool =
        FunctionTool.fromMethod(WeatherAgent.class, "getWeather", String.class);

    Agent agent = Agent.builder()
        .client(agentClient)
        .agentEndpointId("YOUR_AGENT_ENDPOINT_ID")
        .instructions("Perform weather queries using the given tools.")
        .tools(Arrays.asList(getWeatherTool))
        .build();

    agent.setup();
    final String input = "Is it cold in Seattle";
    final Integer maxStep = 3;
    RunOptions runOptions = RunOptions.builder().maxSteps(maxStep).build();
    RunResponse response = agent.run(input, runOptions);
    response.prettyPrint();
  }
}

Si scrive una funzione normale get_weather, si decora con @tool e si utilizza docstring standard per scrivere la descrizione della funzione e le descrizioni dei parametri.

La funzione può restituire tutto ciò che può essere convertito in una stringa. Qui restituiamo solo un Dict che simula un oggetto JSON che otteniamo dal database, dalla cache o dall'endpoint API.

Passare quindi tale funzione all'elenco tools durante la creazione dell'oggetto Agent. In questo modo la funzione viene registrata come strumento all'agente localmente.

Quando si esegue il metodo agent.setup(), ADK applica la configurazione dell'agente locale all'istanza dell'agente remoto, che include le istruzioni dell'agente e lo strumento di funzione. ADK genera automaticamente lo schema JSON della funzione necessario per impostare lo strumento di funzione personalizzato sul server.

Quando si esegue il metodo agent.run(), ADK gestisce l'interazione client-server necessaria per la chiamata di funzione, che include il richiamo della funzione get_weather.

Funzionamento

Quando l'agente remoto decide di utilizzare lo strumento get_weather, risponde con una risposta che contiene un'azione richiesta che il client deve intraprendere. In questo caso, l'azione richiesta per il client è quella di richiamare lo strumento di funzione get_weather, con un argomento location=Seattle.

L'agente remoto applica la classificazione dell'intento per utilizzare lo strumento get_weather e la compilazione dello slot degli argomenti, in base alla query in linguaggio naturale Is it cold in Seattle?.

L'ADK analizza l'azione richiesta, individua la funzione locale registrata, esegue questa funzione con gli argomenti specificati, acquisisce l'output della chiamata di funzione e invia l'output all'agente remoto. L'agente può utilizzare tale output per generare una risposta alla domanda dell'utente.