Leave Copilot — De MCP a un modelo agéntico propio

Una implementación de referencia ejecutable: estandariza un conjunto de herramientas de solicitud de permisos/asistencia deliberadamente difíciles con MCP, construye un agente capaz de operarlas con Google ADK, mide las deficiencias del modelo base con doble evaluación y ajusta un modelo propio que domine de forma nativa la operación de este conjunto de herramientas.

Este es el código de acompañamiento de la serie de 30 días de iThome Ironman 2026.

Por qué las herramientas están «deliberadamente diseñadas para ser difíciles»

El diseño normal de APIs busca la intuición y la facilidad de uso, pero este proyecto necesita lo contrario.

La forma de aceptación es comparar la diferencia de rendimiento antes y después del ajuste fino: si las herramientas son demasiado intuitivas, el modelo base ya puede llamarlas correctamente, la precisión empieza cerca del máximo, y el ajuste fino naturalmente no muestra ninguna mejora. No es que el ajuste fino no funcione, sino que no hay espacio para mejorar.

Así que el criterio de selección es uno solo: el modelo base casi siempre falla, y el ajuste fino puede enseñarle.

Cuatro dificultades deliberadamente implantadas

La característica común de estas cuatro dificultades: todas son reglas que JSON Schema no puede expresar. El Schema puede garantizar que status sea una de cuatro cadenas, pero no puede controlar «de dónde viene este identificador».

Related MCP server: MCP Leave Management

Inicio rápido

Entorno

El primer punto es especialmente fácil de fallar, porque el sitio oficial del SDK de Python de MCP muestra por defecto la documentación de otra API (MCPServer), completamente distinta de la sintaxis de FastMCP que se usa aquí.

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

Iniciar el servidor MCP

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

Verificar las cuatro dificultades

python eval/verify_difficulties.py

Se conecta realmente al servidor, dispara las cuatro dificultades una por una y comprueba los mensajes de error y la semántica de las respuestas:

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

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

Restablecer los datos de prueba

update_leave_status y cancel_approved_leave cambian datos de verdad. Hay que restablecerlos antes de cada ronda de evaluación; de lo contrario, las condiciones previas de la segunda ronda difieren de las de la primera y los resultados no son comparables.

python eval/reset.py

Conjunto de herramientas

Nueve herramientas, más un endpoint de administración exclusivo para el script de evaluación.

readOnlyHint no es solo documentación: la herramienta de evaluación la usa para calcular el «cumplimiento de solo lectura»: si el agente usó herramientas de escritura en tareas de solo lectura.

_reset_fixtures debe excluirse en el lado del agente con tool_filter. Una herramienta llamada «reset» tiene una atracción inexplicable para los LLM.

Por qué los mensajes de error están escritos con tanta claridad

Los mensajes de error de las herramientas vuelven intactos al modelo y se convierten en la base de su siguiente paso.

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

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

Es una técnica típica de compensar la capacidad del modelo con el diseño de las herramientas; el coste es solo escribir unas palabras más.

Estructura del proyecto

.
├── 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 部署

✅ Completado y probado　⏳ En construcción

Asignación de puertos

⚠️ Tanto FastMCP como el api_server de Google ADK usan el puerto 8000 por defecto; hay que cambiar uno de los dos. Este proyecto mueve el servidor MCP al 8090.

Proyectos relacionados

• ADEval — Herramienta de evaluación de agentes de Google ADK (Apache-2.0)

• Twinkle Eval — Evaluación estándar de benchmarks (MIT)

Licencia

Apache-2.0

Partes verificadas

eval/verify_difficulties.py y eval/verify_agent.py se han ejecutado de verdad, no es que «esté escrito en la documentación».

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，且語意正確回報

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

Observaciones de comportamiento del modelo base

La sección B de verify_agent.py no hace aserciones, solo registra — que el modelo responda mal no significa que la prueba falle; eso es precisamente lo que se quiere medir. Lo más notable de la ejecución real es este patrón de fallo:

El modelo responde con texto en lugar de llamar a la herramienta. Ante operaciones destructivas, gemini-3.7-flash tiende a preguntar «¿estás seguro?» en el propio diálogo, en lugar de llamar a cancel_approved_leave para que el servidor emita la Elicitation. El resultado: el flujo de confirmación cae de la capa de protocolo a la capa de diálogo, y la confirmación en la capa de diálogo no tiene fuerza vinculante.

Una variante más grave es el éxito alucinado — el modelo responde «he enviado la solicitud para aprobación», pero en la secuencia de herramientas no hay ningún update_leave_status y el estado de la solicitud no ha cambiado. El usuario cree que está hecho.

Este tipo de fallo no se puede eliminar con prompts, porque proviene de la tendencia innata del modelo hacia la «seguridad». Esto es exactamente lo que el ajuste fino abordará más adelante.