Agents konfigurieren und mit ihnen interagieren¶

Einen Agenten erstellen¶

Erstellen Sie ein Agentenobjekt, indem Sie die Datenbank und das Schema angeben, in dem sich der Agent befinden soll, sowie einen Namen und eine Beschreibung für den Agenten. Geben Sie außerdem den Anzeigenamen, den Avatar und die Farbe an. Diese Attribute werden von der Clientanwendung verwendet, um den Agenten anzuzeigen. Der Anzeigename wird auch als Handle herangezogen, um den Agenten in Konversationen zu referenzieren.

Die folgenden Beispiele zeigen, wie Sie ein Agentenobjekt auf der Snowsight oder mithilfe der REST API erstellen:

Method 1: Snowsight UIMethod 2: REST API

1. Melden Sie sich bei Snowsight an.

2. Wählen Sie im Navigationsmenü die Option AI & ML » Agents aus.

3. Wählen Sie Create agent aus.

4. Geben Sie für Agent object name einen Namen für den Agenten an, der den Benutzern in der UI angezeigt wird.

5. Geben Sie für Display name einen Namen für den Agenten an, der für Administratoren in der Agentenliste angezeigt wird.

6. Wählen Sie Create agent aus.

7. Stellen Sie dem Agenten allgemeine Wissensanfragen.

Tools hinzufügen¶

After you’ve created the agent, you need to add tools and provide instructions on how to orchestrate across the tools. Agents support the following tool types:

• Cortex Analyst: Sie geben die semantischen Ansichten an, damit Cortex Analyst diese zum Abrufen strukturierter Daten verwenden kann. Die Agenten können über mehrere semantische Ansichten routen, um die Antwort bereitzustellen.

• Cortex Search: Sie stellen die Cortex Search-Indizes als Tools bereit, einschließlich zugehöriger Informationen wie Suchfilter, Spaltennamen und Metadaten. Der Cortex Agent verwendet die Cortex Search-Indizes, um unstrukturierte Daten abzurufen.

• Kundenspezifische Tools: Sie können Code für eine bestimmte Geschäftslogik als gespeicherte Prozedur oder benutzerdefinierte Funktion (User-Defined Function, UDF) implementieren. Alternativ können Sie auch die kundenspezifischen Tools verwenden, um mit APIs Daten aus Ihren Backend-Systemen abzurufen.

Sie geben auch die von jedem Tool verwendeten Ressourcen an. Bei Cortex Analyst geben Sie z. B. das Warehouse zusammen mit dem Timeout für die SQL-Abfrageausführung an. Ähnlich wie bei Cortex Search geben Sie die Filter und Spaltennamen an, die in der Suchabfrage verwendet werden, ebenso wie die maximalen Ergebnisse in der Suchantwort. Bei kundenspezifischen Tools geben Sie die Warehouse-Details an.

Method 1: Snowsight UIMethod 2: REST API

To modify the configuration for an existing agent, follow these steps:

1. Wählen Sie im Navigationsmenü die Option AI & ML » Agents aus.

2. Wählen Sie in der Liste der Agenten den Agenten aus, den Sie ändern möchten.

   Die Details zur Konfiguration des Agenten werden angezeigt.

3. Wählen Sie Edit aus.

4. Beschreiben Sie unter Description den Agenten und wie Benutzer mit ihm interagieren können.

5. Um Beispielfragen hinzuzufügen, die Benutzer dem Agenten stellen können, geben Sie eine Beispielfrage ein, und wählen Sie Add a question aus.

6. Wählen Sie Tools aus. Fügen Sie eines oder mehrere der folgenden Tools hinzu.

   • So fügen Sie dem Agenten in Cortex Analyst eine semantische Ansicht hinzu: In diesem Abschnitt wird davon ausgegangen, dass Sie bereits eine semantische Ansicht erstellt haben. Weitere Informationen zu semantischen Ansichten und deren Erstellung finden Sie unter Überblick über die semantischen Ansichten.

     1. Suchen Sie nach Cortex Analyst und wählen Sie die entsprechende Schaltfläche + Add aus.

     2. Geben Sie für Name einen Namen für die semantische Ansicht ein.

     3. Wählen Sie Semantic view aus.

     4. Wählen Sie die semantische Ansicht aus, die der Agent verwendet.

     5. Wählen Sie für Warehouse das Warehouse aus, das der Agent für Abfragen verwendet.

     6. Geben Sie für Query timeout (seconds) die maximale Zeit in Sekunden an, die der Agent auf den Abschluss einer Abfrage wartet, bevor das Zeitlimit überschritten wird.

     7. Beschreiben Sie unter Description die semantische Ansicht.

     8. Wählen Sie Add aus.

   • So fügen Sie dem Agenten einen Cortex Search Service hinzu: In diesem Abschnitt wird davon ausgegangen, dass Sie bereits einen Cortex Search Service erstellt haben. Informationen zum Erstellen eines Cortex Search Service finden Sie unter Cortex Search. Sie können auch eine Cortex Knowledge Extension verwenden (CKE), die für Sie freigegeben ist. Ein Tutorial, das eine CKE verwendet, finden Sie unter Problembehandlung.

     1. Suchen Sie nach Cortex Search Services und wählen Sie die entsprechende Schaltfläche + Add aus.

     2. Geben Sie unter Name einen Namen für den Cortex Search Service ein.

     3. Beschreiben Sie unter Description den Cortex Search Service.

     4. Wählen Sie unter Search service den Cortex Search Service aus, den der Agent verwendet.

     5. Wählen Sie Add aus.

   • So fügen Sie dem Agenten ein kundenspezifisches Tool hinzu: Durch Hinzufügen von kundenspezifischen Tools können Sie die Funktionalität Ihrer Agenten erweitern. Mit kundenspezifischen Tools kann der Agent gespeicherte Prozeduren und Funktionen aufrufen, die Sie definiert haben, um Aktionen auszuführen oder Berechnungen durchzuführen. In diesem Abschnitt wird davon ausgegangen, dass Sie bereits ein kundenspezifisches Tool erstellt haben. Weitere Informationen zu Prozeduren und Funktionen finden Sie unter Erweitern von Snowflake um Funktionen und Prozeduren.

     1. Suchen Sie nach Custom tools und wählen Sie die entsprechende Schaltfläche + Add aus.

     2. Geben Sie unter Name einen Namen für das kundenspezifische Tool ein.

     3. Wählen Sie unter Resource type aus, ob das kundenspezifische Tool eine Funktion oder eine Prozedur ist. Informationen darüber, ob Sie eine Funktion oder Prozedur verwenden sollten, finden Sie unter Entscheidung über das Schreiben einer gespeicherten Prozedur oder einer benutzerdefinierten Funktion.

     4. Wählen Sie unter Custom tool identifier die vorhandene Funktion oder Prozedur aus, die Sie als kundenspezifisches Tool hinzufügen möchten.

     5. Die zugehörigen Parameter für die Funktion oder Prozedur werden automatisch angezeigt. Sie können Parameter für das kundenspezifische Tool manuell hinzufügen, indem Sie einen Namen, einen Typ und eine Beschreibung hinzufügen und auswählen, ob der Parameter erforderlich ist. Sie können auch Parameter ändern, die automatisch ausgefüllt werden.

        Bemerkung

        Snowflake Cortex unterstützt keine gespeicherten Prozeduren und benutzerdefinierten Tools mit einem Parameter vom Typ object.

     6. Wählen Sie für :ui:`Warehouse`das Warehouse aus, das der Agent für die Ausführung des kundenspezifischen Tools verwendet. Sie müssen ein Warehouse manuell auswählen.

     7. Beschreiben Sie unter Description das kundenspezifische Tool und dessen Verwendung.

     8. Wählen Sie Add aus.

     9. Nachdem Sie das kundenspezifische Tool erstellt haben, stellen Sie sicher, dass den Benutzern USAGE-Berechtigungen für die Funktion oder Prozedur gewährt werden, die Sie als kundenspezifisches Tool hinzugefügt haben. Bei der Verwendung von gespeicherten Prozeduren geben Agents an, ob die Prozedur mit Eigentümer- oder Aufruferrechten ausgeführt wird. Weitere Informationen zu Eigentümer- und Aufruferrechten finden Sie unter Erläuterungen zu gespeicherten Prozeduren mit Aufruferrechten und Eigentümerrechten.

7. Wählen Sie Save aus.

Orchestrierung angeben¶

Cortex Agents orchestrieren die Aufgabe, indem sie sie in eine Abfolge von Unteraufgaben aufteilen und das richtige Tool für jede Unteraufgabe identifizieren. Sie geben das LLM an, das der Agent verwenden soll, um diese Orchestrierung durchzuführen. Sie können die Orchestrierung auch beeinflussen, indem Sie Anweisungen bereitstellen. Stellen Sie sich zum Beispiel einen Agenten vor, der so aufgebaut ist, dass er Fragen zu Einzelhandelsprodukten beantwortet. Sie können die Orchestrierungsanweisung "Use the search tool for all requests related to refunds" verwenden, um sicherzustellen, dass der Agent nur Details zur Rückerstattungsrichtlinie bereitstellt (mithilfe von Cortex Search) und nicht tatsächlich die Rückerstattungsbeträge berechnet (mithilfe von Cortex Analyst). Sie können auch Anweisungen formulieren, um die Antwort an eine bestimmte Marke oder Tonalität anzupassen, z. B.: "Always provide provide a concise response; maintain a friendly tone".

Zugriff auf den Agenten einrichten¶

Richten Sie Zugriffsrichtlinien über die Snowsight-UI oder mithilfe von SQL ein, sodass die Benutzer auf den Agenten zugreifen können. Geben Sie die Rolle an, über die Zugriff auf den Agenten gewährt werden soll.

GRANT USAGE ON AGENT my_agent TO ROLE test_rl;

Agenten überprüfen¶

Nachdem Sie den Agenten erstellt haben, können Sie ihn überprüfen, um alle Parameter zu verifizieren.

Agenten testen¶

Nachdem Sie den Agenten erstellt haben, können Sie ihn testen, um zu sehen, wie er auf Abfragen der Benutzer reagiert. Sie können den Agenten auch mit Anforderung zur Agentenausführung mit Agentenobjekt testen.

Um den Agenten zu testen, gehen Sie wie folgt vor:

1. Melden Sie sich bei Snowsight an.

2. Wählen Sie im Navigationsmenü die Option AI & ML » Agents aus.

3. Wählen Sie in der Liste der Agenten den entsprechenden Agenten aus.

4. Geben Sie auf der Seite mit den Agentendetails eine Abfrage im Agent-Playground ein.

5. Überprüfen Sie, ob der Agent wie erwartet auf die Abfrage antwortet. Wenn der Agent nicht wie erwartet antwortet, ändern die Konfiguration des Agenten, indem Sie die Schritte unter Tools hinzufügen ausführen.

Mit dem Agent interagieren¶

Nachdem Sie das Agentenobjekt erstellt haben, können Sie den Agenten über die REST API direkt in Ihre Anwendung integrieren. Verwenden Sie einen Thread, um den Kontext während der Interaktion beizubehalten. Das Agentenobjekt und der Thread in Kombination vereinfachen den Clientanwendungscode.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/threads" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "origin_application": <application_name>,
}'

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run" \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "Authorization: Bearer $PAT" \
 --data '{
     "thread_id": <thread id for context>,
     "parent_message_id": <parent message id>,
     "messages": [
      {
         "role": "user",
         "content": [
           {
            "type": "text",
             "text": "What are the projected transportation costs for the next three quarters? "
             }
         ]
       }
     ],
     "tool_choice": {
       "type": "required",
       "name": [
         "Analyst1",
         "Search1"
       ]
     }
 }'

Feedback über den Agenten sammeln¶

Sie können Feedback von Benutzern zu den Antworten des Agenten sammeln. Dieses Feedback kann Ihnen dabei helfen, den Agenten zu verfeinern, während Sie Ihren Anwendungsfall durchlaufen. Benutzer können eine objektive Bewertung (positiv/negativ) abgeben und über eine Nachricht eine subjektivere Rückmeldung übermitteln. Außerdem können Benutzer das Feedback anhand einer von vielen Kategorien klassifizieren.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>:feedback:" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "request_id": "<request-id>",
    "positive": true
    "feedback_message": "This answer was great",
    "categories":[
        "category1", "category2", "category3"
    ],
    "thread_id": "<thread-id>"
}'

Ohne Agentenobjekt interagieren¶

In manchen Fällen möchten Sie mit der Verwendung von Cortex Agents ohne ein Agentenobjekt loslegen, indem Sie agent:run verwenden. Dies kann z. B. dann nützlich sein, wenn Sie einen Anwendungsfall schnell ausprobieren möchten. Weitere Informationen über die REST API finden Sie unter Agent ohne Ausführung eines Agentenobjekts.