maf-dev-loop

Dev Loop — Logging, DevUI, Telemetry

Task	Where
Set up logging so failures are explainable	this file, below — do this first
The agent returns nothing and you cannot tell why	references/diagnostics.md
Run and debug an agent locally	this file, below
Voice trace attributes, metrics, full telemetry troubleshooting	references/observability.md
Refresh a stale skill against the SDKs	references/skill-sync.md

---

Logging is not optional

A voice agent fails in places nobody can see: inside a tool handler, inside an event loop, inside a config document that absorbed a misspelled key. If the seed cannot explain its own failure, it is not finished. Logging setup is scaffolding step one, not a follow-up task.

diagnostics.py

One module, no local imports, called before anything else at every entry point.

# src/<package>/diagnostics.py
import logging
import os

_NOISY = {
    "azure.identity": logging.WARNING,
    "azure.core.pipeline.policies.http_logging_policy": logging.WARNING,
    "urllib3": logging.WARNING,
}


def setup_logging() -> None:
    """Configure root logging. Must run before any module that can fail is imported."""
    level = os.getenv("LOG_LEVEL", "INFO").upper()
    logging.basicConfig(
        level=level,
        format="%(asctime)s %(levelname)-8s %(name)s %(message)s",
        force=True,  # override any handler a dependency installed at import
    )
    for name, noisy_level in _NOISY.items():
        logging.getLogger(name).setLevel(noisy_level)
    logging.getLogger("agent_framework").setLevel(level)

force=True matters: several Azure SDKs attach a handler on import, and without it basicConfig is a no-op and your format never applies.

# src/<package>/__main__.py — order is load-bearing
from dotenv import load_dotenv

from .diagnostics import setup_logging

load_dotenv()        # Agent Framework never does this for you
setup_logging()      # before any import that can fail

from .voice.runner import main   # noqa: E402 — imported after logging is live