Skip to main content
Glama
field-agent-mcp

field-agent-mcp

by YihengLi-1

Forward-Deployed Agent Lab

CI

A production-shaped, synthetic service-business agent that demonstrates the work between a model demo and a usable customer system: workflow discovery, grounded answers, tool boundaries, human escalation, evaluation, voice integration, and Kubernetes deployment.

This repository contains no client data or client code. The fictional Northstar Clinic dataset was written for reproducible testing. The operating pattern is informed by hands-on work helping small service businesses adopt AI workflows; see the anonymized case study.

System at a glance

Web / Voice / MCP client
          |
          v
  FastAPI + MCP adapters
          |
          v
  deterministic route + safety boundary
      /          |           \
 knowledge    intake tool    human handoff
 citations    pending only   normal / urgent
          |
          v
 tests + synthetic evaluation + Kubernetes runtime controls

Related MCP server: ToolBridge

What is implemented

  • FastAPI endpoints for agent responses, voice-ready SSML/audio, health, readiness, and evaluation

  • Deterministic retrieval over an approved bilingual knowledge base with source citations

  • Explicit escalation for emergencies, professional judgment, and ungrounded questions

  • MCP tools for knowledge search, intake collection, and human escalation

  • Local macOS text-to-speech adapter with no external data transfer

  • Reproducible synthetic evaluation for route, handoff, tool-selection, and grounding behavior

  • Compact BERT intent-router fine-tuning experiment, kept outside the deterministic safety boundary

  • Docker image and Kubernetes Deployment, Service, HPA, probes, resource limits, and NetworkPolicy

  • Automated API, core-engine, MCP-tool, evaluation, and deployment-manifest tests

Run locally

Python 3.11–3.13 is supported.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest
python scripts/run_eval.py
uvicorn field_agent_lab.api:app --reload

Open http://127.0.0.1:8000/docs for the interactive API.

Grounded knowledge request

curl -s http://127.0.0.1:8000/v1/agent/respond \
  -H 'content-type: application/json' \
  -d '{"message":"Do you accept HSA cards?","locale":"en-US"}'

The response includes a knowledge route and citations to the approved payment document.

Scheduling request

curl -s http://127.0.0.1:8000/v1/agent/respond \
  -H 'content-type: application/json' \
  -d '{"message":"I want to book an appointment","customer_id":"demo-123"}'

The system returns a collect_intake tool call and explicitly says that staff must confirm availability.

Voice-ready response

curl -s http://127.0.0.1:8000/v1/voice/respond \
  -H 'content-type: application/json' \
  -d '{"message":"When are you open?","generate_audio":false}'

Set generate_audio to true on macOS to return base64-encoded AIFF audio generated by the local say provider.

MCP server

field-agent-mcp

Tools:

  • search_service_knowledge

  • collect_intake

  • escalate_to_human

The MCP interface reuses the same core engine as the HTTP API, so safety and grounding behavior do not drift by channel.

Compact-model experiment

Install the optional training dependencies and run:

python -m pip install -e ".[train]"
python training/train_router.py

The script fine-tunes prajjwal1/bert-tiny on four synthetic intent classes and writes transparent metrics to artifacts/router_metrics.json. The model is an experiment; deterministic rules remain the safety boundary.

Deployment

docker build -t forward-deployed-agent-lab .
kubectl apply -f deployment/k8s.yaml

The manifest intentionally includes readiness/liveness probes, non-root execution, dropped Linux capabilities, resource requests/limits, horizontal autoscaling, and a network policy.

Evidence and limitations

Generated reports are committed under artifacts/ after execution. All benchmark cases are visible in data/eval_cases.jsonl. The dataset is small and synthetic, so the reported score is a regression baseline—not a claim of clinical quality or production generalization.

Available Tools

3 tools
collect_intakeA

Collect scheduling details without claiming that an appointment is confirmed.

Inputs: name (required), service (required), preferred_time (required), callback_number (required). Returns: object

escalate_to_humanC

Queue a request for a human staff member.

Inputs: summary (required), priority. Returns: object

search_service_knowledgeB

Search approved service-business knowledge and return citations.

Inputs: query (required), locale. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: searching knowledge, collecting intake details, and escalating to a human. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow the same verb_noun pattern with lowercase and underscores: search_service_knowledge, collect_intake, escalate_to_human. This is highly consistent.

    Tool Count5/5

    With only 3 tools, the server is well-scoped for a focused triage workflow. Each tool serves a necessary function without redundancy or bloat.

    Completeness4/5

    The tools cover the core lifecycle of a field agent interaction: retrieving information, gathering details, and escalating when needed. A minor gap is the lack of a confirmation or follow-up action, but this may be intentional to avoid false commitments.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A governed MCP server for integrating AI agents with customer data, featuring role-based access control, field redaction, and human-in-the-loop approval for secure support operations.
      1
      -
    • F
      license
      A
      quality
      D
      maintenance
      A production-grade MCP server that provides a centralized microservice toolkit for LLM agents, enabling web search and extensible tool integration.
      1
      -