Forward-Deployed Agent Lab

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

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.