Build

Agent YAML

Agent-YAML-Felder sowie die Syntax für Prompts, Tools und bedingte Konfigurationen.

Zuletzt aktualisiert 2. Oktober 2026

Auf dieser Seite

Konfigurationsfelder

Feld	Typ	Status	Beschreibung
version	string	Erforderlich	Version des Konfigurationsschemas. Muss '1.0' sein.
name	string	Erforderlich	Eindeutige ID des Agenten. Verwende Kleinbuchstaben, Zahlen und Bindestriche.
type	string	Optional	Agent-Typ: `llm`, `sequential` oder `tool`. Siehe Agent-Typen.Standard: `llm`
description	string	Erforderlich	Lesbare Beschreibung der Aufgabe des Agenten.
model	string	Optional	Primäres KI-Modell. Für LLM-Agenten erforderlich. Siehe KI-Modelle und Provider.
fallback_model	string	Optional	KI-Modell nach einer fehlgeschlagenen primären Anfrage, solange Zeit bleibt und die Anfrage noch keine Ausgabe geliefert hat. Eine konfigurierte Kontextreparatur erfolgt zuerst. Siehe Fallback-Verhalten.
system_prompt	string	Optional	Anweisungen für LLM-Agenten. Verwende das Pipe-Zeichen von YAML für mehrere Zeilen.
tools	list	Optional	Tools, die in den Kontext eines LLM-Agenten geladen werden. Unterstützt Strings, Bedingungs-Mappings und Wildcard-Muster. Siehe Tools bedingt verfügbar machen. Maximal 100 pro Agent, einschließlich generierter `approval.inputs`-Tools. Tools von MCP-Servern und `discoverable_tools` zählen nicht mit.Standard: `[]`
discoverable_tools	list	Optional	Tools, die für die bedarfsgesteuerte Suche indexiert statt direkt geladen werden. Verwendet dieselben Strings, Bedingungen und Wildcards wie `tools`. Siehe Auffindbare Tools.Standard: `[]`
agents	string[]	Optional	Namen der Agenten, die der Reihe nach ausgeführt werden. Für Sequential-Agenten erforderlich.Standard: `[]`
tool_name	string	Optional	Eigenes Tool, das ein Tool-Agent direkt ausführt. Verwende den vollständigen Modulpfad in Punktnotation. Vordefinierte und api:-Tools sind nicht erlaubt.
max_concurrent_runs	integer	Optional	Maximale Anzahl gleichzeitiger Runs, begrenzt durch das Abonnement. Siehe Runtime-Steuerung.Standard: `1`
temperature	number	Optional	Steuert die Zufälligkeit der LLM-Ausgabe. Bei niedrigeren Werten fallen die Antworten gleichmäßiger aus.Standard: `1`
reasoning_effort	string	Optional	Verwende `auto` für modellgesteuertes Verhalten. Unterstützte Overrides unterscheiden sich je nach KI-Modell; siehe connic KI-Modelle oder die Dokumentation des BYOK-Providers.Standard: `auto`
reasoning_budget	integer	Optional	Direktes Reasoning-Token-Budget für KI-Modelle, die ein explizites Budget akzeptieren. Verwende reasoning_effort für KI-Modelle mit benannten Effort-Levels.
retry_options	object	Optional	Steuert Versuche, Zeitlimits pro Anfrage und Backoff bei allen Fehlern von KI-Modell-Anfragen. Der Agent wird dabei nicht neu gestartet. Bei Tool- und Sequential-Agenten gilt weiterhin die Wiederholung des jeweiligen Vorgangs.
attempts	integer	Optional	Maximale reguläre Anzahl einschließlich des ersten Versuchs. Ohne Fallback gilt sie für das primäre KI-Modell. Mit Fallback erhält das primäre KI-Modell einen Versuch und das Fallback-KI-Modell die konfigurierte Anzahl. Eine Kontextreparatur kann pro logischem Aufruf eine zusätzliche Anfrage an dasselbe KI-Modell ermöglichen. Bei Nicht-LLM-Agenten gilt die Anzahl für den Vorgang. Bereich: 1–10.Standard: `3`
attempt_timeout	number	Optional	Positive, endliche Zeitspanne in Sekunden für jede vollständige KI-Modell-Antwort oder den gesamten Stream, begrenzt durch die Restzeit des Runs. Eingehende Chunks setzen sie nicht zurück. Alle Versuche behalten das ursprüngliche Zeitlimit des Runs.Standard: `120`
initial_delay	number	Optional	Anfangswert für den berechneten Backoff in Sekunden. Weitere Anfragen an dasselbe KI-Modell verwenden exponentiellen Backoff mit Equal Jitter, sofern der Provider keinen gültigen Retry-After-Wert sendet. Der Wechsel zum Fallback erfolgt sofort.Standard: `10`
max_delay	number	Optional	Maximaler berechneter Backoff in Sekunden. Ein gültiger Retry-After-Wert ersetzt die berechnete Wartezeit; alle Wartezeiten bleiben durch das Run-Timeout begrenzt. Maximal 300.Standard: `30`
rerun_middleware	boolean	Optional	Before-Middleware erneut ausführen, wenn ein Tool- oder Sequential-Agent nach einem Fehler einen weiteren Versuch startet. Hat keine Auswirkung auf LLM-Agenten.Standard: `false`
timeout	integer	Optional	Maximale Ausführungszeit in Sekunden. Mindestens fünf Sekunden und stets durch das Abonnementlimit begrenzt.
max_iterations	integer	Optional	Maximale LLM-Loop-Iterationen pro Run. Verhindert Endlosschleifen und übermäßigen Ressourcenverbrauch.Standard: `100`
guardrails	object	Optional	Sicherheitsregeln für Input und Output von LLM-Agenten. Siehe Guardrails.
input	object[]	Optional	Regeln, die den eingehenden Input prüfen, bevor Middleware und Agent ihn verarbeiten.
output	object[]	Optional	Regeln, die vor der Rückgabe auf die Antwort angewendet werden.
run_after_on_block	boolean	Optional	Legt fest, ob After-Middleware ausgeführt wird, wenn eine Input-Regel die Anfrage blockiert.Standard: `true`
type	string	Erforderlich	Guardrail-Typ: prompt_injection, pii, moderation, topic_restriction, regex, pii_leakage, system_prompt_leakage, relevance, data_exfiltration oder custom.
mode	string	Optional	block, warn oder redact. Redaction wird nur für pii und pii_leakage unterstützt.Standard: `block`
name	string	Optional	Name des Guardrail-Moduls. Erforderlich, wenn type den Wert custom hat.
config	object	Optional	Optionen pro Regel, darunter messages, fail_run, entities, patterns, provider, sensitivity und model.
rejection_message	string	Optional	Nachricht, die bei einer Blockierung zurückgegeben wird. Ohne eigenen Wert wird off_topic_message verwendet.
off_topic_message	string	Optional	Nachricht bei Blockierungen durch topic_restriction und Fallback für rejection_message.
fail_run	boolean	Optional	Bei true markiert eine Blockierung den Run als fehlgeschlagen. Andernfalls wird eine abgeschlossene Antwort mit der Ablehnungsnachricht zurückgegeben.Standard: `false`
output_schema	string	Optional	Dateiname eines JSON-Schemas aus schemas/. Beschränkt die LLM-Ausgabe auf das Schema. Siehe Output Schema.
database	object	Optional	Zugriffskontrollen für Datenbank-Tools. Für uneingeschränkten Datenbankzugriff weglassen.
collections	string[] \| object	Optional	Beschränkt den Zugriff auf benannte Collections. Die Mapping-Form unterstützt Overrides für prevent_delete und prevent_write pro Collection.
prevent_delete	boolean	Optional	Blockiert db_delete. Ein Override der Collection kann diesen Wert ersetzen.Standard: `false`
prevent_write	boolean	Optional	Blockiert db_insert, db_update und db_upsert. Ein Override der Collection kann diesen Wert ersetzen.Standard: `false`
retrieval	object	Optional	Zugriffskontrollen für Retrieval-Tools. Für uneingeschränkten Retrieval-Zugriff weglassen.
namespaces	string[] \| object	Optional	Beschränkt den Zugriff auf benannte Namespaces. Die Mapping-Form unterstützt Overrides für prevent_delete und prevent_write pro Namespace.
prevent_delete	boolean	Optional	Blockiert retrieval_delete. Ein Override des Namespaces kann diesen Wert ersetzen.Standard: `false`
prevent_write	boolean	Optional	Blockiert retrieval_store. Ein Override des Namespaces kann diesen Wert ersetzen.Standard: `false`
files	object	Optional	Zugriffskontrollen für File-Tools. Für Zugriff auf den ganzen Dateibaum weglassen. Siehe File Tools.
folders	string[] \| object	Optional	Beschränkt den Zugriff auf diese Ordner und alles darunter. Die Mapping-Form unterstützt Overrides für prevent_delete, prevent_write und session_only pro Ordner.
prevent_delete	boolean	Optional	Blockiert file_delete. Ein Override des Ordners kann diesen Wert ersetzen.Standard: `false`
prevent_write	boolean	Optional	Blockiert file_write und file_update. Ein Override des Ordners kann diesen Wert ersetzen.Standard: `false`
session_only	boolean	Optional	Zeigt dem Agent nur Dateien, die in seiner aktuellen Session geschrieben wurden. Setzt session voraus. Ein Override des Ordners kann diesen Wert ersetzen.Standard: `false`
mcp_servers	object[]	Optional	Externe MCP-Server. Maximal 50 pro Agent. Siehe MCP Server verwenden.
name	string	Erforderlich	ID des MCP-Servers.
url	string	Erforderlich	Endpoint-URL des MCP-Servers.
tools	string[]	Optional	Optionaler Filter für zu ladende Tools. Weglassen, um jedes Tool des Servers zu verwenden.
headers	object	Optional	Authentifizierungs-Header. Unterstützt die Interpolation von Variablen mit `${VAR}` sowie die Interpolation pro Run mit `${context.*}`.
discoverable	boolean	Optional	Indexiert Tools dieses Servers für die bedarfsgesteuerte Suche, statt sie direkt zu laden.Standard: `false`
bridge	string	Optional	Bridge-ID für das Routing zu einem privaten Server. Unterstützt die Interpolation von `${VAR}`.
condition	string	Optional	Verbindet den Server nur, wenn dieser Ausdruck für den Run wahr ist. Nutzt dieselbe Syntax wie bedingte Tools.
optional	boolean	Optional	Setzt den Run ohne diesen Server fort, wenn die Verbindung oder das Abrufen seiner Tools fehlschlägt. Siehe Bedingte und optionale Server.Standard: `false`
concurrency	object	Optional	Ein aktiver Run pro aufgelöstem Schlüssel. Für Sequential-Agenten nicht unterstützt. Siehe Regeln zur Nebenläufigkeit.
key	string	Erforderlich	Pfad in Punktnotation zum Schlüssel in der Trigger-Payload.
on_conflict	string	Optional	queue wartet auf den aktiven Run; drop bricht den neuen Run ab; coalesce hält einen wartenden Run pro Schlüssel und ersetzt ihn durch neuere Events.Standard: `queue`
approval	object	Optional	Menschliche Freigaben und Tools für Eingaben. Siehe Approvals.
tools	list	Optional	Bestehende Tool-Referenzen, die eine Ja/Nein-Freigabe erfordern. Ein Mapping-Wert kann mit Ausdrücken für param.* und context.* festlegen, wann eine Freigabe nötig ist.Standard: `[]`
inputs	list	Optional	Nur für LLM-Agenten. Mappings mit je einem ASCII-Bezeichner von höchstens 64 Zeichen, etwa get_mfa, als Schlüssel und prompt, label sowie optional params und sensitive als Konfiguration. Namen müssen eindeutig sein, dürfen keine reservierten Namen der Tool-Suche verwenden und nicht mit tools, discoverable_tools oder approval.tools kollidieren. connic erstellt die Tools automatisch; generierte Eingabe-Tools zählen zum Limit von 100 Tools pro Agent.Standard: `[]`
prompt	string	Erforderlich	Tool-Beschreibung für den Agenten. Beschreibt, wann er eine menschliche Eingabe anfordern soll, und darf nicht leer sein.
params	list	Optional	Mappings mit je einem eindeutigen ASCII-Bezeichner als Schlüssel und str, int, float oder bool als Typ. Python-Schlüsselwörter und context sind als Namen nicht erlaubt. Der Agent muss alle definierten Parameter angeben; zusätzliche Argumente werden abgelehnt. Die Werte erscheinen als Kontext über dem Eingabefeld. Ohne diesen Abschnitt nimmt das Tool keine Argumente entgegen.Standard: `[]`
label	string	Erforderlich	Nicht leere Beschriftung mit höchstens 200 Zeichen über dem Eingabefeld.
sensitive	boolean	Optional	Verdeckt die Eingabe und schützt gespeicherte Antwortdaten. Das KI-Modell erhält weiterhin das Tool-Ergebnis. Den Umfang des Schutzes beschreibt die Approvals-Dokumentation.Standard: `false`
timeout	integer	Optional	Wartezeit auf eine Entscheidung in Sekunden. Bereich: 30–604800.Standard: `3600`
message	string	Optional	Eigene Nachricht für die Person, die den Aufruf prüft.
on_rejection	string	Optional	fail beendet den Run; continue gibt eine Ablehnungsnachricht an das LLM zurück, damit es sich anpassen kann.Standard: `fail`
session	boolean \| object \| null	Optional	True verwendet eine gemeinsame Session für alle Runs des Agenten; ein Objekt erlaubt weitere Einstellungen. False, null oder Weglassen deaktiviert Sessions. Siehe Persistente Sessions.
key	string \| null	Optional	Optionaler Pfad mit context.* oder input.* zur Session-ID. Ohne key oder mit null teilen alle Runs des Agenten eine Session.
ttl	integer \| null	Optional	Sekunden ohne Aktivität bis zum Ablauf der Session. Mindestens 60; ohne Wert oder mit null läuft sie nicht ab.Standard: `null`
history	boolean	Optional	Gesprächsverlauf über Runs hinweg behalten. Bei false beginnt jeder Run mit einem neuen Verlauf.Standard: `true`
browser	boolean	Optional	Browser-Cookies und Local Storage über Runs hinweg behalten. Bei false bleiben Browser-Tools verfügbar und starten mit leerem Browserzustand.Standard: `true`
context_compression	object	Optional	Verkürzt lange LLM-Gesprächsverläufe. Bei überschrittenem Kontextfenster erfolgt die Komprimierung vor dem Fallback und erlaubt eine zusätzliche Anfrage an dasselbe KI-Modell. Siehe Grenzen der Kontextreparatur. Ohne diese Option bleibt die Komprimierung deaktiviert.
enabled	boolean	Optional	Aktiviert die Komprimierung, wenn der Block vorhanden ist.Standard: `true`
model	string	Optional	Optionales KI-Modell, das nur für Zusammenfassungen bei der Komprimierung verwendet wird. Standardmäßig das KI-Modell des Agenten.
max_prompt_tokens	integer	Optional	Prompt-Token-Schwellenwert, der vor einem Kontextfensterfehler des Providers eine Komprimierung auslösen kann.
keep_recent_messages	integer	Optional	Neuere Nachrichten, die bei einer Komprimierung unverändert erhalten bleiben.Standard: `8`
session_history	object	Optional	Optionale Komprimierung des gespeicherten Verlaufs zwischen Runs. Weglassen, um sie zu deaktivieren.
interval	integer	Optional	Komprimiert älteren gespeicherten Verlauf nach dieser Anzahl von Runs.
keep_recent_runs	integer	Optional	Neuere Runs, die bei der Komprimierung des gespeicherten Verlaufs nicht zusammengefasst werden.Standard: `1`
voice_config	object	Optional	Ergänzt die Agentenkonfiguration um native Audio-Ein- und -Ausgabe. Modell, Prompt und Tools werden wie gewohnt konfiguriert. Siehe Voice-Konfiguration.
voice	string	Optional	ID der gewünschten Stimme beim gewählten Provider. Ohne Angabe verwendet er seine Standardstimme.
language	string	Optional	Bevorzugte Sprache, etwa en oder de-DE. connic ergänzt damit die Modellanweisungen und gibt die Sprache, soweit unterstützt, an die Transkription weiter. Die Spracherkennung wird dadurch nicht auf diese Sprache beschränkt.
transcription_model	string	Optional	OpenAI-Modell für die Transkription der Nutzerbeiträge oder Name eines vorhandenen Transkriptions-Deployments in derselben Azure-Ressource. Ohne Angabe werden Nutzerbeiträge bei OpenAI und Azure nicht transkribiert. Gemini und Vertex AI transkribieren nativ ohne diese Einstellung.
greeting	string	Optional	Begrüßung, die das Modell zu Beginn sprechen soll. Ohne Angabe wartet der Agent darauf, dass der Nutzer zuerst spricht.
thinking_sound	boolean	Optional	Spielt einen leisen, wiederkehrenden Ton, während Tools laufen oder der Provider Arbeit im Hintergrund meldet. Der Ton pausiert, sobald der Nutzer oder Agent spricht.Standard: `true`
hang_up_allowed	boolean	Optional	Erlaubt dem Agenten, das Gespräch selbst zu beenden. Die Verabschiedung wird vollständig abgespielt, bevor das Gespräch endet. Mit false wird diese Funktion deaktiviert.Standard: `true`
turn_detection	object	Optional	Einstellungen dafür, wie connic erkennt, dass der Nutzer fertig gesprochen hat.
silence_ms	integer	Optional	Dauer einer Sprechpause in Millisekunden, nach der der Agent davon ausgeht, dass der Nutzer fertig gesprochen hat. Muss größer als null sein. Ohne Angabe gilt der Standardwert des Providers.
interruptions	object	Optional	Steuert, ob der Nutzer die Sprachausgabe unterbrechen kann. Ohne dieses Objekt sind Unterbrechungen aktiviert.
enabled	boolean	Erforderlich	Ob der Nutzer den Agenten unterbrechen kann. Erforderlich, wenn interruptions angegeben ist.
idle_timeout_seconds	integer	Optional	Beendet das Gespräch nach der angegebenen Anzahl von Sekunden ohne Gesprächsaktivität. Laufende Tools und vom Provider gemeldete Arbeit im Hintergrund halten das Gespräch aktiv. Muss größer als null sein. Ohne Angabe gibt es dafür kein eigenes Zeitlimit. Das Timeout des Runs gilt weiterhin.
keypad	object	Optional	Ordnet Tasten (0-9, *, #) Tools zu, die unter tools stehen. Ein Tastendruck führt sein Tool ohne Modellantwort aus. Das Tool darf keine Pflichtparameter haben.

Erforderliche Felder nach Typ

Alle Agenten: version, name und description

LLM: + model und system_prompt · Sequential: + agents · Tool: + tool_name

System Prompts schreiben

agents/agent.yaml

system_prompt: |
  This is a multi-line system prompt.

  You can write multiple paragraphs here.
  The pipe character (|) preserves newlines.

  Use this for complex instructions.

Tools referenzieren

agents/agent.yaml

# Reference tools by exact module path under tools/
tools:
  - search.web_search            # tools/search.py -> web_search()
  - billing.calculator.add       # tools/billing/calculator.py -> add()
  - email.send_notification      # tools/email.py -> send_notification()
  - billing.*                    # all public functions in tools/billing.py
  - support.search_*             # functions starting with search_ in tools/support.py

Tools sind Python-Funktionen unter tools/. Module auf oberster Ebene verwenden Referenzen wie calculator.add; verschachtelte Module nutzen ihren vollständigen Pfad in Punktnotation. Siehe Custom Tools schreiben.

Die Wildcard * steht für beliebige Zeichen im Funktionsnamen oder Modulpfad. billing.* schließt jede öffentliche Funktion in tools/billing.py ein, während support.search_* passende Funktionen einschließt. Wildcards funktionieren auch mit API-Spec-Tools. Eine Wildcard ohne Punkt gleicht die Namen vordefinierter Tools ab; db_* schließt beispielsweise alle vordefinierten Datenbank-Tools ein. Das Deployment schlägt fehl, wenn eine Wildcard nichts findet.

Tools bedingt verfügbar machen

Ordne einer Tool-Referenz einen Ausdruck zu, damit das Tool nur verfügbar ist, wenn der Ausdruck true ergibt. Bei false wird das Tool für diese Anfrage entfernt.

agents/agent.yaml

# Conditional tools use Python expression syntax.
tools:
  - calculator.add
  - calculator.multiply: context.multiply_allowed
  - web_search: input.search_enabled
  - admin.dangerous_tool: input.role == 'admin' or context.admin
  - premium.tool: input.tier == 'pro' and context.feature_on
  - optional.tool: not context.disabled

Expression-Syntax

Python-ähnliche Syntax: and, or, not; Vergleiche == != > < >= <=; Zugehörigkeit mit in und not in; Klammern zur Gruppierung; String-Literale in einfachen oder doppelten Anführungszeichen. Verschachtelte Objekte sind über Pfade mit Punktnotation wie context.user.role erreichbar. Ein einzelner Pfad wie context.active prüft, ob der Wert gesetzt und weder leer noch null oder false ist. Fehlt ein Feld, ist die Bedingung nicht erfüllt; es wird kein Fehler ausgelöst.

context.<key>

Werte aus dem Run-Kontext, einschließlich Middleware-Werten und von connic bereitgestellten Run-Metadaten. Verschachtelte Pfade wie context.user.role werden unterstützt.

input.<key>

Werte aus der JSON-Payload der Verbindung. Bei Nicht-JSON-Payloads ist jede input.*-Prüfung false.

Kontext in Middleware setzen

middleware/assistant.py

async def before(content: dict, context: dict) -> dict:
    # Set context values that tool conditions can check.
    payload = context.get("payload", {})
    context["multiply_allowed"] = True
    context["admin"] = payload.get("role") == "admin"
    return content

Expression-Validierung

Das Deployment lehnt ungültige Syntax von Python-Ausdrücken ab. Zur Laufzeit ergeben nicht unterstützte Ausdrucksformen und unbekannte Root-Werte false. Ein einfacher Zugriff wie context.foo ist eine Truthiness-Prüfung.

Auffindbare Tools

Wenn ein großes Toolset in den KI-Modell-Kontext geladen wird, steigt der Token-Verbrauch und die Genauigkeit kann sinken. Lege selten verwendete Tools unter discoverable_tools ab, damit der Agent sie bei Bedarf über eine natürlichsprachige Suche findet. Die Liste unterstützt dieselben Strings, Wildcards und Bedingungen wie tools. Die Suche gleicht die Wörter der Anfrage des Agenten mit Tool-Namen und Beschreibungen ab. Schreibe Beschreibungen daher in der Sprache, in der der Agent arbeitet. Das Finden eines Tools kostet einen zusätzlichen Schritt des KI-Modells vor dem Aufruf; häufig genutzte Tools gehören deshalb in tools.

agents/multi-purpose-assistant.yaml

version: "1.0"

name: multi-purpose-assistant
type: llm
model: connic/gpt-5.6-terra
description: "Assistant that discovers tools on demand to keep context lean"
system_prompt: |
  You are a multi-purpose assistant with access to many tools.

# Always available in the LLM context
tools:
  - math.calculator.add
  - math.calculator.multiply

# Indexed for on-demand discovery at runtime
discoverable_tools:
  - math.calculator.calculate_tax
  - orders.*
  - social.twitter.post_tweet
  - assistant_tools.*

Auffindbare MCP Server

Markiere einen vollständigen MCP Server als auffindbar, um seine Tools zu indexieren, statt sie direkt zu laden.

agents/agent.yaml

mcp_servers:
  - name: large-toolset
    url: https://mcp.example.com/tools
    discoverable: true   # tools indexed for search, not loaded upfront

Keine Überschneidungen erlaubt

Eine Funktion darf nicht gleichzeitig über tools und discoverable_tools aufgelöst werden. Bei einer Überschneidung der Listen schlägt das Deployment fehl.

Agent-Konfiguration fortsetzen

Runtime-SteuerungParallele Runs, Sessions und gemeinsame Standardwerte konfigurieren Output SchemaOutput mit einem JSON Schema beschränken KI-Modelle und ProviderEin unterstütztes KI-Modell auswählen und konfigurieren Agent-TypenDen passenden Agent-Typ für den Workflow auswählen