1# Microsoft Agent Framework — Best Practices for Hosted Agents
2 
3Best practices when building hosted agents with Microsoft Agent Framework for deployment to Foundry Agent Service.
4 
5## Official Resources
6 
7| Resource | URL |
8|----------|-----|
9| **GitHub Repo** | https://github.com/microsoft/agent-framework |
10| **MS Learn Overview** | https://learn.microsoft.com/agent-framework/overview/agent-framework-overview |
11| **Quick Start** | https://learn.microsoft.com/agent-framework/tutorials/quick-start |
12| **User Guide** | https://learn.microsoft.com/agent-framework/user-guide/overview |
13| **Hosted Agents Concepts** | https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents |
14| **Python Samples (MAF repo)** | https://github.com/microsoft/agent-framework/tree/main/python/samples |
15| **.NET Samples (MAF repo)** | https://github.com/microsoft/agent-framework/tree/main/dotnet/samples |
16| **PyPI** | https://pypi.org/project/agent-framework/ |
17| **NuGet** | https://www.nuget.org/profiles/MicrosoftAgentFramework/ |
18 
19## Installation
20 
21**Python:** `pip install agent-framework agent-framework-foundry-hosting` (installs all sub-packages)
22 
23**.NET:** `dotnet add package Microsoft.Agents.AI`
24 
25## Hosting Adapter
26 
27Hosted agents must expose an HTTP server using the hosting adapter. This enables local testing and Foundry deployment with the same code.
28 
29**Python adapter packages:** `agent_framework_foundry_hosting`
30 
31**.NET adapter packages:** `Azure.AI.AgentServer.Core`, `Microsoft.Agents.AI.Foundry.Hosting`
32 
33The adapter handles protocol translation between Foundry request/response formats and your framework's native data structures, including conversation management, message serialization, and streaming.
34 
35> 💡 **Tip:** Make HTTP server mode the default entrypoint (no flags needed). This simplifies both local debugging and containerized deployment.
36 
37## Key Patterns
38 
39### Python: Credentials
40 
41For **local development**, use `DefaultAzureCredential` from `azure.identity`. In production, use `ManagedIdentityCredential`. See [auth-best-practices.md](../../../references/auth-best-practices.md).
42 
43### Python: Environment Variables
44 
45Always use `load_dotenv(override=False)` so environment variables set by Foundry at runtime take precedence over local `.env` values.
46 
47Required `.env` variables:
48- `FOUNDRY_PROJECT_ENDPOINT` — project endpoint URL
49- `FOUNDRY_MODEL_DEPLOYMENT_NAME` — model deployment name
50 
51### Authentication
52 
53If explicitly asked to use API key instead of managed identity, then use AzureOpenAIResponsesClient and pass in api_key parameter to it.
54 
55### Agent Naming Rules
56 
57Agent names must: start/end with alphanumeric characters, may contain hyphens in the middle, max 63 characters. Examples: `MyAgent`, `agent-1`. Invalid: `-agent`, `agent-`, `sample_agent`.
58 
59### Python: Virtual Environment
60 
61Always use a virtual environment. Never use bare `python` or `pip` — use venv-activated versions or full paths (e.g., `.venv/bin/pip`).
62 
63## Workflow Patterns
64 
65Agent Framework supports single-agent and multi-agent workflow patterns using graph-based orchestration:
66 
67- **Single Agent** — Basic agent with tools, RAG, or MCP integration
68- **Multi-Agent Workflow** — Graph-based orchestration connecting multiple agents and deterministic functions
69- **Advanced Patterns** — Reflection, switch-case, fan-out/fan-in, loop, human-in-the-loop
70 
71For workflow samples and advanced patterns, search the [Agent Framework GitHub repo](https://github.com/microsoft/agent-framework).
72 
73## Debugging
74 
75Use [AI Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio) with the `agentdev` CLI tool for interactive debugging:
76 
771. Install `debugpy` for VS Code Python Debugger support
782. Install `agent-dev-cli` (pre-release) for the `agentdev` command
793. Key debug tasks: `agentdev run <entrypoint>.py --port 8087` starts the agent HTTP server, `debugpy --listen 127.0.0.1:5679` attaches the debugger, and the `ai-mlstudio.openTestTool` VS Code command opens the Agent Inspector UI
80 
81For VS Code `launch.json` and `tasks.json` configuration templates, see [AI Toolkit Agent Inspector — Configure debugging manually](https://github.com/microsoft/vscode-ai-toolkit/blob/main/doc/agent-test-tool.md#configure-debugging-manually).
82 
83## Common Errors
84 
85| Error | Cause | Fix |
86|-------|-------|-----|
87| `ModuleNotFoundError` | Missing SDK | `pip install agent-framework agent-framework-foundry-hosting` in venv |
88| Credential error | Wrong import | Use `azure.identity.DefaultAzureCredential` (local dev) or `ManagedIdentityCredential` (production) |
89| Agent name validation error | Invalid characters | Use alphanumeric + hyphens, start/end alphanumeric, max 63 chars |
90| Hosting adapter not found | Missing package | Install `agent-framework-foundry-hosting` |
91