Cortex Agent-Versionierung¶

So funktioniert die Versionierung von Agenten¶

Der Lebenszyklus eines Agenten folgt einem Commit-basierten Modell:

1. Wenn Sie einen Agenten erstellen, erstellt dieser automatisch eine übergebene VERSION$1-Version und eine LIVE-Version mit derselben Spezifikation.

2. Sie erstellen oder ändern die Live-Version des Agenten während der Entwicklung.

3. Wenn der Agent für die Bereitstellung bereit ist, übertragen Sie die Live-Version. Snowflake erstellt eine benannte Version mit einem vom System zugewiesenen Bezeichner im Format VERSION$N (z. B. VERSION$2, VERSION$3).

4. Sie weisen einen Alias zu oder legen die benannte Version als Standard fest.

5. Interaktionsanforderungen zielen auf die benannte Version ab – entweder über den Namen, den Alias oder die Tastenkombination – um ein stabiles, wiederholbares Verhalten zu erreichen.

Nach einem Commit wird die Live-Version nicht automatisch neu erstellt. Sie erstellen explizit eine neue Live-Version, wenn Sie bereit sind, die Entwicklung fortzusetzen.

Sie können benannte Versionen auch direkt aus einem Stagingbereich oder Git-Repository erstellen, ohne die Live-Version durchgehen zu müssen. Dies unterstützt Workflows, bei denen Änderungen offline zusammengeführt und dann als neue Version importiert werden.

Live-Versionen¶

Die Live-Version ist der veränderbare, bearbeitbare Zustand eines Agenten. Sie verwenden sie während der Entwicklung, um die Konfiguration, die Anweisungen, die Tools und die Fähigkeiten des Agenten zu iterieren. Jeder Agent kann immer nur eine Live-Version haben.

Für das Erstellen einer Live-Version gibt es folgende Möglichkeiten:

• Von der Agentenerstellung: Wenn Sie einen neuen Agenten erstellen, wird automatisch eine Live-Version erstellt.

• Von der letzten bestätigten Version: Stellen Sie die Live-Version von der letzten benannten Version wieder her, um die Entwicklung von einem bekannten Zustand aus fortzusetzen.

• Von der |sf-web-interface| UI: Die UI kann die Erstellung einer neuen Live-Version veranlassen.

-- Create a live version from the last committed version
ALTER AGENT my_agent ADD LIVE VERSION FROM LAST
  COMMENT = 'Resuming development from v3';

Sie können der Live-Version zum Zeitpunkt der Erstellung optional einen Alias zuweisen:

-- Create a live version with an alias
ALTER AGENT my_agent ADD LIVE VERSION dev FROM LAST;

Die Live-Version ist für die interaktive Entwicklung konzipiert. Snowflake empfiehlt, die Live-Version zu committen, bevor Sie sie in der Produktion verwenden, um sicherzustellen, dass Sie einen unveränderlichen Referenzpunkt haben.

Benannte Versionen¶

Eine benannte Version ist ein unveränderlicher Snapshot der Konfiguration des Agenten zum Zeitpunkt des Commit. Einmal erstellt, kann eine benannte Version nicht mehr geändert werden – Sie können nur ihre Metadaten aktualisieren (Kommentar oder Alias) oder sie ganz löschen. Diese Unveränderlichkeit macht benannte Versionen zur Grundlage für stabile, reproduzierbare Bereitstellungen.

Snowflake weist jeder benannten Version eine Systembezeichner im Format VERSION$N zu, wobei N sich bei jedem Commit erhöht:

-- Commit the live version to create a named version
ALTER AGENT my_agent COMMIT
  COMMENT = 'Production release for Q1';

Dadurch wird VERSION$2 (oder die nächste verfügbare Zahl) erstellt. Sie können benannte Versionen auch direkt aus einem Stagingbereich oder Git-Repository erstellen:

-- Create a named version from a stage
ALTER AGENT my_agent ADD VERSION FROM @my_stage/agents/my_agent
  COMMENT = 'Imported from feature branch';

So zeigen Sie alle Versionen eines Agenten an:

SHOW VERSIONS IN AGENT my_agent;

Um eine benannte Version zu entfernen, ist Folgendes nicht mehr erforderlich:

ALTER AGENT my_agent DROP VERSION VERSION$1;

Aliasse¶

Ein Alias ist eine von Menschen lesbare Bezeichnung, die Sie einer Version zuweisen. Aliasse erleichtern das Referenzieren von Versionen in API-Aufrufen und Stagingoperationen, ohne die vom System zugewiesene Versionsnummer zu kennen. Zu den üblichen Alias-Mustern gehören production, staging, canary und rollback.

Sie weisen einer benannten Version oder der Live-Version einen Alias zu:

-- Assign an alias to a named version
ALTER AGENT my_agent
  MODIFY VERSION VERSION$3 SET ALIAS = production;

-- Assign an alias to the live version
ALTER AGENT my_agent
  MODIFY LIVE VERSION SET ALIAS = dev;

Einmal zugewiesen, können Sie den Alias überall dort verwenden, wo ein Versionsbezeichner akzeptiert wird – in API-Aufrufen, Stagingbereich-URIs und SQL-Befehlen.

Alias-Verhalten:

• Jeder Alias muss innerhalb eines Agenten eindeutig sein.

• Aliasnamen werden zwischen Groß- und Kleinschreibung unterschieden, wenn sie mit Bezeichnern in doppelten Anführungszeichen erstellt werden. Andernfalls werden sie in Großbuchstaben gespeichert.

• Sie können einen Alias von einer Version auf eine andere neu zuweisen, um den Datenverkehr umzuleiten, ohne den aufrufenden Code zu ändern.

Um beispielsweise eine neue Version in die Produktion zu überführen, weisen Sie den``production``-Alias neu zu:

-- Point the production alias to the latest version
ALTER AGENT my_agent
  MODIFY VERSION VERSION$4 SET ALIAS = production;

Alle API-Aufrufe, die auf den production-Alias abzielen, werden jetzt zu VERSION$4 weitergeleitet, ohne dass die aufrufende Anwendung geändert wird.

Tastenkombinationen bei Versionen¶

Snowflake bietet integrierte Tastenkombinationen für das Referenzieren von Versionen an, ohne dass der genaue Versionsname oder Alias bekannt ist. Sie können diese Tastenkombinationen im API-Endpunkt und in den StagingbereichURIs verwenden:

Tastenkombinationen sind nützlich für Automatisierungsskripte und CI-/CD-Pipelines, bei denen die genaue Versionsnummer nicht im Voraus bekannt ist. Beispielsweise können Sie mit dem Kürzel LAST immer die zuletzt übergebene Version ausführen oder gezielt die Version ansteuern, die vom Eigentümer des Agenten als Standard festgelegt wurde

Standardversion¶

Wenn Sie nichts explizit festlegen, ist die DEFAULT-Version die letzte übergebene Version. Sie können auch eine Version als Standard für den Agenten festlegen. Die Standardversion ist die Version, die der Agent verwendet, wenn in einem API-Aufruf keine Version angegeben ist.

-- Set the default version
ALTER AGENT my_agent
  SET DEFAULT_VERSION = 'VERSION$3';

Sie können den Standard auch auf eine Systemverknüpfung wie FIRST oder LAST festlegen.

ALTER AGENT my_agent
  SET DEFAULT_VERSION = LAST;

Durch das Festlegen einer Standardversion können Sie kontrollieren, welche Version den Datenverkehr bedient, ohne dass der Aufrufer in jeder Anforderung eine Version angeben muss. Wenn Sie eine neue Version hochstufen, aktualisieren Sie die Standardeinstellung, um alle nicht versionierten API-Aufrufe umzuleiten.

Versionierung und CI/CD¶

Die Versionierung von Agenten lässt sich in CI-/CD-Workflows integrieren, indem sie die Erstellung von Versionen aus externen Quellen – wie Stagingbereiche und Git-Repositorys – unterstützt und Aliase sowie Kürzel für das Umgebungsrouting bereitstellt.

Ein typischer CI-/CD-Workflow für Agenten folgt diesem Muster:

1. Entwickeln: Bearbeiten Sie die Live-Version des Agenten auf in der Snowsight UI oder überSQL. Testen Sie interaktiv.

2. Commit: Wenn der Agent fertig ist, übertragen Sie die Live-Version, um eine unveränderliche benannte Version zu erstellen.

3. Testen: Leiten Sie den Testdatenverkehr an die neue benannte Version unter Verwendung der System-ID oder eines staging-Alias weiter

4. Heraufstufen: Weisen Sie den production-Alias wieder der neuen Version zu, sobald die Tests abgeschlossen sind.

5. Zurücksetzen (Rollback)*: Wenn Probleme auftreten, weisen Sie den production-Alias wieder der vorherigen benannten Version zu.

Für Teams, die Agentenkonfigurationen in Git verwalten, wechselt der Workflow zu einem Importmodell:

1. Entwickeln: Bearbeiten Sie die Konfigurationsdateien des Agenten in einem Git-Repository.

2. Merge: Überprüfen und fassen Sie Änderungen über Ihren standardmäßigen Pull-Anforderungsprozess zusammen.

3. Importieren: Erstellen Sie eine benannte Version aus dem mit Git verbundenen Stagingbereich und umgehen Sie die Live-Version vollständig.

4. Bereitstellen: Weisen Sie den production-Alias der importierten Version zu.

-- Import a version from a Git-connected stage after a merge
ALTER AGENT my_agent ADD VERSION FROM @my_repo/tags/v2.1/agents/my_agent
  COMMENT = 'Automated deploy from CI pipeline';

Sie können einen neuen Agenten auch direkt aus einem Stagingbereich erstellen, als Teil eines Infrastruktur-as-Code-Workflows:

CREATE AGENT my_agent
  COMMENT = 'Deployed by CI pipeline'
  FROM @my_stage/agents/my_agent;

Stagingbereichsoperationen¶

Jede Agentenversion hat einen internen, versionierten Stagingbereichspfad, auf den Sie über das snow://agent/ URI-Schema zugreifen können. Hier können Sie die Dateien prüfen, aus denen eine Version besteht – einschließlich der Agentenspezifikation, der Fähigkeitsdefinitionen und der unterstützenden Skripte.

Das URI-Format ist:

snow://agent/<agent_name>/versions/<version>/[<file_name>]

Das <version>-Segment akzeptiert eine Systemversions-ID (VERSION$N), einen benutzerdefinierten Alias oder das Schlüsselwort live.

-- List all files in the production version
LIST snow://agent/my_agent/versions/production/;

-- Download the agent spec from a specific version
GET snow://agent/my_agent/versions/VERSION$2/agent.yaml file:///tmp/;

Stagingbereichsoperationen sind schreibgeschützt und nützlich für die Prüfung, das Debuggen und den Vergleich von Versionen.

Ausführen einer bestimmten Version¶

Sie können eine Anforderung an eine bestimmte Version eines Agenten senden, indem Sie den versionierten API-Endpunkt verwenden:

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

Der {version}-Pfadparameter akzeptiert einen der folgenden Werte:

Standardmäßig streamt die API Antworten als vom Server gesendete Ereignisse (SSE). Um eine einzelne JSON-Antwort zu erhalten, legen Sie stream auf false im Anforderungstext fest.

Einschränkungen¶

Die folgenden Einschränkungen gelten für die Versionierung des Cortex -Agent:

• Eine Live-Version: Jeder Agent kann immer nur eine Live-Version haben.

• Live-Version nicht automatisch erstellt: Nachdem Sie die Live-Version übertragen haben, wird nicht automatisch eine neue Live-Version erstellt. Sie müssen explizit eine erstellen.

• Benannte Versionen sind unveränderlich: Sie können die Konfiguration einer benannten Version nicht ändern. Sie können nur Metadaten (Kommentar, Alias) aktualisieren oder löschen.

• Nur Benannte löschen: Sie können benannte Versionen löschen, aber nicht die Live-Version.

• Alias-Eindeutigkeit: Jeder Alias muss innerhalb eines Agenten eindeutig sein. Die Zuweisung eines Alias, der bereits in einer anderen Version existiert, führt zu einem Fehler.

• Unterscheidung nach Groß-/Kleinschreibung: Aliasnamen werden zwischen Groß- und Kleinschreibung unterschieden, wenn sie mit Bezeichnern in doppelten Anführungszeichen erstellt werden. Andernfalls werden sie in Großbuchstaben gespeichert.