Documentação do Oracle Cloud Infrastructure

Início rápido

Visão Geral

Siga este guia de duas etapas para provisionar, configurar e executar um agente.

Etapa 1: Provisionar um agente com um ponto final na Console do OCI

Nesta etapa, na Console do OCI, crie uma instância do agente e um ponto final para o agente. Não é necessário adicionar ferramentas a este agente. Esta etapa é sobre a configuração da infraestrutura e você usa a Console do OCI para fazer isso. Você também pode criar uma instância do agente e seu ponto final por meio do OCI SDK ou com o Terraform.

Observação: As instruções ou ferramentas de configuração da instância do agente são abordadas na Etapa 2.

Etapa 2: Configurando e executando o agente usando o ADK

Nesta etapa, use o ADK para configurar e executar seu agente. Para configurar seu agente, você pode iterar com suas instruções e ferramentas localmente. Após a configuração local do agente, envie as informações do agente para a instância do agente remoto executando o método agent.setup(). Para um agente em execução, execute o método agent.run() para atender às solicitações, sem precisar gravar código para tratar as interações cliente-servidor de baixo nível, como gerenciar sessões, localizar e chamar funções e assim por diante.

Pré-requisitos

Etapa 1: Provisionando o ponto final do agente

Siga este guia para criar uma instância do agente e um ponto final do agente usando a Console do OCI com as seguintes especificações:

  • Não adicione ferramentas por meio da Console do OCI.

  • Mantenha a caixa de seleção Criar um ponto final automaticamente para este agente marcada para obter um ponto final do agente.

  • Depois que o agente for criado, copie o id (OCID) do ponto final do agente para colá-lo em um bloco de notas para a próxima etapa.

Para cada agente que você está desenvolvendo, você só precisa executar esta etapa uma vez.

Observação: Você não adiciona nenhuma ferramenta por meio da Console do OCI nesta etapa.

Em vez disso, na próxima etapa, você usa o ADK para configurar as ferramentas localmente. Em seguida, você usa o ADK para sincronizar automaticamente suas ferramentas locais com a instância do agente remoto. O objetivo é que, usando o ADK, você possa ter uma única fonte de verdade para as ferramentas que incluem o esquema de função e o chamável real que trata a chamada de função.

Nesta etapa, você está provisionando uma instância do agente e um ponto final do agente na nuvem. Pense nesse ponto final do agente como um ponto final de API do LLM ao qual o ADK se conecta, mas é aprimorado com comportamentos agênticos, suas ferramentas pré-registradas e é dedicado ao seu aplicativo. Na etapa 2, conecte o objeto do agente ADK a esse ponto final do agente.

Etapa 2: Configurando e executando o agente

Python

Crie um projeto com um ambiente virtual:

# Create a project folder with name of your choice
mkdir <your-project-name>
cd <your-project-name>

# Create and activate a virtual environment under `<myenv>` subfolder
python -m venv <myenv>
source <myenv>/bin/activate

O Python ADK requer o Python 3.10 ou posterior. Certifique-se de ter a versão correta do Python instalada em seu ambiente.

Instalando o ADK

Depois de criar um projeto e um ambiente virtual, instale a versão mais recente do ADK:

pip install "oci[adk]"

Dica: Ocorreu um erro de "conexão com pypi.org expirada"?

Se você receber o erro acima ao executar o comando pip install, é provável que ele seja causado por um problema de rede. Tente se desconectar da sua VPN e execute o comando novamente.

Java

Para incluir o ADK no seu projeto Java, adicione a seguinte dependência do Maven ao seu pom.xml:

    <dependency>
        <groupId>com.oracle.oci.sdk</groupId>
        <artifactId>oci-java-sdk-addons-adk</artifactId>
        <version>{latest-version}</version>
    </dependency>

Instale-o no repositório Maven local

mvn clean install

Autenticando seu aplicativo ADK no OCI

O ADK fornece uma classe AgentClient para simplificar o tratamento da autenticação e do gerenciamento de recursos do agente. Quatro tipos de autenticação são suportados:

Python

Autenticação de Chave de API (Padrão)

A autenticação de chave de API é o método padrão e mais comum para autenticação com serviços do OCI.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="api_key",
    profile="DEFAULT",
    region="<your-region>"  # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Para configurar a autenticação de chave de API, siga o guia de configuração de chave de API da OCI.

Autenticação de Token de Segurança

A autenticação de token de segurança cria um token de sessão temporário que pode ser usado para autenticar o ADK para usar os serviços do OCI. Este método é comumente usado em testes locais.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="security_token",
    profile="DEFAULT",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Para autenticar uma sessão da CLI, execute o comando a seguir no terminal. Substitua o nome do perfil e a região pelos seus valores.

oci session authenticate --auth security_token --profile-name DEFAULT --region <your-region>

Se a autenticação for bem-sucedida, seu aplicativo ADK que está sendo executado no mesmo terminal também será autenticado.

Autenticação do Controlador de Instâncias

A autenticação do controlador de instâncias é recomendada para instâncias de computação do OCI.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="instance_principal",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Autenticação do Controlador de Recursos

A autenticação do controlador de recursos é recomendada para recursos do OCI, como o Functions.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="resource_principal",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Java

Autenticação de Chave de API (Padrão)

A autenticação de chave de API é o método padrão e mais comum para autenticação com serviços do OCI.

import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new ConfigFileAuthenticationDetailsProvider(
                ConfigFileReader.parse("~/.oci/config", "DEFAULT"));

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

Para configurar a autenticação de chave de API, siga o guia de configuração de chave de API da OCI.

Autenticação de Token de Segurança

A autenticação de token de segurança cria um token de sessão temporário que pode ser usado para autenticar o ADK para usar os serviços do OCI. Essa abordagem é comumente usada em testes locais.

import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.SessionTokenAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new SessionTokenAuthenticationDetailsProvider(
                ConfigFileReader.parse("~/.oci/config", "DEFAULT"));

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

Para autenticar uma sessão da CLI, execute-a no seu terminal. Substitua o nome do perfil e a região pelos seus valores.

oci session authenticate --auth security_token --profile-name DEFAULT --region us-chicago-1

Após a autenticação bem-sucedida, seu aplicativo ADK em execução no mesmo terminal deverá ser autenticado.

Autenticação do Controlador de Instâncias

A autenticação do controlador de instâncias é recomendada para instâncias de computação do OCI.

import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.InstancePrincipalsAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new InstancePrincipalsAuthenticationDetailsProvider();

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

Autenticação do Controlador de Recursos

A autenticação do controlador de recursos é recomendada para recursos do OCI, como o Functions.

import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.ResourcePrincipalAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new ResourcePrincipalAuthenticationDetailsProvider();

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

Observação: Certifique-se de que o usuário que está sendo autenticado tem permissões para usar o serviço OCI Generative AI Agents.

Configurando e executando um agente

Depois que o ponto final do agente estiver ativo, você poderá configurar e executar o exemplo de agente meteorológico simples a seguir usando o ADK.

Python

Crie um arquivo chamado quickstart.py na raiz do projeto e copie o seguinte código no arquivo:

quickstart.py

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

# Use @tool to signal that this Python function is a function tool.
# Apply standard docstring to provide function and parameter descriptions.
@tool
def get_weather(location: str) -> Dict[str, str]:
    """
    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():
    # Create an agent client with your authentication and region details
    # Replace the auth_type with your desired authentication method.
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="us-chicago-1",
    )

    # Create a local agent object with the client, instructions, and tools.
    # You also need the agent endpoint id. To obtain the OCID, follow Step 1.
    agent = Agent(
        client=client,
        agent_endpoint_id="<your-agent-endpoint-OCID>",
        instructions="You perform weather queries using tools.",
        tools=[get_weather]
    )

    # Sync local instructions and tools to the remote agent resource
    # You only need to invoke setup() when you change instructions and tools
    agent.setup()

    # Run the agent. You can embed this method in your webapp, slack bot, etc.
    # You invoke the run() when you need to handle your user's request.
    input = "Is it cold in Seattle?"
    response = agent.run(input)

    # Print the response
    response.pretty_print()

if __name__ == "__main__":
    main()

Executar o script

Em seguida, execute o script quickstart.py e você deverá ver a saída desta forma:

Java

Crie um arquivo chamado QuickStart.java na raiz do projeto e copie o código a seguir para ele.

QuickStart.java

package demos;
import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.adk.agent.Agent;
import com.oracle.bmc.adk.client.AgentClient;
import com.oracle.bmc.adk.tools.FunctionTool;
import com.oracle.bmc.adk.tools.Param;
import com.oracle.bmc.adk.tools.Tool;
import com.oracle.bmc.adk.run.RunResponse;
import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.SessionTokenAuthenticationDetailsProvider;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class QuickStart {
    @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(QuickStart.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();

        String input = "Is it cold in Seattle";
        RunResponse response = agent.run(input);
        response.prettyPrint();
    }
}

IntelliJ IDEIA

Se você estiver usando o IntelliJ, selecione a configuração de execução chamada QuickStart e clique em Executar ▶️ ou pressione Shift + F10 para iniciar o programa.

Terminal

Se você estiver usando o terminal:

mvn compile exec:java \
  -Dexec.mainClass="demos.QuickStart" \
  -Dexec.workingdir=java/examples

Certifique-se de que você esteja executando isso na raiz do projeto (onde seu pom.xml está localizado).

Você deverá ver a saída desta forma:

Resumo

Agora você tem um agente meteorológico simples usando o ADK em execução localmente, com conexão de saída com o ponto final do agente na OCI.

Observação: Por que você precisa de um ponto final de agente? Você pode usar o ADK localmente sem um ponto final de agente remoto?

O ADK requer que um ponto final do agente funcione da mesma forma que uma estrutura do agente do lado do cliente precisa de um ponto final do LLM. Pense no ponto final do agente como um ponto final de LLM aprimorado, oferecendo recursos agênticos avançados, como prompts de raciocínio otimizados e ferramentas do servidor da OCI. O ADK não suporta conexões diretas com pontos finais brutos do LLM.

Este agente está equipado com uma ferramenta de função personalizada local get_weather que você implementou. O agente está pronto para lidar com a solicitação do seu usuário expressa em linguagem natural.

Nos bastidores, o ADK lida com a orquestração de cliente-servidor de baixo nível, enquanto o ponto final do agente lida com a execução do loop do agente principal, conversando com um LLM e potencialmente invocando outras ferramentas hospedadas, como uma ferramenta RAG (não implementada nesse início rápido).

Como Funciona

Normalmente, seu código ADK é incorporado em um aplicativo maior e é implantado em seu ambiente. Seu aplicativo maior pode ser um aplicativo web, um Slackbot, um serviço ou um script.

Por meio de ferramentas de função do ADK, você pode integrar um agente à sua base de código local, seus bancos de dados remotos, microsserviços remotos e assim por diante usando a autenticação nativa do seu ambiente.

O ADK chama o ponto final do agente, exposto pelo serviço OCI Generative AI Agents, que executa o loop do agente remotamente para seu ambiente.

Quando o loop do agente decide chamar uma ferramenta hospedada (como uma ferramenta RAG), essas chamadas acontecem sem voltar ao ADK.

Quando o loop do agente decide chamar as ferramentas de função local, o controle é retornado ao ADK. O ADK chama suas ferramentas de função locais e envia a saída da ferramenta de função de volta para os Agentes de IA Generativa, que, em seguida, continua a próxima iteração do loop do agente.

Próximas Etapas