Documentazione dell'infrastruttura Oracle Cloud

Avvio rapido

Panoramica

Seguire questa guida in due passaggi per eseguire il provisioning, l'impostazione e l'esecuzione di un agente.

Passo 1: eseguire il provisioning di un agente con un endpoint nella console OCI

In questo passo, in OCI Console, creare un'istanza agente e un endpoint per l'agente. Non è necessario aggiungere strumenti a questo agente. Questo passo riguarda l'impostazione dell'infrastruttura e si utilizza OCI Console per farlo. Puoi anche creare un'istanza agente e il relativo endpoint tramite l'SDK OCI o con Terraform.

Nota: le istruzioni di configurazione o gli strumenti per l'istanza dell'agente sono descritti nel Passo 2.

Passo 2: Configurazione ed esecuzione dell'agente mediante ADK

In questo passo, utilizzare l'ADK per impostare ed eseguire l'agente. Per impostare l'agente, è possibile eseguire iterazioni locali con le istruzioni e gli strumenti. Dopo l'impostazione locale dell'agente, eseguire il PUSH delle informazioni sull'agente nell'istanza dell'agente remoto eseguendo il metodo agent.setup(). Per un agente in esecuzione, eseguire il metodo agent.run() per soddisfare le richieste, senza dover scrivere codice per gestire le interazioni client-server di basso livello come la gestione delle sessioni, la ricerca e il richiamo delle funzioni e così via.

Requisiti indispensabili

Passo 1: provisioning dell'endpoint dell'agente

Seguire questa guida per creare un'istanza agente e un endpoint agente utilizzando OCI Console con le specifiche riportate di seguito.

  • Non aggiungere strumenti tramite OCI Console.

  • Mantenere selezionata la casella di controllo Crea automaticamente un endpoint per questo agente per ottenere un endpoint agente.

  • Dopo la creazione dell'agente, copiare l'ID (OCID) dell'endpoint dell'agente in un blocco note per il passo successivo.

Per ogni agente in fase di sviluppo, è necessario eseguire questo passaggio solo una volta.

Nota: in questo passo non si aggiungono strumenti tramite OCI Console.

Invece, nel passo successivo, si utilizza l'ADK per configurare gli strumenti localmente. Quindi si utilizza ADK per sincronizzare automaticamente gli strumenti locali con l'istanza dell'agente remoto. L'obiettivo è che utilizzando l'ADK, è possibile avere un'unica fonte di verità per gli strumenti che includono lo schema di funzione e l'effettivo richiamabile che gestisce la chiamata di funzione.

In questo passo, viene eseguito il provisioning di un'istanza agente e di un endpoint agente nel cloud. Pensa a questo endpoint dell'agente come a un endpoint API LLM a cui ADK si connette ma è migliorato con comportamenti identici, strumenti pre-registrati ed è dedicato alla tua applicazione. Nel passo 2, connettere l'oggetto agente ADK all'endpoint dell'agente.

Passo 2: Configurazione ed esecuzione dell'agente

Python

Creare un progetto con un ambiente virtuale:

# 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

Python ADK richiede Python 3.10 o versioni successive. Assicurarsi di avere installato la versione corretta di Python nell'ambiente in uso.

Installazione dell'ADK

Dopo aver creato un progetto e un ambiente virtuale, installare la versione più recente di ADK:

pip install "oci[adk]"

Suggerimento: si è verificato un errore di "timeout della connessione a pypi.org"?

Se viene visualizzato l'errore riportato sopra durante l'esecuzione del comando pip install, è possibile che si sia verificato un problema di rete. Prova a disconnetterti dalla tua VPN ed esegui di nuovo il comando.

Java

Per includere ADK nel progetto Java, aggiungere la seguente dipendenza Maven al file pom.xml:

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

Installarlo nel repository Maven locale

mvn clean install

Autenticazione dell'applicazione ADK in OCI

ADK fornisce una classe AgentClient per semplificare la gestione dell'autenticazione e della gestione delle risorse degli agenti. Sono supportati quattro tipi di autenticazione:

Python

Autenticazione chiave API (predefinita)

L'autenticazione della chiave API è il metodo predefinito e più comune per l'autenticazione con i servizi 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"
)

Per impostare l'autenticazione della chiave API, seguire la guida all'impostazione della chiave API OCI.

Autenticazione token di sicurezza

L'autenticazione del token di sicurezza crea un token di sessione temporaneo che può essere utilizzato per autenticare ADK per utilizzare i servizi OCI. Questo metodo è comunemente usato nei test locali.

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

Per autenticare una sessione dell'interfaccia CLI, eseguire il comando seguente sul terminale. Sostituire il nome e l'area del profilo con i valori.

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

Se l'autenticazione riesce, viene autenticata anche l'app ADK in esecuzione dallo stesso terminale.

Autenticazione principal dell'istanza

L'autenticazione del principal dell'istanza è consigliata per le istanze di computazione 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"
)

Autenticazione principal risorsa

L'autenticazione del principal risorsa è consigliata per le risorse OCI come 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

Autenticazione chiave API (predefinita)

L'autenticazione della chiave API è il metodo predefinito e più comune per l'autenticazione con i servizi 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();

Per impostare l'autenticazione della chiave API, seguire la guida all'impostazione della chiave API OCI.

Autenticazione token di sicurezza

L'autenticazione del token di sicurezza crea un token di sessione temporaneo che può essere utilizzato per autenticare ADK per utilizzare i servizi OCI. Questo approccio è comunemente usato nei test locali.

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

Per autenticare una sessione CLI, eseguire questa operazione sul terminale. Sostituire il nome e l'area del profilo con i valori.

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

Dopo aver eseguito correttamente l'autenticazione, è necessario autenticare l'applicazione ADK in esecuzione dallo stesso terminale.

Autenticazione principal dell'istanza

L'autenticazione del principal dell'istanza è consigliata per le istanze di computazione 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();

Autenticazione principal risorsa

L'autenticazione del principal risorsa è consigliata per le risorse OCI come 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();

Nota: assicurarsi che l'utente autenticato disponga delle autorizzazioni per utilizzare il servizio OCI Generative AI Agents.

Configurazione ed esecuzione di un agente

Dopo che l'endpoint dell'agente è attivo, è possibile impostare ed eseguire il seguente esempio di agente meteorologico semplice utilizzando l'ADK.

Python

Creare un file denominato quickstart.py nella radice del progetto e copiare il codice seguente nel file:

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

Eseguire lo script

Quindi eseguire lo script quickstart.py e si dovrebbe vedere l'output in questo modo:

Java

Creare un file denominato QuickStart.java nella radice del progetto e copiarvi il codice seguente.

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 IDEA

Se si utilizza IntelliJ, selezionare la configurazione di esecuzione denominata QuickStart, quindi fare clic su Esegui ▶️ o premere Maiusc + F10 per avviare il programma.

Terminale

Se si utilizza il terminale:

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

Assicurarsi di eseguire questa operazione dalla radice del progetto (dove si trova pom.xml).

Dovresti vedere l'output in questo modo:

Riepilogo

Ora hai un semplice agente meteorologico che utilizza ADK in esecuzione localmente, con connessione in uscita all'endpoint dell'agente su OCI.

Nota: perché è necessario un endpoint agente? Può utilizzare ADK localmente senza un endpoint agente remoto?

ADK richiede che un endpoint dell'agente funzioni in modo molto simile a un framework dell'agente lato client che richiede un endpoint LLM. Pensa all'endpoint dell'agente come a un endpoint LLM avanzato, che offre funzioni Agentic avanzate come prompt di ragionamento ottimizzati e strumenti lato server di OCI. ADK non supporta le connessioni dirette agli endpoint LLM raw.

Questo agente ha una funzione personalizzata locale get_weather implementata. L'agente è pronto a gestire la richiesta dell'utente espressa in linguaggio naturale.

Dietro le quinte, l'ADK gestisce l'orchestrazione client-server di basso livello, mentre l'endpoint dell'agente gestisce l'esecuzione del loop dell'agente principale, parla con un LLM e potenzialmente richiama altri strumenti ospitati come uno strumento RAG (non implementato in questo avvio rapido).

Funzionamento

In genere, il codice ADK è incorporato in un'applicazione più grande e viene distribuito nell'ambiente in uso. La tua app più grande potrebbe essere un'app web, uno Slackbot, un servizio o uno script.

Attraverso gli strumenti di funzione ADK, puoi integrare un agente con il tuo codebase locale, i tuoi database remoti, i microservizi remoti e così via utilizzando l'autenticazione nativa per il tuo ambiente.

L'ADK chiama l'endpoint dell'agente, esposto dal servizio OCI Generative AI Agents, che esegue il loop dell'agente in remoto all'ambiente in uso.

Quando il loop dell'agente decide di chiamare uno strumento ospitato (come uno strumento RAG), le chiamate avvengono senza tornare ad ADK.

Quando il loop dell'agente decide di chiamare gli strumenti della funzione locale, il controllo viene riportato all'ADK. L'ADK chiama gli strumenti di funzione locali e invia l'output dello strumento di funzione agli agenti AI generativi, che quindi continua l'iterazione successiva del loop dell'agente.

Passi successivi