Merge pull request #805 from gewarren/ug-pass-1

Edit pass on user-guide/workflows docs

Author: markwallace-microsoft

agent-framework/user-guide/model-context-protocol/index.md

@@ -16,7 +16,8 @@ Model Context Protocol is an open standard that defines how applications provide
 You can extend the capabilities of your Agent Framework agents by connecting it to tools hosted on remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) servers.
 
 ## Considerations for using third party Model Context Protocol servers
-Your use of Model Context Protcol servers is subject to the terms between you and the service provider. When you connect to a non-Microsoft service, some of your data (such as prompt content) is passed to the non-Microsoft service, or your application might receive data from the non-Microsoft service. You're responsible for your use of non-Microsoft services and data, along with any charges associated with that use.
+
+Your use of Model Context Protocol servers is subject to the terms between you and the service provider. When you connect to a non-Microsoft service, some of your data (such as prompt content) is passed to the non-Microsoft service, or your application might receive data from the non-Microsoft service. You're responsible for your use of non-Microsoft services and data, along with any charges associated with that use.
 
 The remote MCP servers that you decide to use with the MCP tool described in this article were created by third parties, not Microsoft. Microsoft hasn't tested or verified these servers. Microsoft has no responsibility to you or others in relation to your use of any remote MCP servers.
 
@@ -25,6 +26,7 @@ We recommend that you carefully review and track what MCP servers you add to you
 The MCP tool allows you to pass custom headers, such as authentication keys or schemas, that a remote MCP server might need. We recommend that you review all data that's shared with remote MCP servers and that you log the data for auditing purposes. Be cognizant of non-Microsoft practices for retention and location of data.
 
 ## How it works
+
 You can integrate multiple remote MCP servers by adding them as tools to your agent. Agent Framework makes it easy to convert an MCP tool to an AI tool that can be called by your agent.
 
 The MCP tool supports custom headers, so you can connect to MCP servers by using the authentication schemas that they require or by passing other headers that the MCP servers require. **TODO You can specify headers only by including them in tool_resources at each run. In this way, you can put API keys, OAuth access tokens, or other credentials directly in your request. TODO**
@@ -41,4 +43,3 @@ For more information on using MCP, see:
 > [!div class="nextstepaction"]
 > [Using MCP tools with Agents](./using-mcp-tools.md)
 > [Using MCP tools with Foundry Agents](./using-mcp-with-foundry-agents.md)
-

agent-framework/user-guide/model-context-protocol/using-mcp-tools.md

@@ -11,11 +11,11 @@ ms.service: agent-framework
 
 # Using MCP tools with Agents
 
-The Microsoft Agent Framework supports integration with Model Context Protocol (MCP) servers, allowing your agents to access external tools and services. This guide shows how to connect to an MCP server and use its tools within your agent.
+Microsoft Agent Framework supports integration with Model Context Protocol (MCP) servers, allowing your agents to access external tools and services. This guide shows how to connect to an MCP server and use its tools within your agent.
 
 ::: zone pivot="programming-language-csharp"
 
-The .Net version of Agent Framework can be used together with the [official MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) to allow your agent to call MCP tools.
+The .NET version of Agent Framework can be used together with the [official MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) to allow your agent to call MCP tools.
 
 The following sample shows how to:
 
@@ -55,7 +55,7 @@ var mcpTools = await mcpClient.ListToolsAsync().ConfigureAwait(false);
 
 The `ListToolsAsync()` method returns a collection of tools that the MCP server exposes. These tools are automatically converted to AITool objects that can be used by your agent.
 
-### Creating an Agent with MCP Tools
+### Create an Agent with MCP Tools
 
 Create your agent and provide the MCP tools during initialization:
 
@@ -65,7 +65,7 @@ AIAgent agent = new AzureOpenAIClient(
     new AzureCliCredential())
      .GetChatClient(deploymentName)
      .CreateAIAgent(
-         instructions: "You answer questions related to GitHub repositories only.", 
+         instructions: "You answer questions related to GitHub repositories only.",
          tools: [.. mcpTools.Cast<AITool>()]);
 
 ```
@@ -97,7 +97,7 @@ The agent will:
 Make sure to set up the required environment variables:
 
 ```csharp
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? 
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ??
     throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 ```
@@ -123,8 +123,7 @@ Popular MCP servers include:
 Each server provides different tools and capabilities that extend your agent's functionality.
 This integration allows your agents to seamlessly access external data and services while maintaining the security and standardization benefits of the Model Context Protocol.
 
-
-The full source code and instructions to run this sample is available [here](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server).
+The full source code and instructions to run this sample is available at <https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server>.
 
 ::: zone-end
 ::: zone pivot="programming-language-python"
@@ -148,8 +147,8 @@ async def local_mcp_example():
     """Example using a local MCP server via stdio."""
     async with (
         MCPStdioTool(
-            name="calculator", 
-            command="uvx", 
+            name="calculator",
+            command="uvx",
             args=["mcp-server-calculator"]
         ) as mcp_server,
         ChatAgent(
@@ -159,7 +158,7 @@ async def local_mcp_example():
         ) as agent,
     ):
         result = await agent.run(
-            "What is 15 * 23 + 45?", 
+            "What is 15 * 23 + 45?",
             tools=mcp_server
         )
         print(result)
@@ -240,7 +239,7 @@ if __name__ == "__main__":
 Common MCP servers you can use with Python Agent Framework:
 
 - **Calculator**: `uvx mcp-server-calculator` - Mathematical computations
-- **Filesystem**: `uvx mcp-server-filesystem` - File system operations  
+- **Filesystem**: `uvx mcp-server-filesystem` - File system operations
 - **GitHub**: `npx @modelcontextprotocol/server-github` - GitHub repository access
 - **SQLite**: `uvx mcp-server-sqlite` - Database operations
 

agent-framework/user-guide/observability.md

@@ -13,7 +13,7 @@ ms.service: agent-framework
 
 Observability is a key aspect of building reliable and maintainable systems. Agent Framework provides built-in support for observability, allowing you to monitor the behavior of your agents.
 
-This guide will walk you through the steps to enable observability with Agent Framework to help you understand how your agents are performing and diagnose any issues that may arise.
+This guide will walk you through the steps to enable observability with Agent Framework to help you understand how your agents are performing and diagnose any issues that might arise.
 
 ## OpenTelemetry Integration
 
@@ -47,10 +47,10 @@ var agent = new ChatClientAgent(
 ```
 
 > [!IMPORTANT]
-> When you enable observability for your chat clients and agents, you may see duplicated information, especially when sensitive data is enabled. The chat context (including prompts and responses) that is captured by both the chat client and the agent will be included in both spans. Depending on your needs, you may choose to enable observability only on the chat client or only on the agent to avoid duplication. See the [GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for more details on the attributes captured for LLM and Agents.
+> When you enable observability for your chat clients and agents, you might see duplicated information, especially when sensitive data is enabled. The chat context (including prompts and responses) that is captured by both the chat client and the agent will be included in both spans. Depending on your needs, you might choose to enable observability only on the chat client or only on the agent to avoid duplication. See the [GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for more details on the attributes captured for LLM and Agents.
 
 > [!NOTE]
-> Only enable sensitive data in development or testing environments, as it may expose user information in production logs and traces. Sensitive data includes prompts, responses, function call arguments, and results.
+> Only enable sensitive data in development or testing environments, as it might expose user information in production logs and traces. Sensitive data includes prompts, responses, function call arguments, and results.
 
 ### Configuration
 
@@ -79,14 +79,14 @@ var resourceBuilder = ResourceBuilder
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .SetResourceBuilder(resourceBuilder)
     .AddSource(SourceName)
-    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry
-    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry
+    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry.
+    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry.
     .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
     .Build();
 ```
 
 > [!TIP]
-> Depending on your backend, you can use different exporters, see the [OpenTelemetry .NET documentation](https://opentelemetry.io/docs/instrumentation/net/exporters/) for more information. For local development, consider using the [Aspire Dashboard](#aspire-dashboard).
+> Depending on your backend, you can use different exporters. For more information, see the [OpenTelemetry .NET documentation](https://opentelemetry.io/docs/instrumentation/net/exporters/). For local development, consider using the [Aspire Dashboard](#aspire-dashboard).
 
 #### Metrics
 
@@ -151,8 +151,8 @@ Consider using the Aspire Dashboard as a quick way to visualize your traces and
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .SetResourceBuilder(resourceBuilder)
     .AddSource(SourceName)
-    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry
-    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry
+    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry.
+    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry.
     .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
     .Build();
 ```
@@ -307,7 +307,7 @@ These are wrappers of the OpenTelemetry API that return a tracer or meter from t
 The following environment variables control Agent Framework observability:
 
 - `ENABLE_INSTRUMENTATION` - Default is `false`, set to `true` to enable OpenTelemetry instrumentation.
-- `ENABLE_SENSITIVE_DATA` - Default is `false`, set to `true` to enable logging of sensitive data (prompts, responses, function call arguments and results). Be careful with this setting as it may expose sensitive data.
+- `ENABLE_SENSITIVE_DATA` - Default is `false`, set to `true` to enable logging of sensitive data (prompts, responses, function call arguments, and results). Be careful with this setting as it might expose sensitive data.
 - `ENABLE_CONSOLE_EXPORTERS` - Default is `false`, set to `true` to enable console output for telemetry.
 - `VS_CODE_EXTENSION_PORT` - Port for AI Toolkit or Azure AI Foundry VS Code extension integration.
 
@@ -396,7 +396,7 @@ agent = ChatAgent(
 
 ### Aspire Dashboard
 
-For local development without Azure setup, you can use the [Aspire Dashboard](/dotnet/aspire/fundamentals/dashboard/standalone) which runs locally via Docker and provides an excellent telemetry viewing experience.
+For local development without Azure setup, you can use the [Aspire Dashboard](/dotnet/aspire/fundamentals/dashboard/standalone), which runs locally via Docker and provides an excellent telemetry viewing experience.
 
 #### Setting up Aspire Dashboard with Docker
 
@@ -409,7 +409,8 @@ docker run --rm -it -d \
     mcr.microsoft.com/dotnet/aspire-dashboard:latest
 ```
 
-This will start the dashboard with:
+This command will start the dashboard with:
+
 - **Web UI**: Available at <http://localhost:18888>
 - **OTLP endpoint**: Available at `http://localhost:4317` for your applications to send telemetry data
 
@@ -437,11 +438,11 @@ Once everything is setup, you will start seeing spans and metrics being created
 The metrics that are created are:
 
 - For the chat client and `chat` operations:
-    - `gen_ai.client.operation.duration` (histogram): This metric measures the duration of each operation, in seconds.
-    - `gen_ai.client.token.usage` (histogram): This metric measures the token usage, in number of tokens.
+  - `gen_ai.client.operation.duration` (histogram): This metric measures the duration of each operation, in seconds.
+  - `gen_ai.client.token.usage` (histogram): This metric measures the token usage, in number of tokens.
 
 - For function invocation during the `execute_tool` operations:
-    - `agent_framework.function.invocation.duration` (histogram): This metric measures the duration of each function execution, in seconds.
+  - `agent_framework.function.invocation.duration` (histogram): This metric measures the duration of each function execution, in seconds.
 
 ### Example trace output
 
@@ -485,6 +486,6 @@ This trace shows:
 
 ## Samples
 
-We have a number of samples in our repository that demonstrate these capabilities, see the [observability samples folder](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/observability) on Github. That includes samples for using zero-code telemetry as well.
+There are a number of samples in the `microsoft/agent-framework` repository that demonstrate these capabilities. For more information, see the [observability samples folder](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/observability). That folder includes samples for using zero-code telemetry as well.
 
 ::: zone-end

agent-framework/user-guide/overview.md

@@ -10,4 +10,4 @@ ms.service: agent-framework
 
 # Agent Framework User Guide
 
-Welcome to the Agent Framework User Guide. This guide provides comprehensive information for developers and solution architects working with the Agent Framework. Here, you'll find detailed explanations of agent concepts, configuration options, advanced features, and best practices for building robust, scalable agent-based applications. Whether you're just getting started or looking to deepen your expertise, this guide will help you understand how to leverage the full capabilities of the Agent Framework in your projects.
+Welcome to the Agent Framework User Guide. This guide provides comprehensive information for developers and solution architects working with Agent Framework. Here, you'll find detailed explanations of agent concepts, configuration options, advanced features, and best practices for building robust, scalable agent-based applications. Whether you're just getting started or looking to deepen your expertise, this guide will help you understand how to leverage the full capabilities of Agent Framework in your projects.

agent-framework/user-guide/workflows/as-agents.md

@@ -11,7 +11,7 @@ ms.service: agent-framework
 
 # Microsoft Agent Framework Workflows - Using Workflows as Agents
 
-This document provides an overview of how to use **Workflows as Agents** in the Microsoft Agent Framework.
+This document provides an overview of how to use **Workflows as Agents** in Microsoft Agent Framework.
 
 ## Overview
 
@@ -41,7 +41,7 @@ When you convert a workflow to an agent:
 
 To use a workflow as an agent, the workflow's start executor must be able to handle `IEnumerable<ChatMessage>` as input. This is automatically satisfied when using `ChatClientAgent` or other agent-based executors.
 
-## Creating a Workflow Agent
+## Create a Workflow Agent
 
 Use the `AsAgent()` extension method to convert any compatible workflow into an agent:
 

agent-framework/user-guide/workflows/core-concepts/events.md

@@ -11,7 +11,7 @@ ms.service: agent-framework
 
 # Microsoft Agent Framework Workflows Core Concepts - Events
 
-This document provides an in-depth look at the **Events** system of Workflows in the Microsoft Agent Framework.
+This document provides an in-depth look at the **Events** system of Workflows in Microsoft Agent Framework.
 
 ## Overview
 

agent-framework/user-guide/workflows/observability.md

@@ -14,9 +14,9 @@ ms.service: agent-framework
 Observability provides insights into the internal state and behavior of workflows during execution. This includes logging, metrics, and tracing capabilities that help monitor and debug workflows.
 
 > [!TIP]
-> Observability is a framework-wide feature and is not limited to workflows. For more information, refer to [Observability](../observability.md).
+> Observability is a framework-wide feature and is not limited to workflows. For more information, see [Observability](../observability.md).
 
-Aside from the standard [GenAI telemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/), Agent Framework Workflows emits additional spans, logs, and metrics to provide deeper insights into workflow execution. These observability features help developers understand the flow of messages, the performance of executors, and any errors that may occur.
+Aside from the standard [GenAI telemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/), Agent Framework Workflows emits additional spans, logs, and metrics to provide deeper insights into workflow execution. These observability features help developers understand the flow of messages, the performance of executors, and any errors that might occur.
 
 ## Enable Observability
 
@@ -34,13 +34,13 @@ Please refer to [Enabling Observability](../observability.md#enable-observabilit
 
 ## Workflow Spans
 
-| Span Name                        | Description                                      |
-|----------------------------------|--------------------------------------------------|
-| `workflow.build`                 | For each workflow build                          |
-| `workflow.run`                   | For each workflow execution                      |
-| `message.send`                   | For each message sent to an executor             |
-| `executor.process`               | For each executor processing a message           |
-| `edge_group.process`             | For each edge group processing a message         |
+| Span Name            | Description                              |
+|----------------------|------------------------------------------|
+| `workflow.build`     | For each workflow build                  |
+| `workflow.run`       | For each workflow execution              |
+| `message.send`       | For each message sent to an executor     |
+| `executor.process`   | For each executor processing a message   |
+| `edge_group.process` | For each edge group processing a message |
 
 ### Links between Spans