Zum Hauptinhalt springen
connic
Starte kostenlos
Apps

Instanzen

Agenten veröffentlichen Seiten, etwa einen Bericht mit Diagrammen, als Instanzen einer App. Jede Instanz hat eine eigene URL auf dem Host der App und nutzt deren Anmeldung und Zugriffsregeln.

Zuletzt aktualisiert

So funktioniert es

  1. Trage die App im YAML des Agenten unter apps ein. Der Agent bekommt das Tool app_publish in jedem Run, in dem die Bedingung eines Eintrags zutrifft; unter tools steht es nicht. Das Tool beschreibt dem Agenten jede App so, wie sie deployt ist: ihre Content-Security-Policy, welche Dateien sie annimmt, die Daten-API und die Zugriffsregeln der App. Im Prompt des Agenten steht dann nur noch, wofür die Seiten da sind.
  2. Der Agent schreibt statische Dateien mit den Datei-Tools in einen Ordner, mit einer index.html direkt darin.
  3. Er ruft app_publish mit App und Ordner auf und bekommt die URL der Instanz: https://<app host>/i/<instance id>/.
  4. Besucher öffnen die URL wie jede andere Seite der App: mit ihrer Anmeldung, ihrer Data API unter ihren Zugriffsregeln und ihren Connectors.
agents/analyst.yaml
name: analyst
model: connic/gpt-5.6-terra
description: "Beantwortet Fragen zum Umsatz und zeigt sie als Berichte"
system_prompt: |
  Wenn ein Diagramm oder eine Tabelle hilft, baue eine Seite in
  reports/drafts/<thema>/ mit index.html und veröffentliche sie mit app_publish.
  Teile die zurückgegebene url.
apps:
  - app: reports
    condition: context.user.role != null   # optional; gleiche Syntax wie bei bedingten Tools
    max_age_days: 90                       # optional; ohne bleiben Instanzen, bis jemand sie löscht
    user: context.user                     # optional; ergänzt embed_url im Ergebnis
apps/reports.yaml
name: Reports
instances_only: true          # nur Seiten unter /i/<instance id>/; build wird optional
build:                        # optionaler Basis-Build mit deinen Komponenten und Styles
  command: npm run build
  output: dist
auth:
  mode: oidc
  issuer: ${REPORTS_ISSUER}
  client_id: ${REPORTS_CLIENT_ID}
  client_secret: ${REPORTS_CLIENT_SECRET}
access:
  database:
    sales:
      read: doc.region in user.groups

Konfiguration im Agenten

Jeder Eintrag unter apps nennt eine App. Zwei Agenten können in dieselbe App veröffentlichen, jeder mit eigenen Einstellungen. Nur LLM-Agenten können apps nutzen, und jede genannte App braucht eine Datei in apps/ und muss im Environment des Agenten deployt sein, sonst scheitert das Deployment.

FeldTypStatusBeschreibung
appstringErforderlichDer Key der App, also der Name ihrer Datei apps/<key>.yaml. Jede App darf nur einmal vorkommen.
conditionstringOptionalBietet die App nur an, wenn dieser Ausdruck für den Run wahr ist. Nutzt die Syntax der bedingten Tools. Trifft kein Eintrag zu, hat der Run weder app_publish noch app_preview.
max_age_daysintegerOptionalLöscht die Instanzen, die dieser Agent veröffentlicht, so viele Tage nach ihrer ersten Veröffentlichung. Erneutes Veröffentlichen verlängert die Frist nicht. Ohne das Feld bleiben Instanzen, bis jemand sie löscht.
userstringOptionalEin context.<path> mit dem Endnutzer: eine ID oder ein Objekt mit id und optional email, name und groups, meist von einer Middleware gesetzt. app_publish gibt dann zusätzlich einen Embed-Link zurück, der als dieser Nutzer anmeldet. Steht in einem Run nichts unter dem Pfad, fehlt der Embed-Link im Ergebnis.

Veröffentlichen

app_publish nimmt app, eine der Apps, die der Run anbietet, folder, einen Ordner in Files, und optional instance, die ID einer Instanz, die ersetzt werden soll. Die Dateien behalten ihre Pfade unterhalb des Ordners: reports/drafts/q3/charts/sales.svg liegt dann unter /i/<instance id>/charts/sales.svg. Der Agent kann nur Dateien veröffentlichen, die er nach seinen Zugriffsregeln lesen darf.

Ergebnis von app_publish
{
  "instance": "5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13",
  "url": "https://reports-1a2b3c4d.connic.app/i/5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13/",
  "version": 1,
  "expires_at": "2027-02-18T09:30:00Z",
  "embed_url": "https://reports-1a2b3c4d.connic.app/i/5f0c2b7e-8a14-4d3e-9b6a-2c71e0d94f13/?connic_embed=..."
}

Ohne max_age_days ist expires_at null. Ist die connic.app-Adresse abgeschaltet, nutzt die URL die Custom Domain der App.

Um eine Instanz zu ändern, schreibt der Agent die neuen Dateien und veröffentlicht erneut mit instance. Alle Dateien werden ersetzt, die URL bleibt gleich, und version steigt um eins. Die Instanz muss zur selben App gehören.

Mit app_publish bekommt der Agent auch app_preview. Das Tool öffnet eine Seite, die im selben Run veröffentlicht wurde, über ihren Embed-Link, falls es einen gibt. Es liefert einen Screenshot und die Fehler und Warnungen, die die Seite protokolliert hat, etwa Dateien, die ihre Content-Security-Policy blockiert hat. Der Agent behebt, was er sieht, und veröffentlicht erneut. Vorschauen nutzen den Browser des Runs und zählen als Browser-Nutzung.

Der Ordner darf dieselben Dateitypen enthalten wie der Quellcode einer App, und die Dateien einer Instanz dürfen zusammen so groß sein wie die Build-Ausgabe einer App im Tarif des Projekts, mit bis zu 16 MiB pro Datei und 20.000 Dateien. Fehlt die index.html, enthält der Ordner einen anderen Dateityp oder ist er zu groß, bekommt der Agent einen Fehler, und nichts ändert sich.

Aus eigenem Code

Tools und Middleware veröffentlichen mit connic.tools.app_publish in jede App, die der Agent unter apps nennt. Die Funktion nimmt dieselben Argumente und liefert dasselbe Ergebnis.

tools/reports.py
from connic.tools import app_publish


async def publish_report(topic: str) -> str:
    """Veröffentlicht den Berichtsentwurf zu einem Thema und gibt seine URL zurück."""
    result = await app_publish("reports", f"reports/drafts/{topic}")
    return result["url"]

Basis-Build

Instanzen liegen auf dem Host der App, ihre Seiten können also die Dateien aus dem Build der App über absolute Pfade laden. Lege deine Komponenten, Styles und Diagramm-Bibliotheken in den Build der App, dann schreibt der Agent nur noch die Seite, die sie nutzt. So bleiben die Seiten in deinem Design, und die Ausgabe des Agenten bleibt kurz.

reports/drafts/q3/index.html
<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="/assets/reports.css">
    <script type="module" src="/assets/reports.js"></script>
  </head>
  <body>
    <sales-chart region="emea" months="12"></sales-chart>
  </body>
</html>

Für Instanzen gilt die Content-Security-Policy der App. Mit dem Standard lädt eine Seite Skripte, Styles und Bilder nur vom Host der App; die Seiten des Agenten können also keinen Code von anderen Websites holen, außer content_security_policy erlaubt es.

Nur Instanzen

Mit instances_only: true in apps/<key>.yaml liefert die App nur ihre Instanzen aus, jede andere Seite antwortet mit 404. Die übrigen Dateien des Basis-Builds, etwa Skripte, Styles, Schriften und Bilder, bleiben für die Instanzen erreichbar. build wird optional; ohne build hat die App keinen Basis-Build und keinen Quellordner in apps/.

Auslieferung

/i/<instance id>/ liefert die index.html der Instanz, und Pfade darunter folgen innerhalb der Instanz denselben Regeln wie die Auslieferung der App selbst. Browser prüfen die Dateien einer Instanz bei jedem Aufruf neu, eine neue Version erscheint also sofort. Eine Instanz, die es nicht gibt, die abgelaufen ist oder gelöscht wurde, antwortet mit 404.

Lebensdauer und Speicher

  • Eine Instanz bleibt, bis jemand sie löscht oder max_age_days nach ihrer ersten Veröffentlichung abgelaufen ist. Instanzen überdauern die Session und den Run, die sie erstellt haben, Links in alten Unterhaltungen funktionieren also weiter.
  • Wer eine Instanz löscht, entfernt ihre Dateien und beendet ihre Embed-Links.
  • Instanzen folgen ihrer App: Wird die App stillgelegt, liefert sie auch ihre Instanzen nicht mehr aus, und sobald ein Deployment die App wieder deklariert, sind sie zurück. Wer das Environment löscht, löscht auch die Instanzen.
  • Die Zahl der Instanzen ist nicht begrenzt. connic behält eine Kopie der Dateien jeder Instanz in Files unter apps/<key>/<instance id>/; sie zählt dort als Speicher von Files. Den Ordner apps/ verwalten die Apps: Seine Dateien lassen sich über Files lesen, auflisten und herunterladen, aber nicht hochladen, verschieben, umbenennen, bearbeiten oder löschen.

Im Dashboard

Der Tab Instances einer App listet ihre Instanzen mit Link, dem Agenten, der sie veröffentlicht hat, Erstellungs- und Ablaufdatum sowie Größe. Sehen kannst du sie mit View apps, löschen mit Manage apps. connic MCP bietet dasselbe mit list_app_instances und delete_app_instance.