Cortex Agents

Cortex-Agenten orchestrieren sowohl strukturierte als auch unstrukturierte Datenquellen, um Erkenntnisse zu liefern. Sie planen Aufgaben, verwenden Tools, um diese Aufgaben auszuführen, und erstellen Antworten. Agenten verwenden Cortex Analyst (strukturiert) und Cortex Search (unstrukturiert) als Tools, zusammen mit LLMs, um Daten zu analysieren. Cortex Search extrahiert Erkenntnisse aus unstrukturierten Quellen, während Cortex Analyst SQL zur Verarbeitung strukturierter Daten generiert. Eine umfassende Unterstützung für die Tool-Identifizierung und Tool-Ausführung ermöglicht die Bereitstellung anspruchsvoller Anwendungen auf der Grundlage von Unternehmensdaten.

Der Arbeitsablauf umfasst vier Hauptkomponenten:

  1. Planung: Anwendungen wechseln oft zwischen der Verarbeitung von Daten aus strukturierten und unstrukturierten Quellen. Nehmen wir zum Beispiel eine dialogorientierte App, mit der Sie Abfragen von Benutzern beantworten können. Ein Geschäftsanwender kann zunächst nach den Top-Vertriebshändlern nach Umsatz (strukturiert) fragen und dann zu einer Anfrage nach einem Vertrag (unstrukturiert) wechseln. Cortex-Agenten können eine Anfrage analysieren, um einen Plan zu orchestrieren und eine Lösung oder Antwort zu finden.

    1. Erkunden Sie die Optionen: Wenn der Benutzer eine mehrdeutige Frage stellt (z.B. „Erzählen Sie mir etwas über Acme Supplies“), zieht der Agent verschiedene Möglichkeiten in Betracht – Produkte, Standort oder Verkaufspersonal – um die Eindeutigkeit und Genauigkeit zu verbessern.

    2. Aufteilung in Teilaufgaben: Cortex-Agenten können eine Aufgabe oder Anfrage (z. B. „Was sind die Unterschiede zwischen den Vertragsbedingungen von Acme Supplies und Acme Stationery?“) in mehrere Teile aufteilen, um eine präzisere Antwort zu erhalten.

    3. Toolübergreifendes Routing: Der Agent wählt das richtige Tool – Cortex Analyst oder Cortex Search – um einen geregelten Zugriff und die Einhaltung der Unternehmensrichtlinien zu gewährleisten.

  2. Verwendung des Tools: Wenn ein Plan vorhanden ist, ruft der Agent die Daten effizient ab. Cortex Search extrahiert Erkenntnisse aus unstrukturierten Quellen, während Cortex Analyst SQL erstellt, um strukturierte Daten zu verarbeiten. Eine umfassende Unterstützung für die Tool-Identifizierung und Tool-Ausführung ermöglicht die Bereitstellung anspruchsvoller Anwendungen auf der Grundlage von Unternehmensdaten.

  3. Reflexion: Nach jeder Verwendung des Tools wertet der Agent die Ergebnisse aus, um die nächsten Schritte zu bestimmen – um eine Klärung zu bitten, zu iterieren oder eine endgültige Antwort zu erstellen. Diese Orchestrierung ermöglicht es, komplexe Abfragen zu verarbeiten und gleichzeitig die Genauigkeit und die Einhaltung von Vorschriften innerhalb des sicheren Bereichs von Snowflake zu gewährleisten.

  4. Überwachen und optimieren Sie: Nach der Bereitstellung können die Kunden Metriken verfolgen, die Leistung analysieren und die Verhaltensweise für kontinuierliche Verbesserungen verfeinern. Auf der Client-Seite können Entwickler TruLens verwenden, um die Interaktion mit dem Agenten zu überwachen. Durch die kontinuierliche Überwachung und Verfeinerung der Governance-Kontrollen können Unternehmen die Agenten von AI zuverlässig skalieren und gleichzeitig die Sicherheit und Compliance gewährleisten.

Tutorials, die Ihnen den Einstieg erleichtern, finden Sie unter Tutorials für Cortex Agents.

Bemerkung

Obwohl Snowflake sich bemüht, qualitativ hochwertige Antworten zu liefern, kann die Richtigkeit der LLM-Antworten oder der angegebenen Zitate nicht garantiert werden. Sie sollten alle Antworten von den Agenten-API überprüfen, bevor Sie sie Ihren Benutzern zur Verfügung stellen.

Anforderungen an die Zugriffssteuerung

Der abfragende Benutzer muss über die entsprechende Berechtigung verfügen:

  • USAGE für den in der Abfrage referenzierten Cortex Search Service.

  • USAGE für die Datenbank, das Schema und die Tabellen, auf die im semantischen Modell von Cortex Analyst verwiesen wird

  • Eine Rolle, der die Datenbankrolle CORTEX_USER zugewiesen wurde. Weitere Informationen dazu finden Sie unter Erforderliche Berechtigungen.

So verwenden Sie die Agent-API

In diesem Abschnitt werden die Schritte zur Erstellung eines Agent mit Hilfe der Agent-API beschrieben.

Konfigurieren Sie RESTAPI-Authentifizierung

Snowflake REST-APIs unterstützen die Authentifizierung über programmatische Zugriffstoken (PATs), die Authentifizierung über ein Schlüsselpaar mit JSON-Web Token (JWTs) und OAuth. Weitere Details dazu finden Sie unter Authentifizierung von Snowflake REST APIs mit Snowflake.

Erstellen Sie ein semantisches Modell für Cortex Analyst

Sie können Cortex Analyst verwenden, um SQL-Abfragen aus natürlicher Sprache zu erstellen. Um Cortex Analyst zu verwenden, müssen Sie ein semantisches Modell erstellen. Weitere Informationen dazu finden Sie unter Ein semantisches Modell erstellen.

Einen Cortex Search Service erstellen

Verwenden Sie Cortex Search, um Ihre Daten zu durchsuchen. Weitere Informationen dazu finden Sie unter CREATE CORTEX SEARCH SERVICE.

Bemerkung

Die DEFAULT_ROLE des abfragenden Benutzers muss über die Berechtigung USAGE für den Cortex Search Service sowie für die Datenbank und das Schema, in dem er sich befindet, verfügen.

Anrufen der API

Suchen Sie zunächst Ihr Snowflake-Konto URL. Sobald Sie Ihre URL und Ihre PAT haben, können Sie die Agenten-API von der Befehlszeile aus mit cURL abfragen, indem Sie die folgende Syntax verwenden:

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/agent:run" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "model": "llama3.1-70b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "what are the top 3 customers by revenue"
                }
            ]
        }
    ],
    "tools": [
        {
            "tool_spec": {
                "type": "cortex_search",
                "name": "transcript_search"
            }
        },
        {
            "tool_spec": {
                "type": "cortex_analyst_text_to_sql",
                "name": "data_model"
            }
        }
    ],
    "tool_resources": {
        "transcript_search": {"name": "testdb.testschema.transcript_search_service"},
        "data_model": {"semantic_model_file": "@testdb.testschema.stage/sample_data_model.yaml"}
    }
}'
Copy

Die Antwort wird inkrementell an den Client gestreamt.

Unterstützte Modelle

Sie können die folgenden Modelle mit Cortex-Agenten verwenden, um die Antwort zu erzeugen. Bitte beachten Sie, dass das Modell nicht für die Orchestrierung verwendet wird.

  • llama3.1-70b

  • lama3.3-70b

  • mistral-large2

  • claude-3-5-sonnet

Sie können auch eine Antwortanweisung angeben, um die Antworten des Agenten anzupassen.

{
    "response_instruction": "You will always maintain a friendly tone and provide concise response"
}
Copy

Wichtig

Cortex Agents verwendet Modelle, die möglicherweise nicht in allen Regionen verfügbar sind. Weitere Informationen dazu finden Sie unter Verfügbarkeit.

Regionsverfügbarkeit

Die Cortex Agents-Funktion ist in den folgenden Regionen verfügbar:

Funktion
(Modell)
AWS US West 2
(Oregon)
AWS US East 1
(N. Virginia)
AWS Europe Central 1
(Frankfurt)
AWS Europe West 1
(Ireland)
AWS AP Southeast 2
(Sydney)
AWS AP Northeast 1
(Tokio)
Azure East US 2
(Virginia)
Azure West Europe
(Niederlande)
AWS
(Regionsübergreifend)
COMPLETE
(claude-3-5-sonnet)

✔

✔

✔
COMPLETE
(llama3.2-1b)

✔

✔
COMPLETE
(llama3.2-3b)

✔

✔
COMPLETE
(llama3.1-8b)

✔

✔

✔

✔

✔

✔

✔

✔
llama3.1-70b

✔

✔

✔

✔

✔

✔

✔

✔

✔
llama3.3-70b

✔

✔

✔
snowflake-llama-3.3-70b

✔

✔
llama3.1-405b

✔

✔

✔

✔
snowflake-llama-3.1-405b

✔

✔
snowflake-arctic

✔

✔

✔
deepseek-r1

✔
reka-core

✔

✔
reka-flash

✔

✔

✔

✔
mistral-large2

✔

✔

✔

✔

✔

✔

✔

✔

✔
mixtral-8x7b

✔

✔

✔

✔

✔

✔

✔

✔

✔
mistral-7b

✔

✔

✔

✔

✔

✔

✔

✔

✔
jamba-instruct

✔

✔

✔

✔
jamba-1.5-mini

✔

✔

✔

✔
jamba-1.5-large

✔

✔
gemma-7b

✔

✔

✔

✔

✔

✔
e5-base-v2

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-m

✔

✔

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-m-v1.5

✔

✔

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-l-v2.0

✔

✔

✔

✔

✔

✔

✔

✔

✔
nv-embed-qa-4

✔

✔
multilingual-e5-large

✔

✔

✔

✔

✔

✔

✔

✔

✔

voyage-multilingual-2

✔

✔

✔

✔

✔

✔

✔

✔

✔

Hinweise zu Kosten

In der Vorschau verursachen die Cortex Search Services Kosten gemäß den Angaben in der Snowflake Service Consumption Table.

Einen Cortex Agent erstellen

Wir werden Cortex Agents einsetzen, um eine konversationelle Anwendung zu entwickeln, die Fragen von Geschäftsanwendern zu Vertragsbedingungen beantwortet. Schauen wir uns die wichtigsten Komponenten an. (Das vollständige Tutorial finden Sie unter Erste Schritte mit Cortex Agents).

Schritt 1: Geben Sie die Tools an, die Sie in der Anfrage verwenden möchten

{
    "tools": [
        {
            "tool_spec": {
                "name": "data_model",
                "type": "cortex_analyst_text_to_sql"
            }
        },
        {
            "tool_spec": {
                "name": "transcript_search",
                "type": "cortex_search"
            }
        },
        {
            "tool_spec": {
                "type": "sql_exec",
                "name": "sql_exec"
            }
        },
        {
            "tool_spec": {
                "type": "data_to_chart",
                "name": "data_to_chart"
            }
        }
    ]
}
Copy

Schritt 2: Stellen Sie den Tools statische Argumente (Ressourcen) zur Verfügung, die Cortex Agent für Toolaufrufe verwenden kann.

{
    "tool_resources": {
        "data_model": {
            "semantic_model_file": "@cortex_tutorial_db.public.revenue_semantic_model.yaml"
        },
        "transcript_search": {
            "name": "cortex_tutorial_db.public.contract_terms",
            "max_results": 5,
            "title_column": "TRANSCRIPT_TITLE",
            "id_column": "TRANSCRIPT_ID",
            "filter": {"@eq": {"TRANSCRIPT_TYPE": "ENTERPRISE"} }
        }
    }
}
Copy

Schritt 3: Jetzt geben wir das Modell und die Systemaufforderung an, um die Antwort zu erzeugen

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": {
                "type": "text",
                "text": "You’re a friendly assistant to answer questions."
            }
        }
    ]
}
Copy

Schritt 4: Erstellen Sie eine semantische Modelldatei, die vom Analysten-Tool für den Zugriff auf strukturierte Daten verwendet werden soll

Führen Sie die Schritte 1 bis 3 in dieser Anleitung aus, um ein semantisches Modell für Cortex Analyst zu erstellen Erste Schritte mit Cortex-Agenten

Schritt 5: Als nächstes richten wir einen Suchdienst für das Tool Search ein, um auf unstrukturierte Daten zuzugreifen

Folgen Sie den Schritten 4 bis 5 in dieser Anleitung, um den Cortex Search Service zu erstellen Erste Schritte mit Cortex Agents

Schritt 6: Wir sind nun bereit, mit dem Agent zu interagieren. Sie werden das Nachrichtenfeld verwenden, um Anfragen zu senden und Antworten zu erhalten

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "You’re a friendly assistant to answer questions"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "hello"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "hi there!"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "..."
                }
            ]
        }
    ]
}
Copy

Schritt 7: Im weiteren Verlauf der Interaktion identifiziert der Agent die Tools und führt sie aus (auf der Service-Seite), um die Aufgabe zu erfüllen. In dem folgenden Beispiel identifiziert der Agent Text2SQL als das Tool und führt die SQL-Abfrage aus. Während der Interaktion kann der Agent die Verwendung eines Tools für die Client-Anwendung (auf der Client-Seite) anfordern. Der Agent gibt zum Beispiel die SQL-Abfrage an, die ausgeführt werden soll.

{
    "role": "assistant",
    "content": [
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_001",
                "name": "cortex_analyst_text_to_sql",
                "input": {
                    "query": "...",
                    "semantic_model_file": "..."
                }
            }
        },
        {
            "type": "tool_results",
            "tool_results": {
                "status": "success",
                "tool_use_id": "tool_001",
                "content": [
                    {
                        "type": "json",
                        "json": {
                            "sql": "select * from table"
                        }
                    }
                ]
            }
        },
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_002",
                "name": "sql_exec",
                "input": {
                    "sql": "select * from table"
                }
            }
        }
    ]
}
Copy
Sprache: Deutsch