agentleFS
JinLee794JinLee794/agent-framework-skills/.github/skills/maf-voice-agent/SKILL.md

maf-voice-agent

Skill2 starsChanged 4 months agoMITView on GitHub

Repo layout, fixed MAF-bridge topology, two-resource default with optional alternate VoiceLive overrides, and conformance checklist. Load when scaffolding, placing code/config, or reviewing this Foundry + Azure AI Search voice seed before it ships.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

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

    Use the Foundry project settings for both reasoning and VoiceLive.

    line 25
  2. Distinctive:

    Use the canonical SDK variable names — do not invent new ones.

    line 109
  3. Very specific:

    Write config/agents/<name>.yaml as a kind: Prompt document — stock MAF schema, camelCase keys, domain policy in instructions.

    line 133
  4. Very specific:

    Write config/voice/<name>.yaml with topology: maf_bridge, mounts.agent: <name>, bridge-only session.instructions, and an interim_response.

    line 135
  5. Very specific:

    Create each tool in tools/ with tests, then register it in the bindings mapping under the exact name the agent document binds.

    line 137
  6. Very specific:

    Add settings.py entries for any new env var and mirror them in .env.example.

    line 139
  7. Distinctive:

    Add a DevUI entity that loads the same agent document — no copied config.

    line 146
  8. Very specific:

    Run the preflight check (python -m <package> --check) before the first call.

    line 147
  9. Distinctive:

    Run the conformance review.

    line 150

≈ “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

Voice Agent — Structure & Topology

The repo-wide house rules are in .cursor/rules/repository.mdc.md and always apply. This skill owns three things no other skill does: which topology, where files go, and the conformance checklist. Routing to sibling skills is in rules/repository.mdc.md.

Fixed integration topology

This seed uses exactly one topology: B — maf_bridge. A local MAF Agent reasons behind a VoiceLive function tool, and session.interim_response is required so retrieval and model latency do not become dead air.

Use the Foundry project settings for both reasoning and VoiceLive. The settings layer derives the VoiceLive resource endpoint by removing /api/projects/<project> and reuses FOUNDRY_API_KEY / FOUNDRY_MODEL. The MAF bridge keeps instructions and tools local:

from agent_framework.foundry import FoundryChatClient
from azure.ai.voicelive.aio import connect
from azure.core.credentials import AzureKeyCredential
from azure.identity.aio import AzureCliCredential

voice_endpoint, voice_key, voice_model = resolve_voicelive_settings()

async with (
  AzureCliCredential() as credential,
  FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["FOUNDRY_MODEL"],
    credential=credential,
  ) as chat_client,
  connect(
    endpoint=voice_endpoint,
    credential=AzureKeyCredential(voice_key),
    model=voice_model,
  ) as connection,
):
  ...

The loader constraints for maf_bridge are in maf-agent-config.

Canonical repository layout

Full annotations in references/repo-layout.md.

<repo>/
  config/
    agents/                  # kind: Prompt documents — stock MAF AgentFactory schema
    workflows/               # kind: Workflow documents — reference agent files by path
    voice/                   # seed-owned VoiceLive session documents; mount an agent/workflow
    profiles/                # environment overlays
    schemas/voice.schema.json
  src/<package>/
    config/                  # loader: voice models, overlay merge, bindings registry, builders
    agents/                  # thin factories — no literal instructions
    tools/                   # tool functions, grouped by domain; no agent imports
    workflows/               # only once a second agent exists
    voice/                   # VoiceLive event loop and audio I/O — no literal session config
    retrieval/               # RAG: Azure AI Search context providers and tools
    diagnostics.py           # logging setup + preflight; called once at the entry point
    settings.py              # typed env resolution, one place only
  skills/                    # runtime Agent Skills served via SkillsProvider
  entities/                  # DevUI discovery roots; each exports `agent` or `workflow`
  tests/
  .cursor/skills/            # engineering skills for the coding agent (this directory)
  .env.example

config/ holds behaviour, env holds deployment values, src/ holds code. A value in the wrong one of those three is the most common config defect.

Behaviour documents are MAF's own schema, not a private dialect: agent documents are kind: Prompt loaded by AgentFactory, workflow documents are kind: Workflow loaded by WorkflowFactory. Only the voice document is seed-owned, because VoiceLive session shape has no declarative equivalent. Details and the rejected layout alternatives: maf-agent-config.

Two skill trees, deliberately: skills/ is runtime (loaded by SkillsProvider); .cursor/skills/ is build-time (loaded by the coding agent). Never ship the latter.

Layering rules

  • tools/ must not import from agents/. Tools are pure, testable, and reusable.
  • voice/ must not contain business logic. It translates audio events to agent invocations.
  • settings.py exposes only the Foundry and Azure AI Search values in .env.example.
  • diagnostics.py imports nothing from the rest of the package, so it can be set up before anything that might fail.

Once a second agent appears, the workflows/ tree, participant configs, and the import direction between them are owned by maf-multi-agent-workflows.

Environment contract

Use the canonical SDK variable names — do not invent new ones. Full table with which component reads each: references/env-contract.md.

FOUNDRY_PROJECT_ENDPOINT=https://<foundry-resource>.services.ai.azure.com/api/projects/<project>
FOUNDRY_API_KEY=<foundry-resource-key>
FOUNDRY_MODEL=gpt-5.4-mini
FOUNDRY_EMBEDDING_MODEL=text-embedding-3-small
AZURE_SEARCH_ENDPOINT=https://<search-service>.search.windows.net
AZURE_SEARCH_API_KEY=<search-key>
AZURE_SEARCH_INDEX_NAME=<index>
AZURE_SEARCH_API_VERSION=2026-04-01

# OPTIONAL: only for VoiceLive on another Foundry resource/project.
# AZURE_VOICELIVE_ENDPOINT=https://<other-foundry-resource>.services.ai.azure.com
# AZURE_VOICELIVE_API_KEY=<other-resource-key>
# AZURE_VOICELIVE_MODEL=<other-model-or-deployment-name>

# Unset for a Voice Live-managed model; a byom-* profile reaches a deployment you own.
AZURE_VOICELIVE_PROFILE=byom-azure-openai-chat-completion

Scaffolding checklist

  1. Write config/agents/<name>.yaml as a kind: Prompt document — stock MAF schema, camelCase keys, domain policy in instructions.
  2. Write config/voice/<name>.yaml with topology: maf_bridge, mounts.agent: <name>, bridge-only session.instructions, and an interim_response.
  3. Create each tool in tools/ with tests, then register it in the bindings mapping under the exact name the agent document binds.
  4. Add settings.py entries for any new env var and mirror them in .env.example. Behaviour values go in YAML, never in .env.
  5. Wire diagnostics.setup_logging() as the first call at every entry point — voice loop, DevUI entity, and CLI. A seed that cannot explain its own failure is not shippable. → maf-dev-loop
  6. Construct project chat with Entra; derive VoiceLive from Foundry settings unless explicitly overridden.
  7. Add a DevUI entity that loads the same agent document — no copied config.
  8. Run the preflight check (python -m <package> --check) before the first call. It must fail loudly on unset env, unreachable endpoint, unbound tools, or a mismounted agent.
  9. Reject dependencies or settings for any Azure resource beyond Foundry and Azure AI Search.
  10. Run the conformance review.

GA-conformance review

The grep checklist is references/conformance.md — removed APIs, misplaced behaviour, loader validation, lifecycle, and security trimming. Load it before declaring any work complete. It is the only file in this pack permitted to restate a fact that another skill owns, because each row is a literal search pattern.

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.