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
In this repository19 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/repository.mdcCursor rule
- ai-searchSkill
- maf-agent-configSkill
- maf-dev-loopSkill
- maf-foundry-agentSkill
- maf-multi-agent-workflowsSkill
- maf-voice-agentSkill
- mermaid-diagramsSkill
- skill-pack-auditSkill
- voicelive-realtimeSkill
- ai-searchSkill
- maf-agent-configSkill
- maf-dev-loopSkill
- maf-foundry-agentSkill
- maf-multi-agent-workflowsSkill
- mermaid-diagramsSkill
- skill-pack-auditSkill
- voicelive-realtimeSkill
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
- Very specific: line 25
Use the Foundry project settings for both reasoning and VoiceLive.
- Distinctive: line 109
Use the canonical SDK variable names — do not invent new ones.
- Very specific: line 133
Write config/agents/<name>.yaml as a kind: Prompt document — stock MAF schema, camelCase keys, domain policy in instructions.
- Very specific: line 135
Write config/voice/<name>.yaml with topology: maf_bridge, mounts.agent: <name>, bridge-only session.instructions, and an interim_response.
- Very specific: line 137
Create each tool in tools/ with tests, then register it in the bindings mapping under the exact name the agent document binds.
- Very specific: line 139
Add settings.py entries for any new env var and mirror them in .env.example.
- Distinctive: line 146
Add a DevUI entity that loads the same agent document — no copied config.
- Very specific: line 147
Run the preflight check (python -m <package> --check) before the first call.
- Distinctive: line 150
Run the conformance review.
≈ “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.
Files
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.exampleconfig/ 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 fromagents/. Tools are pure, testable, and reusable.voice/must not contain business logic. It translates audio events to agent invocations.settings.pyexposes only the Foundry and Azure AI Search values in.env.example.diagnostics.pyimports 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-completionScaffolding checklist
- Write
config/agents/<name>.yamlas akind: Promptdocument — stock MAF schema, camelCase keys, domain policy ininstructions. - Write
config/voice/<name>.yamlwithtopology: maf_bridge,mounts.agent: <name>, bridge-onlysession.instructions, and aninterim_response. - Create each tool in
tools/with tests, then register it in the bindings mapping under the exact name the agent document binds. - Add
settings.pyentries for any new env var and mirror them in.env.example. Behaviour values go in YAML, never in.env. - 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 - Construct project chat with Entra; derive VoiceLive from Foundry settings unless explicitly overridden.
- Add a DevUI entity that loads the same agent document — no copied config.
- 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. - Reject dependencies or settings for any Azure resource beyond Foundry and Azure AI Search.
- 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.
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
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.

