Hintergrund: KI-Agenten, das sind Task-Container

Task-Container sind jetzt allgemein in der Upsun Cloud verfügbar und bieten dir einen Ort, an dem du KI-Agenten zusammen mit dem Rest deiner Anwendung ausführen kannst. Der Agent läuft als Container innerhalb deines Upsun-Cloud-Projekts, direkt neben der App, an der er arbeitet, und hat denselben Zugriff auf deine Umgebung und deine Daten wie alles andere, was dort bereitgestellt ist. Der Lebenszyklus ist das Neue daran: Er passt sich dem Verhalten von Agent-Workloads an, anstatt sie zu zwingen, sich als Server auszugeben.

Ein paar Hinweise vorab:

Dies ist eine praktische Anleitung. Wenn du eine umfassendere Einführung in die Features suchst, lies zuerst „Task-Container: Run-to-Completion-Aufgaben auf Upsun“.

Der Task-Container ist von Grund auf als reine Ausführungsprimitive konzipiert. Es gibt kein KI-Gateway, kein verwaltetes LLM und keine darüber liegende Orchestrierungs-Benutzeroberfläche – du stellst den Agent-Code, die LLM-Schlüssel und den Trigger bereit. Das ist eine bewusste Entscheidung: Eine flexible Ausführungsumgebung bleibt nützlich, egal welches Modell, Framework oder Agent-Muster du verwendest, anstatt dich an das zu binden, was wir eingebaut hätten.

Bevor du loslegst

Du benötigst:

• Ein Upsun-Projekt.
• Eine Agenten-Laufzeitumgebung deiner Wahl. Das kann ein Framework wie LangChain, LlamaIndex oder AutoGen sein oder selbst programmierter Code, der direkt eine LLM-API aufruft. Upsun schränkt die Auswahl nicht ein.
• Einen API-Schlüssel für den LLM-Anbieter, den du nutzen möchtest. Speichere ihn als vertrauliche Upsun-Projektvariable, nicht beim Programmieren.
• Eine klare Antwort auf die Frage „Was soll diesen Agenten auslösen?“ Die Antwort bestimmt alles, was folgt.

Wenn du noch keine Antwort auf die Auslösefrage hast, ist das der richtige Ausgangspunkt. Ein KI-Agent ohne klar definierten Auslöser ist ein Prozess, der nach einem Vorwand sucht, um ausgeführt zu werden; ein Agent mit einem präzisen Auslöser ist ein Teil der Infrastruktur.

Die Struktur eines KI-Agenten in der Upsun Cloud

Ein Agent kann in einem App-Container oder einem Worker laufen, aber ein Task-Container bietet in der Regel das bessere Ausführungsmodell. Definiere den Agenten als Task, und er verfügt über:

• Er ist als Eintrag auf oberster Ebene unter „tasks:“ in „.upsun/config.yaml“ definiert, auf einer Stufe mit „applications:“ und „services:“.
• Er verfügt über ein eigenes Container-Image und einen eigenen Build-Schritt, unabhängig von der Anwendung. Du kannst jede beliebige Python-, Node- oder andere Laufzeitumgebung installieren, ohne die Hauptanwendung zu verändern.
• Es greift über das Standard-Beziehungsmodell auf die Dienste des Projekts (Datenbanken, Caches, queues) zu.
• Es startet, wenn es über die Upsun Cloud API ausgelöst wird, läuft bis zum Abschluss und wird automatisch entfernt, sobald der Befehl beendet wird.
• Es verfügt standardmäßig über Timeouts, Ressourcenbeschränkungen und Aktivitätsprotokollierung.
• Ein isolierter Container mit derselben Netzwerkisolierung wie deine Anwendungen.

Das mentale Modell, an dem du dich orientieren solltest: Ein Agent ist ein Stück Code mit einer Aufgabe, kein Server. Behandle ihn wie einen einmaligen Job, der zufällig ein LLM aufruft, und die meisten Fragen zum Design klären sich von selbst.

Praxisbeispiel: Ein Agent zur Triage von Support-Tickets

Um das zu veranschaulichen, geht der Rest des Beitrags auf einen Agenten zur Triage von Support-Tickets ein. Das Szenario:

Wenn ein neues Ticket eingeht, startest du einen Agenten, der den Ticketinhalt liest, ihn anhand deiner Support-Kategorien klassifiziert, eine Antwort entwirft und diese zurück ins Ticket stellt, damit ein Mensch sie überprüfen oder versenden kann.

Dasselbe Muster lässt sich verallgemeinern. Ersetze „Ticket-Triage“ durch „Code-Review“, „Vorfallzusammenfassung“ oder „Datenqualitätsprüfung“, und die Struktur ändert sich kaum.

Schritt 1: Definiere den Agenten als Aufgabe

Füge in „.upsun/config.yaml“ auf oberster Ebene einen „tasks:“-Block hinzu. Die Aufgabe erhält einen Namen, ein Container-Image, einen Build-Schritt und einen Befehl. Die genauen Feldreferenzen findest du in der Dokumentation zu Task-Containern; die konzeptionelle Struktur sieht so aus:

applications:
  api:
    # your long-running API

services:
  postgres:
    type: postgresql:16

tasks:
  ticket-triage-agent:
    type: python:3.14
    run:
      command: python agent.py

Drei Entscheidungen sind hier entscheidend. Wähle das kleinste Basis-Image aus, das dein Agent benötigt. Ein Python-Agent, der eine kleine LLM-Client-Bibliothek nutzt, braucht kein schwerfälliges Image, und ein schnellerer Start bedeutet eine schnellere End-to-End-Antwort. Installiere die Abhängigkeiten deines Agenten während des Build-Schritts statt zur Laufzeit, damit die Aufgabe sofort nach dem Start ausführbar ist. Und halte den Ausführungsbefehl auf ein einziges, idempotentes Skript beschränkt. Wenn der Agent einen erneuten Versuch unternimmt, sollte er sauber von vorne beginnen, ohne bereits geleistete Arbeit zu wiederholen oder etwas halbfertig zu lassen.

Schritt 2: Den Auslöser einrichten

Aufgaben auf Upsun Cloud werden über die Plattform-API, die Konsole oder die CLI ausgelöst. Für das Ticket-Triage-Szenario ist der Auslöser ein Webhook aus deinem Ticketingsystem, der ausgelöst wird, wenn ein neues Ticket erstellt wird.

Es gibt zwei gängige Vorgehensweisen, um einen Webhook in einen Aufruf der Aufgabe umzuwandeln. Deine bestehende API kann den GitHub-Webhook direkt empfangen, die Signatur validieren, den relevanten Kontext extrahieren (PR-Nummer, Repo, Base- und Head-SHAs) und die Upsun cloud-API aufrufen, um die Aufgabe mit diesen Werten als Eingaben zu starten. Oder es kann einen dedizierten, schlanken Handler geben, der ausschließlich dazu dient, Webhooks zu empfangen und Aufgaben auszulösen – nützlich, wenn du die Hauptanwendung frei von Agent-bezogenen Codepfaden halten möchtest.

Für einen Ticket-Triage-Agenten reicht das erste Muster in der Regel aus. Der Handler umfasst zwanzig Zeilen, die programmiert werden müssen; die eigentliche Arbeit findet im Agenten selbst statt.

Wenn dein Auslöser eher ein Zeitplan als ein Ereignis ist (zum Beispiel ein nächtlicher Bereinigungsagent), kann dieselbe Aufgabe von einer Cron-App oder einem externen Scheduler aus aufgerufen werden. Dem Agenten ist es egal, wer ihn aufgerufen hat.

Schritt 3: Umgang mit Anmeldedaten bei Workload-Berechtigungen

Der Agent benötigt Anmeldedaten, und es gibt zwei Arten, die unterschiedlich behandelt werden sollten.

Externe Anmeldedaten, wie dein LLM-Anbieter-API-Schlüssel und ein GitHub-Token, werden als Upsun Cloud-Projektvariablen gespeichert. Sie stehen der Aufgabe zur Laufzeit als Umgebungsvariablen zur Verfügung. Behandle sie wie jedes andere Geheimnis: auf das Projekt beschränkt, in regelmäßigen Abständen aktualisiert, niemals in das Repository committet.

Anmeldedaten der Upsun Cloud-Plattform – für alle Fälle, in denen der Agent die Upsun Cloud-API selbst aufrufen muss – sind der Zweck von Workload-Berechtigungen. Die Aufgabe fordert bei der Ausführung ein kurzlebiges, eng begrenzte Token von Upsun Cloud an, nutzt das Token und lässt es ablaufen. Es gibt keine langlebigen Plattform-Anmeldedaten, die rotiert werden müssen, und kein geteiltes Geheimnis, das in Protokollen durchgesickert werden könnte.

Für einen reinen Ticket-Triage-Agenten, der lediglich ein Ticket liest und eine Antwort postet, brauchst du möglicherweise gar keine Workload-Autorisierungen. Sie werden nützlich, sobald der Agent Informationen auf Plattformebene oder Zusammensetzungen benötigt: das Abfragen von Umgebungsmetadaten bei der Upsun Cloud, das Auslösen einer Folgeaufgabe oder das Kennzeichnen von Ausgaben mit Zweigkontext. Die Dokumentation zur Workload-Autorisierung behandelt den Anforderungsablauf.

Schritt 4: Lege Grenzwerte fest, bevor du den Agenten unbeaufsichtigt laufen lässt

Das ist der Schritt, den die meisten Agent-Anleitungen überspringen. Überspringe ihn nicht.

Lege für den Agenten ein festes Timeout fest. Der Standardwert beträgt eine Stunde, aber für einen Ticket-Triage-Agenten solltest du einen niedrigeren Wert wählen. Wenn ein Lauf nach fünf Minuten noch nicht abgeschlossen ist, stimmt etwas nicht, und die richtige Vorgehensweise ist, die Aufgabe als fehlgeschlagen zu markieren und zu protokollieren, anstatt sie weiterlaufen zu lassen. Ohne Timeout wird eine endlose Schleife oder ein hängender LLM-Aufruf den Container belasten, bis etwas anderes eingreift.

Stell die CPU- und Speicherzuweisung des Containers so ein, dass sie der tatsächlichen Arbeitslast entspricht. Ein Agent, der LLM-gestütztes Schlussfolgern durchführt, wartet größtenteils auf die Modell-API, sodass er selten eine große Zuweisung benötigt.

Agenten führen vom Modell generierte Befehle aus, und derzeit bieten Aufgaben-Container keine Begrenzung des ausgehenden Datenverkehrs an, sodass du den ausgehenden Netzwerkzugriff einer Aufgabe noch nicht auf bestimmte Endpunkte beschränken kannst. Bis diese Funktion verfügbar ist, behandle die Anmeldedaten des Agenten als die eigentliche Grenze: Gib ihm nur den Zugriff, den er benötigt, da der Container selbst nicht einschränkt, wohin er gelangen kann. Kombiniere dies mit einer containerinternen Sandbox wie „bubblewrap“, um genauer zu kontrollieren, was der Agentenprozess tatsächlich tun kann.

Jeder Task-Lauf erhält einen eigenen isolierten Container mit demselben Namespace und derselben Netzwerkisolierung wie deine Anwendungen. Für einen Agenten, der modellgenerierte Befehle ausführt, kombiniere dies mit einer containerinternen Sandbox wie „bubblewrap“, um das für den Agentenprozess sichtbare Dateisystem und die Systemaufrufe weiter einzuschränken. Standardmäßig bleibt zwischen den Läufen nichts erhalten; alles, was bestehen bleiben muss, sollte daher in einen Dienst (Postgres, Objektspeicher) und nicht auf die lokale Festplatte geschrieben werden.

Eine weitere Einschränkung, die du bei der Planung berücksichtigen solltest: Upsun Cloud führt standardmäßig bis zu drei Aufgaben pro Projekt gleichzeitig aus. Wenn dein Repository einen Ansturm an Pull-Anfragen verzeichnet, werden zusätzliche Trigger in die Queue gestellt, bis ein Platz frei wird, anstatt sofort fehlzuschlagen. Für einen Ticket-Triage-Agenten ist das in der Regel kein Problem, da eine Verzögerung von ein paar Minuten bei der Antwort selten ins Gewicht fällt – aber es ist gut, das zu wissen, bevor du an einem geschäftigen Nachmittag denkst, dass etwas kaputt ist.

Wenn ihr das richtig hinbekommt, unterscheidet sich ein Agent, den ihr unbeaufsichtigt laufen lassen könnt, von einem, den ihr ständig im Auge behalten müsst.

Schritt 5: Mach die Agentenläufe nachvollziehbar

Die Aktivitätsprotokollierung ist integriert. Die Aufgabe zeichnet auf, was wann und mit welchem Status ausgeführt wurde. Das deckt die betriebliche Sicht ab.

Was sie nicht abdeckt, ist die agenteninterne Sicht: welche Eingabeaufforderungen der Agent generiert hat, welche Tools er aufgerufen hat, welche Modellantworten er erhalten hat und wie er sich entschieden hat, vorzugehen. Dafür musst du den Agenten selbst mit Überwachungsfunktionen ausstatten. Protokolliere mindestens die Eingaben, die der Agent erhalten hat (PR-Nummer, Dateipfade, Commit-SHAs), jeden LLM-Aufruf (das Modell, einen Hash der Eingabeaufforderung, die Antwortlänge und die Kosten, falls du diese verfolgst), jede externe Aktion, die der Agent ausgeführt hat (API-Aufruf, geposteter Kommentar, geschriebene Datei) sowie das Endergebnis.

Leite diese Daten an die Observability-Tools weiter, die du bereits nutzt. Der Sinn dahinter ist, die Agent-Läufe im Nachhinein rekonstruierbar zu machen, da sich das Verhalten von LLMs ändert und du in drei Wochen wissen willst, was ein Agent tatsächlich getan hat.

Schritt 6: Starte den Agenten und beobachte

Nachdem die Aufgabe definiert, der Trigger eingerichtet, die Anmeldedaten hinterlegt und die Grenzwerte festgelegt sind, eröffne einen Pull-Request und lass den Agenten laufen. Beobachte das Aktivitätsprotokoll. Lies die Kommentare, die er veröffentlicht. Passe die Eingabeaufforderung, die Grenzwerte und die Auslösebedingungen an, während du dazulernst.

Die ersten zehn Durchläufe sind am wertvollsten. Sie zeigen dir, ob dein Anwendungsbereich richtig ist, ob der Agent nach Dingen greift, auf die er nicht zugreifen sollte, und ob die Eingabeaufforderung bei echten Daten das tut, was du erwartest. Betrachte die erste Serie als Kalibrierungsphase, nicht als Start.

Über die Ticket-Triage hinaus: weitere Agentenmuster

Die obige Anleitung ist allgemein gehalten. Hier sind ein paar weitere Agentenmuster, die sich nahtlos in den Aufgaben-Container einfügen:

• Nächtlicher Bereinigungs-Agent. Wird per Cron ausgelöst, durchläuft die Umgebungen und Zweige des Projekts und entfernt alles, was älter ist als ein konfigurierbarer Schwellenwert. Nutzt Workload-Berechtigungen, um die Upsun Cloud API aufzurufen.
• Agent zur Vorfalluntersuchung. Wird ausgelöst, wenn eine Metrik einen Schwellenwert überschreitet. Ruft relevante Protokolle ab, fasst den Vorfall zusammen und veröffentlicht eine Zusammenfassung in einem Chat-Kanal. Nützlich, um dem Bereitschaftstechniker schneller den Kontext zu vermitteln.
• Agent für die Datenqualität. Wird nach Abschluss eines nächtlichen ETL-Jobs ausgelöst. Liest Stichproben der neuen Daten, markiert Anomalien und veröffentlicht sie auf einem Dashboard.

In jedem Fall ist der Ablauf derselbe: Ein Trigger geht ein, der Agent läuft bis zum Abschluss, der Container wird entfernt. Was sich ändert, sind die Eingabeaufforderung, die Tools und das Ziel der Ausgabe.

Was das abdeckt

Der Aufgaben-Container liefert die Laufzeitumgebung; du bringst den Agenten mit: dein eigenes Framework, die LLM-Verbindung und das Prompt-Management. Das ist bewusst so gewählt. Agenten-Frameworks und Orchestrierungsmuster ändern sich von Monat zu Monat, und eine Primitive, die dich nicht bindet, ist um Längen besser als eine, die das tut.

Bereit loszulegen? Schau dir die Dokumentation zu den Aufgaben-Containern auf developer.upsun.com an, um loszulegen.

Häufig gestellte Fragen (FAQs)

Muss ich ein bestimmtes Agent-Framework verwenden? 
Nein. Der Task-Container ist frameworkunabhängig. Verwende LangChain, LlamaIndex, AutoGen, die SDKs von OpenAI oder Anthropic direkt oder deinen eigenen Code, um zu programmieren.

Kann der Agent auf andere Teile meines Upsun-Cloud-Projekts zugreifen? 
Ja. Aufgaben haben über Standardbeziehungen Zugriff auf die Dienste des Projekts (Datenbanken, Caches, queues, Objektspeicher) – genau wie eine App oder ein Worker.

Wie kommuniziert der Agent mit der Upsun Cloud-API? 
Über Workload-Autorisierungen. Die Aufgabe fordert zur Laufzeit ein kurzlebiges, eng begrenzte Token an und nutzt es, um die API aufzurufen. In der Umgebung des Agenten gibt es keine langlebigen Plattform-Anmeldedaten.

Was passiert, wenn der Agent länger läuft als das Timeout? 
Die Aufgabe wird beendet und der Fehler im Aktivitätsprotokoll vermerkt. Das Standard-Timeout beträgt eine Stunde; das Maximum liegt bei einem Tag. Stelle das Timeout auf einen Wert ein, der den langsamsten legitimen Lauf bequem abdeckt, aber endlose Schleifen verhindert.

Kann ich mehrere Agenten im selben Projekt ausführen? 
Ja. Jeder Agent ist ein eigener Eintrag unter „tasks:“ mit eigenem Image, eigenem Build-Schritt und eigenem Befehl.

Wie viele Agent-Läufe können gleichzeitig stattfinden? Standardmäßig 
drei pro Projekt. Zusätzliche Auslöser werden in die Queue gestellt, bis ein Platz frei wird, anstatt fehlzuschlagen.

Wo kann ich sehen, was der Agent tatsächlich gemacht hat? 
Aktivitätsprotokolle zeigen den Status auf Aufgabenebene und gestreamte Protokolle an. Agenteninterne Entscheidungen (Eingabeaufforderungen, Tool-Aufrufe, Modellantworten) müssen aus dem Agenten-Code heraus protokolliert werden. Beide Ansichten sind wichtig.