guidepost-mcp

Ein Server, der einen Beratungs-Entscheidungsbaum über MCP durchläuft. Wenn der Agent das Label einer Antwort übergibt, kommt regelbasiert zurück, was als Nächstes abgefragt oder mitgeteilt werden soll. Ist das Ende erreicht, ist die Beratung abgeschlossen.

Schleifenartige Agenten sind flexibel, gehen aber bei derselben Anfrage jedes Mal einen anderen Weg. Bei Vorgängen wie Rückerstattung oder Identitätsprüfung, bei denen nichts schiefgehen darf, ist das weder für Audit noch für Eskalationsentscheidungen tragbar. Die Entscheidungspunkte werden stattdessen als externer Entscheidungsbaum fixiert; dem Agenten wird nur die Versprachlichung überlassen.

Das ist nicht nur für den Kundenservice gedacht. Das Vokabular des Entscheidungsbaums ist nicht domänenabhängig, damit lässt es sich für alle Arbeiten nutzen, die einen Prozess in Schritten voranbringen.

  顧客の発話                      guidepost-mcp (MCP · 8127)
      │                    ┌──────────────────────────┐
  ┌───▼────────┐  values   │ flows/*.yaml ← 起動時に   │
  │  エージェント  ├──────────▶│   メモリ常駐（読むだけ）  │
  │             │◀──────────┤ engine = 純関数で遷移     │
  └────────────┘  next     │ SQLite = runs / steps    │
      │  発話をラベルに        └──────────┬───────────────┘
      │  落とすのはこちら側                │ 読み取り専用
      ▼                              ┌───▼──────────┐
   顧客へ返す                          │ Web UI (SSR)  │ いま樹形図のどこにいるか
                                     └───────────────┘

Die Auswertung von natürlichsprachiger Eingabe zu Labels liegt beim Agenten. Der Server sieht sich nur das erhaltene Label an und geht zum nächsten Knoten über; dadurch kommen keine zusätzlichen LLM-Aufrufe: Die Messung (Raspberry Pi 5) liegt bei p95 0,006 ms für die Übergangsberechnung, p95 0,76 ms inklusive SQLite, und p95 9,1 ms Ende-zu-Ende über das HTTP-basierte MCP. Eine Sprachinteraktionsrunde liegt bei ca. 2,5 Sekunden, ihr sind die HTTP-Antwortzeit also einen Anteil von ca. 0,4 % – d.h. weitere Details in docs/research/voice-agent-latency-budget.md.

Entscheidungsbaum schreiben

flows/<flow_id>.yaml ist je ein Baum. Es gibt nur vier Arten von Knoten.

id: payment_failed
title: 支払いが失敗した
entry: n_error_code
max_unmatched: 3          # 聞き直しの上限
max_branch_fanout: 3      # これより枝が多いと畳まない
branch_depth: 2           # 枝を辿って結末を探す深さ
on_unknown: broaden       # 分からないと言われたとき。broaden / escalate
on_stuck: 原因が絞れないため、決済窓口の担当者に引き継ぐ

nodes:
  - id: n_error_code
    kind: ask
    say: 決済画面に出ているエラーコードを確認する     # 逐語原稿ではなく「何を伝えるか」
    accepts:                                      # ラベル → そのラベルに落とす条件
      E01: カードが拒否された
      E02: 残高不足・限度額超過
    next:
      E01: n_card_age
      E02: n_balance
      __other__: n_symptom        # 想定外のラベルの逃がし先（任意）
      __unknown__: n_generic      # 分からないときの逃がし先（任意）

  - id: n_identity
    kind: collect
    say: 本人確認に必要な情報を集める
    on_unknown: escalate          # 重要な手続きなので畳ませない
    slots:
      order_id:
        ask: 注文番号を聞く
        required: true            # 埋まらないと進めない
      phone: 登録の電話番号を聞く   # 短い書き方（任意扱い）
    next: n_verify

  - id: n_resolved
    kind: end
    outcome: resolved
    say: 解消したことを確認し、対応を締める

say ist kein wörtlich-formuliertes Skript, sondern das Material, wie ein Inhal einer Information aufdenkt. Die Strukturformulierung übernimmt der Agent dem im jeweiligen Rahmen passt. Ein 1-Knotenknoten = eine einzelne Frage oder einzelneinterranweiterung.

Nach dem Schreiben einmal prüfen. Nicht eröffnetbare Knoten oder Labels ohne Zielfähigkeit funktionieren zum Zeitpunkt des Schreibens noch; erst bei der Reichzeit fällt es auf.

uv run guidepost-mcp lint flows/          # CI でも回している
uv run guidepost-mcp show payment_failed --flows flows   # 樹形図を木で表示

MCP-Werkzeuge

Antworten werden gesammelt und so weit automatisch fortgesetzt, wie gefüllt

Wenn eine Kundin oder ein Kunde in einem Zug sagt „E01 ist vorhanden und die Karte ist drei Jahre alt equation", ist es besser nicht, abgetreittern sie jede einzelnen Punkt erneut zu fragen, obwohl die Antwort ist. valuesWerte passieren wir als bekannt übergeben; der Ablauf geht so weit weiter, wie Felder gefüllt sind, und hält am ersten unklarsten Knoten an.

  収集済み: {n_error_code: E01, n_card_age: over_1y}

  n_error_code ──E01──▶ n_card_age ──over_1y──▶ n_expiry_check ──?──▶ …
   ✓ 聞かずに通過        ✓ 聞かずに通過           ▲ ここで止まる

Übersprungen Systeme werden als skipped zurückgegeben. Damit der Agent die ID der nachfolgenden Systeme hat, liefert guide_start einmal ** einen Index** (Die mystabe per Node/Schaltfeld, was dort abgefragt wird).

Beim collect verfasst es umgekehrt: egalencher Reihenfolge ausgefüllt, aber auf einmal wieder fortgesetzt.

Bei “weiß nicht” nicht anhalten

Es ist normal, dass die anfragende Person die Antwort nicht hat. Weiter bohren bringt nichts weiter.

   guide_answer
        ├─ ラベルが accepts にある ──────────▶ advanced / completed
        ├─ accepts に無い ──────────────────▶ unmatched（聞き直す）
        │                                       │ max_unmatched 回で下へ
        └─ choice="__unknown__" ──────────┐   │
                                          ▼   ▼
                               next.__unknown__ があるか
                                  ├─ ある ─▶ advanced（逃がし先へ）
                                  └─ 無い ─▶ on_unknown は
                                              ├─ escalate ─▶ stalled（有人へ）
                                              └─ broaden ──▶ 枝を畳めるか
                                                   ├─ できる ─▶ branched
                                                   └─ 無理 ───▶ stalled

branched ist der Zustand, in dem der Zweig nicht festgelegt, aber die Ausgänge jedes Zweigs angegeben werden. Das liefert Material für die Formulierung „Bei E01 bitte zur Kreditpal, bei E02 sowie der Saldo prüfen“. Wenn es einen Knoten gibt, in dem alle Zweige wieder zusammentreffen, steht dieser unter common; dannkam es mit „In allen Fällen bitte …“ abschließend zusammengefasst werden.

Grenztätige Verfahren wie Rückerstattung oder Identitätsfeststellung, bei deren ungeklärter Anleitung Schäden entstehen könnten, it is mit on_unknown: escalate versehen, damit es nicht zusammenfällt. Die nicht zusammenfaltbaren Knoten werden vom lint namentlich gemeldet, so muss dort nur angegangen werden.

Start

uv sync
uv run uvicorn guidepost_mcp.web:app --host 127.0.0.1 --port 8127
uv run python scripts/mcp_smoke.py            # 実プロトコルで 1 周辿る
uv run python scripts/mcp_smoke.py --parallel # 2 本の run を交互に進める

Die Web-UI ist erreichbar unter http://127.0.0.1:8127/. Dort läuft sich der run wird aufgestreckt, und unter /r/<run_id> werden über den Baum hinwegpositioniert, der eingeschlagen te Abst Meinung, die Hauptknoten und die zusammengefaltete Knoten eingefärbt dargestellt.

Agentenseitig wird über die HTTP-MCP-Verbindung angebunden.

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "guidepost-mcp": {"url": "http://127.0.0.1:8127/mcp/", "transport": "streamable_http"},
    }
)
tools = await client.get_tools()

Versionierung

Die kanonische Stelle für die Version liegt als einzelnes version-Feld in pyproject.toml und ist unter SemVer: (0.x und die Minor-Version) kann breaking Changes einführen) Fehlersucht, was als gross ändert Durchbruch, ist der CHANGELOG.md zu sehen.

Was genau als eatagationalis bezeichnet ist bezieht werden, steht in docs/adr/0009-versioning.md. – Kern: die Entwicklungsschema für die Entscheidungsbäume und der Vertrag der MCP-Tools (Toolnamen, Argumenten, Rückgabeschlüssel, der fünf Zustände von status), aber der voll endgültige Austassen von next ist dabei der nicht eine.

Das Feld version in flows/*.yaml versucht die Version des Prozedio-Handlings und ist unabhängig von der Version dieser Bibliothek.

Designhintergrund

Warum die Label-Auslegung auf Agenterseyte liegt, warum bei „Weiß nicht“ die Zweige zusammengefängt werden und warum die Web-UI vollständig nur lesbar ist, ist mit den Gründen in docs/adr/ dokumentiert (Überblick in docs/verzeichnis.md resp. die Zusammenfassung in docs/adr/README.md). Recherchen für die Grundüberlegungen liegen in docs/research/.