Cortex Agents REST API¶

Verwenden Sie diese API, um die Erstellung einer interaktiven Chat-Anwendung zu vereinfachen.

Agent ausführen¶

POST <account_url>/api/v2/cortex/agent:run

Sendet eine Abfrage eines Benutzers an den im Anfrage-Body angegebenen Cortex Agents-Dienst und gibt dessen Antwort zurück.

Anfrage¶

Pfadparameter¶

Parameter	Beschreibung
`account_url`	(Erforderlich) Ihre Snowflake-Konto-URL. Anweisungen zum Auffinden Ihrer Konto-URL finden Sie unter Suchen von Organisations- und Kontonamen eines Kontos.

Header der Anforderung¶

Header	Beschreibung
`Authorization`	(Erforderliche) Autorisierungstoken. Weitere Informationen dazu finden Sie unter Konfigurieren Sie RESTAPI-Authentifizierung.
`Content-Type`	(Erforderlich) Anwendung/json

Anforderungstext¶

Der Anfrage-Body enthält das Modell, die Antwortanweisung, experimentelle Felder, Tools, Tool-Ressourcen und Nachrichten.

Feld	Typ	Beschreibung
`model`	string	Der Name des Modells, das der Agent verwendet, um eine Antwort zu erzeugen. Eine Liste der unterstützten Modelle finden Sie unter Unterstützte Modelle.
`response_instruction`	string	Die Anweisungen, denen das Modell folgt, wenn es die Antwort erzeugt.
`experimental`	Objekt	Experimentelle Flaggen, die an den Agenten übergeben werden.
`tools`	Array	Eine Reihe von Tool-Spezifikationen, die dem Agenten zur Verfügung stehen.
`tool_resources`	Objekt	Von den Tools benötigte Ressourcen.
`tool_choice`	Objekt	Die Konfiguration, mit der Sie das Tool auswählen.
`messages`	Array	Array von Nachrichten in der Konversation.

Antwortanweisung¶

Das Feld response_instruction ist eine Zeichenfolge, die dem Modell Anweisungen für die Erstellung von Antworten gibt.

Tool-Konfiguration¶

Dieser Abschnitt beschreibt die unterstützten Tool-Typen, ihre Konfigurationsoptionen und wie Sie die erforderlichen Ressourcen für jedes Tool angeben.

Tool-Spezifikationen¶

Das Feld tools enthält eine Reihe von verfügbaren Tools:

Feld	Typ	Beschreibung
`tool_spec.type`	string	Der Typ des Tools. Eine Kombination aus Typ und Name ist ein eindeutiger Bezeichner.
`tool_spec.name`	string	Der Name des Tools. Eine Kombination aus Typ und Name ist ein eindeutiger Bezeichner.

Zu den unterstützten Werten von tool_spec.type gehören die folgenden:

cortex_search: Wird für die Cortex-Suchfunktionalität verwendet
cortex_analyst_text_to_sql: Verwendet für Cortex Analyst Text-zu-SQL
sql_exec: Wird für die Ausführung von SQL-Abfragen verwendet. Sie sind dafür verantwortlich, die SQL-Abfrage auszuführen und die Ergebnisse als Tool-Ergebnisse bereitzustellen. Weitere Einzelheiten finden Sie unter Beispielantworten anfordern unten.
data_to_chart: Für die Erstellung von Diagrammen

Tool-Ressourcen¶

Das Objekt tool_resources bietet Konfigurationsobjekte für jedes Tool.

tool_resources: {
    "toolName1": {configuration object for toolName1},
    "toolName2": {configuration object for toolName2},
    // ...
}

Copy

Die Konfiguration für jeden Tool-Typ wird im Folgenden beschrieben.

cortex_search

Das Objekt SearchName enthält die Konfiguration für ein Cortex Search-Tool.

"SearchName": {
    // Required: The Snowflake search service identifier
    "name": "database.schema.service_name",
    // Optional: Number of search results to include
    "max_results": 5,
    // Optional: Column to use as document title
    "title_column": "title",
    // Optional: Column to use as document identifier
    "id_column": "id",
     // Optional: Filters to apply to search results (such as @eq for equality)
    "filter": {
      "@eq": {"<column>": "<value>"}
    }
}

Copy

cortex_analyst_text_to_sql

Das Objekt AnalystName enthält die Konfiguration für ein Cortex Analyst Text-zu-SQL-Tool. Die Konfiguration muss das zu verwendende semantische Modell oder die Ansicht enthalten. Beispiel:

"AnalystName": {
    // Stage path to semantic model file in `semantic_model_file`
    "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml"
}

Copy

oder mit Überblick über die semantischen Ansichten

"AnalystName": {
    // Fully qualified name of the semantic view object
    "semantic_view": "@database.schema.semantic_view"
}

Copy

Tool-Auswahl¶

Das Feld tool_choice konfiguriert die Verhaltensweise der Tool-Auswahl.

Feld	Typ	Beschreibung
`type`	string	Wie Tools ausgewählt werden sollten. Gültige Werte: `"auto"` ` (Standard) `"required"` (mindestens ein Tool verwenden) `"tool"` (angegebenes Tool verwenden)
`name`	Array	Optionales Array der zu verwendenden Tool-Namen. Nur gültig, wenn `type = "tool"`.

Feld

Typ

Beschreibung

type

string

Wie Tools ausgewählt werden sollten.

Gültige Werte:

"auto" ` (Standard)
"required" (mindestens ein Tool verwenden)
"tool" (angegebenes Tool verwenden)

name

Array

Optionales Array der zu verwendenden Tool-Namen. Nur gültig, wenn type = "tool".

Nachrichten¶

Das Array messages enthält den Gesprächsverlauf zwischen dem Benutzer und dem Assistenten:

Feld	Typ	Beschreibung
`messages[].role`	string	Die Rolle des Absenders der Nachricht. Gültige Werte: `"system"` `"user"` `"assistant"`
`messages[].content`	Array	Array von Inhaltselementen, aus denen die Nachricht besteht.

Feld

Typ

Beschreibung

messages[].role

string

Die Rolle des Absenders der Nachricht.

Gültige Werte:

"system"
"user"
"assistant"

messages[].content

Array

Array von Inhaltselementen, aus denen die Nachricht besteht.

Struktur des Nachrichteninhalts¶

Das Array content jeder Nachricht kann mehrere Inhaltselemente mit unterschiedlichen Typen enthalten.

Feld	Typ	Beschreibung
`messages[].content[].type`	string	Der Inhaltstyp. Gültige Werte: `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`

Feld

Typ

Beschreibung

messages[].content[].type

string

Der Inhaltstyp.

Gültige Werte:

"text"
"chart"
"table"
"tool_use"
"tool_results"

Textinhalt

Wenn type "text" ist:

Feld	Typ	Beschreibung
`messages[].content[].text`	string	Der Textinhalt der Nachricht.

Beispiel:

{
  "type": "text",
  "text": "Show me sales by region for Q1 2024"
}

Copy

Diagramminhalt

Wenn type „Diagramm“ ist:

Feld	Typ	Beschreibung
`messages[].content[].chart`	Objekt	Der Diagramminhalt der Nachricht.
`messages[].content[].chart.chart_spec`	string	Diagramm als Vega-Lite Spezifikation.

Beispiel:

{
  "type": "chart",
  "chart": {
    "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{\"values\":[{\"REGION\":\"NORTH_AMERICA\",\"SUM(SALES)\":\"2000.00\"},{\"REGION\":\"EUROPE\",\"SUM(SALES)\":\"1700.00\"},{\"REGION\":\"SAUTH_AMERICA\",\"SUM(SALES)\":\"1500.00\"}]},\"encoding\":{\"x\":{\"field\":\"REGION\",\"sort\":null,\"type\":\"nominal\"},\"y\":{\"field\":\"SUM(SALES)\",\"sort\":null,\"type\":\"quantitative\"}},\"mark\":\"bar\"}",
  }
}

Copy

Tabelleninhalt

Wenn type „Tabelle“ ist:

Feld	Typ	Beschreibung
`messages[].content[].table`	Objekt	Der Tabelleninhalt der Nachricht.
`messages[].content[].table.query_id`	string	Die ID der ausgeführten Abfrage.

Beispiel:

{
  "type": "table",
  "table": {
    "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
  }
}

Copy

Tool-Verwendung

Wenn type „tool_use“ ist:

Feld	Typ	Beschreibung
`messages[].content[].tool_use`	Objekt	Container für Details der Anfrage zur Tool-Verwendung.
`messages[].content[].tool_use.tool_use_id`	string	Eindeutiger Bezeichner für diese Anfrage zur Tool-Verwendung.
`messages[].content[].tool_use.name`	string	Name des auszuführenden Tools. Muss mit einem Tool-Namen aus dem Tools-Array übereinstimmen.
`messages[].content[].tool_use.input`	Objekt	Eingabeparameter für die Ausführung des Tools.

Beispiel:

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "tu_01",
    "name": "Analyst1",
    "input": {
      "query": "Show me sales by region for Q1 2024"
    }
  }
}

Copy

Tool-Ergebnisse

Wenn type "tool_results" ist:

Feld

Typ

Beschreibung

messages[].content[].tool_results

Objekt

Container für Ausführungsergebnisse und Metadaten des Tools.

messages[].content[].tool_results.tool_use_id

string

Verweist auf die tool_use_id, die diese Ergebnisse erzeugt hat.

messages[].content[].tool_results.name

string

Name des Tools, das ausgeführt wurde. Muss mit einem Tool-Namen aus dem Tools-Array übereinstimmen.

messages[].content[].tool_results.status

string

Tool-Ausführungsstatus.

Gültige Werte:

"success"
"error"

messages[].content[].tool_results.content

Array

Array von Inhaltselementen, die durch die Ausführung des Tools erzeugt werden.

Kann Elemente der folgenden Typen enthalten:

Typ	Felder	Beschreibung
`text`	`type: "text"` `text: string`	Vom Tool zurückgegebener Inhalt im Klartext.
`json`	`type: "json"` `json: object`	Strukturierte JSON-Daten, die von dem Tool zurückgegeben werden.

Beispiel:

{
  "type": "tool_results",
  "tool_results": {
    "tool_use_id": "tu_01",
    "status": "success",
    "content": [
      {
        "type": "json",
        "json": {
          "sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
          "text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
        }
      }
    ]
  }
}

Copy

Beispiel für eine vollständige Nachricht¶

Dieses Beispiel zeigt eine vollständige Nachricht mit einer Abfrage des Benutzers (role ist user) und einer Antwort (role ist assistant). Die Antwort enthält ein Ereignis für Tool-Verwendung für ein Tools mit dem Namen Analyst1 und ein Tool-Ereignis für die Ergebnisse desselben Tools.

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Show me sales by region for Q1 2024"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tu_01",
            "name": "Analyst1",
            "input": {
              "query": "Show me sales by region for Q1 2024"
            }
          }
        },
        {
          "type": "tool_results",
          "tool_results": {
            "tool_use_id": "tu_01",
            "name": "Analyst1",
            "status": "success",
            "content": [
              {
                "type": "json",
                "json": {
                  "sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
                  "text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Copy

Antwort¶

Beim Streaming wird jedes Ereignis im Format vom Server gesendete Ereignisse (SSE) mit den folgenden primären Mustern empfangen:

Inkrementelle message.delta-Ereignisse für Blöcke der Ausgabe
error-Ereignisse, wenn etwas schief geht.

`message.delta`-Ereignis¶

Feld	Typ	Beschreibung
`event`	string	`message.delta` für partielle Nachrichtendaten.
`data`	Objekt	Enthält inkrementelle Aktualisierungsdaten.
`data.id`	string	Eindeutiger Bezeichner für die Nachricht.
`data.object`	string	`message.delta` oder einen ähnlichen Deskriptor.
`data.delta.content`	Array	Eine Liste von Blöcken oder Teilsegmenten von Nachrichten.
`data.delta.content[].index`	Ganzzahl	Die Position dieses Blocks innerhalb der aktuellen Nachricht.
`data.delta.content[].type`	string	Inhaltstyp. Gültige Werte: `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`
`data.delta.content[].text`	string	Wenn `type = "text"`, die Teilzeichenfolge.
`data.delta.content[].chart`	Objekt	Wenn `type = "chart"`, der Diagramminhalt der Nachricht.
`data.delta.content[].chart.chart_spec`	string	Diagramm als Vega-Lite Spezifikation.
`data.delta.content[].table`	Objekt	Wenn `type = "table"`, der Tabelleninhalt der Nachricht.
`data.delta.content[].table.query_id`	string	Die ID der ausgeführten Abfrage.
`data.delta.content[].tool_use`	Objekt	Wenn `type = "tool_use"`, zeigt dies an, dass ein Tool-Aufruf im Gange ist. Enthält tool_use_id, Name, Eingabe.
`data.delta.content[].tool_use.tool_use_id`	string	Der eindeutige Bezeichner für den Aufruf des Tools.
`data.delta.content[].tool_use.name`	string	Der Name des aufzurufenden Tools.
`data.delta.content[].tool_use.input`	Objekt	JSON-Nutzlast für das Tool.
`data.delta.content[].tool_results`	Objekt	Wenn `type = "tool_results"`, enthält die Ausgabe des Tools.
`data.delta.content[].tool_results.tool_use_id`	string	Der eindeutige Bezeichner für die Ausgabe des Tools.
`data.delta.content[].tool_results.status`	string	Der Ausführungsstatus des Tools. Gültige Werte: `"success"` `"error"`
`data.delta.content[].tool_results.content`	Array	Eine Liste von Elementen, die die vom Tool zurückgegebenen Daten beschreiben.
`data.delta.content[].tool_results.content[].type`	string	Der Typ des vom Tool zurückgegebenen Inhalts. Gültige Werte: `"text/csv"` `"application/json"` `"application/pdf"`
`data.delta.content[].tool_results.content[].json`	Objekt	Wenn `type = "application/json"`, die vom Tool zurückgegebenen JSON-Daten.
`data.delta.content[].tool_results.content[].text`	string	Falls `type = "text"`, die vom Tool zurückgegebenen Textdaten.

`error`-Ereignis¶

Feld	Typ	Beschreibung
`event`	string	`error` für Fehlerereignisse.
`data`	Objekt	Enthält Fehlerdetails.
`data.code`	string	Der Snowflake-Fehlercode. Zum Beispiel `"399505"`.
`data.message`	string	Eine Beschreibung dessen, was schief gelaufen ist. Zum Beispiel `"Internal server error"`.

Beispielhafter Gesprächsverlauf¶

Dieser Abschnitt zeigt einen beispielhaften Gesprächsablauf zwischen einem Benutzer und einem Assistenten unter Verwendung der Cortex Agents REST API.

Beispielanfrage¶

{
  "model": "llama3.3-70b",
  "response_instruction": "You will always maintain a friendly tone and provide concise response.",
  "experimental": {},
  "tools": [
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst1"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst2"
      }
    },
    {
      "tool_spec": {
        "type": "sql_exec",
        "name": "sql_execution_tool"
      }
    },
    {
      "tool_spec": {
        "type": "data_to_chart",
        "name": "data_to_chart"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_search",
        "name": "Search1"
      }
    }
  ],
  "tool_resources": {
    "Analyst1": { "semantic_model_file": "stage1"},
    "Analyst2": { "semantic_model_file": "stage2"},
    "Search1": {
      "name": "db.schema.service_name",
      "filter": {"@eq": {"region": "North America"} }
    }
  },
  "tool_choice": {
    "type": "auto"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What are the top three customers by revenue?"
        }
      ]
    }
  ]
}

Copy

Beispielantwort¶

{
  "id": "msg_001",
  "object": "message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "tool_use",
        "tool_use": {
          "tool_use_id": "toolu_XXXXXX",
          "name": "analyst1",
          "input": {
            "messages": [
              "role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
            ],
            "model": "snowflake-hosted-semantic",
            "experimental": ""
          }
        }
      },
      {
        "index": 0,
        "type": "tool_results",
        "tool_results": {
          "tool_use_id": "toolu_XXXXXX",
          "content": [
            {
              "type": "json",
              "json": {
                "suggestions": [],
                "sql": "WITH __customers AS (\n  SELECT\n    customer_id,\n    revenue\n  FROM user_database.user_schema.user_table\n)\nSELECT\n  customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3\n -- Generated by Cortex Analyst\n;",
                "text": "This is our interpretation of your question:\n\n__What are the top three customers by revenue?\n\n"
              }
            }
          ],
          "status": "success"
        }
      },
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_002",
            "name": "sql_execution_tool",
            "input": {
              "sql": "WITH __customers AS (SELECT customer_id, revenue FROM user_database.user_schema.user_table) SELECT customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3"
            }
          }
        }
    ]
  }
}

Copy

Anfrage von Beispielantworten¶

Cortex Agents kann auf der Grundlage ausgeführter SQL-Abfragen Text- und Diagrammantworten generieren. Das folgende Beispiel zeigt, wie Sie die Cortex Agents API verwenden, um solche Antworten zu generieren.

Um die Antworten zu erhalten, stellt der Client eine Folgeanfrage an die Cortex-Agenten API mit der query_id der SQL, die auf der Client-Seite ausgeführt wird. Das auszuführende SQL wird im Ereignis tool_use des Tool-Typs sql_exec in der letzten Antwortnachricht angegeben.

Anfragen müssen die Tools cortex_analyst_text_to_sql und sql_exec verwenden, um die textuelle Antwort zu erhalten, und darüber hinaus das Tool data_to_chart, um die Diagrammantwort zu erhalten. Diagramme werden nur zurückgegeben, wenn der Agent entscheidet, dass Diagramme eine gute Möglichkeit sind, die Antwort zu präsentieren.

Bemerkung

Für Resultsets mit mehr als 4000 Zellen wird anstelle der Antworten text und chart eine Antwort table zurückgegeben.

{
  "model": "llama3.3-70b",
  "response_instruction": "You will always maintain a friendly tone and provide concise response.",
  "experimental": {},
  "tools": [
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst1"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst2"
      }
    },
    {
      "tool_spec": {
        "type": "sql_exec",
        "name": "sql_execution_tool"
      }
    },
    {
      "tool_spec": {
        "type": "data_to_chart",
        "name": "data_to_chart"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_search",
        "name": "Search1"
      }
    }
  ],
  "tool_resources": {
    "Analyst1": { "semantic_model_file": "stage1"},
    "Analyst2": { "semantic_model_file": "stage2"},
    "Search1": {
      "name": "db.schema.service_name",
      "filter": {"@eq": {"region": "North America"} }
    }
  },
  "tool_choice": {
    "type": "auto"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What are the top three customers by revenue?"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_001",
            "name": "Analyst1",
            "input": {
              "messages": [
                "role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
              ],
              "model": "snowflake-hosted-semantic",
            }
          }
        },
        {
          "type": "tool_results",
          "tool_results": {
            "status": "success",
            "tool_use_id": "tool_001",
            "content": [
              {
                "type": "json",
                "json": {
                  "sql": "select * from table",
                  "text": "This is our interpretation of your question: What are the top three customers by revenue? \n\n"
                }
              }
            ]
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_results",
          "tool_results": {
            "tool_use_id": "tool_002",
            "result": {
              "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
            }
          }
        }
      ]
    }
  ]
}

Copy

Antwort mit Beispielantworten¶

{
  "id": "msg_001",
  "object": "message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "text",
        "text": "This is a textual answer to your question"
      },
      {
        "index": 0,
        "type": "chart",
        "chart": {
          "chart_spec": "{\"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\", \"title\": \"Example chart\", \"mark\": \"bar\", \"encoding\": {\"x\": {\"field\": \"column_x\", \"type\": \"nominal\", \"sort\": null}, \"y\": {\"field\": \"column_y\", \"type\": \"quantitative\"}}, \"data\": {\"values\": [{\"column_x\": \"A\", \"column_y\": \"1\"}, {\"column_x\": \"A\", \"column_y\": \"1\"}]}}"
        }
      }
    ]
  }
}

Copy

Beschränkungen für Cortex Agents¶

Da Streamlit in Snowflake (SiS)-Anwendungen unter den Rechten des Eigentümers ausgeführt werden, wird die Ausführung von SQL-Anweisungen innerhalb von SiS-Anwendungen nicht unterstützt.
Azure OpenAI-Modelle werden nicht unterstützt.

Cortex Agents REST API¶

Agent ausführen¶

Anfrage¶

Pfadparameter¶

Header der Anforderung¶

Anforderungstext¶

Antwortanweisung¶

Tool-Konfiguration¶

Tool-Spezifikationen¶

Tool-Ressourcen¶

Tool-Auswahl¶

Nachrichten¶

Struktur des Nachrichteninhalts¶

Beispiel für eine vollständige Nachricht¶

Antwort¶

message.delta-Ereignis¶

error-Ereignis¶

Beispielhafter Gesprächsverlauf¶

Beispielanfrage¶

Beispielantwort¶

Anfrage von Beispielantworten¶

Antwort mit Beispielantworten¶

Beschränkungen für Cortex Agents¶

`message.delta`-Ereignis¶

`error`-Ereignis¶