Runtime-Steuerung

Regeln zur Nebenläufigkeit

Regeln zur Nebenläufigkeit stellen sicher, dass pro eindeutigem Schlüssel immer nur ein Run aktiv ist. Verwende sie, wenn ein Agent Events für einen bestimmten Support-Prozess, Kunden oder Auftrag verarbeitet und eine parallele Verarbeitung zu Konflikten führen würde.

Queue-Modus (Standard)

Trifft ein weiteres Event für einen aktiven Schlüssel ein, wartet es, bis der erste Run beendet ist, und startet anschließend automatisch.

version: "1.0"

name: support-processor
type: llm
model: connic/gpt-5.6-terra
description: "Processes support tickets one at a time per process"
system_prompt: "You are a support agent. Process the incoming ticket."

# Only one run per process_id at a time. Additional runs wait in queue.
concurrency:
  key: "process_id"
  on_conflict: queue

Drop-Modus

Trifft ein weiteres Event für einen aktiven Schlüssel ein, wird der neue Run sofort abgebrochen. Verwende diesen Modus, wenn doppelte Arbeit unnötig wäre.

version: "1.0"

name: notification-handler
type: tool
description: "Handles notifications, skipping duplicates"
tool_name: notifications.handle

# Drop duplicate runs for the same customer while one is active.
concurrency:
  key: "data.customer_id"
  on_conflict: drop

Coalesce-Modus

Trifft ein weiteres Event für einen aktiven Schlüssel ein, wartet sein Run wie im Queue-Modus, aber pro Schlüssel kann nur ein Run warten. Ein neueres Event ersetzt den wartenden Run. Viele Events während eines langen Runs führen so zu genau einem Folge-Run mit der neuesten Payload. Verwende diesen Modus, wenn jedes Event den Agenten nur auffordert, denselben Zustand erneut zu prüfen.

Der ersetzte Run wird abgebrochen. Sein Kontext enthält superseded_by_concurrency_rule und superseded_by, die ID des Runs, der ihn ersetzt hat.

version: "1.0"

name: process-agent
type: llm
model: connic/gpt-5.6-terra
description: "Re-evaluates the current process step on every status event"
system_prompt: "Check the current step of the process and act on it."

# Events that arrive during a run collapse into one follow-up run.
concurrency:
  key: "process_id"
  on_conflict: coalesce

Schlüssel extrahieren

key liest die Trigger-Payload in Punktnotation. Wenn ein Kafka-Payload {"data": {"customer_id": "abc"}} lautet, verwende data.customer_id. Existiert der Pfad nicht, wird die Nebenläufigkeitsregel für diesen Run übersprungen.

Zusammenspiel mit max_concurrent_runs

Beide Einschränkungen gelten. Mit max_concurrent_runs: 5 und concurrency.key: "process_id"können fünf Prozess-IDs parallel laufen, aber pro Prozess-ID kann nur ein Run aktiv sein. Runs, die auf ihren Schlüssel warten, belegen keinen Platz.

Wartende Runs

• Wartende Runs werden dauerhaft gespeichert. Sie überstehen Neustarts und Deployments und starten auf dem aktiven Deployment.
• Ein Schlüssel bleibt während eines Deployments belegt. Ein Run, der noch auf dem vorherigen Deployment läuft, behält seinen Schlüssel bis zu seinem Ende.
• Ein Run, der auf eine Freigabe wartet, behält seinen Schlüssel. Nach der Entscheidung läuft er vor allen wartenden Runs weiter.
• Im Queue-Modus starten wartende Runs in der Reihenfolge, in der ihre Events eingetroffen sind.
• Es gibt keine Obergrenze für wartende Runs und kein Warte-Timeout. Die Wartezeit zählt nicht zu timeout, und ein Run verbraucht vor seinem Start kein Projektguthaben. Runs, die durch drop oder coalesce abgebrochen werden, starten nie.

Persistente Sessions

Mit session: true teilen alle Runs des Agenten eine Session. Ein Objekt ohne key oder mit key: null verwendet dieselbe gemeinsame Session. false, null oder das Weglassen von session deaktiviert die dauerhafte Speicherung.

version: "1.0"

name: support-bot
type: llm
model: connic/gpt-5.6-terra
description: "A support chatbot that remembers conversation history"
system_prompt: |
  You are a helpful support agent. Use the conversation history
  to provide contextual responses.

# Maintain persistent sessions keyed by chat ID from middleware
session:
  key: context.chat_id
  ttl: 86400  # Sessions expire after 24 hours of inactivity

# Keep long conversations within the model context window
context_compression:
  enabled: true
  # Optional model for compression summaries; defaults to the agent model
  model: connic/gpt-5.6-luna
  keep_recent_messages: 12
  # Optional early compression based on model-reported prompt usage
  max_prompt_tokens: 100000

Verlauf und Browserzustand

history und browser sind standardmäßig true. Dieses Beispiel behält Cookies und Local Storage pro Chat; jeder Run beginnt mit einem neuen Gesprächsverlauf. Bei browser: false funktionieren Browser-Tools weiterhin, starten aber mit leerem Browserzustand.

session:
  key: context.chat_id
  ttl: 86400
  history: false
  browser: true

Session-Schlüssel

Der optionale key trennt Sessions nach dem aufgelösten Wert. Wenn angegeben, muss er eines von zwei Präfixen verwenden:

• context.<path> liest den Session-Schlüssel aus dem Middleware-Kontext. Die Middleware kann ihn auch aus den Anfragedaten ableiten.
• input.<path> liest den Session-Schlüssel direkt aus der Payload der Verbindung, bevor die Middleware ausgeführt wird. Die Payload muss gültiges JSON sein; auch verschachtelte Felder sind zugänglich.

Schlüssel in Middleware setzen

async def before(content: dict, context: dict) -> dict:
    # Extract a stable identifier for this conversation from the connector payload.
    payload = context.get("payload", {})
    context["chat_id"] = payload.get("chat_id")
    return content

Input-Schlüssel verwenden

# When the connector payload is JSON like {"user_id": "u123", "message": "..."}
session:
  key: input.user_id

TTL und Session-Verwaltung

Der optionale Wert ttl legt fest, nach wie vielen Sekunden ohne Aktivität eine Session abläuft. Das Minimum beträgt 60 Sekunden; ohne TTL laufen Sessions nie ab. Aktive Sessions lassen sich im Dashboard unter Storage > Sessions ansehen und löschen. Sessions gelten pro Environment.

Runs mit derselben Session werden nicht automatisch nacheinander ausgeführt. Überschneiden sich zwei Runs derselben Session, schlägt der Run fehl, der als zweiter schreibt. Wenn das passieren kann, setze eine Regel zur Nebenläufigkeit auf das Feld, das die Session identifiziert, etwa concurrency.key: conversation_id zusammen mit session.key: input.conversation_id.

Kontextkomprimierung

Mit context_compression verkürzt connic den Gesprächsverlauf, wenn der Provider ein überschrittenes Kontextfenster meldet. Die Komprimierung erfolgt vor einem Wechsel zum Fallback. Danach erhält dasselbe KI-Modell eine zusätzliche Anfrage mit dem gekürzten Verlauf. Pro KI-Modell-Aufruf im Agent-Loop ist höchstens ein solcher Reparaturversuch außerhalb der regulären Anzahl erlaubt. Das Zeitlimit des Runs und die bereits verbrauchten Versuche bleiben bestehen. Schlägt die Reparatur fehl, gilt wieder die normale Regel für Wiederholungsversuche oder Fallback. Mit context_compression.model lässt sich ein separates KI-Modell für Zusammenfassungen festlegen. Der Reparaturversuch verwendet das KI-Modell, das den Kontext abgelehnt hat. max_prompt_tokens ermöglicht eine frühere Komprimierung anhand der gemeldeten Prompt-Nutzung. session_history.interval komprimiert auch den gespeicherten Verlauf zwischen Runs.

Für den gespeicherten Verlauf gibt es keine Obergrenze bei Gesamtgröße oder Anzahl der Runs; jede gespeicherte Nachricht darf bis zu 5 MB groß sein. Mit session_history.interval: 4 fasst jeder vierte Run an seinem Ende den älteren Verlauf zusammen und behält die letzten keep_recent_runs Runs (Standard 1) unverändert. Ohne diese Einstellung lädt jeder Run den vollständigen gespeicherten Verlauf, und die Komprimierung kürzt nur die Anfrage, nicht die gespeicherte Session.