# Sweet Spot — When to use what in MAF

> **Scope:** stacks=["dotnet"]
> **Layer:** 0 (always-load via persona maf-expert)
> **Keywords:** sweet spot, when to use agent, agent vs workflow, when not to use workflow, MAF decision, simple agent, tool budget, quantas tools
> **Read by Claude in:** plan (decide arquitetura da feature antes de quebrar em tasks) + implement (validar que a arquitetura ainda é a mais simples possível)

**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Agents.AI.Workflows 1.20.0 (ai-pin 2026-09-08 para o primeiro; o segundo está **fora do pin**, versão apurada no nuget.org em 2026-09-08). **Verificação documental**, sem cláusula `provado por` — este standard é decisão de arquitetura, não API. A escada de complexidade foi reconferida e **continua correta**; o que entrou de novo é o custo de definição de tool por turno e o status do Handoff. Last-verified: 2026-09-08.

---

## The 4-feature rule

```
95% of production AI agents need ONLY:

  1. Chat (the LLM call)
  2. Structured Output (typed records, not free text)
  3. Tools (typed functions the agent can call)
  4. RAG Custom (pgvector tool, not hosted RAG)

If your feature needs ONLY these 4 → use a single agent. Don't reach for workflows.
```

Apply this rule before deciding multi-agent or workflow. Most of the time the answer is "single agent".

### O quinto sinal: quantas tools o agente carrega

A regra das 4 features diz **o que** o agente faz. Falta **quanto** ele carrega — e esse é o custo que ninguém vê no código.

**Toda tool registrada entra na definição enviada ao modelo em CADA turno**: nome, descrição e o JSON Schema completo dos parâmetros. Um agente com 40 tools paga esses 40 schemas de entrada em todo turno, inclusive nos turnos em que nenhuma tool é chamada — e paga de novo em cada volta do laço de tool calling.

**Referência prática: ≤ 12 tools por agente.** Acima disso, dois efeitos se somam, e o segundo é pior que o primeiro:

1. **Custo por turno cresce** com o tamanho da definição.
2. **A escolha piora.** Quanto mais tools parecidas, mais o modelo erra qual chamar — e um erro de escolha custa uma volta inteira.

**Quando estourar o teto, na ordem:** (a) **poda** — remova o que não é usado naquele modo; (b) **plano por fase** — uma allow-list por estado do funil, montada em C# (`ai-agents-context-providers` §Ordem de escolha); (c) **só então** agent-as-tool, com o auxiliar carregando o próprio subconjunto (`ai-agents-multi-agent-patterns`). Servidor MCP com dezenas de tools é o caso mais comum de estouro — ver `ai-agents-mcp-tools` §Custo de definição de tool por turno.

### Status do Handoff (2026-09-08)

O Handoff era marcado **experimental** no 1.0 e **graduou**: `Microsoft.Agents.AI.Workflows.HandoffWorkflowBuilder` **não carrega** `[Experimental]` na assembly 1.20.0 (medido). Isso muda o degrau da escada: handoff deixou de ser "experimental, evite" e passou a ser "estável, mas ainda depois de agent-as-tool" — a ordem de preferência **não** mudou, o motivo mudou. O critério continua o mesmo: agent-as-tool primeiro, handoff quando há N especialistas e a decisão de roteamento não cabe numa tool.

---

## Decision tree (Claude reads this in plan phase)

```
Step 1 — Does the task even need an LLM?
├─ "Can a deterministic function solve this?" → YES → write the function, no agent
└─ NO → continue

Step 2 — Single agent vs multi-agent?
├─ One topic + one decision → single agent (DEFAULT)
├─ Multiple specialized topics with clear handoff → multi-agent
│   └─ Prefer Agent-as-Tool pattern (one agent uses another as a tool)
│   └─ See ai-agents-multi-agent-patterns
└─ "I'm not sure" → start with single agent, escalate if needed

Step 3 — Need a Workflow?
├─ The feature has fan-in/out (many inputs aggregated) → maybe workflow
│   └─ Confirm: can you write it as a foreach + LINQ aggregate?
│       └─ YES → write the foreach, NO workflow
│       └─ NO → workflow may help
├─ Long-running with human-in-the-loop checkpoints → maybe workflow
│   └─ See ai-agents-workflows (Onda 2)
└─ Otherwise → NO workflow

Step 4 — Which provider?
├─ ALWAYS direct models — never a hosted agent service
├─ Provider choice (OpenAI / Google / Anthropic / Ollama) lives in the
│  project's Model Registry, not hardcoded → see ai-agents-providers-model-registry
└─ Hosted services (Foundry Agent Service, Vertex AI hosted) → NOT used

Step 5 — RAG approach?
├─ Need control over chunking/embedding/storage? → RAG custom (pgvector)
│   └─ See ai-agents-rag-custom-pgvector (Onda 2)
└─ Don't reach for hosted RAG — loses control
```

---

## Anti-patterns (what Claude should NOT do)

| Anti-pattern | Why it's wrong | What to do instead |
|--------------|----------------|---------------------|
| Reach for Workflow when a function does the job | "Tudo que Workflows fazem, código C# normal faz com menos complexidade" — pesquisa | Write the function. Wrap in a tool if an agent needs to call it. |
| Use a hosted agent service | Hosted is "always 6-9 months behind" on models + removes control | Direct models always (OpenAI / Google / Anthropic / Ollama) |
| Upload PDFs to a hosted RAG | Loses control of chunking + embedding + storage | Custom RAG with pgvector. See ai-agents-rag-custom-pgvector |
| Add Memory/Session because "agents need state" | If not building a chatbot, don't add chat state | Skip. Add when a real chat UI exists. |
| Use Semantic Kernel for new features | SK is superseded by MAF | Use Microsoft.Agents.AI. See ai-agents-setup |
| Return free text and parse it downstream | LLM output is non-deterministic | Structured Output. See ai-agents-structured-output (Onda 2) |

---

## When the 4-feature rule does NOT apply

You may need to step outside the sweet spot when:
- The feature genuinely fans-out (e.g., monthly report aggregating N items) → workflow with fan-in
- The feature needs vision/audio/image-gen → modality-specific standards (see ai-agents-modalities-* — Onda 3)

**Even in these cases:** the core of the agent still follows the 4-feature rule. Only the orchestration layer changes.

---

## Checklist (verifiable by morph-eval)

- [ ] Was each agent designed as single-agent BEFORE reaching for multi-agent? (Check `decisions.md`.)
- [ ] If a Workflow is used, is fan-in/out or HITL checkpointing genuinely present? Or could `foreach + LINQ` replace it?
- [ ] Are the 4 features (Chat, Structured Output, Tools, RAG Custom) all present where applicable?
- [ ] Are hosted agent services avoided?
- [ ] Nenhum agente carrega mais de ~12 tools sem uma decisão escrita em `decisions.md` sobre a poda

---

## References

- `ai-agents-setup` — packages and DI
- `ai-agents-providers-model-registry` — provider-agnostic config
- `ai-agents-structured-output` (Onda 2)
- `ai-agents-multi-agent-patterns` (Onda 2)
- `ai-agents-workflows` (Onda 2, reframed)
- `ai-agents-rag-custom-pgvector` (Onda 2)
- `ai-agents-mcp-tools` — o caso mais comum de estouro do teto de tools
- `ai-agents-context-providers` — plano por fase com allow-list de tools

---

*MORPH-SPEC by Polymorphism Tech — ai-agents/sweet-spot.md v1.1 (2026-09-08)*