In fünf Minuten zum ersten Agenten-Lauf

Schritt 1 — Zugang einrichten

Der Zugang wird pro Person ausgestellt und ist an Ihre Organisation gebunden. Das lokale Token gilt acht Stunden.

npx @hostspezial/agentctl login --org ihre-org
# Oeffnet den Browser, legt ein kurzlebiges Token unter ~/.agentctl ab.

Schritt 2 — Projekt anlegen

init erzeugt ein Verzeichnis mit Agentendefinition, Policy und einem ersten Testfall. Alles liegt als Datei vor und gehört ins Repository — nicht in eine Web-Oberfläche.

npx @hostspezial/agentctl init mein-erster-agent
cd mein-erster-agent

# mein-erster-agent/
#   agent.ts            Definition des Laufs
#   tools.policy.yaml   Wer darf welches Werkzeug, mit welchem Limit
#   evals/first.spec.ts Ein Testfall, damit die CI von Anfang an gruen ist

Schritt 3 — Ein Werkzeug registrieren

Ein Agent ohne Werkzeug ist ein Chatbot. Registrieren Sie einen MCP-Server — hier eine Testdatenbank, ausschließlich lesend.

agentctl tools add postgres \
  --url "mcp+https://mcp.hostspezial.de/postgres" \
  --scope "read:orders" \
  --secret-ref "vault://demo/pg-readonly"

# Zugangsdaten liegen als Referenz vor, nie als Klartext im Repo.
agentctl tools list

Schritt 4 — Policy hinterlegen

Die Policy ist die Sicherung, nicht der Prompt. Standardentscheidung ist deny; erlaubt wird, was ausdrücklich erlaubt ist.

agent: mein-erster-agent
default: deny

tools:
  - name: postgres.query
    allow: true
    constraints: { statements: ["SELECT"], max_rows: 100 }

# Harte Obergrenze. Ohne Cap kann eine Schleife still teuer werden.
budget: { eur: 0.05, tokens: 50000 }

Schritt 5 — Lauf starten und Trace lesen

Jetzt der eigentliche Moment: ein Lauf mit echter Ausgabe, echten Latenzen und einer Kostenzeile.

agentctl run --input '{"orderId": 4711}'

# run   r-2b91ef   started
# span  agent.run                            2 100 ms
# span  tool.postgres.query   allow            38 ms
# span  agent.answer                          640 ms
# done  status=completed  tokens=3 480  cost=0,009 EUR

# Denselben Lauf ohne echte Aufrufe wiederholen:
agentctl replay r-2b91ef

Was danach sinnvoll ist

1. Einen echten Fall aufnehmen. Nehmen Sie einen realen Vorgang aus Ihrem Betrieb als Eval-Fixture auf — das ist der Grundstein Ihrer Eval-Suite.
2. Ein zweites Werkzeug anbinden. Ab hier wird die Auswahlqualität interessant. Mehr dazu im Tool-Layer.
3. Den Fehlerfall provozieren. Brechen Sie den Lauf mitten im Tool-Call ab und beobachten Sie die Wiederaufnahme — siehe Durable Execution.
4. Erst dann schreibende Rechte. Vorher lohnt der Security-Abschnitt zu Scopes und Freigabeschwellen.