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:
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.
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.
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.
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.
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.
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.
Ü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"}
}
}'
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"
}
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 |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
|
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
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"
}
}
]
}
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"} }
}
}
}
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."
}
}
]
}
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": "..."
}
]
}
]
}
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"
}
}
}
]
}