portfolio-optimiser/docs/research/2026-06-24-maf-capability-map.md

# MAF capability map — feature-utilization for portfolio-optimiser

> **Purpose.** A living map of what Microsoft Agent Framework (MAF) `agent-framework-core`
> **1.9.0** actually offers, what this repo currently hand-rolls, and a per-need decision
> on whether to adopt the MAF feature or keep our own. It exists so Fase 2 wires MAF into
> core *using its features well* instead of reinventing them. Front-end input to the Fase 2
> `/trekbrief`.
>
> **Provenance & trust.** Grounded by two independent passes on 2026-06-24:
> (1) source-introspection of the *installed* `agent_framework` 1.9.0 (+ `agent_framework_orchestrations` 1.0.0)
> with `file:line` citations, and (2) official Microsoft Learn docs via the `microsoft-learn` MCP.
> Each verdict is tagged **[verified-source]** (read in installed bytes), **[verified-docs]**
> (official Learn), or **[hypothesis]** (needs a confirming spike). Version caveat: Learn pages
> are not version-pinned (the .NET API ref shows `v1.0.0-rc2`); where source and docs disagree,
> **the installed 1.9.0 source wins** for our code. Triggered the search-first + verification
> duties: every symbol below was read or cited, not recalled.

## 0. Headline: Microsoft documents the exact footgun Spike B(b) found

Today's `/trekreview` BLOCKER was that Spike B(b) "confirmed" fan-out state isolation with a
tautological call-counter. The rebuilt experiment showed a reused `ConcurrentBuilder` `Workflow`
accumulates the conversation thread across `.run()` calls (project N contaminates N+1). **MAF's
own Workflows "State Isolation" page states this verbatim** [verified-docs]:

> "Agent threads are persisted across workflow runs… content generated by the agent will be
> available in subsequent runs of the same workflow instance… it can also lead to unintended
> state sharing if the same workflow instance is reused for different tasks. To ensure each task
> has isolated agent state, wrap agent and workflow creation inside a helper method so each call
> produces new agent instances with their own threads. **It is not recommended to reuse a single
> workflow instance for multiple tasks or requests.**"
> — learn.microsoft.com/agent-framework/workflows/state

So our `fresh_workflow()` factory **is the documented Microsoft pattern**, and the de-risk
assumption is confirmed both empirically (Spike B) and against official guidance. The lesson is
the thesis of this document: **knowing MAF's semantics is load-bearing — a missing piece of that
knowledge produced a false-confirm that a counter-test would have shipped.**

Mechanism, traced in installed source [verified-source]: cross-run memory flows exclusively
through `AgentSession.state` (`_sessions.py:772`). With a session and no explicit context
provider, `Agent.run` auto-injects an `InMemoryHistoryProvider` (`_agents.py:1200-1209`);
`save_messages` appends into `state["messages"]` (`_sessions.py:889-890`); the next run reloads
the full history via `SessionContext.get_messages(include_input=True)` (`_sessions.py:315-348`).
A reused workflow threads one `AgentSession` into every run → accumulation. A fresh instance per
run gets a clean session.

## 1. Feature-utilization decision table (the core deliverable)

| Need | We hand-roll now | MAF 1.9.0 feature | Status | Verdict | Fase 2 action |
|---|---|---|---|---|---|
| **Token *measurement*** | `len(text.split())` proxy (`spikes/_harness.py`) | `UsageDetails` on `ChatResponse`/`AgentResponse` (`_types.py:393-414`), real provider counts | GA [verified-source] | **ADOPT** | Read `response.usage_details["total_token_count"]`; delete word-count. Handle `None` (not all providers report). |
| **Token *cap* / budget stop** | `TokenMeter.charge` raises `BudgetExceeded` | Stateful `ChatMiddleware` reading `context.result.usage_details`, short-circuits (`_middleware.py:592`); officially the "Guardrails & termination" use case | GA [verified-source+docs] | **ADOPT** | Implement budget as a `ChatMiddleware`; share one meter across agents. No native *orchestration*-level token cap exists. |
| **Round / iteration cap** | `Budget.max_rounds` + `tick_round()` | `GroupChatBuilder.with_max_rounds(n)` (`_group_chat.py:832`); Magentic `max_round_count` ctor kwarg | GA (orchestrations 1.0.0) [verified-source] | **ADOPT native; drop counter** | Use builder round caps for GroupChat/Magentic. Concurrent is single-shot (no rounds). Confirm "1 turn = 1 round" matches intent. |
| **Fan-out state isolation** | `fresh_workflow()` factory (Spike B) | Documented "factory / helper per run" pattern | core [verified-docs] | **KEEP — it is the official pattern** | Promote `fresh_workflow()` into a core fan-out factory; never reuse a built workflow across projects. |
| **Stop / resume around budget** | — | Workflow checkpointing: `WorkflowBuilder(checkpoint_storage=…)` + `run(checkpoint_id=…)` (`_workflow.py:707-731`) | GA [verified-source] | **ADOPT (later)** | Optional for resumable budget-stops; superstep-granular (not mid-LLM-call); resume needs identical graph. Defer past MVP unless needed. |
| **Cost control on long debates** | — | `_compaction.py` (`TokenBudgetComposedStrategy`, `ContextWindowCompactionStrategy`) | GA [verified-source] | **COMPLEMENT** | Reduces per-call tokens; does NOT cap spend or stop. Pair with the meter only if debates grow long (D5: not MVP). |
| **VerdictStore retrieval (ExpeL)** | Structural Jaccard over typed cost-codes + measure-type + magnitude bucket (`spikes/d_verdictstore.py`) | `MemoryStore`/`MemoryContextProvider` (keyword/substring); `mem0` (embeddings) | experimental / Preview, **wrong shape** [verified-source+docs] | **KEEP ours** | MAF retrieval is bag-of-words or embedding; cannot do structural-typed matching. Our store stays. |
| **ExpeL injection seam** | `ExpeLContextProvider(ContextProvider)` | `ContextProvider` base (`_sessions.py:351`) — `source_id` **required** | GA [verified-source] | **KEEP seam, FIX call** | Real contract. Correct the call: `extend_instructions(source_id, instructions)` — two args, `source_id` first (`_sessions.py:253-262`), not the single-list form in the spike. |
| **Deterministic blocking validator** | Hybrid IR+solver+MC returning `ValidatedProposal`\|`Rejection` (`spikes/c_validator.py`) | `_evaluation.py` (`Evaluator`/`LocalEvaluator`) | experimental, **wrong shape** [verified-source] | **KEEP ours** | MAF eval is offline batch returning a *quality score*; our validator is an inline gate returning a *domain object the system branches on*. Not interchangeable. |
| **Maker-checker regression scoring** | — | `LocalEvaluator` + `@evaluator` (`_evaluation.py`) | experimental [verified-source] | **OPTIONAL (CI only)** | "Did the checker catch the planted flaw?" fits an offline CI harness. Not for the live loop. Nice-to-have, not Fase 2 core. |
| **Model map (role→deployment)** | Planned config | `declarative/` (`AgentFactory.create_agent_from_yaml`) | Preview, **not installed** [verified-source+docs] | **ROLL OWN** | No first-class role→model registry in MAF; declarative is per-agent YAML + prerelease. Build a tiny role→deployment dict/YAML → chat-client ctor. |
| **Wrap validator / data fns as tools** | Planned | `@tool` / `FunctionTool` with `schema=` (`_tools.py`) | GA [verified-source] | **ADOPT** | GA tool surface with explicit JSON-Schema — fits "JSON-Schema-validated, fail-fast". |
| **Data access via MCP** | Planned | `MCPStdioTool` (local) / `MCPStreamableHTTPTool` (remote+SSE) / `MCPWebsocketTool` (`_mcp.py`) | GA core [verified-source+docs] | **ADOPT** | `MCPStdioTool` for local-profile data servers; `MCPStreamableHTTPTool` for remote. Pass creds per-run via header provider, never persisted. |
| **Method as Agent Skill** | Planned (CLAUDE.md) | `SkillsProvider.from_paths(...)` consumes standard `SKILL.md` folders (`_skills.py`) | experimental [verified-source] | **ADOPT (pin API)** | MAF natively consumes agentskills.io `SKILL.md` + `references/`+`scripts/`. Surface is experimental → pin version, watch for breaks. |

## 2. Verified MAF semantics worth codifying (the digest)

These are the behaviors whose absence caused today's BLOCKER — capture them so the next session
doesn't relearn them the hard way:

- **Agents are stateless per run; state lives in the session.** `agent.run(...)` with no session
  carries no history; pass `session=agent.create_session()` to accumulate. Sessions are bound to
  the agent that created them (only same-provider agents can share). [verified-docs]
- **Reused workflow ⇒ shared thread ⇒ contamination.** Build fresh per task via a factory. The
  *only* cross-run channel is `AgentSession.state`. [verified-source+docs]
- **`ContextProvider` requires `source_id`** (positional) for attribution; providers filter each
  other's contributions by it (`_sessions.py:362-368`). A history provider instance is shared
  across sessions — never store per-task state on the provider; store it in the session.
  [verified-source+docs]
- **Orchestration round semantics:** GroupChat round = one orchestrator selection/dispatch cycle;
  `with_max_rounds` enforced in `_handle_response` (not the initial handler). If you subclass
  `BaseGroupChatOrchestrator`, the builder's `max_rounds`/`termination_condition` are **ignored** —
  you must set them yourself. [verified-source+docs]
- **Magentic caps are constructor kwargs**, not `with_*` methods: `max_round_count`,
  `max_stall_count` (default 3), `max_reset_count`. There is NO `with_max_round_count`. [verified-source]
- **Token usage is on every response** as `UsageDetails` and as the OTel metric
  `gen_ai.client.token.usage`; **there is no cost/dollar metric** — derive cost = tokens × your
  per-model pricing downstream. [verified-source+docs]
- **Middleware short-circuit = the official termination/guardrail mechanism** (return without
  calling `next`); function-middleware blocking needs a `FunctionInvokingChatClient`. [verified-docs]

## 3. Corrections to existing repo claims (verification duty)

- **CLAUDE.md "Magentic is experimental (NOT the default)" — stands, with a nuance.** The installed
  `agent_framework_orchestrations` 1.0.0 carries **no `@experimental` code gate** [verified-source],
  but Microsoft's *docs* explicitly mark agent-orchestration features experimental, Magentic most so
  ("untested outside the original Magentic-One design") [verified-docs]. So the invariant is correct
  at the documentation/maturity level; it is just not enforced by a decorator. Keep the invariant;
  understand it is a doc-level stance, not a code signal.
- **STATE.md "agent-framework-core 1.9.0" — confirmed** [verified-source] (`importlib.metadata`).
  CLAUDE.md was corrected 1.8.0→1.9.0 in Fase 1.
- **Spike D `extend_instructions([...])` (single list) is the wrong signature.** Installed GA is
  `extend_instructions(source_id, instructions)` — two args, `source_id` first (`_sessions.py:253-262`)
  [verified-source]. Spike D's tests pass because they exercise `retrieve()` ranking, not the
  injection path; fix the call when promoting the ExpeL seam to core in Fase 2.
- **API-naming to confirm in 1.9.0:** docs use `AgentSession`/`ContextProvider`; older docs say
  `AgentThread` and note `BaseContextProvider`/`BaseHistoryProvider` as deprecated aliases. The
  installed source uses `SessionContext`/`ContextProvider`/`AgentSession`/`InMemoryHistoryProvider`
  [verified-source] — trust the source for our code.

## 4. The Skills question (explicit answer to "should we skillify MAF knowledge?")

**No to a MAF-documentation-mirror Skill; yes to two narrow, real uses.**

- **Why not a docs-mirror suite:** MAF docs are live via the `microsoft-learn` MCP and the
  installed source. Mirroring them into local Skills duplicates a moving target (1.9→1.10→…),
  rots, and violates DRY + the verification duty (a stale local copy can drift from truth). It is
  the docs-mirror anti-pattern for Skills and gold-plating against D5/D6.
- **Yes #1 — the *method* as a Skill (already in CLAUDE.md).** Our portfolio-optimization method
  (debate → validate → learn) is correctly an Agent Skill, and MAF can **natively consume** a
  standard `SKILL.md` folder via `SkillsProvider.from_paths(...)` [verified-source]. This is a
  capability, not a reference dump. Caveat: the Skills surface is experimental — pin and watch.
- **Yes #2 — a *digest*, which is THIS document.** §2 (verified semantics) + §3 (corrections) are
  exactly the curated "MAF patterns + footguns" an agent needs while authoring. Their durable home
  is this living capability-map (and, when the method-Skill lands, its `references/`), **not** a
  separate skill suite. A standalone "MAF-expert Skill" only pays off if many future sessions need
  *invokable* MAF fluency on demand — defer that decision until Fase 2 shows the need; the raw
  material (this doc) will already exist.

**Net:** the capability-map is the no-regret first artifact; it feeds both the Fase 2 design and
any later skillification, and it answers "skillify?" with "the method yes, the reference no."

## 5. Fase 2 implications (what changes in the brief)

1. **Replace** hand-rolled token measurement with `UsageDetails`; **re-implement** the budget cap
   as a shared `ChatMiddleware`; **use native** builder round caps. The hand-rolled `Budget`/
   `TokenMeter` shrink to a thin shared-meter object the middleware drives.
2. **Promote** `fresh_workflow()` to a core fan-out factory — it is the documented isolation pattern.
3. **Keep** the hand-rolled VerdictStore (structural retrieval) and validator (inline gate); MAF's
   memory and eval are the wrong shape. Promote the `ExpeLContextProvider` seam with the two-arg fix.
4. **Adopt** GA `@tool` + `MCPStdioTool`/`MCPStreamableHTTPTool` for tools/data access.
5. **Roll** a tiny role→deployment config map (declarative is preview + not installed).
6. **Wire** observability (`gen_ai.client.token.usage`) for cost tracking; derive cost from pricing.
7. **Production-risk flags (D2/D6):** mem0/redis memory, Cosmos/Redis history, and declarative are
   all **Preview** — do not put them on the MVP critical path; the GA core (sessions, middleware,
   observability, tools, MCP, checkpointing) is enough for the vertical slice.

## 6. D7 sibling note

The Claude Agent SDK sibling (eget repo, deler kun spec+golden-suite) faces the same
feature-utilization discipline against a different substrate. This map's *structure* (need →
feature → adopt/keep verdict) is the reusable analog; the *answers* differ. The shared golden-suite
must not bake in MAF-specific assumptions (e.g., MAF's session-accumulation semantics).

---

*Sources: installed `agent_framework` 1.9.0 source (file:line cited inline); Microsoft Learn —
workflows/state, orchestrations/{group-chat,magentic}, agents/{middleware,observability,evaluation,
conversations/storage}, integrations/chat-history-memory-provider, agents/declarative,
agents/tools/local-mcp-tools. Two independent research passes, 2026-06-24.*