Verbindungen im Code
Verbindungen als YAML-Dateien in deinem Projekt deklarieren. Jedes Deployment legt sie für sein Environment an, aktualisiert sie oder legt sie still. Beim Zurücksetzen werden sie wiederhergestellt.
Auf dieser Seite
Verbindungen lassen sich im Dashboard, über die REST API oder Connic MCP anlegen oder in deinem Projekt unter connectors/ deklarieren. Im Code deklarierte Verbindungen werden durch Deployments angelegt, aktualisiert und stillgelegt. Ihre Einstellungen sind damit zusammen mit den verknüpften Agenten versioniert. Bis auf Slack lässt sich jeder Verbindungstyp im Code deklarieren.
Jede Datei deklariert eine Verbindung. Der Dateiname ohne .yaml ist Schlüssel und Identität der Verbindung: connectors/order-events.yaml hat den Schlüssel order-events.
Verbindung deklarieren
type: kafka
mode: inbound
name: Order events # optional, Standard ist der Dateiname
connection: orders-kafka-staging # gespeicherter Kontozugang, per Name
bridge: staging-cluster # Name oder ID der Bridge
config: # Felder der Verbindung, dieselben Namen wie config_json in REST API und MCP
topic: ${ORDER_EVENTS_TOPIC}
agents:
- order-processor
- name: audit-logger
files_required: true
environments: # weglassen, um in jedes Environment zu deployen
Staging: {}
Production:
connection: orders-kafka-prod
bridge: prod-cluster
config:
group_id: connic-orders-prod| Feld | Beschreibung |
|---|---|
| type | Verbindungstyp, zum Beispiel webhook, kafka, email oder twilio_messaging. Twilio Voice heißt twilio, Telnyx Voice telnyx. Statt webhook wird auch http akzeptiert. |
| mode | inbound, outbound oder sync. Pflichtfeld, wenn der Typ mehrere Modi unterstützt. Sonst gilt der einzige Modus des Typs. |
| name | Anzeigename. Standardmäßig der Dateiname. |
| connection | Name eines gespeicherten Kontozugangs (Connection). Pflichtfeld für Typen, die Kontozugänge verwenden. |
| bridge | Name oder ID einer Bridge, für Typen, die die Bridge nutzen können. |
| domain | Hostname einer aktiven Custom Domain, für Typen, die Custom Domains unterstützen. |
| config | Felder der Verbindung, mit denselben Namen wie in config_json der REST API und von Connic MCP. Unbekannte Felder lehnt das Deployment ab. |
| agents | Verknüpfte Agenten. Jede Verbindung verknüpft mindestens einen Agenten, und jeder davon muss in agents/ existieren. |
| environments | Environments, die die Verbindung erhalten, mit optionalen Overrides. Ohne dieses Feld wird die Verbindung in jedes Environment deployt. |
Die Dateien müssen direkt in connectors/ liegen und die Endung .yaml haben. Ein Dateiname beginnt mit einem Buchstaben oder einer Ziffer, enthält nur Buchstaben, Ziffern, - und _ und ist höchstens 100 Zeichen lang.
Agenten verknüpfen
Gib Agenten per Namen an oder als Objekte mit files_required und, bei Outbound-Verbindungen, outbound. Mit files_required: true schlägt ein Run vor dem Start fehl, wenn die Eingabe keine Dateien enthält oder eine Datei ausgelassen wurde.
type: webhook
mode: outbound
config:
outbound_url: ${ORDER_RESULTS_URL}
agents:
- name: order-processor
outbound: { usage: automatic, source: [order-events] } # Schlüssel anderer Verbindungsdateien
- name: invoice-checker
outbound: { usage: middleware, action_name: send_invoice_result }outbound.usage ist automatic, agent_tool oder middleware und entspricht den Modi für Outbound-Verbindungen. Agent-Tool- und Middleware-Verknüpfungen brauchen einen action_name, der mit einem Kleinbuchstaben beginnt und nur Kleinbuchstaben, Ziffern und Unterstriche enthält. Eine automatische Verknüpfung kann unter source die Schlüssel anderer Verbindungsdateien angeben. Sie sendet dann nur für Runs, die diese Verbindungen gestartet haben. Ohne outbound sendet eine Outbound-Verbindung nach jedem abgeschlossenen Run.
Environments und Overrides
Ohne environments wird die Verbindung mit denselben Einstellungen in jedes Environment deployt. Mit dem Feld existiert sie nur in den aufgeführten Environments. Die Schlüssel sind Environment-Namen und müssen exakt übereinstimmen. Staging: {} deployt die Datei unverändert.
Ein Override kann name, connection, bridge, domain, agents und config setzen. agents ersetzt die Liste. config wird Schlüssel für Schlüssel zusammengeführt: Production im Beispiel behält topic und ergänzt group_id. Ein Schlüssel, der zu keinem Environment des Projekts passt, lässt das Deployment scheitern.
Variablen und Secrets
${NAME} liest eine Variable des Ziel-Environments, mit derselben Syntax wie mcp_servers in der Agent-YAML. Verweise funktionieren in config, connection, bridge und domain. Connic löst sie einmal beim Start des Deployments auf. Fehlt eine Variable, scheitert das Deployment. Eine geänderte Variable wirkt ab dem nächsten Deployment.
Secrets, die du selbst mitbringst, etwa ein Telegram-bot_token oder ein Stripe-webhook_secret, müssen als ${NAME}-Verweis angegeben werden. Ein direkt eingetragener Wert lässt das Deployment scheitern.
Kontozugänge und Bridges
Verbindungen für Kafka, SQS, S3, PostgreSQL, E-Mail, Twilio Voice, Twilio Messaging, Telnyx Voice und Telnyx Messaging beziehen ihre Zugangsdaten aus einem Kontozugang (Connection). Die Datei enthält diese Zugangsdaten nie. Verweise mit connection auf den Namen des Kontozugangs; für diese Typen ist das Feld Pflicht. Felder, die zum Kontozugang gehören, etwa die Bootstrap Server von Kafka, lehnt das Deployment in config ab.
Kontozugänge sind wiederverwendbare Zugangsdaten für das ganze Projekt. Verwalte sie unter Projekt-Settings → Connections, wo zu jedem Kontozugang die Verbindungen je Environment aufgelistet sind, oder über die REST API und Connic MCP. Wenn du einen Kontozugang rotierst, übernehmen alle Verbindungen, die ihn verwenden, die neuen Zugangsdaten ohne Deployment. Solange eine Verbindung einen Kontozugang verwendet, lässt er sich nicht löschen. Für eigene Zugangsdaten je Environment setzt du connection in den Overrides der Environments.
bridge erwartet den Namen oder die ID einer Bridge. domain erwartet den Hostnamen einer aktiven Custom Domain des Projekts.
Von Connic erzeugte Werte
Einige Werte erzeugt Connic selbst: Webhook-URLs, die Secrets von Webhook-, WebSocket- und MCP-Verbindungen, das Signatur-Secret ausgehender Webhooks, das Secret der S3-URL und das Secret Token für Telegram. Sie gehören nicht in die Datei; connic lint lehnt sie ab. Connic legt sie beim ersten Deployment an, behält sie bei späteren Deployments bei und zeigt sie wie gewohnt an der Verbindung im Dashboard an. Auch eine weggelassene Kafka-group_id erzeugt Connic.
Voice-Verbindungen
Verbindungen für Twilio Voice und Telnyx Voice geben config.phone_number im E.164-Format an. Das Deployment sucht die Nummer im angegebenen Kontozugang. Eine Voice-Verbindung verknüpft genau einen Agenten, und dieser braucht voice_config.
type: twilio
connection: support-twilio
config:
phone_number: "+4930123456"
agents:
- support-voiceWas Deployments ändern
Jedes Deployment löst die Dateien für sein Environment in einen Snapshot auf, der mit dem Deployment gespeichert wird. Dabei prüft Connic Environment-Namen, Kontozugänge, Bridges, Variablen und Rufnummern. Jeder Fehler lässt das Deployment vor dem Build scheitern. Das Deployment-Log listet die Änderungen auf, die der Snapshot bei der Aktivierung vornimmt:
Connector changes on activation:
create: connectors/order-events.yaml (kafka)
update: connectors/support-inbox.yaml (email)
retire: connectors/legacy-orders.yaml (sqs)Beim Aktivieren eines Deployments wird sein Snapshot angewendet. Das passiert, wenn ein neues Deployment live geht, wenn du einen älteren Commit erneut deployst (die Variablen werden dabei neu aufgelöst) und wenn du zum Zurücksetzen ein älteres Deployment aktivierst. connic dev, Test-Runs und das Deploy Gate ändern keine Verbindungen.
Stillgelegte Verbindungen
Eine Verbindung, die das aktive Deployment nicht mehr deklariert, wird stillgelegt. Ein Deployment ohne Ordner connectors/ legt alle Code-Verbindungen seines Environments still. Eine stillgelegte Verbindung ist pausiert und behält URL, Secrets, Agent-Verknüpfungen, Bindungen beim Provider und den Run-Verlauf. Sie zählt nicht zum Limit aktiver Verbindungen und lässt sich nicht fortsetzen. Connic löscht stillgelegte Verbindungen nicht; lösche sie im Dashboard, wenn du sie nicht mehr brauchst.
Deklariert ein späteres Deployment die Datei wieder mit demselben Typ, kehrt die Verbindung mit ihrer URL, ihren Secrets und ihrem vorherigen Pausenstatus zurück. Wird auf ein Deployment zurückgesetzt, das sie deklariert hat, stellt Connic Konfiguration und Verknüpfungen dieses Deployments wieder her, mit den Variablenwerten, die bei diesem Deployment galten.
Typwechsel und Umbenennungen
name.Auch ein geänderter type legt die alte Verbindung still und erstellt eine neue.
Pausenstatus und Limits
Neue Code-Verbindungen starten aktiv. Das gilt auch für Kafka, SQS und PostgreSQL, die im Dashboard pausiert angelegt werden. Soll ein Environment noch nicht konsumieren, lass es in environments weg, bis es bereit ist. Deployments ändern den Pausenstatus bestehender Verbindungen nie; pausiere und setze sie im Dashboard fort. Das Limit aktiver Verbindungen gilt weiterhin: Eine neue Verbindung über dem Limit bleibt pausiert.
Rufnummern, Absender und Bots
Zwei aktive Verbindungen können nicht dieselbe Rufnummer, denselben Messaging-Absender oder denselben Telegram-Bot verwenden, auch nicht in verschiedenen Environments. Ein Deployment, das dazu führen würde, scheitert. Eine stillgelegte Verbindung gibt Rufnummer, Absender oder Bot frei, sobald eine andere Verbindung darauf angewiesen ist, und übernimmt sie wieder, wenn sie zurückkehrt.
Beim Anlegen oder Ändern einer Verbindung ersetzt Connic Einstellungen beim Provider, die nicht von Connic stammen, etwa einen bestehenden Webhook für eingehende Anrufe in Twilio, und schreibt die vorherigen Werte in die Verbindungs-Logs. Was jeweils ersetzt wird, steht auf den Seiten zu Twilio Voice, Twilio Messaging, Telnyx Voice, Telnyx Messaging und Telegram.
Regeln für Namen
Eine Code-Verbindung und eine im Dashboard angelegte Verbindung können im selben Environment nicht denselben Namen tragen. Ein Deployment, das diesen Konflikt erzeugen würde, scheitert. Dashboard, REST API und Connic MCP verweigern das Anlegen oder Umbenennen einer Dashboard-Verbindung auf einen Namen, den eine Code-Verbindung verwendet, auch wenn diese stillgelegt ist. connic lint meldet zwei Dateien, die im selben Environment denselben Namen verwenden.
Wenn eine Änderung an einer Verbindung fehlschlägt
Die Aktivierung erfolgt ganz oder gar nicht. Schlägt ein Aufruf beim Provider fehl, etwa weil die Twilio API einen Fehler meldet, wird nichts aktiviert und das bisherige Deployment bleibt live.
Um ohne die fehlerhaften Verbindungen live zu gehen, klicke auf der Deployment-Seite auf Deploy anyway. Damit wird der Commit erneut deployt und fehlerhafte Verbindungen werden übersprungen. Beim Zurücksetzen wählst du im Aktivierungsdialog Activate anyway oder rufst POST /v1/projects/{project_id}/deployments/{deployment_id}/activate?force=true auf. Übersprungene Verbindungen behalten ihren bisherigen Zustand; die nächste Aktivierung versucht erneut, sie anzuwenden.
Vor dem Zurücksetzen listet der Aktivierungsdialog auf, welche Verbindungen angelegt, aktualisiert, zurückgeholt oder stillgelegt würden.
Im Dashboard
Code-Verbindungen tragen das Badge In code. Im Dashboard lassen sie sich nicht bearbeiten, löschen oder mit Agenten verknüpfen, REST API und Connic MCP antworten mit 409. Pausieren und Fortsetzen bleiben möglich. Stillgelegte Verbindungen tragen zusätzlich das Badge Retired und lassen sich löschen.
Mit connic lint prüfen
connic lint prüft Verbindungsdateien offline: Aufbau, Typen und Modi, erzeugte Felder, die ${NAME}-Syntax, ob verknüpfte Agenten und source-Schlüssel existieren sowie Namenskonflikte zwischen Dateien. Environment-Namen, Kontozugänge, Bridges, Variablen und die Verfügbarkeit der Rufnummern prüft Connic beim Start des Deployments. connic deploy führt zuerst lint aus und lädt connectors/ mit dem übrigen Projekt hoch.