maf-voice-agent

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