AGENT_RUN (SNOWFLAKE.CORTEX)¶

Syntax¶

SNOWFLAKE.CORTEX.AGENT_RUN( <request_body> )

Argumente¶

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.
models	ModelConfig	Modellkonfiguration für den Agenten. Enthält das Orchestrierungsmodell (z. B. claude-4-sonnet). Wenn keines angegeben ist, wird ein Modell automatisch ausgewählt. Derzeit nur für den Schritt der Orchestrierung verfügbar.
instructions	AgentInstructions	Anweisungen für das Verhalten des Agenten, einschließlich Antwort, Orchestrierung, System und Beispielfragen.
orchestration	OrchestrationConfig	Konfiguration der Orchestrierung, einschließlich Budgeteinschränkungen (z. B. Sekunden, Token).
tools	Array von Tool	Auflistung der Tools, die dem Agenten zur Verfügung stehen. Jedes Tool enthält eine „tool_spec“ mit Typ, Name, Beschreibung und Eingabeschema. Tools können über eine entsprechende Konfiguration in „tool_resources“ verfügen.
tool_resources	Zuordnung von ToolResource	Konfiguration für jedes Tool, auf das im Tools-Array verwiesen wird. Die Schlüssel müssen mit dem Namen des jeweiligen Tools übereinstimmen.

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"
    ]
  },
  "models": {
    "orchestration": "claude-4-sonnet"
  },
  "instructions": {
    "response": "You will respond in a friendly but concise manner",
    "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
    "system": "You are a friendly agent ..."
  },
  "orchestration": {
    "budget": {
      "seconds": 30,
      "tokens": 16000
    }
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "get_revenue",
        "description": "Fetch the delivery revenue for a location.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
  "tool_resources": {
    "get_revenue": {
      "type": "function",
      "execution_environment": {
        "type": "warehouse",
        "warehouse": "MY_WH"
      },
      "identifier": "DB.SCHEMA.UDF"
    }
  }
}

Copy

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 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.

• Im Gegensatz zu DATA_AGENT_RUN (SNOWFLAKE.CORTEX) erfordert diese Funktion nicht, dass Sie zuerst ein Agentenobjekt erstellen. Stattdessen geben Sie die Konfiguration direkt im Anforderungstext an.

Beispiele¶

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

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.AGENT_RUN(
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "What is the total revenue for 2025?"
              }
            ]
          }
        ],
        "models": {
          "orchestration": "claude-4-sonnet"
        }
      }$$
    )
  ) AS resp;

Beispielrückgabewert:

{
  "content": [
    {
      "text": "The total revenue for 2025 was $100,000.",
      "type": "text"
    }
  ],
  "metadata": {
    "usage": {
      "tokens_consumed": [
        {
          "context_window": 200000,
          "input_tokens": {
            "cache_read": 0,
            "cache_write": 0,
            "total": 67,
            "uncached": 67
          },
          "model_name": "claude-4-sonnet",
          "output_tokens": {
            "total": 38
          }
        }
      ]
    }
  },
  "role": "assistant"
}