Microsoft Agent Framework Best Practices

Ten practices for structuring conversations, workflows, and governance in production on Microsoft Agent Framework 1.0. Use them as a design rubric and a PR checklist.

How to Use This List

Walk A when choosing conversation vs workflow shape; B when wiring tools and sessions; C when hardening governance and ops.
Tick items only when true in code, config, or runbooks - not as aspirations.
Pair with Governance and Enterprise Controls in Microsoft Agent Framework for control-plane depth.
Re-check after adding agents, tools, MCP servers, or long-running workflows.

A - Shape Conversations and Workflows

1. Prefer a single agent until roles truly diverge. Extra participants need different goals, tools, or trust boundaries - not duplicate prompts.
2. Choose sequential chat for critique loops; graphs for fixed processes. Draft/review thrives in orchestration builders; regulated pipelines need typed edges, joins, and checkpoints.
3. Name every agent and executor for traces. Readable name / executor ids beat anonymous multi-agent soup in logs.
4. Cap rounds, stalls, wall time, and tokens in the host. Builder limits help; host budgets are mandatory for production.
5. Checkpoint any workflow that can outlive one HTTP request. Long HITL or multi-hour jobs must resume without replaying privileged side effects blindly.

B - Tools, Sessions, and Connectors

6. Attach least-privilege tools per agent. Shared kitchen-sink plugins recreate single-agent risk inside multi-agent costumes.
7. Use sessions deliberately. Agents are not durable chat logs by default - create/resume AgentSession (or provider sessions) per user thread and tenant.
8. Package enterprise capabilities as versioned tools or MCP servers. Prefer shared libraries/toolboxes over copy-pasted plugin code; document schemas and owners.
9. Gate irreversible tools with approval or workflow HITL. Deletes, payments, IAM changes, and deploys need a human or policy gate outside the prompt.
10. Standardize chat clients and auth. One factory for Foundry/OpenAI/Azure routing with Entra-friendly credentials beats five ad-hoc connectors.

C - Govern and Operate

11. Enforce policy in middleware, not only prompts. Function allowlists, redaction, and fail-closed blocks belong in agent/function/chat middleware.
12. Log phase labels and policy decisions. Include agent/workflow id, tool name, stop reason, token cost, and block vs allow outcomes.
13. Eval multi-agent trajectories, not only final answers. Track rounds, handoff failures, repeated tools, budget hits, and approval latency.
14. Isolate tenants and secrets in the host. No cross-tenant sessions; inject secrets via DI; treat tool outputs as untrusted.
15. Migrate AutoGen/SK with golden suites. Port tools and single agents first; require quality/cost parity before deleting legacy packages.

Applying These Practices in Order

Shape (1-5): cheapest on a whiteboard; expensive after chat sprawl.
Tools and sessions (6-10): launch blockers when real systems or money are involved.
Govern and operate (11-15): required to keep multi-agent systems auditable under load.

FAQs

Why fifteen checkboxes if the title says ten practices?

Items 1-10 are the core shipping practices. Items 11-15 extend them into governance and migration so the list stays useful after go-live.

What is the single highest-leverage practice?

Host-enforced budgets plus least-privilege tools. Everything else fails more safely when loops and tools cannot run unbounded.

When is multi-agent chat justified?

When specialists need different instructions, tools, or approval boundaries and you can name a stop condition. Otherwise keep one agent.

When should we force a graph workflow?

When steps, joins, approvals, or resume requirements must be explicit for auditability or reliability - not when you only want a friendlier demo.

Do these practices require Azure Foundry?

No. They apply to open-source Agent Framework generally. Foundry strengthens identity, hosted tools, and observability when you choose that host.

How do we apply middleware without slowing every prototype?

Use a shared middleware pack in non-prod with logging + allowlists early. Add stricter approvals and redaction as tools gain privileges.

How often should we revisit agent names and roles?

At every new tool or MCP server addition, and during incident reviews when traces are hard to read.

What belongs in CI for Agent Framework apps?

Golden task suite, tool schema linting, middleware fail-closed tests, and a cost/latency budget check on representative traces.

How do Magentic orchestrations fit this list?

Treat them as multi-agent shapes under practices 2-5 with mandatory stall/reset/round caps and manager tool limits.

Can declarative YAML agents skip these practices?

No. YAML is still production config - review tools, middleware hooks, and environment bindings in PRs.

What evidence shows practice 1 was violated?

Three near-identical agents, shared full tool belts, and no handoff contract - cost up, quality flat.

Where should teams link this checklist?

Section close-out in docs, architecture decision records for agent systems, and on-call runbook footers for multi-agent incidents.

From AutoGen and Semantic Kernel to Microsoft Agent Framework 1.0 - product context
Microsoft Agent Framework Basics - first two-agent handoff
Conversational Multi-Agent Patterns: Agent-to-Agent Chat - chat patterns
Graph-Based Workflows in Microsoft Agent Framework - workflow model
Enterprise Plugins and Connectors from Semantic Kernel - tools path
Migrating an Existing AutoGen Project to Microsoft Agent Framework - migration
Governance and Enterprise Controls in Microsoft Agent Framework - control plane
Agent Architectures Best Practices - pattern-level checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Microsoft Agent Framework Best Practices

Ten practices for structuring conversations, workflows, and governance in production on Microsoft Agent Framework 1.0. Use them as a design rubric and a PR checklist.

How to Use This List

Walk A when choosing conversation vs workflow shape; B when wiring tools and sessions; C when hardening governance and ops.
Tick items only when true in code, config, or runbooks - not as aspirations.
Pair with Governance and Enterprise Controls in Microsoft Agent Framework for control-plane depth.
Re-check after adding agents, tools, MCP servers, or long-running workflows.

A - Shape Conversations and Workflows

1. Prefer a single agent until roles truly diverge. Extra participants need different goals, tools, or trust boundaries - not duplicate prompts.
2. Choose sequential chat for critique loops; graphs for fixed processes. Draft/review thrives in orchestration builders; regulated pipelines need typed edges, joins, and checkpoints.
3. Name every agent and executor for traces. Readable name / executor ids beat anonymous multi-agent soup in logs.
4. Cap rounds, stalls, wall time, and tokens in the host. Builder limits help; host budgets are mandatory for production.
5. Checkpoint any workflow that can outlive one HTTP request. Long HITL or multi-hour jobs must resume without replaying privileged side effects blindly.

B - Tools, Sessions, and Connectors

6. Attach least-privilege tools per agent. Shared kitchen-sink plugins recreate single-agent risk inside multi-agent costumes.
7. Use sessions deliberately. Agents are not durable chat logs by default - create/resume AgentSession (or provider sessions) per user thread and tenant.
8. Package enterprise capabilities as versioned tools or MCP servers. Prefer shared libraries/toolboxes over copy-pasted plugin code; document schemas and owners.
9. Gate irreversible tools with approval or workflow HITL. Deletes, payments, IAM changes, and deploys need a human or policy gate outside the prompt.
10. Standardize chat clients and auth. One factory for Foundry/OpenAI/Azure routing with Entra-friendly credentials beats five ad-hoc connectors.

C - Govern and Operate

11. Enforce policy in middleware, not only prompts. Function allowlists, redaction, and fail-closed blocks belong in agent/function/chat middleware.
12. Log phase labels and policy decisions. Include agent/workflow id, tool name, stop reason, token cost, and block vs allow outcomes.
13. Eval multi-agent trajectories, not only final answers. Track rounds, handoff failures, repeated tools, budget hits, and approval latency.
14. Isolate tenants and secrets in the host. No cross-tenant sessions; inject secrets via DI; treat tool outputs as untrusted.
15. Migrate AutoGen/SK with golden suites. Port tools and single agents first; require quality/cost parity before deleting legacy packages.

Applying These Practices in Order

Shape (1-5): cheapest on a whiteboard; expensive after chat sprawl.
Tools and sessions (6-10): launch blockers when real systems or money are involved.
Govern and operate (11-15): required to keep multi-agent systems auditable under load.

FAQs

Why fifteen checkboxes if the title says ten practices?

Items 1-10 are the core shipping practices. Items 11-15 extend them into governance and migration so the list stays useful after go-live.

What is the single highest-leverage practice?

Host-enforced budgets plus least-privilege tools. Everything else fails more safely when loops and tools cannot run unbounded.

When is multi-agent chat justified?

When specialists need different instructions, tools, or approval boundaries and you can name a stop condition. Otherwise keep one agent.

When should we force a graph workflow?

When steps, joins, approvals, or resume requirements must be explicit for auditability or reliability - not when you only want a friendlier demo.

Do these practices require Azure Foundry?

No. They apply to open-source Agent Framework generally. Foundry strengthens identity, hosted tools, and observability when you choose that host.

How do we apply middleware without slowing every prototype?

Use a shared middleware pack in non-prod with logging + allowlists early. Add stricter approvals and redaction as tools gain privileges.

How often should we revisit agent names and roles?

At every new tool or MCP server addition, and during incident reviews when traces are hard to read.

What belongs in CI for Agent Framework apps?

Golden task suite, tool schema linting, middleware fail-closed tests, and a cost/latency budget check on representative traces.

How do Magentic orchestrations fit this list?

Treat them as multi-agent shapes under practices 2-5 with mandatory stall/reset/round caps and manager tool limits.

Can declarative YAML agents skip these practices?

No. YAML is still production config - review tools, middleware hooks, and environment bindings in PRs.

What evidence shows practice 1 was violated?

Three near-identical agents, shared full tool belts, and no handoff contract - cost up, quality flat.

Where should teams link this checklist?

Section close-out in docs, architecture decision records for agent systems, and on-call runbook footers for multi-agent incidents.

From AutoGen and Semantic Kernel to Microsoft Agent Framework 1.0 - product context
Microsoft Agent Framework Basics - first two-agent handoff
Conversational Multi-Agent Patterns: Agent-to-Agent Chat - chat patterns
Graph-Based Workflows in Microsoft Agent Framework - workflow model
Enterprise Plugins and Connectors from Semantic Kernel - tools path
Migrating an Existing AutoGen Project to Microsoft Agent Framework - migration
Governance and Enterprise Controls in Microsoft Agent Framework - control plane
Agent Architectures Best Practices - pattern-level checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Microsoft Agent Framework Best Practices

Search Documentation

Microsoft Agent Framework Best Practices