Cortex Agent-Code-Ausführungstool¶

Die Cortex Agent-Code-Ausführung ist ein integriertes Tool, das es einem Agenten ermöglicht, Code während einer Konversation auszuführen. Mit Zugriff auf ein aktiviertes Code-Ausführungstool können Ihre Agenten Skripte ausführen, um Daten zu verarbeiten, Berechnungen durchzuführen und Visualisierungen zu erstellen. Standardmäßig wird das Code-Ausführungstool in einer isolierten Umgebung ausgeführt, die nur auf Daten in der aktuellen Agentensitzung zugreifen kann.

Sie aktivieren das Code-Ausführungstool, indem Sie es in einer Agentenspezifikation konfigurieren. Der Agent entscheidet dann während der Orchestrierung, wann Code auf der Grundlage der Abfrage des Benutzers generiert und ausgeführt werden soll. Das Code-Ausführungstool wird auch verwendet, wenn Python-Skripte als Teil einer Agenten-Fähigkeit ausgeführt werden.

Wie die Ausführung des Codes funktioniert¶

Der Agent nutzt die Code-Ausführung zusammen mit anderen konfigurierten Tools und Fähigkeiten. Während der Orchestrierung wertet der Agent die Abfrage des Benutzers aus und stellt fest, ob die Ausführung von Code der beste Ansatz ist. Wenn dies der Fall ist, ruft der Agent das Code-Ausführungstool auf.

Der Agent erzeugt dann Code und führt ihn in einer sicheren Sandbox aus. Standardmäßig ist die Umgebung des Code-Ausführungstools isoliert und kann nur auf Daten zugreifen, die an die Sitzung übergeben werden. Zusätzliche Lese- oder Schreibrechte können in der Spezifikation des Agenten vergeben werden.

Standardzugriffsbereich¶

Die Sandbox des Code-Ausführungstools bleibt für eine einzelne Sitzung bestehen. Die im Konversationskontext bereitgestellten Daten sind das, was dem Code-Ausführungstool für den Betrieb zur Verfügung steht. Die Sandbox speichert Importe, Variablen und Zwischenergebnisse über mehrere Ausführungen hinweg innerhalb der Sitzung.

Aktivieren des Code-Ausführungstools¶

Um das Code-Ausführungstool mit einem Cortex Agent zu verwenden, muss der Agent sowohl über die erforderlichen Zugriffssteuerungsberechtigungen als auch über den Abschnitt mit den Agentenspezifikationen verfügen, der das Code-Ausführungstool beschreibt.

Erforderliche Cortex Agent-Berechtigungen¶

Die folgenden Berechtigungen für einen Cortex Agent wirken sich auf Ihre Möglichkeit aus, den Agenten zu konfigurieren und auch abzufragen:


Berechtigung	Erforderlich für
USAGE	Ermöglicht den Aufruf des Agenten, einschließlich der Verwendung des Code-Ausführungstools
MODIFY	Ändern einer Agentenspezifikation, um das Code-Ausführungstool zu aktivieren oder zu konfigurieren
OWNERSHIP	Vollständige Kontrolle über die Konfiguration und Verwendung der Agenten

Agentenspezifikation¶

Sie aktivieren das Code-Ausführungstool, indem Sie die Ressourcen und die Konfiguration zu einer Agentenspezifikation hinzufügen.

Die Definition des Tools, das dem Abschnitt tools Ihrer Agentenspezifikation hinzugefügt werden soll, ist:

tools:
  - tool_spec:
    type: code_execution
    name: code_execution

Aktivieren Sie das Tool, indem Sie einen Abschnitt code_execution zu tool_resources in Ihrer Agentenspezifikation hinzufügen:

tool_resources:
  code_execution:

Umfassende Informationen zum Format der Agentenspezifikation und eine Anleitung, wie Sie die Spezifikation eines bestehenden Agenten ändern können, finden Sie unter Agents konfigurieren und mit ihnen interagieren.

Standardmäßig verfügbare Bibliotheken¶

Die Standard-Ausführungsumgebung für das Code-Ausführungstool verwendet Python 3.12 mit der verfügbaren Python-Standardbibliothek. Die folgenden zusätzlichen Bibliotheken sind standardmäßig verfügbar:


Bibliothek	Version
`numpy`	TKTK
`pandas`	TKTK

Hinzufügen von Bibliotheken über Artifact Repository¶

Sie können das Snowflake Standard Artefakt-Repository verwenden, um Pakete von PyPI in der Umgebung des Code-Ausführungstools abzurufen. Fügen Sie den artifact_repositories-Schlüssel zu den code_execution-Ressourcen in Ihrer Agentenspezifikation hinzu, als Liste mit einem Eintrag für SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY:

tool_resources:
  code_execution:
    artifact_repositories:
      - SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY

Um auf das PyPI-Repository zuzugreifen, müssen Sie auch die Rolle SNOWFLAKE.PYPI_REPOSITORY_USER an den Eigentümer des Cortex Agent zuweisen.

Wichtig

Damit erhält das Code-Ausführungstool Zugriff, um jedes auf PyPI veröffentlichte Paket abzurufen. Seien Sie vorsichtig, wenn Sie diesen Zugriff gewähren.

Aktivieren des externen Zugriffs¶

Sie können der Code-Ausführung den Zugriff auf externe Endpunkte über das Internet ermöglichen, indem Sie eine Netzwerkregel und eine Integration für den externen Zugriff erstellen und dann in der Spezifikation des Agenten angeben, auf welche Integrationen das Code-Ausführungstool Zugriff hat.

Das folgende Beispiel zeigt die Erstellung einer neuen Netzwerkregel (github_access_rule) und Integration des externen Zugriffs (github_integration), die den Zugriff auf github.com und einige Subdomänen über HTTP und HTTPS ermöglichen:

CREATE OR REPLACE NETWORK RULE github_access_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('github.com', 'api.github.com', 'raw.githubusercontent.com');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION github_integration
  ALLOWED_NETWORK_RULES = (github_access_rule)
  ENABLED = true;

Um Integrationen für den externen Zugriff zu aktivieren, fügen Sie die external_access_integrations-Schlüssel für die code_execution-Ressourcen in Ihrer Agentenspezifikation hinzu, die eine Liste der Integrationen für den externen Zugriff enthalten, auf die das Code-Ausführungstool zugreifen kann. Das folgende Beispiel-Snippet einer Agentenspezifikation zeigt, wie dem Code-Ausführungstool Zugriff auf die github_integration-Integration für den externen Zugriff gewährt wird:

tool_resources:
  code_execution:
    external_access_integrations:
      - github_integration

Ausführliche Informationen zum Einrichten von Netzwerkregeln und von Integrationen für den externen Zugriff finden Sie unter Erstellen und Verwenden einer Integration für den externen Zugriff.

Bekannte Einschränkungen¶

Das Cortex Agent-Tool zur Ausführung von Code unterliegt den folgenden bekannten Einschränkungen:

Einzelsitzungsbereich: Standardmäßig kann das Code-Ausführungstool nur auf Daten in der aktuellen Sitzung zugreifen. Der Status wird nicht zwischen Sitzungen oder über separate Aufrufe hinweg gemeinsam genutzt. Um die vom Code-Ausführungstool erzeugten Informationen aufzubewahren, benötigen Sie einen eigenen Persistenzspeicher auf Snowflake, auf den das Code-Ausführungstool Lese- und Schreibzugriff hat.
Vererbung des Zugriffs: Das Code-Ausführungstool arbeitet mit den Rollenberechtigungen des Eigentümers des Cortex Agent. Stellen Sie sicher, dass die Eigentümerrolle eines Agenten mit aktivierter Code-Ausführung einen angemessenen Geltungsbereich hat.