Docs

Agentenmodus-Ausgabe

TL;DR

  • Die ppl-CLI hat zwei Oberflächen — eine Human-Oberfläche (hübsche Tabellen, interaktive Prompts, jedes Verb verfügbar mit expliziter Bestätigung) und eine Agenten-Oberfläche (maschinenlesbares JSON, schlanke Projektionen, destruktive commit-seitige Verben versiegelt). Dasselbe Binary bedient beide; das aktive Profil entscheidet, welche Oberfläche antwortet.
  • Der Agentenmodus ist eine echte Ausführungsoberfläche, kein Formatierungs-Flag. Die Ausgabeform ändert sich, die verfügbaren Verben ändern sich, der Sicherheitsvertrag ändert sich. Das Wechseln von Profilen erfolgt mit ppl mode <profile> (klebrig) oder ppl --agent=<profile> <cmd> (einmalig, kein Probelauf).
  • Jeder Befehl im Agentenmodus gibt eine von vier Ausgabe-Envelope-Formen zurück — einzelner Datensatz als JSON, paginiertes {count, items}, Mutation {ok:true, data:…} oder Fehler {ok:false, error:{…}} auf stderr. Der Exit-Code ist 0 bei Erfolg, 1 bei Fehler.
  • Listenbefehle geben standardmäßig eine schlanke Projektion pro Datensatz, begrenzt auf 20 Datensätze zurück, ausgelegt auf LLM-Kontext-Effizienz. Filtere mit --query=<text> (Agenten-only-Flag, Matcher pro Ressource); hebe die Grenze mit --limit an.
  • Destruktive commit-seitige Verben sind im Agentenmodus für Menschen versiegelt (ppl component promote, Überschreiben freigegebener Versionen). Agenten bereiten vor und schlagen vor; Menschen committen. Der Rückweg von Agent zu human erfordert ein frisches ppl login — kein schneller Wechsel, per Design.

Was der Agentenmodus tatsächlich ist

Der Agentenmodus ist ein benanntes, persistentes Ausführungsprofil der ppl-CLI, das drei Dinge auf einmal ändert: die Ausgabeform wird zu maschinenlesbaren JSON-Envelopes, die verfügbare Befehlsoberfläche lässt die destruktiven commit-seitigen Verben fallen, und die Session-Grenze verhindert, dass ein Agentenprofil mitten im Workflow stillschweigend zurück ins Human-Profil wechselt. Es ist eine eigenständige Ausführungsoberfläche, kein --json-Formatierungs-Flag, das über die Human-Befehle gelegt wird.

Die drei Änderungen sind gekoppelt, weil ein LLM, das die Plattform steuert, sie alle zusammen braucht. JSON-Envelopes geben dem LLM eine stabile Form zum Parsen statt Human-Tabellen, die es abkratzen müsste. Das Entfernen destruktiver Verben aus dem Agentenprofil bedeutet, dass das LLM sie gar nicht aufrufen kann, statt sich darauf zu verlassen, dass das LLM sie erkennt und vermeidet. Die Session-Grenze hält einen Agenten-Workflow innerhalb des Agentenprofils, bis ein Mensch sich explizit wieder anmeldet.

Diese Entscheidungen bilden die Arten ab, auf die ein LLM, das Shell-Befehle ausführt, scheitert, wenn die Oberfläche für Menschen gebaut ist. Breite Tabellen verbrauchen Kontext, für den das LLM ein festes Budget hat. Interaktive Bestätigungs-Prompts blockieren, weil das LLM keine Möglichkeit hat, sie zu beantworten. Destruktive Verben können feuern, wenn eine Bestätigung falsch gelesen wird. Lang laufende Befehle emittieren Log-Rauschen, das das LLM dann filtern muss. Die Agenten-Oberfläche adressiert jedes davon auf Plattformebene, sodass das LLM nicht darum herum arbeiten muss.

Der Vertrag, den dies von Agentenautoren verlangt — ob der Agent eine Claude-Session, ein CI-gesteuertes Skript oder irgendein anderer LLM-gesteuerter Workflow ist — lautet: das richtige Profil für die Aufgabe wählen, die Envelope-Form parsen und die Versiegelungen respektieren. Die Plattform legt dann eine Oberfläche offen, die das LLM direkt steuern kann, statt einer, die es umhüllen muss.

Mentales Modell — ein Binary, zwei Oberflächen

   ┌──────────────────────────────────────────────────────────────┐
   │ ppl                                                          │
   │   ├── human surface                                          │
   │   │     pretty tables, prompts, interactive flows            │
   │   │     destructive commit-side verbs callable with          │
   │   │     explicit confirm                                     │
   │   │                                                          │
   │   └── agent surface                                          │
   │         ppl mode <profile>  OR  ppl --agent=<profile>        │
   │         machine-readable JSON envelopes                      │
   │         lean per-record projections                          │
   │         per-resource --query matcher (agent-only flag)       │
   │         destructive commit-side verbs SEALED                 │
   └──────────────────────────────────────────────────────────────┘

Für einen Eröffnungs-Prompt gibt ppl mode general einem LLM die breiteste Startoberfläche. Wechsle zu component, backend, ci-cd oder application, sobald die Aufgabe bekannt ist.

Das Ausgabe-Envelope

Jeder Befehl im Agentenmodus schreibt eine von vier Formen:

single-record stdout : <json>
paginated list stdout: {"count":<total>,"items":[...]}
mutation stdout      : {"ok":true,"data":<json>}
error stderr         : {"ok":false,
                        "error":{"error":"<msg>",
                                 "code":"<machine-code>",
                                 "detail":"...",
                                 "suggestion":"...",
                                 "fields":{...},
                                 "trace_id":"...",
                                 "status_code":<int>}}

Der Exit-Code ist 0 bei Erfolg, 1 bei Fehler. Das Fehler-Envelope ist verschachtelt — das äußere Objekt hat immer {"ok":false,"error":{…}}, und das innere Objekt trägt error (Human-Nachricht), code (maschinenlesbare Kennung) sowie detail / suggestion / fields / trace_id / status_code. Diese inneren Slots sind immer vorhanden: nicht gesetzte String-Slots serialisieren als "" und fields als {}, verzweige also danach, ob ein Wert nicht leer ist, statt danach, ob der Schlüssel vorhanden ist. Prüfe stets den Exit-Code UND parse stderr; der Exit-Code allein genügt nicht, um Fehlerkategorien zu unterscheiden.

Schlanke Listenprojektionen

Jeder Listenbefehl gibt im Agentenmodus eine schlanke Projektion pro Datensatz zurück, nicht das vollständige Objekt. Jeder Datensatz trägt nur, was ein Agent braucht, um ein Ergebnis nachzuschlagen, zu verwandten Ressourcen zu routen und in den nächsten Aufruf zu verketten — eine id, ein menschenlesbares Label, einen Status, die ids, die ihn mit anderen Ressourcen verbinden, ein paar Zähler und die relevanten Zeitstempel. Die schweren Felder — vollständige Konfigurationen, Dokumentinhalte, verschachtelte Graphen — werden weggelassen, damit Antworten klein und günstig zu parsen bleiben.

Wenn der vollständige Datensatz gebraucht wird, hole ihn per id mit dem passenden get-Befehl (ppl component get <id>, ppl backend get <id> und so weiter).

Paginierte Befehle umhüllen die Datensätze als {"count": <total>, "items": [...]}; die übrigen geben ein nacktes Array zurück. Der genaue Feldsatz, den jeder Befehl behält, ist Teil des Vertrags dieses Befehls — er wird unter Output schema: in --help ausgegeben, was die maßgebliche Referenz ist. Diese Seite erklärt die Form, nicht die Feldlisten pro Befehl.

Pagination und die Grenze von 20 Datensätzen

Listen im Agentenmodus liefern standardmäßig 20 Datensätze, und die Grenze gilt auch, wenn --query gesetzt ist. Übergib --limit=N, um sie bei Befehlen anzuheben, die das Flag unterstützen. Kombiniere --query mit --limit, wann immer eine Teilübereinstimmung plausibel auf mehr als 20 Zeilen auflösen könnte.

Das Flag --query

Jeder durchsuchbare Listenbefehl akzeptiert im Agentenmodus --query=<text>. Die übereinstimmende Oberfläche ist pro Ressource — keine einheitliche Teilstring-Suche auf name/display_name:

  • ppl file list — passt auf display_name und read_me.
  • ppl node list — passt auf display_name.
  • ppl component list, ppl backend list, ppl runtime list, ppl team list — passen auf name und/oder display_name, mit Trigramm-Ähnlichkeit bei manchen Ressourcen.

Der genaue Matcher ist pro Befehl in --help dokumentiert.

ppl component list --query=detect-objectsppl backend list   --query=demoppl runtime list   --query=prodppl file list      --query=modelppl node list      --query=gpu

Drei Muster, die beim Skripten gegen die CLI wiederholt auftauchen:

# 1. Component lookup by partial nameCOMP_ID=$(ppl component list --query=detect-objects \          | jq -r '.items[] | select(.name=="detect_objects") | .id')# 2. Latest version of a componentVER_ID=$(ppl component versions $COMP_ID \         | jq -r '.[-1].id')# 3. A Runtime by display nameCAP_ID=$(ppl runtime list --query=staging \         | jq -r '.items[0].id')

--query ist agenten-only — es erscheint nicht in der Hilfe des Human-Modus.

Streaming-Befehle

ppl component publish, ppl backend deploy und andere lang laufende Befehle halten das finale JSON standardmäßig maschinenlesbar. Reaktiviere das vollständige Streaming-Log mit --verbosity build|all zum Debuggen.

Sessions und die human-only Commit-Grenze

Ein ppl login öffnet eine Human-Session. Der Wechsel in ein Agentenprofil erfolgt mit ppl mode <profile> (persistiert) oder ppl --agent=<profile> <cmd> (pro Aufruf); die Rückkehr zu human ist ein frisches ppl login, kein schneller Wechsel. Die Asymmetrie ist bewusst: Agentenprofile versiegeln die destruktiven commit-seitigen Verben, sodass Agenten vorbereiten und vorschlagen, während Menschen committen. Welche Verben versiegelt sind und warum, ist abgedeckt in Destruktive Operationen und Publish-Semantik — diese Seite wiederholt es nicht.

Die Docs-Registry als Karte des Agenten

Die Docs-Registry ist die kanonische Quelle der Wahrheit für das, was die Plattform offenlegt. Bevorzuge sie gegenüber Annahmen oder veralteten Referenzen — die Registry ist das, was sich ändert, wenn sich die Plattform ändert; alles andere kann hinterherhinken.

ppl docs tree                  # everything availableppl docs search <substring>    # path or title contains substringppl docs get flows/quickstart  # fetch one doc

Das Muster, das gut für ein LLM funktioniert, das die Plattform steuert: mit ppl docs tree beginnen, um die Form der Dokumentation zu sehen, suchen, wenn ein bestimmtes Thema auftaucht, den genauen Flow holen, den die Aufgabe braucht, die begrenzten Befehle ausführen, die der Flow beschreibt. Die Registry ist absichtlich baumförmig — entdecken, suchen, holen, ausführen — sodass das LLM sie so navigieren kann, wie ein Benutzer jede strukturierte Referenz navigieren würde.

Wo das hineinpasst

Der Agentenmodus macht LLM-gesteuerte Workflows zu einer erstklassigen Oberfläche der CLI. Die Ausgabe-Envelopes, die schlanken Projektionen, der Matcher --query pro Ressource, die Versiegelungen destruktiver Operationen und die Session-Grenze existieren jeweils, um abzubilden, wie ein LLM einen echten Workflow steuert. Der Kompromiss ist, dass die Human-Oberfläche und die Agenten-Oberfläche dort auseinanderlaufen, wo sie sonst identisch wären, im Gegenzug dafür, dass jede Oberfläche auf ihren vorgesehenen Aufrufer zugeschnitten ist.

Der Vertrag, den dies von Agentenautoren verlangt, lautet: durch sie hindurch steuern, nicht um sie herum: die Envelopes parsen, die die Plattform zurückgibt, die schlanken Projektionen respektieren (den vollständigen Datensatz bei Bedarf mit get holen), --query für den Suchschritt verwenden, für den der Matcher gebaut wurde, und die Versiegelungen destruktiver Verben akzeptieren, indem Kandidaten zur menschlichen Prüfung vorgelegt werden. Der Vertrag hält, solange der Agent seinen Teil tut.

Verwandtes

War diese Seite hilfreich?