Leave Copilot — Von MCP zu einem eigenen Agentic-Modell

Eine ausführbare Referenzimplementierung: Mit MCP wird eine Gruppe absichtlich schwer gestalteter Urlaubs-/Anwesenheitstools standardisiert, mit Google ADK wird ein Agent gebaut, der sie bedienen kann, mit doppelter Evaluierung werden die Schwächen des Basismodells gemessen, und anschließend wird ein eigenes Modell feinabgestimmt, das von Natur aus gut mit dieser Toolgruppe umgehen kann.

Dies ist der Begleitcode zur 30-Tage-Serie des iThome Ironman-Wettbewerbs 2026.

Warum die Tools „absichtlich schwer gestaltet" sind

Normale API-Designs streben nach intuitiver Bedienbarkeit, aber dieses Projekt braucht das Gegenteil.

Die Abnahme erfolgt durch den Vergleich der Leistung vor und nach dem Feintuning – wenn die Tools zu intuitiv wären, würde das Basismodell sie ohnehin korrekt aufrufen, die Genauigkeit wäre von Anfang an nahezu perfekt, und das Feintuning würde keinerlei Verbesserung zeigen. Das liegt nicht daran, dass Feintuning wirkungslos wäre, sondern daran, dass es schlicht keinen Raum für Verbesserung gibt.

Die Auswahlkriterien sind also nur eines: Das Basismodell macht fast sicher Fehler, und Feintuning kann es lehren.

Vier absichtlich eingebaute Schwierigkeiten

Das gemeinsame Merkmal dieser vier Schwierigkeiten: Sie sind allesamt Regeln, die JSON Schema nicht ausdrücken kann. Schema kann erzwingen, dass status einer von vier Strings sein muss, aber nicht, woher diese Nummer kommt.

Related MCP server: MCP Leave Management

Schnellstart

Umgebung

Der erste Punkt ist besonders tückisch, weil die offizielle MCP-Python-SDK-Website standardmäßig die Dokumentation einer anderen API anzeigt (MCPServer), die sich völlig von der hier verwendeten FastMCP-Schreibweise unterscheidet.

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

MCP-Server starten

python -m mcp_server.server        # streamable-http on 127.0.0.1:8090

Die vier Schwierigkeiten verifizieren

python eval/verify_difficulties.py

Verbindet sich tatsächlich mit dem Server, löst nacheinander die vier Schwierigkeiten aus und prüft Fehlermeldungen sowie Rückgabesemantik:

難點 ① 跨呼叫依賴
  ✓ 捏造的編號被擋下
  ✓ 錯誤訊息指出正確取得方式
  ✓ search_leaves 查得到真實編號
…
難點 ④ 參數陷阱
  ✓ 餘額欄位以小時命名
  ✓ 傳姓名而非員工編號被擋下
難點 ② Elicitation 三態
  ✓ accept            → cancelled
  ✓ decline           → aborted
  ✓ cancel            → aborted
  ✓ accept_but_false  → aborted
  ✓ 撤銷後時數退回餘額
  ✓ decline 的訊息明確禁止繞道
  ✓ cancel 的訊息與 decline 語意不同

──────────────────────────────────────────────
19/19 通過

Testdaten zurücksetzen

update_leave_status und cancel_approved_leave verändern tatsächlich Daten. Vor jeder Evaluierungsrunde muss zurückgesetzt werden, sonst unterscheiden sich die Vorbedingungen der zweiten Runde von denen der ersten und die Ergebnisse sind nicht vergleichbar.

python eval/reset.py

Toolset

Neun Tools plus einen verwaltungsspezifischen Endpunkt für das Evaluierungsskript.

readOnlyHint ist nicht nur Dokumentation – das Evaluierungstool nutzt es zur Berechnung der „Read-only-Konformität": Hat der Agent bei Read-only-Aufgaben Schreibwerkzeuge eingesetzt?

_reset_fixtures muss auf Agent-Seite per tool_filter ausgeschlossen werden. Ein Tool namens „Reset" hat eine merkwürdige Anziehungskraft auf LLMs.

Warum Fehlermeldungen so klar formuliert sein müssen

Die Fehlermeldungen der Tools gelangen unverändert zurück zum Modell und dienen als Grundlage für seinen nächsten Schritt.

# ✗ 模型只知道錯了，得猜哪裡錯
raise ValueError("Invalid status transition")

# ✓ 模型知道錯在哪、也知道該改成什麼
raise ValueError(
    f"狀態不可從 {current} 跳至 {target}，下一個合法狀態為 {next_valid}"
)

Dies ist eine typische Methode, Modellfähigkeiten durch Tool-Design zu kompensieren – die Kosten sind nur ein paar zusätzliche Wörter.

Projektstruktur

.
├── mcp_server/          # ✅ MCP Server：九個工具 + 四個難點
│   ├── server.py
│   ├── store.py         #    模擬資料層
│   └── fixtures.py      #    初始資料與 reset
├── eval/                # ✅ 驗證與重置腳本
│   ├── verify_difficulties.py   # 19/19
│   ├── verify_agent.py          # 架構驗證 10/10
│   └── reset.py
├── agents/leave_copilot/ # ✅ Google ADK Agent（含 elicitation callback）
├── plugins/             # ⏳ 軌跡記錄與生產防禦 Plugin
├── data/                # ⏳ 軌跡萃取與資料擴增
├── training/            # ⏳ SFT 訓練腳本
└── deploy/              # ⏳ 權重合併、量化、vLLM 部署

✅ Fertiggestellt und getestet　⏳ Im Aufbau

Port-Zuordnung

⚠️ FastMCP und Google ADK api_server verwenden beide standardmäßig Port 8000 – einer davon muss geändert werden. Dieses Projekt verschiebt den MCP-Server auf 8090.

Verwandte Projekte

• ADEval — Google-ADK-Agent-Evaluierungstool (Apache-2.0)

• Twinkle Eval — Standard-Benchmark-Evaluierung (MIT)

Lizenz

Apache-2.0

Verifizierte Teile

eval/verify_difficulties.py und eval/verify_agent.py wurden tatsächlich ausgeführt, nicht nur „so in der Dokumentation beschrieben".

MCP Server 層（eval/verify_difficulties.py）              19/19
  四個難點的錯誤訊息、Elicitation 四條路徑

Google ADK 層（eval/verify_agent.py，A 段架構驗證）        10/10
  McpToolset 載入、tool_filter 排除管理端點
  accept / decline / cancel / accept-but-false 四條路徑
  都確認走到 Client callback，且語意正確回報

Umgebung: mcp 1.29.1 + google-adk 2.7.1 + gemini-3.7-flash.

Verhaltensbeobachtungen des Basismodells

Teil B von verify_agent.py macht keine Assertions, sondern protokolliert nur – eine falsche Antwort des Modells bedeutet keinen Testfehler, genau das ist das, was gemessen werden soll. Das bemerkenswerteste Fehlermuster aus der tatsächlichen Ausführung ist dieses:

Das Modell antwortet mit Text statt mit einem Tool-Aufruf. Bei destruktiven Operationen neigt gemini-3.7-flash dazu, selbst im Dialog zu fragen „Bist du sicher?", statt cancel_approved_leave aufzurufen, damit der Server eine Elicitation auslöst. Die Folge: Der Bestätigungsprozess fällt von der Protokollebene zurück auf die Dialogebene, und Bestätigungen auf Dialogebene haben keine Durchsetzungskraft.

Eine schwerwiegendere Variante ist der halluzinierte Erfolg – das Modell antwortet „Ich habe den Urlaubsantrag zur Genehmigung eingereicht", aber in der Tool-Sequenz gibt es gar kein update_leave_status, und der Antragsstatus hat sich auch nicht geändert. Der Nutzer glaubt, es sei erledigt.

Diese Art von Fehlern lässt sich nicht per Prompt beseitigen, weil sie aus der eingebauten Neigung des Modells zu „Sicherheit" stammt. Genau das ist es, was im weiteren Verlauf per Feintuning behandelt werden soll.