microsoft-agent-framework

Microsoft Agent Framework is an open-source platform for building production AI agents and workflows, unifying AutoGen's simplicity with Semantic Kernel's enterprise features.

Core Capabilities: AI Agents (stateful conversations, tool integration) | Workflows (graph-based orchestration, parallel processing) | Enterprise features (telemetry, middleware, MCP support)

Installation:

• Python: pip install agent-framework --pre
• C#: dotnet add package Microsoft.Agents.AI --prerelease

Repository: https://github.com/microsoft/agent-framework (5.1k stars)

---

Use Microsoft Agent Framework when you need:

1. Production AI Agents with enterprise features (telemetry, middleware, structured outputs)
2. Multi-Agent Orchestration via graph-based workflows with conditional routing
3. Tool/Function Integration with approval workflows and error handling
4. Cross-Platform Development requiring both Python and C# implementations
5. Research-to-Production Pipeline leveraging AutoGen + Semantic Kernel convergence

Integration with amplihack: Use Agent Framework for stateful conversational agents and complex orchestration. Use amplihack's native agent system for stateless task delegation and simple orchestration. See @integration/decision-framework.md for detailed guidance.

---

1. AI Agents

Stateful conversational entities that process messages, call tools, and maintain context.

Python Example:

```python

from agents_framework import Agent, ModelClient

# Create agent with model

agent = Agent(

name="assistant",

model=ModelClient(model="gpt-4"),

instructions="You are a helpful assistant"

)

# Single-turn conversation

response = await agent.run(message="Hello!")

print(response.content)

# Multi-turn with thread

from agents_framework import Thread

thread = Thread()

response = await agent.run(thread=thread, message="What's 2+2?")

response = await agent.run(thread=thread, message="Double that")

```

C# Example:

```csharp

using Microsoft.Agents.AI;

var agent = new Agent(

name: "assistant",

model: new ModelClient(model: "gpt-4"),

instructions: "You are a helpful assistant"

);

var response = await agent.RunAsync("Hello!");

Console.WriteLine(response.Content);

```

2. Tools & Functions

Extend agent capabilities by providing callable functions.

Python Example:

```python

from agents_framework import function_tool

@function_tool

def get_weather(location: str) -> str:

"""Get weather for a location."""

return f"Weather in {location}: Sunny, 72°F"

agent = Agent(

name="assistant",

model=ModelClient(model="gpt-4"),

tools=[get_weather]

)

response = await agent.run(message="What's the weather in Seattle?")

# Agent automatically calls get_weather() and responds with result

```

C# Example:

```csharp

[FunctionTool]

public static string GetWeather(string location)

{

return $"Weather in {location}: Sunny, 72°F";

}

var agent = new Agent(

name: "assistant",

model: new ModelClient(model: "gpt-4"),

tools: new[] { typeof(Tools).GetMethod("GetWeather") }

);

```

3. Workflows

Graph-based orchestration for multi-agent systems with conditional routing and parallel execution.

Python Example:

```python

from agents_framework import Workflow, GraphWorkflow

# Define workflow graph

workflow = GraphWorkflow()

# Add agents as nodes

workflow.add_node("researcher", research_agent)

workflow.add_node("writer", writer_agent)

workflow.add_node("reviewer", review_agent)

# Define edges (control flow)

workflow.add_edge("researcher", "writer") # Sequential

workflow.add_edge("writer", "reviewer")

# Conditional routing

def should_revise(state):

return state.get("needs_revision", False)

workflow.add_conditional_edge(

"reviewer",

should_revise,

{"revise": "writer", "done": "END"}

)

# Execute workflow

result = await workflow.run(initial_message="Research AI trends")

```

C# Example:

```csharp

var workflow = new GraphWorkflow();

workflow.AddNode("researcher", researchAgent);

workflow.AddNode("writer", writerAgent);

workflow.AddNode("reviewer", reviewAgent);

workflow.AddEdge("researcher", "writer");

workflow.AddEdge("writer", "reviewer");

var result = await workflow.RunAsync("Research AI trends");

```

4. Context & State Management

Maintain conversation history and shared state across agents.

Python:

```python

from agents_framework import Thread, ContextProvider

# Thread maintains conversation history

thread = Thread()

await agent.run(thread=thread, message="Remember: My name is Alice")

await agent.run(thread=thread, message="What's my name?") # "Alice"

# Custom context provider

class DatabaseContext(ContextProvider):

async def get_context(self, thread_id: str):

return await db.fetch_history(thread_id)

async def save_context(self, thread_id: str, messages):

await db.save_history(thread_id, messages)

agent = Agent(model=model, context_provider=DatabaseContext())

```

5. Middleware & Telemetry

Add cross-cutting concerns like logging, auth, and monitoring.

Python:

```python

from agents_framework import Middleware

from opentelemetry import trace

# Custom middleware

class LoggingMiddleware(Middleware):

async def process(self, message, next_handler):

print(f"Processing: {message.content}")

response = await next_handler(message)

print(f"Response: {response.content}")

return response

# OpenTelemetry integration

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("agent-run"):

response = await agent.run(message="Hello")

```

C#:

```csharp

public class LoggingMiddleware : IMiddleware

{

public async Task ProcessAsync(Message message, Func> next)

{

Console.WriteLine($"Processing: {message.Content}");

var response = await next(message);

Console.WriteLine($"Response: {response.Content}");

return response;

}

}

```

---

Human-in-the-Loop Approval

```python

from agents_framework import HumanInTheLoop

@function_tool

def delete_file(path: str) -> str:

"""Delete a file (requires approval)."""

return f"Deleted {path}"

# Add approval wrapper

delete_file_with_approval = HumanInTheLoop(

tool=delete_file,

approval_prompt="Approve deletion of {path}?"

)

agent = Agent(tools=[delete_file_with_approval])

```

Parallel Agent Execution

```python

workflow = GraphWorkflow()

# Add multiple agents

workflow.add_node("analyst1", analyst_agent)

workflow.add_node("analyst2", analyst_agent)

workflow.add_node("synthesizer", synthesis_agent)

# Parallel execution

workflow.add_edge("START", ["analyst1", "analyst2"]) # Both run in parallel

workflow.add_edge(["analyst1", "analyst2"], "synthesizer") # Wait for both

result = await workflow.run(message="Analyze market trends")

```

Structured Output Generation

```python

from pydantic import BaseModel

class WeatherReport(BaseModel):

location: str

temperature: float

conditions: str

agent = Agent(

model=model,

instructions="Generate weather reports",

response_format=WeatherReport

)

response = await agent.run(message="Weather in Seattle")

report: WeatherReport = response.parsed

print(f"{report.location}: {report.temperature}°F, {report.conditions}")

```

Error Handling & Retries

```python

from agents_framework import RetryPolicy

agent = Agent(

model=model,

retry_policy=RetryPolicy(

max_retries=3,

backoff_factor=2.0,

exceptions=[TimeoutError, ConnectionError]

)

)

try:

response = await agent.run(message="Hello")

except Exception as e:

print(f"Failed after retries: {e}")

```

---

Decision Framework

Use Microsoft Agent Framework when:

• Building stateful conversational agents (multi-turn dialogue)
• Need enterprise features (telemetry, middleware, auth)
• Complex multi-agent orchestration with conditional routing
• Cross-platform requirements (Python + C#)
• Integration with Microsoft ecosystem (Azure, M365)

Use amplihack native agents when:

• Stateless task delegation (code review, analysis)
• Simple sequential/parallel orchestration
• File-based operations and local tooling
• Rapid prototyping without infrastructure
• Token-efficient skill-based architecture

Hybrid Approach:

```python

# Use amplihack for orchestration

from claude import Agent as ClaudeAgent

orchestrator = ClaudeAgent("orchestrator.md")

# Delegate to Agent Framework for stateful agents

from agents_framework import Agent, Thread

conversational_agent = Agent(

model=ModelClient(model="gpt-4"),

instructions="Maintain conversation context"

)

thread = Thread()

response1 = await conversational_agent.run(thread=thread, message="Start task")

response2 = await conversational_agent.run(thread=thread, message="Continue")

# Use amplihack for final synthesis

result = orchestrator.process({"responses": [response1, response2]})

```

See @integration/amplihack-integration.md for complete patterns.

---

1. Install: pip install agent-framework --pre (Python) or dotnet add package Microsoft.Agents.AI --prerelease (C#)

1. Create Basic Agent:

```python

from agents_framework import Agent, ModelClient

agent = Agent(

name="assistant",

model=ModelClient(model="gpt-4"),

instructions="You are a helpful assistant"

)

response = await agent.run(message="Hello!")

```

1. Add Tools:

```python

@function_tool

def calculate(expr: str) -> float:

return eval(expr)

agent = Agent(model=model, tools=[calculate])

```

1. Build Workflow:

```python

workflow = GraphWorkflow()

workflow.add_node("agent1", agent1)

workflow.add_node("agent2", agent2)

workflow.add_edge("agent1", "agent2")

result = await workflow.run(message="Task")

```

1. Add Telemetry:

```python

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("agent-run"):

response = await agent.run(message="Hello")

```

---

For detailed information, see:

• @reference/01-overview.md - Architecture, components, use cases
• @reference/02-agents.md - Agent creation, lifecycle, advanced features
• @reference/03-workflows.md - Workflow patterns, executors, checkpointing
• @reference/04-tools-functions.md - Tool definition, approval workflows, error handling
• @reference/05-context-middleware.md - Context providers, middleware patterns, auth
• @reference/06-telemetry-monitoring.md - OpenTelemetry, logging, debugging
• @reference/07-advanced-patterns.md - Multi-agent patterns, streaming, DevUI

• @examples/01-basic-agent.py - Simple conversational agent
• @examples/02-tool-integration.py - Agent with function calling
• @examples/03-simple-workflow.py - Multi-agent workflow
• @examples/04-basic-agent.cs - C# agent implementation
• @examples/05-tool-integration.cs - C# tool integration
• @examples/06-simple-workflow.cs - C# workflow example

Check framework freshness: python @scripts/check-freshness.py

Current version tracking: @metadata/version-tracking.json

---

Token Count: ~4,200 tokens (under 4,800 limit)