Agenten erstellen¶

Struktur des Agenten¶

Ein Agent besteht aus den folgenden Teilen:

• Das Basismodell, das die Grundlage für das Verhalten des Agenten bietet

• Ein Modell (der Orchestrator), das die Absicht interpretiert, die richtigen Tools auswählt und die Sequenz der Aktionen plant

• Anleitung für das Verhalten des Agenten

• Tools, die der Agent verwenden kann

• Ressourcen für die Tools

In den folgenden Abschnitten finden Sie Informationen zur Modellauswahl und zur Konfiguration der Tools. Dieses Beispiel verwendet eine semantische Ansicht, einen Cortex Search Service und ein kundenspezifisches Tool, um Antworten zu liefern. Obwohl Sie einen Basisagenten erstellen können, der keines dieser Tools verwendet, kann dieser Basisagent nur das Basismodell verwenden, um Antworten zu liefern. Infolgedessen hat der Agent keinen Zugriff auf Daten innerhalb Ihres Snowflake-Kontos und hat nur einen begrenzten Kontext für Antworten.

Informationen über die anderen Komponenten des Agenten finden Sie unter Cortex Agents.

Voraussetzungen¶

Um einen Cortex Agent zu erstellen, müssen Sie eine Rolle mit den folgenden Berechtigungen verwenden:

Der folgende Code gewährt die erforderlichen Berechtigungen zur Erstellung eines Cortex Agent:

GRANT USAGE ON DATABASE <database_name> to ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;
GRANT CREATE AGENT ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;

Copy

Zusätzlich zu den Berechtigungen, die für das Erstellen eines Cortex Agent erforderlich sind, sind die folgenden Voraussetzungen nötig, um den Agenten mit bestimmten Tools zu verbinden:

• Eine semantische Ansicht, um die Verbindung zum Agenten herzustellen

  Informationen zum Erstellen einer semantischen Ansicht finden Sie unter Überblick über die semantischen Ansichten.

• Ein Cortex Analyst-Tool zur Verbindung mit dem Agenten

  Informationen zum Erstellen eines Cortex Analyst-Tools finden Sie unter Cortex Analyst.

• Unstrukturierte Daten in einer Datenbank, die mit dem Agenten verbunden werden soll

• Ein Cortex Search-Tool zur Verbindung mit dem Agenten

  Informationen zum Erstellen eines Cortex Search-Tools finden Sie unter Cortex Search.

• Ein kundenspezifisches Tool zur Verbindung mit dem Agenten

  Weitere Informationen zum Erstellen von benutzerdefinierten Funktionen (UDFs) und gespeicherten Prozeduren, die als kundenspezifische Tools verwendet werden können, finden Sie unter Erweitern von Snowflake um Funktionen und Prozeduren.

Um Tools an einen Agenten anzuhängen, muss die Rolle, mit der der Agent erstellt wird, über die folgenden Berechtigungen verfügen:

Grundlagen zur Konfiguration von Agenten¶

Wenn Sie einen Agenten erstellen, müssen Sie Informationen über den Agenten angeben, wie z. B. den Namen, die Beschreibung und das Modell. Sie können auch die Tools angeben, die der Agent verwenden kann, und die Ressourcen, auf die der Agent zugreifen kann. Diese Ressourcen werden als YAML-Spezifikation in der FROM SPECIFICATION-Klausel des Befehls CREATE AGENT übergeben.

Die folgenden Empfehlungen bieten Best Practices für diese Konfiguration:

Geltungsbereich des Agenten einschränken: Bevor Sie Tools hinzufügen oder Anweisungen schreiben, sollten Sie definieren, warum der Agent existiert, wem er dient und welche spezifischen Fragen er beantworten soll. Dieser Schritt ist die Grundlage für alles, was folgt: von der Auswahl des Tools bis hin zu Leistung und Vertrauen. Snowflake empfiehlt, den Geltungsbereich des Agenten auf einen bestimmten, hochwertigen Anwendungsfall einzuschränken.

Nachdem sich ein Agent in einem Bereich als zuverlässig erwiesen hat, können Sie das Muster für andere replizieren. Beispielsweise könnten Sie einen Agenten haben, der die aktuellen Verkaufs- und Marketingdaten Ihres Geschäfts analysiert, und einen anderen, der die besten SKUs empfiehlt, um den Einzelhändler zu präsentieren.

Anzahl der Tools sorgfältig auswählen: Jeder Agent sollte nur Zugriff auf die Tools haben, die er benötigt. Um dies festzustellen, prüfen Sie die Dokumente oder Daten, die der Agent benötigt, um seinen Zweck zu erfüllen. Wenn der Agent auf unstrukturierte Daten zugreifen muss, verwenden Sie Cortex Search. Wenn der Agent auf strukturierte Daten zugreifen muss, verwenden Sie Cortex Analyst. Wenn der Agent andere Tools benötigt, können Sie kundenspezifische Tools verwenden.

Eine nützliche Tool-Beschreibung schreiben: Diese Beschreibungen werden verwendet, um dem Agenten zu helfen, zu verstehen, was das Tool tut und wie es zu verwenden ist. Ungenaue Tool-Beschreibungen können kaskadierende Fehler verursachen und zu „Halluzinationen“ führen.

Damit eine nützliche Tool-Beschreibung erstellt werden kann, beachten Sie die folgenden Richtlinien:

• Fügen Sie einen eindeutigen und spezifischen Tool-Namen hinzu, der die Domäne des Tools („Kundschaft“, „Vertrieb“) und die Funktion („Analytik“, „Suche“) verdeutlicht.

• Schreiben Sie eine zweckdienliche Beschreibung des Tools, die dem Agenten Folgendes mitteilt:

  • Was das Tool tut

  • Auf welche Daten es zugreift

  • Wann es verwendet wird

  • Wann es NOT verwendet wird

• Seien Sie bezüglich der erwarteten Eingaben des Tools explizit. Mehrdeutige Eingaben in Ihre Tools führen zu falschen Tool-Aufrufen und Fehlern.

  • Seien Sie konkret.

  • Geben Sie das Datenformat an.

  • Geben Sie klare Datenanweisungen an.

  • Geben Sie Standardhinweise an.

  • Verwenden Sie eine einheitliche Terminologie.

Weitere Empfehlungen für die Konfiguration der Agenten finden Sie unter Best Practices beim Erstellen von Cortex Agents.

Modellauswahl¶

Wenn Sie einen Agenten erstellen, empfehlen wir Ihnen, auto für das Modell auszuwählen. Mit dieser Option wählt Cortex automatisch das beste Modell für Ihr Konto aus, und die Qualität verbessert sich automatisch, sobald neue Modelle verfügbar sind. Weitere Informationen zu den verfügbaren Modellen finden Sie unter Unterstützte Modelle und Regionen.

Das folgende Beispiel zeigt, wie Sie das Modell für den Agenten angeben:

models:
  orchestration: auto

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

Semantische Ansichten mit Cortex Analyst verbinden (strukturierte Daten)¶

Snowflake Intelligence unterstützt semantische Ansichten, die eine Art von strukturierten Daten mit Anweisungen sind, die dem Agenten mitteilen, wie er die Daten abfragen oder interpretieren soll. Cortex Agents verwendet Cortex Analyst, um strukturierte Daten aus semantischen Ansichten abzurufen, indem Anfragen in natürlicher Sprache in SQL-Abfragen konvertiert werden. Die Agenten können über mehrere semantische Ansichten routen, um die Antwort bereitzustellen.

Jede semantische Ansicht sollte einen ähnlichen Satz von Tabellen abdecken. Sie können datenspezifische Standardeinstellungen festlegen, z. B. immer einen Datumsfilter für die letzten drei Monate hinzufügen, falls nicht angegeben, oder interne Konten immer ausschließen.

Sie können eine semantische Ansicht mit einem Agenten verbinden, indem Sie die semantische Ansicht als Teil der Tool-Ressourcen angeben. Das folgende Beispiel zeigt, wie Sie eine semantische Ansicht mit einem Agenten verbinden und wie Sie das Cortex Analyst-Tool angeben, um strukturierte Daten aus der semantischen Ansicht abzurufen:

tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "<your cortex analyst tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex analyst tool name>:
    semantic_view: "<db>.<schema>.<semantic_view>"

Cortex Search verbinden (unstrukturierte Daten)¶

Um unstrukturierte Daten zu verarbeiten, können Sie ein Cortex Search-Tool mit einem Agenten verbinden, indem Sie das Cortex Search-Tool in der YAML-Spezifikation als Teil der Tool-Ressourcen angeben. Cortex Search Services rufen Dokumente und Datensätze aus unstrukturierten Datenquellen mithilfe der semantischen Suche ab. Die beiden Hauptanwendungsfälle für Cortex Search sind das Abrufen von Augmented Generation (RAG) und die Unternehmenssuche. 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.

Wenn Sie ein Cortex Search-Tool mit einem Agenten verbinden, ist es besonders wichtig, die folgenden Informationen zu den Parametern und deren erwarteten Werten anzugeben:

• Typ und Format (einschließlich Beispiele)

• Ob erforderlich oder optional (mit Standardwerten)

• Gültige Werte oder Einschränkungen (Enumerationen, Bereiche, Formate)

• Beziehung zu anderen Parametern (Abhängigkeiten, Konflikte)

• Wie Sie den Wert erhalten (insbesondere für IDs)

Das folgende Beispiel zeigt, wie Sie ein Cortex Search-Tool mit einem Agenten verbinden und wie Sie das Cortex Search-Tool in der YAML-Spezifikation angeben:

tools:
  - tool_spec:
      type: "cortex_search"
      name: "<your cortex search tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex search tool name>:
    name: "<db>.<schema>.<search_service_name>"
    max_results: "5"
    filter:
      "@eq":
        region: "North America"
    title_column: "<title_name>"
    id_column: "<column_name>"

Kundenspezifische Tools hinzufügen¶

Snowflake Intelligence unterstützt kundenspezifische Tools, d. h. benutzerdefinierte Funktionen oder gespeicherte Prozeduren, mit denen kundenspezifische Geschäftslogik implementiert werden kann. Sie können ein kundenspezifisches Tool mit einem Agenten verbinden, indem Sie das kundenspezifische Tool in der YAML-Spezifikation als Teil der Tool-Ressourcen angeben.

Das folgende Beispiel zeigt, wie Sie ein kundenspezifisches Tool mit einem Agenten verbinden und wie Sie das kundenspezifische Tool in der YAML-Spezifikation angeben:

tools:
  - tool_spec:
      type: "custom_tool"
      name: "<your custom tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your custom tool name>:
    user-defined-function-argument: "argument1"

Einen Agenten erstellen¶

• Kombinieren Sie alle Tools und Komponenten, um einen Agenten mit SQL zu erstellen:

  CREATE OR REPLACE AGENT <agent_name>
      COMMENT = 'agent level comment'
      PROFILE = '{"display_name": "My Business Assistant", "avatar":  "business-icon.png", "color": "blue"}'
      FROM SPECIFICATION
      $$
      models:
      orchestration: claude-4-sonnet
  
      orchestration:
      budget:
          seconds: 30
          tokens: 16000
  
      instructions:
      response: "You will respond in a friendly but concise manner"
      orchestration: "For any revenue question, use Analyst; for policy questions, use Search"
      system: "You are a friendly agent that helps with business questions"
      sample_questions:
          - question: "What was our revenue last quarter?"
          answer: "I'll analyze the revenue data using our financial database."
  
      tools:
      - tool_spec:
          type: "cortex_analyst_text_to_sql"
          name: "<your cortex analyst tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "cortex_search"
          name: "<your cortex search tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "data_to_chart"
          name: "data_to_chart"
          description: "Generates visualizations from data"
  
      tool_resources:
      <your cortex analyst tool name>:
          semantic_view: "<db>.<schema>.<semantic_view>"
      <your cortex search tool name>:
          name: "<db>.<schema>.<search_service_name>"
          max_results: "5"
          filter:
          "@eq":
              region: "North America"
          title_column: "<title_name>"
          id_column: "<column_name>"
      $$;
  

  Copy

Ändern eines bestehenden Agenten¶

Anweisungen zum Ändern der Konfiguration für einen vorhandenen Agenten, einschließlich des Hinzufügens von Tools und der Aktualisierung anderer Details, finden Sie unter Tools hinzufügen.