Schnellstart

Überblick

Befolgen Sie diese zweistufige Anleitung, um einen Agent bereitzustellen, einzurichten und auszuführen.

Schritt 1: Agent mit einem Endpunkt in der OCI-Konsole bereitstellen

In diesem Schritt erstellen Sie in der OCI-Konsole eine Agent-Instanz und einen Endpunkt für den Agent. Sie müssen diesem Agent keine Tools hinzufügen. Bei diesem Schritt geht es um das Infrastruktursetup, und Sie verwenden dazu die OCI-Konsole. Sie können auch eine Agent-Instanz und ihren Endpunkt über das OCI-SDK oder mit Terraform erstellen.

Hinweis: Konfigurationsanweisungen oder -tools für die Agent-Instanz werden in Schritt 2 behandelt.

Schritt 2: Agent mit ADK konfigurieren und ausführen

In diesem Schritt können Sie den Agent mit ADK einrichten und ausführen. Um Ihren Agent einzurichten, können Sie mit Ihren Anweisungen und Tools lokal iterieren. Nachdem der Agent lokal eingerichtet wurde, senden Sie die Agent-Informationen an die Remote-Agent-Instanz, indem Sie die Methode agent.setup() ausführen. Führen Sie bei einem ausgeführten Agent die Methode agent.run() aus, um Anforderungen zu erfüllen, ohne Code schreiben zu müssen, um die Client/Server-Interaktionen auf niedriger Ebene zu verarbeiten, wie z.B. die Verwaltung von Sessions, das Suchen und Aufrufen von Funktionen usw.

Voraussetzungen

Berechtigungen: Stellen Sie sicher, dass Sie einen OCI-Account haben und Ihre Identität Zugriff auf den OCI Generative AI Agents-Service hat. Möglicherweise müssen Sie den OCI-Administrator bitten, die erforderlichen Policys einzurichten und Ihnen Zugriff zu erteilen.
Region: Stellen Sie sicher, dass Sie eine Region verwenden, die den OCI Generative AI Agents-Service unterstützt, wie us-chicago-1, eu-frankfurt-1 und ap-osaka-1. Sie müssen dieselbe Region in beiden Schritten unten verwenden.

Schritt 1: Agent-Endpunkt bereitstellen

Befolgen Sie dieses Handbuch, um eine Agent-Instanz und einen Agent-Endpunkt mit der OCI-Konsole mit den folgenden Details zu erstellen:

Fügen Sie keine Tools über die OCI-Konsole hinzu.
Lassen Sie das Kontrollkästchen Endpunkt für diesen Agent automatisch erstellen aktiviert, um einen Agent-Endpunkt abzurufen.
Nachdem der Agent erstellt wurde, kopieren Sie die ID (OCID) des Agent-Endpunkts, und fügen Sie sie für den nächsten Schritt in ein Notizbuch ein.

Für jeden Agent, den Sie entwickeln, müssen Sie diesen Schritt nur einmal ausführen.

Hinweis: Sie fügen in diesem Schritt keine Tools über die OCI-Konsole hinzu.

Stattdessen verwenden Sie im nächsten Schritt das ADK, um die Tools lokal einzurichten. Anschließend synchronisieren Sie mit ADK Ihre lokalen Tools automatisch mit der Remote-Agent-Instanz. Das Ziel ist, dass Sie mit dem ADK eine Single Source of Truth für die Tools haben können, die das Funktionsschema und das eigentliche aufrufbare Tool enthalten, das den Funktionsaufruf verarbeitet.

In diesem Schritt stellen Sie eine Agent-Instanz und einen Agent-Endpunkt in der Cloud bereit. Stellen Sie sich diesen Agent-Endpunkt wie einen LLM-API-Endpunkt vor, mit dem ADK eine Verbindung herstellt, aber durch das Agent-Verhalten, Ihre vorab registrierten Tools und die dedizierte Anwendung verbessert wird. Verbinden Sie im 2. Schritt das ADK-Agent-Objekt mit diesem Agent-Endpunkt.

Schritt 2: Agent konfigurieren und ausführen

Python

Erstellen Sie ein Projekt mit einer virtuellen Umgebung:

# 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 erfordert Python 3.10 oder höher. Stellen Sie sicher, dass die korrekte Version von Python in Ihrer Umgebung installiert ist.

ADK installieren

Nachdem Sie ein Projekt und eine virtuelle Umgebung erstellt haben, installieren Sie die neueste Version von ADK:

pip install "oci[adk]"

Tipp: Fehler "Verbindung zu pypi.org wegen Timeout abgebrochen"?

Wenn Sie den obigen Fehler beim Ausführen des Befehls pip install erhalten, ist dies wahrscheinlich auf ein Netzwerkproblem zurückzuführen. Versuchen Sie, die Verbindung zu Ihrem VPN zu trennen, und führen Sie den Befehl erneut aus.

Java

Um ADK in Ihr Java-Projekt aufzunehmen, fügen Sie der pom.xml die folgende Maven-Abhängigkeit hinzu:

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

Installieren Sie es in Ihrem lokalen Maven-Repository

mvn clean install

ADK-App bei OCI authentifizieren

ADK stellt eine AgentClient-Klasse bereit, um die Authentifizierung und Verwaltung von Agent-Ressourcen zu vereinfachen. Vier Authentifizierungstypen werden unterstützt:

Python

API-Schlüsselauthentifizierung (Standard)

Die API-Schlüsselauthentifizierung ist die Standardmethode und die häufigste Methode zur Authentifizierung mit OCI-Services.

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

Um die API-Schlüsselauthentifizierung einzurichten, befolgen Sie die Dokumentation zum Setup von OCI-API-Schlüsseln.

Sicherheitstokenauthentifizierung

Die Sicherheitstokenauthentifizierung erstellt ein temporäres Sessiontoken, das zur Authentifizierung von ADK zur Verwendung von OCI-Services verwendet werden kann. Diese Methode wird häufig bei lokalen Tests verwendet.

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

Um eine CLI-Sitzung zu authentifizieren, führen Sie den folgenden Befehl in Ihrem Terminal aus. Ersetzen Sie den Profilnamen und die Region durch Ihre Werte.

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

Wenn die Authentifizierung erfolgreich ist, wird Ihre ADK-App, die vom selben Terminal ausgeführt wird, ebenfalls authentifiziert.

Instanz-Principal-Authentifizierung

Die Authentifizierung des Instanz-Principals wird für OCI-Compute-Instanzen empfohlen.

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

Resource-Principal-Authentifizierung

Die Resource-Principal-Authentifizierung wird für OCI-Ressourcen wie Functions empfohlen.

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

API-Schlüsselauthentifizierung (Standard)

Die API-Schlüsselauthentifizierung ist die Standardmethode und die häufigste Methode zur Authentifizierung mit OCI-Services.

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

Um die API-Schlüsselauthentifizierung einzurichten, befolgen Sie die Dokumentation zum Setup von OCI-API-Schlüsseln.

Sicherheitstokenauthentifizierung

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

Um eine CLI-Sitzung zu authentifizieren, führen Sie diese in Ihrem Terminal aus. Ersetzen Sie den Profilnamen und die Region durch Ihre Werte.

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

Nach erfolgreicher Authentifizierung muss Ihre ADK-App, die auf demselben Terminal ausgeführt wird, authentifiziert werden.

Instanz-Principal-Authentifizierung

Die Authentifizierung des Instanz-Principals wird für OCI-Compute-Instanzen empfohlen.

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

Resource-Principal-Authentifizierung

Die Resource-Principal-Authentifizierung wird für OCI-Ressourcen wie Functions empfohlen.

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

Hinweis: Stellen Sie sicher, dass der zu authentifizierende Benutzer Berechtigungen zur Verwendung des OCI Generative AI Agents-Service hat.

Agent konfigurieren und ausführen

Nachdem der Agent-Endpunkt aktiv ist, können Sie das folgende einfache Wetter-Agent-Beispiel mit dem ADK einrichten und ausführen.

Python

Erstellen Sie eine Datei mit dem Namen quickstart.py im Projekt-Root, und kopieren Sie den folgenden Code in die Datei:

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

Führen Sie das Skript aus

Führen Sie dann das Skript quickstart.py aus, und die Ausgabe sollte wie folgt angezeigt werden:

Java

Erstellen Sie eine Datei mit dem Namen QuickStart.java im Projekt-Root, und kopieren Sie den folgenden Code.

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

Wenn Sie IntelliJ verwenden, wählen Sie die Ausführungskonfiguration mit dem Namen QuickStart aus, und klicken Sie auf "Run ▶️", oder drücken Sie Umschalt + F10, um das Programm zu starten.

Terminal

Wenn Sie das Terminal verwenden:

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

Stellen Sie sicher, dass Sie dies über die Root des Projekts ausführen (wo sich Ihre pom.xml befindet).

Die Ausgabe sollte wie folgt angezeigt werden:

Übersicht

Jetzt haben Sie einen einfachen Wetter-Agent, der ADK lokal mit ausgehender Verbindung zu Ihrem Agent-Endpunkt auf OCI verwendet.

Hinweis: Warum benötigen Sie einen Agent-Endpunkt? Kann ADK lokal ohne Remote-Agent-Endpunkt verwendet werden?

ADK erfordert einen Agent-Endpunkt, der so funktioniert, als ob ein clientseitiges Agent-Framework einen LLM-Endpunkt benötigt. Stellen Sie sich den Agent-Endpunkt als verbesserten LLM-Endpunkt vor, der erweiterte Agent-Features wie optimierte Begründungs-Prompts und serverseitige Tools von OCI bietet. ADK unterstützt keine direkten Verbindungen zu LLM-Raw-Endpunkten.

Dieser Agent ist mit einem lokalen benutzerdefinierten Funktionstool get_weather ausgestattet, das Sie implementiert haben. Der Agent ist bereit, die Anforderung Ihres Benutzers in natürlicher Sprache zu bearbeiten.

Hinter den Kulissen verarbeitet ADK die Client-Server-Orchestrierung auf niedriger Ebene, während der Agent-Endpunkt die Ausführung der Core-Agent-Schleife, das Sprechen mit einem LLM und das Aufrufen anderer gehosteter Tools wie einem RAG-Tool (in diesem Schnellstart nicht implementiert) verarbeitet.

Funktionsinformationen

In der Regel ist Ihr ADK-Code in eine größere App eingebettet und wird in Ihrer Umgebung bereitgestellt. Ihre größere App kann eine Web-App, ein Slackbot, ein Service oder ein Skript sein.

Mit ADK-Funktionstools können Sie einen Agent mit Ihrer lokalen Codebasis, Ihren Remotedatenbanken, Remote-Microservices usw. integrieren. Verwenden Sie dazu die Authentifizierung, die in Ihrer Umgebung nativ ist.

Der ADK ruft den Agent-Endpunkt auf, der vom OCI Generative AI Agents-Service bereitgestellt wird, der die Agent-Schleife remote in Ihrer Umgebung ausführt.

Wenn die Agent-Schleife beschließt, ein gehostetes Tool (wie ein RAG-Tool) aufzurufen, geschieht dies, ohne zu ADK zurückzukehren.

Wenn die Agent-Schleife beschließt, die lokalen Funktionstools aufzurufen, wird das Steuerelement wieder an das ADK zurückgegeben. Der ADK ruft Ihre lokalen Funktionstools auf und leitet die Funktionstoolausgabe an Generative AI Agents zurück, die dann die nächste Iteration der Agent-Schleife fortsetzen.

Oracle Cloud Infrastructure-Dokumentation

Schnellstart

Überblick

Schritt 1: Agent mit einem Endpunkt in der OCI-Konsole bereitstellen

Schritt 2: Agent mit ADK konfigurieren und ausführen

Voraussetzungen

Schritt 1: Agent-Endpunkt bereitstellen

Schritt 2: Agent konfigurieren und ausführen

Python

ADK installieren

Java

ADK-App bei OCI authentifizieren

Python

API-Schlüsselauthentifizierung (Standard)

Sicherheitstokenauthentifizierung

Instanz-Principal-Authentifizierung

Resource-Principal-Authentifizierung

Java

API-Schlüsselauthentifizierung (Standard)

Sicherheitstokenauthentifizierung

Instanz-Principal-Authentifizierung

Resource-Principal-Authentifizierung

Agent konfigurieren und ausführen

Python

Führen Sie das Skript aus

Java

IntelliJ IDEA

Terminal

Übersicht

Funktionsinformationen

Nächste Schritte