Agente com uma ferramenta de função

Saiba como criar um agente com uma ferramenta de função personalizada.

Exemplo de agente climático

Neste exemplo, temos um agente meteorológico equipado com uma ferramenta de função personalizada. Isso também é conhecido como agente de chamada de função.

Com as ferramentas de função, um agente pode usar funções personalizadas definidas localmente como ferramentas. As ferramentas de função são flexíveis e particularmente úteis para casos de uso corporativos devido ao processamento local, à fácil autenticação e à integração perfeita com os recursos de funcionalidade existentes.

---

Informações: As ferramentas de função são executadas localmente no seu lado.

O que é enviado ao agente remoto no lado do servidor do OCI é a definição da função (nome da função, parâmetros da função e suas descrições). Os servidores OCI não acessam a implementação da função.

---

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();
  }
}

Você grava uma função simples get_weather, decora-a com @tool e usa docstring padrão para gravar descrições de função e parâmetros.

Sua função pode retornar qualquer coisa que possa ser convertida em uma string. Aqui apenas retornamos um Dict simulando um objeto JSON que obtemos do banco de dados, cache ou ponto final da API.

Em seguida, você passa essa função para a lista tools ao criar o objeto Agent. Isso registra a função como uma ferramenta para o agente localmente.

Quando você executa o método agent.setup(), o ADK aplica a configuração do agente local à instância do agente remoto, que inclui as instruções do agente e a ferramenta de função. O ADK gera automaticamente o esquema JSON de função necessário para configurar a ferramenta de função personalizada no servidor.

Quando você executa o método agent.run(), o ADK trata a interação cliente-servidor necessária para a chamada de função, que inclui chamar a função get_weather.

Como Ele Funciona

Quando o agente remoto decide usar a ferramenta get_weather, ele responde com uma resposta que contém uma ação necessária que o cliente precisa executar. Nesse caso, a ação necessária para o cliente é chamar a ferramenta de função get_weather, com um argumento location=Seattle.

O agente remoto aplica a classificação de intenção para usar a ferramenta get_weather e o preenchimento do slot de argumento, com base na consulta de linguagem natural Is it cold in Seattle?.

O ADK analisa a ação necessária, localiza a função local registrada, executa essa função com os argumentos fornecidos, captura a saída de chamada da função e submete a saída de volta ao agente remoto. O agente pode usar essa saída para gerar uma resposta à pergunta do usuário.