guidepost-mcp

Сервер, который ведет агента по дереву инструкций через MCP. Когда агент передает метку ответа, правило возвращает, что именно нужно уточнить или сообщить дальше. Когда путь пройден до конца, инструкция завершена.

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

Агенты с собственным циклом обработки гибкие, но на один и тот же запрос каждый раз проходят разный путь. Для операций, в которых нельзя ошибиться, — возврат средств, подтверждение личности — такие ответы не выдерживают ни аудита, ни принятия решений об эскалации. Места, требующие решения, фиксируются снаружи в виде дерева решений, а агенту доверяется только формулировка ответа.

Это не только для CS. Словарь дерева решений не привязан к домену, поэтому его можно применять для любой работы, требующей последовательного прохождения процедур.

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: 解消したことを確認し、対応を締める

Интерпретация «естественный текст → метка» лежит на стороне агента. Сервер просто смотрит на полученную метку и выполняет переход, поэтому количество вызовов LLM не увеличивается. Замеры (Raspberry Pi 5): p95 0,006 мс на вычисление перехода, p95 0,76 мс с SQLite, p95 9,1 мс эн-ту-энц через HTTP-версию MCP. Один цикл голосового обслуживания занимает около 2,5 секунды, то есть даже с HTTP это 0,4%. Детализацию и то, как этот бюджет рассчитывался, см. в docs/research/voice-agent-latency-budget.md.

Как описать дерево решений

flows/<flow_id>.yaml — это одно дерево решений. Узлы бывают только четырёх видов.

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

say — это не дословный сценарий, а материал «что сообщить». Формулировку агент подстраивает под собеседника. 1 узел = один вопрос или одно указание.

Проверяйте написанное. Недостижимые узлы или метки без перехода выглядят рабочими в момент написания, поэтому заметить их можно только во время исполнения.

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

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

MCP-инструменты

Ответы накапливаются, и система автоматически продвигается с заполнением

Если клиент говорит сразу «У меня E01, и карта трехлетней давности», не надо переспрашивать по одному пункту, когда ответы уже есть. Достаточно передать всё известное в values — система будет идти дальше, пока заполнены данные, и остановится только на первом незаполненном узле.

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

Пропущенные из-за этого узлы возвращаются как skipped, чтобы агент знал идентификаторы следующих узлов; guide_start один раз передаёт индекс — по одной строке описания того, что спрашивают узел или слот.

Для collect произвольный порядок — та же логика: какие узлы заполнены не влияет, они проходятся сразу, когда собрано всё.

«Не знаю» не останавливает

Человек, обратившийся с вопросомъ, часто не имеет ответа. Сколько ни переспрашивай, ответ не появится.

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 を交互に進める

branched — это состояние, при котором ветвь не фиксируется: выводятся результаты для каждой ветви без выбора. Возвращаются материалы для фразы «Если E01 — обратитесь в банк, если E02 — проверьте остаток». Если есть узел, где все ветви сходятся, он попадает в common, и можно обобщить: «В любом случае, в конце сделайте следующее».

Процедуры, в которых нелочный ответ причиняет вред — возврат средств, подтверждение личности — можно не давать сойтись, установив on_unknown: escalate. Узлы, которые нельзя невнятить, lint перечисляет по имени, так что достаточно обработать только их.

Завершение

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()

Web UI доступен по адресу http://127.0.0.1:8127/. Там виден список текущих run, а по адресу /r/<run_id> на дереве реакций цветом выделены текущее местоположение, пройденный вызванный путь, пропущенные узлы и сложенные ветви.

Агент подключается к серверу через MCP в HTTP-режиме.

Версия

Эталонная версия задэдена единственным значением version в pyproject.toml и соответствует SemVer (для версии 0.x в minor могли входить критические изменения). История изменений — в CHANGELOG.md.

Что считаются критическим изменением, определено в docs/adr/0009-versioning.md. Суть — схема YAML для дерева решений и контракт MCP-инструментов (имена инструментов, аргументы, ключи возвращаемых значений и пять зачений status). Формулировка текстового сообщения next в это не входит.

version в flows/*.yaml — это версия процедуры, она отделена от версии библиотеки.

Обоснование дизайна

Почему интерпретация метки остаска на стороне агента, почему при «не знаю» ветвь сворачивается, почему Web-интерфейс сделан только здесь, — записано с обоснованием в docs/adr/ (список — docs/adr/README.md). Исследования, на которые опирались, находятся в docs/research/.