agentleFS
JinLee794JinLee794/agent-framework-skills/.cursor/skills/maf-dev-loop/SKILL.md

maf-dev-loop

Skill2 starsChanged 4 months agoMITView on GitHub

Inner development loop: mandatory logging setup, startup preflight, text-only DevUI run/debug from entities/, trace correlation, and diagnosing a silent agent. Load for DevUI, logging, telemetry, or when an agent produces no answer. NOT for local microphone/speaker VoiceLive loops - load voicelive-realtime instead.

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every entry point runs the same check before opening a session, and a --check flag runs it alone.

    line 80
  2. Very specific:

    __init__.py exports agent or workflow at module level: No other name is discovered.

    line 138
  3. Very specific:

    entity_id is the agent's name=, not the directory name: Keep them equal.

    line 143
  4. Distinctive:

    Check this when "DevUI doesn't show X".

    line 173
  5. Distinctive:

    If the repo grows workflows, their structure and orchestration are owned by maf-multi-agent-workflows.

    line 183
  6. Very specific:

    Keep local initialization outside entities//__init__.py.

    line 245

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Dev Loop — Logging, DevUI, Telemetry

TaskWhere
Set up logging so failures are explainablethis file, below — do this first
The agent returns nothing and you cannot tell whyreferences/diagnostics.md
Run and debug an agent locallythis file, below
Voice trace attributes, metrics, full telemetry troubleshootingreferences/observability.md
Refresh a stale skill against the SDKsreferences/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

Agent Framework's own logger is agent_framework, with agent_framework.declarative for document loading. Raising the root level to DEBUG gives tool dispatch and HTTP calls.

Startup preflight

Every entry point runs the same check before opening a session, and a --check flag runs it alone. It must fail loudly, never warn and continue.

AssertWhy
Every variable in .env.example is setAn unset name becomes an empty string and fails mid-call
Every document under config/ loads and validatesLazy loading turns a typo into a phone-call failure
Each agent document's model.id resolved to a literalCatches safe_mode blocking =Env.
Every declared function tool resolved to a callablefunc=None is silent and calls a no-op
The mounted stem in each voice document existsA mismount looks like a bad prompt
A credential can be acquired for the project endpointFails at boot instead of on the first caller
python -m <package> --check

Log the four startup facts — loaded documents, resolved model, tool binding status, voice mounts — at INFO. The exact lines and the triage table that consumes them are in references/diagnostics.md.

Never swallow an exception

The VoiceLive dispatcher, background asyncio tasks, and tool handlers all discard exceptions by default, which is exactly why "it just goes quiet" is the usual bug report. Log with logger.exception(...), speak a fallback, and re-raise. Details: references/diagnostics.md.


DevUI

DevUI is a sample app, not a hosting surface. Never deploy it, never point production traffic at it, never add repo features that only work because DevUI is running.

pip install agent-framework-devui --pre
$env:PYTHONPATH="."; devui ./entities --port 8080

Directory discovery (devui ./entities) is the default. serve(entities=[agent]) is for throwaway scripts only — never in src/<package>/.

entities/ conventions

entities/
  .env                     # shared across all entities; gitignored
  concierge/
    __init__.py            # MUST export a module-level `agent` (or `workflow`)
    .env                   # entity-scoped overrides; gitignored

Discovery looks for agent.py, workflow.py, or __init__.py in each directory — Python modules only. DevUI never discovers YAML. This is why entities/ is directory-per-entity while config/ is a flat file per document; do not generalise one shape to the other.

Not optional:

  1. __init__.py exports agent or workflow at module level. No other name is discovered; a factory function alone is invisible.
  2. entities/ re-exports; it never redefines. Load the same config/agents/<name>.yaml through the same AgentFactory the voice loop and tests use. Instructions, tool lists, or model names written here guarantee drift between what you tested and what ships.
  3. entity_id is the agent's name=, not the directory name. Keep them equal.
  4. Use the same credential and bindings as the voice loop. Reuse one async credential.
  5. Sibling imports need PYTHONPATH=. or DevUI reports an import error.
  6. .env loads automatically — entities/.env then entities/<name>/.env. Commit only .env.example.
# entities/concierge/__init__.py
from agent_framework.declarative import AgentFactory
from azure.identity.aio import AzureCliCredential

from mypkg.config import agent_document_path
from mypkg.settings import settings
from mypkg.tools import TOOL_BINDINGS

credential = AzureCliCredential()
agent = AgentFactory(
    client_kwargs={
        "credential": credential,
        "project_endpoint": settings.foundry_project_endpoint,
    },
    bindings=TOOL_BINDINGS,
    safe_mode=False,
).create_agent_from_yaml_path(agent_document_path("concierge"))

Register credential.close with the entity cleanup hook so reloads do not leak transports.

Making components show up

Check this when "DevUI doesn't show X". Each row is a code convention, not a UI setting.

Want to seeYour code must
The entity in the sidebarexport module-level agent / workflow from entities/<name>/__init__.py
Tool calls with argumentsregister real @tool functions with docstrings and typed params
An approve/reject promptapproval_mode="always_require" on the tool
Images / files / structured data inlinereturn DataContent / UriContent, not a stringified blob
Spans in the debug panellaunch with the instrumentation flag (below)

If the repo grows workflows, their structure and orchestration are owned by maf-multi-agent-workflows. Two things are DevUI's own: verify topology offline with WorkflowViz(workflow).to_mermaid() before blaming the UI, and do not hard-code checkpoint_storage= in entities/ — DevUI injects workflow-session storage and hard-coding it removes the checkpoint dropdown.

Traces in DevUI

DevUI does not create spans; it displays the ones Agent Framework already emits.

devui ./entities --instrumentation      # newer flag name
devui ./entities --tracing              # name used by the GA docs

The flag was renamed and the docs and shipped package have disagreed. Run devui --help once and use what your version lists — do not encode a guess in a task or script.

The failure that costs the most time: an entities/**/__init__.py that initializes telemetry at import. DevUI imports every entity, so N entities register N provider sets and every span exports N times. Let DevUI's flag own instrumentation locally.

Voice agents and DevUI

DevUI has no audio path. It cannot drive a VoiceLive session.

Mount the MAF brain agent in DevUI. Exercise tools, Search retrieval, and instructions in text before adding VoiceLive latency; DevUI does not drive the audio path.

This works only because of the factory rule: build_<name>_agent() returns the same object whether called by the voice loop, a test, or entities/.

Auth

Auth is on by default; a dev token prints at startup. Unauthenticated mode is permitted only on loopback. Binding 0.0.0.0 or a LAN IP requires DEVUI_AUTH_TOKEN / --auth-token and fails closed if combined with the no-auth flag. --mode user restricts developer APIs. Never run DevUI against production credentials — it has hot reload and arbitrary local module import by design.


Telemetry

Telemetry is a layer on top of logging, not a replacement for it. Get setup_logging() and the preflight working first; spans are useless if the process dies before it emits one.

This seed provisions no cloud telemetry resource. Use DevUI's instrumentation flag or console exporters during local development. Do not add Application Insights, Azure Monitor, or a deployed OTLP collector to the runtime contract.

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)   # or ENABLE_CONSOLE_EXPORTERS=true

Instrumentation is enabled by default in agent-framework 1.12.x — enable_instrumentation() exists only to force it on programmatically, and disable_instrumentation() is sticky. So "no spans" almost never means instrumentation is off; it means no provider or exporter was configured, or setup ran after the clients were built.

Keep local initialization outside entities/**/__init__.py; DevUI owns instrumentation when launched with its tracing flag. Initializing providers in every entity duplicates spans.

Sensitive data

FlagRecordsProduction
ENABLE_SENSITIVE_DATAprompts, responses, tool args/resultsoff
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTVoiceLive message content, transcriptsoff

Voice payloads are recordings and transcripts of real people. Enabling either is a privacy decision, not a debugging convenience. Never default them to true in a committed .env.example; leave ENABLE_SENSITIVE_DATA on only in entities/.env.

Span/metric names, voice attributes, correlation across topology B, and full telemetry troubleshooting: references/observability.md. Triaging an agent that returns nothing: references/diagnostics.md.

Anti-patterns

PatternVerdict
No setup_logging() at an entry pointFailures are invisible; this is the defect that hides every other defect
logging.basicConfig() without force=TrueA dependency already installed a handler; your config is a no-op
print() for diagnostics in src/Not levelled, not filterable, not correlated
except Exception: pass anywhere in the voice dispatcherThe call goes silent and nothing is recorded
A tool handler that raises without a spoken fallbackCaller hears dead air
Startup that warns and continues on unset envFails on the first real caller instead of at boot
Agent instructions, model, or tool list written in entities/**/__init__.pyDrift from shipped config — load the document, call the factory
Telemetry initializer called in an entity moduleDuplicate providers across every entity
serve() called from src/<package>/Move it to scripts/
More than one configure_otel_providers callEvery span exported twice
Telemetry set up after clients are constructedMisses spans on existing objects
Cloud telemetry exporter or collectorAdds a forbidden resource
--host 0.0.0.0 with auth disabledFails closed — and would expose local module execution
Treating DevUI as the demo or deployment surfaceIt is a sample app; host with the SDK
Committing entities/**/.envLeaks credentials
ENABLE_SENSITIVE_DATA=true in .env.exampleShips a privacy default

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.