Build

Agent YAML

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

Zuletzt aktualisiert 20. August 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	Fallback, wenn die Anfrage an das primäre KI-Modell fehlschlägt, bevor eine Ausgabe zurückgegeben wurde.
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.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	Legt fest, wie fehlgeschlagene Vorgänge wiederholt werden. Bei LLM-Agenten wird nur die fehlgeschlagene KI-Modell-Anfrage erneut gesendet. Bei Tool- und Sequential-Agenten wird der Vorgang erneut ausgeführt.
attempts	integer	Optional	Maximale Anzahl der Versuche einschließlich des ersten Aufrufs. Bei konfiguriertem Fallback wird das primäre KI-Modell einmal aufgerufen; die angegebene Anzahl gilt dann für das Fallback-KI-Modell. Bei Tool- und Sequential-Agenten gilt sie für den gesamten Vorgang. Maximal 10.Standard: `3`
initial_delay	number	Optional	Wartezeit vor dem ersten Wiederholungsversuch in Sekunden. KI-Modell-Anfragen verwenden begrenzten exponentiellen Backoff mit Jitter, sofern der Provider kein Retry-After sendet.Standard: `10`
max_delay	number	Optional	Maximale automatisch berechnete Wartezeit zwischen Versuchen in Sekunden. Auch wenn der Provider mit Retry-After eine Wartezeit vorgibt, gilt weiterhin das Gesamt-Timeout. 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`
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}`.
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.Standard: `queue`
approval	object	Optional	Menschliche Freigabe für ausgewählte Tools. Siehe Approvals.
tools	list	Erforderlich	Tool-Referenzen, die eine Freigabe erfordern. Ein Mapping-Wert kann mit Ausdrücken für param.* und context.* festlegen, wann eine Freigabe nötig ist.
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	object	Optional	Gespeicherter Gesprächsverlauf, der über einen Schlüssel zugeordnet wird. Siehe Persistente Sessions.
key	string	Erforderlich	Pfad in Punktnotation zur Session-ID. Muss mit context. oder input. beginnen.
ttl	integer	Optional	Zeit ohne Aktivität, nach der eine Session abläuft, in Sekunden. Mindestens 60; ohne diesen Wert laufen Sessions nicht ab.
context_compression	object	Optional	Komprimierung während langer LLM-Sessions. Weglassen, um die Komprimierung zu deaktivieren.
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`

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. 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.

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-Steuerung

Parallele Runs, Sessions und gemeinsame Standardwerte konfigurieren

Output Schema

Output mit einem JSON Schema beschränken

KI-Modelle und Provider

Ein unterstütztes KI-Modell auswählen und konfigurieren

Agent-Typen

Den passenden Agent-Typ für den Workflow auswählen