multica-creating-agents

Erstellen von Multica-Agenten

Dies ist die Spezifikation für den Erstellungsweg von Multica-Agenten: Was die Erstellungs-Einstiegspunkte akzeptieren, was der Server validiert und ablehnt, wie jedes Feld persistiert wird und welche Felder der Daemon zum Zeitpunkt der Anforderung tatsächlich ausliest. Es handelt sich nicht um ein Parameterhandbuch – es enthält auf den Quellcode zurückverfolgbare Fakten, und jeder Anspruch wird durch „Datei:Zeile“ in „references/creating-agents-source-map.md“ belegt.

Schnellstart (schreibgeschützte Überprüfung)

Diese Befehle lesen den Status aus und haben keine Nebenwirkungen:

multica agent get  --output json      # vollständiger persistierter Agent-Datensatz
multica agent skills list  --output json   # aktuelle Skill-Zuordnungen
multica agent env get  --output json  # Umgebungsvariablen im Klartext (nur für Eigentümer/Administratoren, Agenten haben keinen Zugriff)

„agent get“ gibt den gespeicherten Agenten zurück, einschließlich runtime_id, model, thinking_level, service_tier, custom_args, has_custom_env, custom_env_key_count und skills. Es gibt niemals „custom_env“ im Klartext zurück.

Kernmodell

Ein Agent ist eine Zeile im Arbeitsbereich (Tabelle „agent“). Die Erstellung erfolgt über einen einzelnen POST-Aufruf an /api/agents (multica agent create). Zum Zeitpunkt der Aufgabenübernahme liest der Daemon die Agent-Zeile erneut ein und stellt die Laufzeit-Nutzlast zusammen – daher basieren die Ausführungen des Agenten auf den persistierten Feldern und nicht auf den Werten zum Zeitpunkt der Erstellung.

Zwei unterschiedliche Textfelder, die oft verwechselt werden:

• „description“ ist eine Katalogzusammenfassung. Sie wird gespeichert und in Listen angezeigt; der Daemon fügt sie NICHT in die Laufzeit-Eingabeaufforderung des Agenten ein. Behandeln Sie sie ausschließlich als für Menschen bestimmte Metadaten. Begrenzt auf 255 Unicode-Codepunkte.
• „instructions“ ist die Vereinbarung zum Laufzeitverhalten. Der Daemon liest sie zum Zeitpunkt der Anforderung und übermittelt sie als dauerhafte Anweisungen des Agenten an den Anbieter. Persona, Verantwortlichkeiten, Grenzen, Ausgabe- und Eskalationsregeln gehören hierher, nicht in die „description“.

CLI-/API-Einstiegspunkte

Mindestanforderung für den Erstellungsaufruf (--name und --runtime-id sind beide erforderlich):

multica agent create --name  --runtime-id  \
  --description "" \
  --instructions "" \
  --output json

runAgentCreate erstellt einen JSON-Body und sendet ihn an /api/agents. Es fügt nur dann einen Schlüssel hinzu, wenn das entsprechende Flag angegeben wurde –description/instructions mit einem nicht leeren Wert, den Rest (runtime-config, custom-args, model, thinking-level, service-tier, visibility, …) bei Änderung des Flags – so werden weggelassene Flags auf die Server-Standardwerte zurückgesetzt, anstatt leere Zeichenfolgen zu senden.

Der HTTP-Body (CreateAgentRequest) akzeptiert: name, description, instructions, avatar_url, runtime_id, runtime_config, custom_env, custom_args, model, thinking_level, service_tier, visibility, max_concurrent_tasks, mcp_config.

Feldkonventionen

Standardwerte bei Weglassung: runtime_config → {}, custom_env → {}, custom_args → [], avatar_url → ein zufälliges Emoji:, visibility → private, max_concurrent_tasks → 6 (alles wird vor dem Einfügen serverseitig materialisiert).custom_args/runtime_config sind vom Typ []string/any und werden unverändert marshaled – die Ablehnung aufgrund der JSON-Struktur erfolgt in der CLI, nicht im Create-Handler.

„thinking_level“ wird nur auf Anbieterebene validiert: Anbieter mit festem Katalog lehnen ein unbekanntes Literal ab, während Anbieter mit dynamischem Katalog wie Codex/OpenCode ein syntaktisch korrektes Token akzeptieren. Ein Wert, der für das gewählte Modell nicht unterstützt wird, wird hier NICHT abgelehnt – der Daemon überprüft seinen lokalen Modellkatalog zur Laufzeit, protokolliert eine Warnung und lässt die inkompatible Überschreibung außer Acht.

Stellen Sie ihn über die CLI mit `--thinking-level` bei `agent create ` und `agent update` ein, analog zu `--model`: Das Flag ist eine einfache Weiterleitung an das oberste `thinking_level` -Feld, und bei einer Aktualisierung setzt eine leere Zeichenkette (`--thinking-level ""`) den Wert wieder auf den Laufzeitschutzwert zurück. Die Befehlszeile listet bewusst nicht die gültigen Stufen auf – sie sind laufzeit- und modellspezifisch (Claude verwendet derzeit low|medium|high|xhigh|max; Codex-Werte werden aus dem Modellkatalog der Laufzeitumgebung abgerufen). Sie leitet das Token weiter, der Server wendet die „fixed-enum“- oder „safe-token“-Prüfung des Anbieters an, und der Daemon führt die genaue Modell-/Stufen- Prüfung durch. Eine Laufzeitumgebung, deren Anbieter kein „thinking“-Konzept hat, lehnt jeden nicht leeren Wert mit einem 400-Fehler ab.

„service_tier“ ist die entsprechende erstklassige Codex-Geschwindigkeitssteuerung. Setzen Sie sie mit „--service-tier “ beim Erstellen/Aktualisieren; verwenden Sie „--service-tier ""“ beim Aktualisieren, um sie zu löschen. Der Modellkatalog der Laufzeitumgebung verwaltet sowohl die Verfügbarkeit als auch die Anzeigekopie (derzeit „priority“, angezeigt als „Fast“). Der Server akzeptiert sichere zukünftige Codex-Katalog-IDs, während der Daemon das genaue Modell-/Tier-Paar vor der Ausführung überprüft und eine veraltete, inkompatible Überschreibung auslässt. Agenten ohne ein explizites Modell schlagen mit „closed“ fehl, da das effektive „config.toml“-Modell unbekannt ist.

Modell vs. custom_args

„model“ ist eine persistierte Spalte erster Klasse, die der Daemon direkt ausliest. „custom_args“ sind rohe CLI-Argumente des Anbieters. In der CLI-Hilfe wird darauf hingewiesen, dass einige Anbieter (Codex App-Server, Openclaw) „--model“ innerhalb von „custom_args“ ablehnen – dies ist jedoch eine dokumentierte CLI-Richtlinie und keine vom Server erzwungene Invariante; im „create“-Handler wird „custom_args“ nicht auf ein Modell-Flag überprüft.

Umgebung & Geheimnisse

„custom_env“ enthält vertrauliche Daten. Die CLI bietet drei Eingabekanäle; zwei halten Geheimnisse aus dem Shell-Verlauf und der Prozessliste fern:

multica agent create --name  --runtime-id  --custom-env-stdin --output json
multica agent create --name  --runtime-id  --custom-env-file <0600-json> --output json

--custom-env-stdin liest das JSON-Objekt aus der Standard-Eingabe; --custom-env-file liest es aus einer Datei (empfohlene Berechtigung 0600). Der dritte Kanal, --custom-env , stellt den Wert in die Befehlszeile, wo er vom Shell-Verlauf und von `ps` eingesehen werden kann – vermeiden Sie dies bei echten Geheimnissen.

Fakten auf der Leseseite (dies sind die falschen Annahmen, die es zu vermeiden gilt):

• Agent-Ressourcen geben „custom_env“ niemals im Klartext preis. Die Befehle „agent list/get/create/update“ sowie WS-Ereignisse geben nur „has_custom_env“ (bool) und „custom_env_key_count“ (int) zurück.
• Das Auslesen von Werten im Klartext erfordert den speziellen GET-Endpunkt /api/agents/{id}/env (multica agent env get). Der Zugriff ist auf den Workspace -Besitzer und die Administratoren beschränkt, und Agenten-Akteuren wird der Zugriff unabhängig von der Rolle des zugrunde liegenden Mitglieds verweigert – ein laufender Agent kann die Geheimnisse eines anderen Agenten nicht lesen.
• Das Schreiben von Werten nach der Erstellung erfolgt NICHT über die Agent-Aktualisierung. Der generische Update-Handler lehnt jedes „custom_env“-Feld mit einem 400-Fehler ab („use PUT /api/agents/{id}/env“). Das Schreiben von Umgebungsvariablen im Klartext wird über PUT /api/agents/{id}/env (Multica-Agent-Umgebungsvariable setzen) abgewickelt, was nur für Eigentümer/Administratoren zugänglich ist und eine Audit-Zeile schreibt.

mcp_config

mcp_config ist die MCP-Serverkonfiguration des Agenten (ein JSON-Objekt wie z. B. {"mcpServers": {…}}). Es handelt sich ebenfalls um vertrauliche Daten – MCP-Einträge enthalten regelmäßig API-Token – und bietet dieselben drei Eingabekanäle wie „custom_env“, sowohl beider Agentenerstellung als auch bei der Agentenaktualisierung:

multica agent create --name  --runtime-id  --mcp-config-file <0600-json> --output json
multica agent update  --mcp-config-stdin --output json
multica agent update  --mcp-config 'null'   # löscht die Konfiguration

--mcp-config-stdin / --mcp-config-file: Der Wert wird nicht in den Shell-Verlauf und in „ps“ übernommen; bei der Inline-Option --mcp-config ist dies nicht der Fall. Die CLI erfordert einJSON-Objekt oder den Literalwert „null“; ein Array oder ein primitiver Typ auf oberster Ebene wird auf Client-Seite abgelehnt, und leere Eingaben über stdin oder aus einer Datei führen zu Fehlern, anstatt stillschweigend gelöscht zu werden.

Zwei Unterschiede zwischen mcp_config und custom_env:

• Es IST über ein Agent-Update einstellbar. Im Gegensatz zu custom_env verfügt mcp_config über keinen dedizierten, auditierten Endpunkt – der generische PUT-Endpunkt /api/agents/{id} akzeptiert es. Drei Zustände je nach Rohdaten des Request-Bodys: Feld weggelassen → keine Änderung; null → löschen; Objekt → ersetzen.
• Es wird beim Lesen serialisiert, jedoch redigiert. agentget/list geben mcp_config nur an Aufrufer zurück, die zur Einsicht in Agent-Geheimnisse berechtigt sind; andernfalls ist das Feld null und mcp_config_redacted ist wahr. Agent-Akteure sehen es niemals, und ein Workspace kann die Redigierung für alle erzwingen.

Die Unterstützung durch Anbieter ist nicht einheitlich: Qwen Code akzeptiert ein verwaltetes `mcp_config` über eine dem Daemon gehörende temporäre JSON-Datei mit der Berechtigungsstufe 0600, die mit `--mcp-config` übergeben wird; diese wird beim Beenden des Laufs entfernt. Lassen Sie das Feld ungesetzt (null), um die nativen Einstellungen von Qwen Code zu übernehmen.

Skill-Bindung

Das Erstellen eines Agenten bindet KEINE Workspace-Skills – die Bindung erfolgt über einen separaten Aufruf, nachdem der Agent existiert. Zwei unterschiedliche Verben:

• „add“ ist additiv – es fügt die angegebenen IDs zu den bestehenden Bindungen hinzu (POST /api/agents/{id}/skills/add).
• „set“ ersetzt alles – es überschreibt die gesamte Bindungsliste vollständig durch genau die angegebenen IDs (PUT /api/agents/{id}/skills); „--skill-ids “ löscht alle.

multica agent skills add  --skill-ids  --output json
multica agent skills list  --output json

Zum Zeitpunkt der Anforderung stellt der Daemon ZUERST die Fähigkeiten des Agenten als arbeitsbereichsgebundene Fähigkeiten zusammen, dann werden die in die Plattform integrierten Fähigkeiten angehängt. „LoadAgentSkills“ lädt den Inhalt jedes gebundenen Skills sowie dessen zugehörige Dateien; integrierte Skills werden zur Kompilierungszeit eingebettet und aus „SKILL.md“ sowie den zugehörigen Dateien geladen. Beides gelangt als Skill-Inhalt zum Anbieter – weshalb die Fähigkeit in einem gebundenen Skill enthalten sein sollte und nicht in Anweisungen eingefügt werden darf.

Genehmigungspflichtige Nebenwirkungen

Schreibgeschützt (sicher): Agent abrufen, Agenten-Fähigkeitenliste, Agentenumgebung abrufen.

Zustandsändernd (erfordern eine explizite Anweisung – nicht spekulativ ausführen):

• multica agent create – fügt eine neue Agentenzeile ein.
• multica agent skills add / set – verändert Bindungen (set ist destruktiv: es löscht Bindungen, die nicht in der neuen Liste enthalten sind).
• multica agent env set – überschreibt die gesamte „custom_env“-Map und schreibt eine Audit-Zeile.

Häufige falsche Annahmen

• „Die Beschreibung ist die Eingabeaufforderung.“ Das ist nicht der Fall – nur Anweisungen gelangen in die Laufzeit. Eine ausführliche Beschreibung mit leeren Anweisungen führt zu einer benannten Shell ohne Ausführungskontrakt.
• „Create bindet die Fähigkeiten des Agenten.“ Das tut es nicht; binde sie anschließend explizit.
• „`agent update ` kann die Umgebung rotieren.“ Das kann es nicht – es gibt einen 400-Fehler bei ` custom_env`; verwende den `env`-Endpunkt.
• „mcp_config verhält sich bei einem Update wie custom_env.“ Das tut es nicht – mcp_config kann über `agent update ` (--mcp-config) gesetzt werden, wobei --mcp-config null gesetzt wird, um es zu löschen; nur custom_env wird über den dedizierten env-Endpunkt gesteuert.
• „`agent get ` zeigt `env`-Werte an.“ Es werden nur ` has_custom_env ` und `custom_env_key_count` angezeigt.
• „Eine ungültige Kombinationaus thinking_level und model wird beim Erstellen erkannt.“ Dies gilt nur für unbekannte Literale auf Anbieterebene – modellspezifische Lücken führen zu Fehlern zur Laufzeit.
• „set und add sind bei Skills austauschbar.“ set ersetzt alle Bindungen; wenn Sie es verwenden, obwohl Sie add gemeint haben, werden Fähigkeiten stillschweigend entfernt.

Referenzen

references/creating-agents-source-map.md ordnet jeden der oben genannten Verträge seiner Datei:Zeile im aktuellen Baum, der Auswirkung zur Laufzeit und einem sicheren, schreibgeschützten Überprüfungsbefehl zu.