Kategorien:: Zeichenfolgen- und Binärfunktionen (AI-Funktionen)

DATA_AGENT_RUN (SNOWFLAKE.CORTEX)¶

Führt einen :doc:` Cortex-Agent</user-guide/snowflake-cortex/cortex-agents>` aus und gibt die Antwort als JSON zurück.

Sie können diese Funktion verwenden, um einen Cortex Agent zu starten, der sowohl über strukturierte als auch über unstrukturierte Datenquellen hinweg orchestriert, um Erkenntnisse zu liefern. Dazu gehören die Planung von Aufgaben, die Verwendung von Tools zur Ausführung dieser Aufgaben und die Generierung von Antworten.

Bemerkung

SNOWFLAKE.CORTEX.DATA_AGENT_RUN ist ein Hilfsprogramm-Wrapper im Rahmen der Cortex Agents Run API. Für die meisten Anwendungsintegrationen empfiehlt Snowflake, die Streaming RESTAPI direkt aufzurufen.

Siehe auch:: CREATE-AGENT, SHOW-AGENTS, DESCRIBE-AGENT, DROP-AGENT

Syntax¶

SNOWFLAKE.CORTEX.DATA_AGENT_RUN( '<agent_name>', <request_body> )

Copy

Argumente¶

'agent_name'

Vollqualifizierter Name des auszuführenden Agenten in der Form database.schema.agent_name.

request_body

JSON-Anforderungstext, der an den Agenten gesendet werden soll. Dieser Wert muss eine Zeichenfolge sein (z. B. ein Literal des Typs $$...$$).

Die folgenden Felder werden im Anforderungstext unterstützt:

Feld	Typ	Beschreibung
`thread_id`	Ganzzahl	Die Thread-ID für die Konversation. Wenn „thread_id“ verwendet wird, muss auch „parent_message_id“ übergeben werden.
`parent_message_id`	Ganzzahl	Die ID der übergeordneten Nachricht im Thread. Wenn dies die erste Nachricht ist, sollte „parent_message_id“ 0 sein.
`messages`	Array von Message	Wenn „thread_id“ und „parent_message_id“ in der Anfrage übergeben werden, enthalten Nachrichten die aktuelle Benutzernachricht in der Konversation. Andernfalls enthalten die Nachrichten den Konversationsverlauf und die aktuelle Nachricht. Nachrichten enthalten sowohl Benutzerabfragen als auch die Assistentenantworten in chronologischer Reihenfolge.
`stream`	boolean	Ob eine Streaming-Antwort (`text/event-stream`) oder eine Nicht-Streaming-JSON-Antwort (`application/json`) zurückgegeben werden soll. Bei „true“ wird die Antwort als vom Server gesendete Ereignisse gestreamt. Bei „false“ wird die Antwort als JSON zurückgegeben.
`tool_choice`	ToolChoice	Konfiguriert, wie der Agent während der Interaktion Tools auswählen und verwenden soll. Steuert, ob die Verwendung von Tools automatisch erfolgt, erforderlich ist oder ob bestimmte Tools verwendet werden müssen.

Beispiel

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

Copy

Wichtig

Das Feld stream wird ignoriert. Es wird immer eine Nicht-Streaming-Antwort zurückgegeben.

Rückgabewerte¶

Gibt eine JSON-Zeichenfolge zurück, die die Antwort des Agenten enthält.

Anforderungen an die Zugriffssteuerung¶

Um einen Agenten auszuführen, müssen Sie eine Rolle verwenden, die auf Cortex Agents und das Agentenobjekt, das Sie aufrufen, zugreifen kann. Weitere Details dazu finden Sie unter Anforderungen an die Zugriffssteuerung.

Nutzungshinweise¶

Die Funktion gibt eine JSON-Zeichenfolge zurück. Übergeben Sie diese Zeichenfolge an:doc:try_parse_json, um die Antwort in einen VARIANT-Wert zu konvertieren.

Beispiele¶

Starten Sie einen Agenten und analysieren Sie das Antwort-JSON:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT',
      $${
        "parent_message_id": 1234,
        "thread_id": 5678,
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS resp;

Copy

Beispielrückgabewert:

{
  "role": "assistant",
  "content": [
    {
      "thinking": {
        "text": "\n...\n"
      },
      "type": "thinking"
    },
    {
      "tool_use": {
        "input": {
          "...": "..."
        },
        "name": "<tool_name>",
        "tool_use_id": "<tool_use_id>",
        "type": "<tool_type>"
      },
      "type": "tool_use"
    },
    {
      "text": "Based on the data available, there are two main types of products...",
      "type": "text"
    }
  ],
  "metadata": {
    "run_id": "<run_id>"
  }
}

Copy