Cortex Agents mit API-Ausführung¶

Es gibt zwei Methoden, um mit einem Agenten zu interagieren:

Erstellen eines Agentenobjekts und Referenzieren dieses Agentenobjekts in einer Anfrage an die agent:run API.
Direktes Aufrufen von agent:run ohne ein Agentenobjekt. Sie geben die Konfiguration im Anfragetext von agent:run an.

Beide Methoden verwenden Streaming-APIs, die mit den unter angegebenen Streaming Responses vom Server gesendeten Ereignissen antworten.

Anforderung zur Agentenausführung mit Agentenobjekt¶

POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run

Sendet eine Benutzerabfrage an das Agentenobjekt und gibt dessen Antwort als Ereignisstream zurück.

Pfadparameter¶

Parameter	Beschreibung
`database`	(Erforderlich) Datenbank, die den Agenten enthält. Sie können die GET-Anforderung `/api/v2/databases` verwenden, um eine Liste der verfügbaren Datenbanken abzurufen.
`schema`	(Erforderlich) Schema, das den Agenten enthält. Sie können die GET-Anforderung `/api/v2/databases/{Datenbank}/schemas` verwenden, um eine Liste der verfügbaren Schemas für die angegebene Datenbank abzurufen.
`name`	(Erforderlich) Name des Agenten.

Header der Anforderung¶

Header	Beschreibung
`Authorization`	(Erforderliche) Autorisierungstoken. Siehe Authentifizierung.
`Content-Type`	(Erforderlich) Anwendung/json

Anforderungstext¶

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.
`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?"
        }
      ]
    }
  ],
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

Copy

Agent ohne Ausführung eines Agentenobjekts¶

POST /api/v2/cortex/agent:run

Sendet eine Benutzerabfrage an den im Anfragetext angegebenen Cortex Agents-Dienst und gibt dessen Antwort zurück. Interagiert mit dem Agenten, ohne ein Agentenobjekt zu erstellen.

Bemerkung

Vor dem 1. September 2025 unterschieden sich die Anfrage- und Antwortschemas für die agent:run-API von dem in diesem Dokument aufgeführten Schema. Zuvor war die Orchestrierung statisch, und es wurde dieselbe Abfolge von Tools verwendet, um eine Antwort zu generieren. agent:run verfügt jetzt über ein aktualisiertes Schema sowohl für die Anfrage als auch für die Antwort. Darüber hinaus orchestriert und iteriert die API nun dynamisch, um zur endgültigen Antwort zu gelangen. Für eine bessere Benutzererfahrung empfehlen wir, das in diesem Dokument beschriebene Schema zu verwenden.

Wenn Sie das alte Schema und Verhalten vorziehen, verwenden Sie das folgende Schema:

{
  "model": "claude-4-sonnet",
  "messages": [
     {"role":"user", "content": [] }
  ]
}

Copy

Header der Anforderung¶

Header	Beschreibung
`Authorization`	(Erforderliche) Autorisierungstoken. Siehe Authentifizierung.
`Content-Type`	(Erforderlich) Anwendung/json

Anforderungstext¶

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.
`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?"
        }
      ]
    }
  ],
  "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

Streaming-Antworten¶

Die agent:run-API bietet Streaming-Antworten. Der Server streamt Ereignisse zurück. So können Sie Antworten in Ihrer Anwendung Token für Token anzeigen, sobald sie vom Agenten generiert wurden. Jedes in der API-Antwort gestreamte Ereignis verfügt über ein streng typisiertes Schema. Im folgenden Abschnitt finden Sie eine Liste aller Ereignisse. Hier können Sie auswählen, welche Ereignisse Sie abonnieren möchten.

Das letzte von der API gesendete Ereignis ist ein response-Ereignis. Dieses Ereignis enthält die gesamte Ausgabe des Agenten. Sie können es als endgültige Antwort des Agenten verwenden. Für alle Nicht-Streaming-Clients können Sie dieses Ereignis abonnieren, da es die logische Aggregation aller vorherigen Ereignisse darstellt. Wenn Sie keine Streaming-Antworten verwenden möchten, warten Sie auf das response-Ereignis und ignorieren alle vorherigen Ereignisse.

Die meisten der anderen Ereignisse, die gestreamt werden, lassen sich in zwei Kategorien unterteilen: Delta und Inhaltselemente.

Delta-Ereignisse stellen ein einzelnes Token dar, das vom Agenten erzeugt wurde. Durch Überwachen dieser Ereignisse können Sie einen Typewriter-Effekt erzeugen. Die wichtigsten Delta-Ereignisse sind response.thinking.delta, das ein Token für logisches Denken darstellt, und response.text.delta, das ein Antworttoken darstellt.

Inhaltselement-Ereignisse stellen Elemente aus dem Array Inhalt in der endgültigen Antwort des Agenten dar.

Bemerkung

Stellen Sie sicher, dass Ihre Anwendung unbekannte Ereignistypen verarbeiten kann.

Beispielantwort

event: response.status
data: {"message":"Planning the next steps","status":"planning"}

event: response.thinking.delta
data: {"content_index":0,"text":"\nThe user is asking for a"}

event: response.thinking.delta
data: {"content_index":0,"text":" chart showing the"}

...
...
...

event: response.status
data: {"message":"Reviewing the results","status":"reasoning_agent_stop"}

event: response.status
data: {"message":"Forming the answer","status":"proceeding_to_answer"}

Copy

`response`¶

Ereignis, das gestreamt wird, sobald die endgültige Antwort verfügbar ist. Dies ist das letzte Ereignis, das ausgegeben wurde. Es stellt die Aggregation aller anderen zuvor gestreamten Ereignisse dar.

Feld	Typ	Beschreibung
`role`	string	Die Rolle für die Nachricht. Dies ist immer `assistant` in der API-Antwort.
`content`	Array von MessageContentItem	Der vom Agenten generierte Inhalt.

Beispiel

{
  "role": "assistant",
  "content": [
    {
      "type": "chart",
      "chart": {
        "tool_use_id": "toolu_123",
        "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
      }
    }
  ]
}

Copy

`response.text`¶

Ein Ereignis, das gestreamt wird, wenn das Streaming eines Text-Inhaltsblocks abgeschlossen ist. Dies schließt alle aggregierten Deltas für einen bestimmten Inhaltsindex ein.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`text`	string	Ein Textergebnis des Agenten.
`annotations`	Array von Annotation	Alle Anmerkungen, die an das Textergebnis angefügt sind (z. B. Zitate).
`is_elicitation`	boolean	Gibt an, ob es sich bei diesem Textinhalt darum handelt, dass der Agent weitere Informationen vom Benutzer anfordert.

Beispiel

{
  "content_index": 0,
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false
}

Copy

`response.text.delta`¶

Ereignis, das gestreamt wird, wenn ein neues Ausgabetextdelta generiert wird.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`text`	string	Textdelta
`is_elicitation`	boolean	Gibt an, ob es sich bei diesem Textinhalt darum handelt, dass der Agent weitere Informationen vom Benutzer anfordert.

Beispiel

{
  "content_index": 0,
  "text": "Hello",
  "is_elicitation": false
}

Copy

`response.text.annotation`¶

Ereignis, das gestreamt wird, wenn eine Anmerkung zu einem Textinhalt hinzugefügt wird.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`annotation_index`	Ganzzahl	Der Index im Anmerkungsarray, zu dem diese `annotation` gehört.
`annotation`	Annotation	Das Anmerkungsobjekt, das hinzugefügt wird.

Beispiel

{
  "content_index": 0,
  "annotation_index": 0,
  "annotation": {
    "type": "cortex_search_citation",
    "index": 0,
    "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
    "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
    "doc_title": "Earnings Report",
    "text": "The revenue for 2025 was..."
  }
}

Copy

`response.thinking`¶

Ein Ereignis, das gestreamt wird, wenn das Streaming eines Thinking-Inhaltsblocks abgeschlossen ist. Dies schließt alle aggregierten Deltas für einen bestimmten Inhaltsindex ein.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`text`	string	Thinking-Token vom Agenten

Beispiel

{
  "content_index": 0,
  "text": "To answer your question I must..."
}

Copy

`response.thinking.delta`¶

Ereignis, das gestreamt wird, wenn ein Thinking-Delta generiert wird.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`text`	string	Thinking-Token

Beispiel

{
  "content_index": 0,
  "text": "lorem ipsum"
}

Copy

`response.tool_use`¶

Ein Ereignis, das gestreamt wird, wenn der Agent eine Toolverwendung anfordert.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`tool_use_id`	string	Eindeutiger Bezeichner für diese Toolverwendung. Kann verwendet werden, um Toolergebnisse zu verknüpfen.
`type`	string	Die Art des Tools (z. B. „cortex_search“, „cortex_analyst_text2sql“).
`name`	string	Der eindeutige Bezeichner für diese Toolinstanz.
`input`	Objekt	Die strukturierte Eingabe für dieses Tool. Das Schema dieses Objekts sollte je nach Toolspezifikation variieren.
`client_side_execute`	boolean	Gibt an, ob die Toolverwendung auf Clientseite ausgeführt wird.

Beispiel

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

Copy

`response.tool_result`¶

Ereignis, das gestreamt wird, wenn die Ausführung eines Tools beendet ist, einschließlich des Ergebnisses des Tools.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`tool_use_id`	string	Eindeutiger Bezeichner für diese Toolverwendung. Kann verwendet werden, um Toolergebnisse zu verknüpfen.
`type`	string	Die Art des Tools (z. B. „cortex_search“, „cortex_analyst_text2sql“).
`name`	string	Der eindeutige Bezeichner für diese Toolinstanz.
`content`	Array von ToolResultContent	Der Inhalt des Toolergebnisses.
`status`	string	Der Status der Ausführung des Tools.

Beispiel

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

Copy

`response.tool_result.status`¶

Aktualisierung des Status für eine bestimmte Verwendung des Tools.

Feld	Typ	Beschreibung
`tool_use_id`	string	Eindeutiger Bezeichner für diese Toolverwendung.
`tool_type`	string	Die Art des Tools (z. B. „cortex_search“, „cortex_analyst_text2sql“).
`status`	string	Aufzählung für den aktuellen Status.
`message`	string	Eine aussagekräftigere Nachricht, die den aktuellen Status näher erläutert.

Beispiel

{
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text2sql",
  "status": "Executing SQL",
  "message": "Executing query 'SELECT * FROM my_table'"
}

Copy

`response.tool_result.analyst.delta`¶

Ein Delta-Ereignis, das für die Ausführung des Cortex Analyst-Tools gestreamt wird.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`tool_use_id`	string	Eindeutiger Bezeichner für diese Toolverwendung. Kann verwendet werden, um Toolergebnisse zu verknüpfen.
`tool_type`	string	Die Art des Tools (für dieses Ereignis immer „cortex_analyst_text2sql“).
`tool_name`	string	Der eindeutige Bezeichner für diese Toolinstanz.
`delta`	CortexAnalystToolResultDelta	Das Inhaltsdelta

Beispiel

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text2sql",
  "tool_name": "my_cortex_analyst_semantic_view",
  "delta": {
    "text": "The...",
    "think": "Thinking...",
    "sql": "SELECT...",
    "sql_explanation": "This...",
    "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "verified_query_used": false,
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "suggestions": {
      "index": 0,
      "delta": "What..."
    }
  }
}

Copy

`response.table`¶

Ein Ereignis, das gestreamt wird, wenn ein Tabelleninhaltsblock hinzugefügt wird.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`tool_use_id`	string	Die ID der Toolverwendung, die diese Tabelle generiert hat.
`query_id`	string	Die Abfrage-ID der SQL-Abfrage , die diese Daten erzeugt hat.
`result_set`	ResultSet	Die SQL-Ergebnisse zum Rendern einer Tabelle. Entspricht dem Schema des SQL-API-ResultSet von Snowflake (https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset)
`title`	string	Der Titel für diese Tabelle

Beispiel

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

Copy

`response.chart`¶

Ein Ereignis, das gestreamt wird, wenn ein Diagramminhaltsblock hinzugefügt wird.

Feld	Typ	Beschreibung
`content_index`	Ganzzahl	Der Index im Antwortinhaltsarray, das dieses Ereignis darstellt.
`tool_use_id`	string	Die ID der Toolverwendung, die dieses Diagramm generiert hat.
`chart_spec`	string	Die „vega-lite“-Diagrammspezifikation, serialisiert als Zeichenfolge.

Beispiel

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

Copy

`response.status`¶

Aktualisierung des Status der Agentausführung.

Feld	Typ	Beschreibung
`status`	string	Aufzählung für den aktuellen Status.
`message`	string	Eine aussagekräftigere Nachricht, die den aktuellen Status näher erläutert.

Beispiel

{
  "status": "executing_tool",
  "message": "Executing tool `my_analyst_tool`"
}

Copy

`error`¶

Wird gesendet, wenn ein schwerwiegender Fehler auftritt.

Feld	Typ	Beschreibung
`code`	string	Der Snowflake-Fehlercode.
`message`	string	Die Fehlermeldung
`request_id`	string	Der eindeutige Bezeichner dieser Anforderung.

Beispiel

{
  "code": "399504",
  "message": "Error during execution",
  "request_id": "61987ff6-6d56-4695-83c0-1e7cfed818c7"
}

Copy

`metadata`-Ereignis¶

Metadaten zur Anforderung. Dieses Ereignis wird gesendet, wenn eine Nachricht zum Thread hinzugefügt wird. Es ist nützlich, um die parent_message_id für die Verwendung in folgenden Anfragen an die Agenten-API zu erhalten.

Feld	Typ	Beschreibung
`role`	string	Gibt an, wer die Nachricht gesendet hat – entweder der Benutzer oder der Assistent.
`message_id`	Ganzzahl	Die ID der Thread-Nachricht. Verwenden Sie diese ID (wenn die Rolle `assistant` ist), um eine Folgefrage im Thread zu stellen.

Beispiel

{
  "role": "user",
  "message_id": 0
}

Copy

Schemas¶

`AgentInstructions`¶

Feld	Typ	Beschreibung
`response`	string	Anweisungen zum Generieren der Antwort.
`orchestration`	string	Diese kundenspezifischen Anweisungen werden verwendet, wenn der Agent plant, welche Tools verwendet werden sollen.
`system`	string	Systemanweisungen für den Agenten.

Beispiel

{
  "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 ..."
}

Copy

`Annotation`¶

Feld

Typ

Beschreibung

type

string

Der Zitattyp (immer cortex_search_citation)

index

Ganzzahl

Der Index des Zitats in den Suchergebnissen.

search_result_id

string

Der eindeutige Bezeichner für das Suchergebnis.

doc_id

string

Der eindeutige Bezeichner für das Dokument.

doc_title

string

Der Titel des Dokuments.

text

string

Der Textauszug aus dem Dokument, das als Zitat verwendet wurde.

Beispiel
{
  "type": "cortex_search_citation",
  "index": 0,
  "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
  "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
  "doc_title": "Earnings Report",
  "text": "The revenue for 2025 was..."
}
Copy

Feld	Typ	Beschreibung
`type`	string	Der Zitattyp (immer `cortex_search_citation`)
`index`	Ganzzahl	Der Index des Zitats in den Suchergebnissen.
`search_result_id`	string	Der eindeutige Bezeichner für das Suchergebnis.
`doc_id`	string	Der eindeutige Bezeichner für das Dokument.
`doc_title`	string	Der Titel des Dokuments.
`text`	string	Der Textauszug aus dem Dokument, das als Zitat verwendet wurde.

`BudgetConfig`¶

Feld	Typ	Beschreibung
`seconds`	Ganzzahl	Zeitbudget in Sekunden.
`tokens`	Ganzzahl	Token-Budget.

Beispiel

{
  "seconds": 30,
  "tokens": 16000
}

Copy

`ChartContent`¶

Feld	Typ	Beschreibung
`tool_use_id`	string	Die ID der Toolverwendung, die dieses Diagramm generiert hat.
`chart_spec`	string	Die „vega-lite“-Diagrammspezifikation, serialisiert als Zeichenfolge.

Beispiel

{
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

Copy

`CortexAnalystSuggestionDelta`¶

Feld	Typ	Beschreibung
`index`	Ganzzahl	Der Index des Vorschlagsarrays, das dieses Delta darstellt.
`delta`	string	Das Textdelta für den Vorschlag in diesem Index.

Beispiel

{
  "index": 0,
  "delta": "What..."
}

Copy

`CortexAnalystToolResultDelta`¶

Feld	Typ	Beschreibung
`text`	string	Ein Textdelta aus der endgültigen Antwort von Cortex Analyst.
`think`	string	Ein Textdelta aus den Argumentationsschritten von Cortex Analyst.
`sql`	string	Ein Delta aus der SQL-Ausgabe von Cortex Analyst. Derzeit entspricht die gesamte SQL-Abfrage einem einzelnen Ereignis. Es kann aber sein, dass wir das SQL künftig Token für Token streamen.
`sql_explanation`	string	Ein Delta aus der Erklärung von Cortex Analyst, was die ist SQL-Abfrage tut.
`query_id`	string	Die Abfrage-ID nach dem Starten der SQL-Ausführung.
`verified_query_used`	boolean	Gibt an, ob eine verifizierte Abfrage verwendet wurde, um diese Antwort zu generieren.
`result_set`	ResultSet	Die Ergebnisse der SQL-Ausführung. Entspricht dem Schema des SQL-API-ResultSet von Snowflake (https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset)
`suggestions`	CortexAnalystSuggestionDelta	Ein Delta aus den vorgeschlagenen Fragen von Cortex Analyst. Wird gesendet, wenn Analyst die Frage aufgrund fehlender Informationen oder anderer Fehler nicht beantworten kann.

Beispiel

{
  "text": "The...",
  "think": "Thinking...",
  "sql": "SELECT...",
  "sql_explanation": "This...",
  "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "verified_query_used": false,
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "suggestions": {
    "index": 0,
    "delta": "What..."
  }
}

Copy

`ExecutionEnvironment`¶

Konfiguration für vom Server ausgeführte Tools.

Feld	Typ	Beschreibung
`type`	string	Der Typ der Ausführungsumgebung, derzeit wird nur `Warehouse` unterstützt.
`warehouse`	string	Name des Warehouse. Es wird zwischen Groß-/Kleinschreibung unterschieden. Wenn es sich um einen Bezeichner ohne Anführungszeichen handelt, geben Sie den Namen in Großbuchstaben an.
`query_timeout`	Ganzzahl	Abfrage-Timeout in Sekunden.

Beispiel

{
  "type": "warehouse",
  "warehouse": "MY_WAREHOUSE",
  "query_timeout": 60
}

Copy

`Message`¶

Stellt eine einzelne Nachricht in der Konversation dar. Kann vom Benutzer oder Assistenten sein.

Feld	Typ	Beschreibung
`role`	string	Gibt an, wer die Nachricht gesendet hat – entweder der Benutzer oder der Assistent. Benutzernachrichten enthalten i. d. R. Abfragen, während Assistentennachrichten Antworten und Toolergebnisse umfassen.
`content`	Array von MessageContentItem	Array von Inhaltselementen, aus denen die Nachricht besteht. Kann Text, Toolergebnisse oder kundenspezifische Inhaltstypen enthalten.

Beispiel

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What is the total revenue for 2023?"
    }
  ]
}

Copy

`MessageContentItem`¶

Feld	Typ	Beschreibung
`type`	string	Der Inhaltstyp (immer `chart`).
`chart`	ChartContent	Das Diagramm.

Beispiel

{
  "type": "chart",
  "chart": {
    "tool_use_id": "toolu_123",
    "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
  }
}

Copy

Feld	Typ	Beschreibung
`type`	string	Der Inhaltstyp (immer `table`).
`table`	TableContent	Die Tabelle.

Beispiel

{
  "type": "table",
  "table": {
    "tool_use_id": "toolu_123",
    "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "title": "Revenue by Month"
  }
}

Copy

Feld	Typ	Beschreibung
`text`	string	Ein Textergebnis des Agenten.
`annotations`	Array von Annotation	Alle Anmerkungen, die an das Textergebnis angefügt sind (z. B. Zitate).
`is_elicitation`	boolean	Gibt an, ob es sich bei diesem Textinhalt darum handelt, dass der Agent weitere Informationen vom Benutzer anfordert.
`type`	string	Der Inhaltstyp (immer `text`).

Beispiel

{
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false,
  "type": "text"
}

Copy

Feld	Typ	Beschreibung
`type`	string	Der Inhaltstyp (immer `thinking`).
`thinking`	ThinkingContent	Der Inhalt des logischen Denkens.

Beispiel

{
  "type": "thinking",
  "thinking": {
    "text": "To answer your question I must..."
  }
}

Copy

Feld	Typ	Beschreibung
`type`	string	Der Inhaltstyp (immer `tool_result`).
`tool_result`	ToolResult	Das Ergebnis des Tools.

Beispiel

{
  "type": "tool_result",
  "tool_result": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text2sql",
    "name": "my_cortex_analyst_semantic_view",
    "content": [
      {
        "type": "json",
        "json": {
          "answer": 42
        }
      }
    ],
    "status": "success"
  }
}

Copy

Feld	Typ	Beschreibung
`type`	string	Der Inhaltstyp (immer `tool_use`).
`tool_use`	ToolUse	Die Verwendung des Tools.

Beispiel

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text2sql",
    "name": "my_cortex_analyst_semantic_view",
    "input": {
      "location": "San Francisco, CA"
    },
    "client_side_execute": "true"
  }
}

Copy

`ModelConfig`¶

Feld	Typ	Beschreibung
`orchestration`	string	Modell, das für die Orchestrierung verwendet werden soll. Wenn keines angegeben ist, wird ein Modell automatisch ausgewählt.

Beispiel

{
  "orchestration": "claude-4-sonnet"
}

Copy

`OrchestrationConfig`¶

Feld	Typ	Beschreibung
`budget`	BudgetConfig	Budgeteinschränkungen für den Agenten. Wenn mehr als eine Einschränkung angegeben ist, wird die Anfrage bei der ersten Einschränkung beendet.

Beispiel

{
  "budget": {
    "seconds": 30,
    "tokens": 16000
  }
}

Copy

`ResultSet`¶

Feld	Typ	Beschreibung
`statementHandle`	string	Die Abfrage-ID.
`resultSetMetaData`	ResultSetMetaData	Metadaten zum Resultset.
`data`	Array von Array	2D-Array, das die Daten darstellt.

Beispiel

{
  "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "resultSetMetaData": {
    "partition": 0,
    "numRows": 0,
    "format": "jsonv2",
    "rowType": [
      {
        "name": "my_column",
        "type": "VARCHAR",
        "length": 0,
        "precision": 0,
        "scale": 0,
        "nullable": false
      }
    ]
  },
  "data": [
    [
      "row1 col1",
      "row1 col2"
    ],
    [
      "row2 col1",
      "row2 col2"
    ]
  ]
}

Copy

`ResultSetMetaData`¶

Feld	Typ	Beschreibung
`partition`	Ganzzahl	Die Indexnummer der Partition.
`numRows`	Ganzzahl	Die Gesamtzahl der Ergebniszeilen.
`format`	string	Format der Daten im Resultset.
`rowType`	Array von RowType	Beschreibung der Spalten im Ergebnis.

Beispiel

{
  "partition": 0,
  "numRows": 0,
  "format": "jsonv2",
  "rowType": [
    {
      "name": "my_column",
      "type": "VARCHAR",
      "length": 0,
      "precision": 0,
      "scale": 0,
      "nullable": false
    }
  ]
}

Copy

`RowType`¶

Feld	Typ	Beschreibung
`name`	string	Name der Spalte.
`type`	string	Snowflake-Datentypen der Spalte. (https://docs.snowflake.com/en/sql-reference/intro-summary-data-types)
`length`	Ganzzahl	Länge der Spalte.
`precision`	Ganzzahl	Genauigkeit der Spalte.
`scale`	Ganzzahl	Skalierung der Spalte.
`nullable`	boolean	Gibt an, ob die Spalte nullwertfähig ist oder nicht.

Beispiel

{
  "name": "my_column",
  "type": "VARCHAR",
  "length": 0,
  "precision": 0,
  "scale": 0,
  "nullable": false
}

Copy

`TableContent`¶

Feld	Typ	Beschreibung
`tool_use_id`	string	Die ID der Toolverwendung, die diese Tabelle generiert hat.
`query_id`	string	Die Abfrage-ID der SQL-Abfrage , die diese Daten erzeugt hat.
`result_set`	ResultSet	Die SQL-Ergebnisse zum Rendern einer Tabelle. Entspricht dem Schema des SQL-API-ResultSet von Snowflake (https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset)
`title`	string	Der Titel für diese Tabelle

Beispiel

{
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

Copy

`ThinkingContent`¶

Feld	Typ	Beschreibung
`text`	string	Thinking-Token vom Agenten

Beispiel

{
  "text": "To answer your question I must..."
}

Copy

`Tool`¶

Definiert ein Tool, das vom Agenten verwendet werden kann. Tools stellen bestimmte Fähigkeiten wie Datenanalyse, Suche oder allgemeine Funktionen bereit.

Feld	Typ	Beschreibung
`tool_spec`	ToolSpec	Spezifikation der Art, Konfiguration und Eingabeanforderungen des Tools.

Beispiel

{
  "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"
    ]
  }
}

Copy

`ToolChoice`¶

Feld	Typ	Beschreibung
`type`	string	Legt fest, wie Tools ausgewählt werden: – auto – automatische Toolauswahl (Standard) – required – Es muss mindestens ein Tool verwendet werden – tool – Verwenden Sie bestimmte benannte Tools.
`name`	Ein Array von Zeichenfolgen.	Liste der spezifischen Toolnamen, die verwendet werden sollen, wenn der Typ „tool“ ist.

Beispiel

{
  "type": "auto",
  "name": [
    "analyst_tool",
    "search_tool"
  ]
}

Copy

`ToolInputSchema`¶

Feld	Typ	Beschreibung
`type`	string	Der Typ des Eingabeschemaobjekts.
`description`	string	Eine Beschreibung der Eingabe.
`properties`	Zuordnung von ToolInputSchema	Beim Typ `object` Definitionen jedes Eingabeparameters.
`items`	ToolInputSchema	Beim Typ `array` das Schema für die Elemente des Arrays.
`required`	Ein Array von Zeichenfolgen.	Beim Typ `object` eine Liste der Namen der erforderlichen Eingabeparameter.

Beispiel

{
  "type": "object",
  "description": "Input for my custom tool",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, e.g. San Francisco, CA"
    }
  },
  "items": {},
  "required": [
    "location"
  ]
}

Copy

`ToolResource`¶

Konfiguration für das Analysetool Text-to-SQL. Stellt Parameter für die SQL-Abfragegenerierung und -ausführung bereit. Es muss genau eines von „semantic_model_file“ oder „semantic_view“ angegeben werden.

Feld

Typ

Beschreibung

semantic_model_file

string

Der Pfad zu einer Datei, die in einem Snowflake-Stagingbereich gespeichert ist, welches das semantische Modell „yaml“ enthält.

semantic_view

string

Der Name des nativen semantischen Modellobjekts von Snowflake.

execution_environment

ExecutionEnvironment

Konfiguration für die Ausführung der generierten SQL-Abfrage.

Beispiel
{
  "semantic_model_file": "@db.schema.stage/semantic_model.yaml",
  "semantic_view": "db.schema.semantic_view",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  }
}
Copy
Konfiguration der Suchfunktionalität. Legt fest, wie die Suche und das Abrufen von Dokumenten durchgeführt werden soll.

Feld

Typ

Beschreibung

search_service

string

Der vollqualifizierte Name des Suchservice.

title_column

string

Die Titelspalte des Dokuments.

id_column

string

Die ID-Spalte des Dokuments.

filter

Objekt

Filtern der Abfrage nach Suchergebnissen.

Beispiel
{
  "search_service": "database.schema.service_name",
  "title_column": "account_name",
  "id_column": "account_id",
  "filter": {
    "@eq": {
      "<column>": "<value>"
    }
  }
}
Copy
Feld

Typ

Beschreibung

type

string

Ob das Tool serverseitig ausgeführt wird, unabhängig davon, ob es sich um eine gespeicherte Prozedur oder eine UDF handelt.

execution_environment

ExecutionEnvironment

identifier

string

Vollqualifizierter Name der gespeicherten Prozedur oder UDF.

Beispiel
{
  "type": "function",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  },
  "identifier": "MY_DB.MY_SCHEMA.MY_UDF"
}
Copy

Feld	Typ	Beschreibung
`semantic_model_file`	string	Der Pfad zu einer Datei, die in einem Snowflake-Stagingbereich gespeichert ist, welches das semantische Modell „yaml“ enthält.
`semantic_view`	string	Der Name des nativen semantischen Modellobjekts von Snowflake.
`execution_environment`	ExecutionEnvironment	Konfiguration für die Ausführung der generierten SQL-Abfrage.

Feld	Typ	Beschreibung
`search_service`	string	Der vollqualifizierte Name des Suchservice.
`title_column`	string	Die Titelspalte des Dokuments.
`id_column`	string	Die ID-Spalte des Dokuments.
`filter`	Objekt	Filtern der Abfrage nach Suchergebnissen.

Feld	Typ	Beschreibung
`type`	string	Ob das Tool serverseitig ausgeführt wird, unabhängig davon, ob es sich um eine gespeicherte Prozedur oder eine UDF handelt.
`execution_environment`	ExecutionEnvironment
`identifier`	string	Vollqualifizierter Name der gespeicherten Prozedur oder UDF.

`ToolResult`¶

Feld	Typ	Beschreibung
`tool_use_id`	string	Eindeutiger Bezeichner für diese Toolverwendung. Kann verwendet werden, um Toolergebnisse zu verknüpfen.
`type`	string	Die Art des Tools (z. B. „cortex_search“, „cortex_analyst_text2sql“).
`name`	string	Der eindeutige Bezeichner für diese Toolinstanz.
`content`	Array von ToolResultContent	Der Inhalt des Toolergebnisses.
`status`	string	Der Status der Ausführung des Tools.

Beispiel

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

Copy

`ToolResultContent`¶

Feld

Typ

Beschreibung

type

string

Der Typ des Ergebnisses (immer json).

json

Objekt

Strukturierte Ausgabe von einem Tool. Das Schema variiert je nach Tooltyp.

Beispiel
{
  "type": "json",
  "json": {
    "answer": 42
  }
}
Copy
Feld

Typ

Beschreibung

type

string

Der Typ des Ergebnisses (immer text)

text

string

Der Ergebnistext

Beispiel
{
  "type": "text",
  "text": "The answer is 42"
}
Copy

Feld	Typ	Beschreibung
`type`	string	Der Typ des Ergebnisses (immer `json`).
`json`	Objekt	Strukturierte Ausgabe von einem Tool. Das Schema variiert je nach Tooltyp.

Feld	Typ	Beschreibung
`type`	string	Der Typ des Ergebnisses (immer `text`)
`text`	string	Der Ergebnistext

`ToolSpec`¶

Spezifikation der Art, Konfiguration und Eingabeanforderungen des Tools.

Feld	Typ	Beschreibung
`type`	string	Die Art der Tool-Fähigkeit. Dies können spezielle Arten wie „cortex_analyst_text_to_sql“ oder „generic“ für allgemeine Tools sein.
`name`	string	Eindeutiger Bezeichner zum Verweisen auf diese Toolinstanz. Wird für den Abgleich mit der Konfiguration in „tool_resources“ verwendet.
`description`	string	Beschreibt das Tool, das für die Toolverwendung berücksichtigt werden soll.
`input_schema`	ToolInputSchema	JSON-Schemadefinition der erwarteten Eingabeparameter für dieses Tool. Sie wird an den Agenten weitergeleitet, sodass dieser die Struktur kennt, der er beim Generieren der Eingabe für ToolUses folgen soll. Erforderlich für generische Tools zur Angabe ihrer Eingabeparameter.

Beispiel

{
  "type": "generic",
  "name": "get_weather",
  "description": "lorem ipsum",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      }
    },
    "required": [
      "location"
    ]
  }
}

Copy

`ToolUse`¶

Feld	Typ	Beschreibung
`tool_use_id`	string	Eindeutiger Bezeichner für diese Toolverwendung. Kann verwendet werden, um Toolergebnisse zu verknüpfen.
`type`	string	Die Art des Tools (z. B. „cortex_search“, „cortex_analyst_text2sql“).
`name`	string	Der eindeutige Bezeichner für diese Toolinstanz.
`input`	Objekt	Die strukturierte Eingabe für dieses Tool. Das Schema dieses Objekts sollte je nach Toolspezifikation variieren.
`client_side_execute`	boolean	Gibt an, ob die Toolverwendung auf Clientseite ausgeführt wird.

Beispiel

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

Copy

Cortex Agents mit API-Ausführung¶

Anforderung zur Agentenausführung mit Agentenobjekt¶

Pfadparameter¶

Header der Anforderung¶

Anforderungstext¶

Agent ohne Ausführung eines Agentenobjekts¶

Header der Anforderung¶

Anforderungstext¶

Streaming-Antworten¶

response¶

response.text¶

response.text.delta¶

response.text.annotation¶

response.thinking¶

response.thinking.delta¶

response.tool_use¶

response.tool_result¶

response.tool_result.status¶

response.tool_result.analyst.delta¶

response.table¶

response.chart¶

response.status¶

error¶

metadata-Ereignis¶

Schemas¶

AgentInstructions¶

Annotation¶

BudgetConfig¶

ChartContent¶

CortexAnalystSuggestionDelta¶

CortexAnalystToolResultDelta¶

ExecutionEnvironment¶

Message¶

MessageContentItem¶

ModelConfig¶

OrchestrationConfig¶

ResultSet¶

ResultSetMetaData¶

RowType¶

TableContent¶

ThinkingContent¶

Tool¶

ToolChoice¶

ToolInputSchema¶

ToolResource¶

ToolResult¶

ToolResultContent¶

ToolSpec¶

ToolUse¶

`response`¶

`response.text`¶

`response.text.delta`¶

`response.text.annotation`¶

`response.thinking`¶

`response.thinking.delta`¶

`response.tool_use`¶

`response.tool_result`¶

`response.tool_result.status`¶

`response.tool_result.analyst.delta`¶

`response.table`¶

`response.chart`¶

`response.status`¶

`error`¶

`metadata`-Ereignis¶

`AgentInstructions`¶

`Annotation`¶

`BudgetConfig`¶

`ChartContent`¶

`CortexAnalystSuggestionDelta`¶

`CortexAnalystToolResultDelta`¶

`ExecutionEnvironment`¶

`Message`¶

`MessageContentItem`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`ResultSet`¶

`ResultSetMetaData`¶

`RowType`¶

`TableContent`¶

`ThinkingContent`¶

`Tool`¶

`ToolChoice`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolResult`¶

`ToolResultContent`¶

`ToolSpec`¶

`ToolUse`¶