Merge pull request #669 from MicrosoftDocs/main

9/26 Publish

Author: huypub

agent-framework/docfx.json

@@ -45,7 +45,7 @@
       "zone_pivot_group_filename:": "zone_pivot_group.json",
       "uhfHeaderId": "MSDocsHeader-AgentFramework",
       "layout": "Conceptual",
-      "breadcrumb_path": "/breadcrumb/agent-framework/toc.yml",
+      "breadcrumb_path": "/agent-framework/breadcrumb/agent-framework/toc.json",
       "feedback_system": "Standard",
       "permissioned-type": "public"
     },

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

@@ -47,7 +47,7 @@ RequestInfoEvent        // A request is issued
 ```python
 # Workflow lifecycle events
 WorkflowStartedEvent    # Workflow execution begins
-WorkflowCompletedEvent  # Workflow reaches completion
+WorkflowOutputEvent     # Workflow produces an output
 WorkflowErrorEvent      # Workflow encounters an error
 
 # Executor events
@@ -98,7 +98,7 @@ await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 from agent_framework import (
     ExecutorCompleteEvent,
     ExecutorInvokeEvent,
-    WorkflowCompletedEvent,
+    WorkflowOutputEvent,
     WorkflowErrorEvent,
 )
 
@@ -108,8 +108,8 @@ async for event in workflow.run_stream(input_message):
             print(f"Starting {invoke.executor_id}")
         case ExecutorCompleteEvent() as complete:
             print(f"Completed {complete.executor_id}: {complete.data}")
-        case WorkflowCompletedEvent() as finished:
-            print(f"Workflow finished: {finished.data}")
+        case WorkflowOutputEvent() as output:
+            print(f"Workflow produced output: {output.data}")
             return
         case WorkflowErrorEvent() as error:
             print(f"Workflow error: {error.exception}")

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

@@ -147,6 +147,46 @@ class SampleExecutor(Executor):
         await ctx.send_message(number * 2)
 ```
 
+### The `WorkflowContext` Object
+
+The `WorkflowContext` object provides methods for the handler to interact with the workflow during execution. The `WorkflowContext` is parameterized with the type of messages the handler will emit and the type of outputs it can yield.
+
+The most commonly used method is `send_message`, which allows the handler to send messages to connected executors.
+
+```python
+from agent_framework import WorkflowContext
+
+class SomeHandler(Executor):
+
+    @handler
+    async def some_handler(message: str, ctx: WorkflowContext[str]) -> None:
+        await ctx.send_message("Hello, World!")
+```
+
+A handler can use `yield_output` to produce outputs that will be considered as workflow outputs and be returned/streamed to the caller as an output event:
+
+```python
+from agent_framework import WorkflowContext
+
+class SomeHandler(Executor):
+
+    @handler
+    async def some_handler(message: str, ctx: WorkflowContext[Never, str]) -> None:
+        await ctx.yield_output("Hello, World!")
+```
+
+If a handler neither sends messages nor yields outputs, no type parameter is needed for `WorkflowContext`:
+
+```python
+from agent_framework import WorkflowContext
+
+class SomeHandler(Executor):
+
+    @handler
+    async def some_handler(message: str, ctx: WorkflowContext) -> None:
+        print("Doing some work...")
+```
+
 ::: zone-end
 
 ## Next Step

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

@@ -11,6 +11,10 @@ ms.service: semantic-kernel
 
 # Microsoft Agent Framework Workflows - Observability
 
+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.
+
+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.
+
 ::: zone pivot="programming-language-csharp"
 
 Coming soon...
@@ -19,6 +23,46 @@ Coming soon...
 
 ::: zone pivot="programming-language-python"
 
-Coming soon...
+## Enable Observability
+
+Observability is enabled framework-wide by setting the `ENABLE_OTEL=true` environment variable or calling `setup_observability()` at the beginning of your application.
+
+```env
+# This is not required if you run `setup_observability()` in your code
+ENABLE_OTEL=true
+# Sensitive data (e.g., message content) will be included in logs and traces if this is set to true
+ENABLE_SENSITIVE_DATA=true
+```
+
+```python
+from agent_framework.observability import setup_observability
+
+setup_observability(enable_sensitive_data=True)
+```
+
+## 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         |
+
+### Links between Spans
+
+When an executor sends a message to another executor, the `message.send` span is created as a child of the `executor.process` span. However, the `executor.process` span of the target executor will not be a child of the `message.send` span because the execution is not nested. Instead, the `executor.process` span of the target executor is linked to the `message.send` span of the source executor. This creates a traceable path through the workflow execution.
+
+For example:
+
+![Span Relationships](./resources/images/workflow-trace.png)
 
 ::: zone-end
+
+## Next Steps
+
+- [Learn how to use agents in workflows](./using-agents.md) to build intelligent workflows.
+- [Learn how to handle requests and responses](./request-and-response.md) in workflows.
+- [Learn how to manage state](./shared-states.md) in workflows.
+- [Learn how to create checkpoints and resume from them](./checkpoints.md).