diff --git a/README.md b/README.md index e86cf94e60..5dc11508e7 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu ### ✨ **Highlights** - **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities - - [Python workflows](./python/samples/getting_started/workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/) + - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/) - **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives - [Labs directory](./python/packages/lab/) - **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows @@ -73,11 +73,11 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu - **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs - [Python packages](./python/packages/) | [.NET source](./dotnet/src/) - **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging - - [Python observability](./python/samples/getting_started/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/) + - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/) - **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously - - [Python examples](./python/samples/getting_started/agents/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/) + - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/) - **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines - - [Python middleware](./python/samples/getting_started/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/) + - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/) ### πŸ’¬ **We want your feedback!** @@ -159,9 +159,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram ### Python -- [Getting Started with Agents](./python/samples/getting_started/agents): basic agent creation and tool usage -- [Chat Client Examples](./python/samples/getting_started/chat_client): direct chat client usage patterns -- [Getting Started with Workflows](./python/samples/getting_started/workflows): basic workflow creation and integration with agents +- [Getting Started with Agents](./python/samples/01-get-started): progressive tutorial from hello-world to hosting +- [Agent Concepts](./python/samples/02-agents): deep-dive samples by topic (tools, middleware, providers, etc.) +- [Getting Started with Workflows](./python/samples/03-workflows): workflow creation and integration with agents ### .NET diff --git a/agent-samples/README.md b/agent-samples/README.md index ea5c8b0aeb..953affeb08 100644 --- a/agent-samples/README.md +++ b/agent-samples/README.md @@ -1,3 +1,3 @@ # Declarative Agents -This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/getting_started/declarative/). +This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/02-agents/declarative/). diff --git a/docs/decisions/0012-python-typeddict-options.md b/docs/decisions/0012-python-typeddict-options.md index 23864c2459..5e754dc3dc 100644 --- a/docs/decisions/0012-python-typeddict-options.md +++ b/docs/decisions/0012-python-typeddict-options.md @@ -126,4 +126,4 @@ response = await client.get_response( Chosen option: **"Option 2: TypedDict with Generic Type Parameters"**, because it provides full type safety, excellent IDE support with autocompletion, and allows users to extend provider-specific options for their use cases. Extended this Generic to ChatAgents in order to also properly type the options used in agent construction and run methods. -See [typed_options.py](../../python/samples/concepts/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions. +See [typed_options.py](../../python/samples/02-agents/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions. diff --git a/dotnet/Directory.Packages.props b/dotnet/Directory.Packages.props index d0227c1dbe..de0efb2eb5 100644 --- a/dotnet/Directory.Packages.props +++ b/dotnet/Directory.Packages.props @@ -89,7 +89,7 @@ - + diff --git a/dotnet/nuget/nuget-package.props b/dotnet/nuget/nuget-package.props index 7399e723a7..c87a80361b 100644 --- a/dotnet/nuget/nuget-package.props +++ b/dotnet/nuget/nuget-package.props @@ -2,9 +2,9 @@ 1.0.0 - $(VersionPrefix)-$(VersionSuffix).260209.1 - $(VersionPrefix)-preview.260209.1 - 1.0.0-preview.260209.1 + $(VersionPrefix)-$(VersionSuffix).260212.1 + $(VersionPrefix)-preview.260212.1 + 1.0.0-preview.260212.1 Debug;Release;Publish true diff --git a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs index 0754f52710..f0533c8461 100644 --- a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs +++ b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/GitHubCopilotAgent.cs @@ -147,21 +147,7 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable // Create or resume a session with streaming enabled SessionConfig sessionConfig = this._sessionConfig != null - ? new SessionConfig - { - Model = this._sessionConfig.Model, - Tools = this._sessionConfig.Tools, - SystemMessage = this._sessionConfig.SystemMessage, - AvailableTools = this._sessionConfig.AvailableTools, - ExcludedTools = this._sessionConfig.ExcludedTools, - Provider = this._sessionConfig.Provider, - OnPermissionRequest = this._sessionConfig.OnPermissionRequest, - McpServers = this._sessionConfig.McpServers, - CustomAgents = this._sessionConfig.CustomAgents, - SkillDirectories = this._sessionConfig.SkillDirectories, - DisabledSkills = this._sessionConfig.DisabledSkills, - Streaming = true - } + ? CopySessionConfig(this._sessionConfig) : new SessionConfig { Streaming = true }; CopilotSession copilotSession; @@ -283,16 +269,64 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable } private ResumeSessionConfig CreateResumeConfig() + { + return CopyResumeSessionConfig(this._sessionConfig); + } + + /// + /// Copies all supported properties from a source into a new instance + /// with set to true. + /// + internal static SessionConfig CopySessionConfig(SessionConfig source) + { + return new SessionConfig + { + Model = source.Model, + ReasoningEffort = source.ReasoningEffort, + Tools = source.Tools, + SystemMessage = source.SystemMessage, + AvailableTools = source.AvailableTools, + ExcludedTools = source.ExcludedTools, + Provider = source.Provider, + OnPermissionRequest = source.OnPermissionRequest, + OnUserInputRequest = source.OnUserInputRequest, + Hooks = source.Hooks, + WorkingDirectory = source.WorkingDirectory, + ConfigDir = source.ConfigDir, + McpServers = source.McpServers, + CustomAgents = source.CustomAgents, + SkillDirectories = source.SkillDirectories, + DisabledSkills = source.DisabledSkills, + InfiniteSessions = source.InfiniteSessions, + Streaming = true + }; + } + + /// + /// Copies all supported properties from a source into a new + /// with set to true. + /// + internal static ResumeSessionConfig CopyResumeSessionConfig(SessionConfig? source) { return new ResumeSessionConfig { - Tools = this._sessionConfig?.Tools, - Provider = this._sessionConfig?.Provider, - OnPermissionRequest = this._sessionConfig?.OnPermissionRequest, - McpServers = this._sessionConfig?.McpServers, - CustomAgents = this._sessionConfig?.CustomAgents, - SkillDirectories = this._sessionConfig?.SkillDirectories, - DisabledSkills = this._sessionConfig?.DisabledSkills, + Model = source?.Model, + ReasoningEffort = source?.ReasoningEffort, + Tools = source?.Tools, + SystemMessage = source?.SystemMessage, + AvailableTools = source?.AvailableTools, + ExcludedTools = source?.ExcludedTools, + Provider = source?.Provider, + OnPermissionRequest = source?.OnPermissionRequest, + OnUserInputRequest = source?.OnUserInputRequest, + Hooks = source?.Hooks, + WorkingDirectory = source?.WorkingDirectory, + ConfigDir = source?.ConfigDir, + McpServers = source?.McpServers, + CustomAgents = source?.CustomAgents, + SkillDirectories = source?.SkillDirectories, + DisabledSkills = source?.DisabledSkills, + InfiniteSessions = source?.InfiniteSessions, Streaming = true }; } @@ -427,9 +461,8 @@ public sealed class GitHubCopilotAgent : AIAgent, IAsyncDisposable string tempFilePath = await dataContent.SaveToAsync(tempDir, cancellationToken).ConfigureAwait(false); attachments ??= []; - attachments.Add(new UserMessageDataAttachmentsItem + attachments.Add(new UserMessageDataAttachmentsItemFile { - Type = UserMessageDataAttachmentsItemType.File, Path = tempFilePath, DisplayName = Path.GetFileName(tempFilePath) }); diff --git a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj index f4f79c27bd..4c436263c1 100644 --- a/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj +++ b/dotnet/src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj @@ -17,6 +17,10 @@ + + + + diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.cs b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.cs index ba15f9d0c7..de779128f5 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.cs +++ b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.cs @@ -65,7 +65,7 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen this._values = [evaluatedValue]; } - await this.ResetAsync(context, null, cancellationToken).ConfigureAwait(false); + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); return default; } @@ -84,9 +84,19 @@ namespace Microsoft.Agents.AI.Workflows.Declarative.CodeGen AssignVariable(this.Index, "this._index", tightFormat: true); } - this.Write("\n\n this._index++;\n }\n }\n\n public async ValueTask ResetAsy" + - "nc(IWorkflowContext context, object? _, CancellationToken cancellationToken)\n " + - " {"); + this.Write(@" + + this._index++; + } + } + + public async ValueTask CompleteAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + { + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); + } + + private async ValueTask ResetAsync(IWorkflowContext context, CancellationToken cancellationToken) + {"); AssignVariable(this.Value, "UnassignedValue.Instance", tightFormat: true); diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.tt b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.tt index 77f13c5184..8a9c8d5910 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.tt +++ b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/CodeGen/ForeachTemplate.tt @@ -36,7 +36,7 @@ internal sealed class <#= this.Name #>Executor(FormulaSession session) : ActionE this._values = [evaluatedValue]; } - await this.ResetAsync(context, null, cancellationToken).ConfigureAwait(false); + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); return default; } @@ -59,7 +59,12 @@ internal sealed class <#= this.Name #>Executor(FormulaSession session) : ActionE } } - public async ValueTask ResetAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + public async ValueTask CompleteAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + { + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); + } + + private async ValueTask ResetAsync(IWorkflowContext context, CancellationToken cancellationToken) {<# AssignVariable(this.Value, "UnassignedValue.Instance", tightFormat: true); diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs index a90b1bd9c9..3ecb91ea3a 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs +++ b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs @@ -201,7 +201,7 @@ internal sealed class WorkflowActionVisitor : DialogActionVisitor { // Transition to end of inner actions string endActionsId = ForeachExecutor.Steps.End(action.Id); - this.ContinueWith(new DelegateActionExecutor(endActionsId, this._workflowState, action.ResetAsync), action.Id); + this.ContinueWith(new DelegateActionExecutor(endActionsId, this._workflowState, action.CompleteAsync), action.Id); // Transition to select the next item this._workflowModel.AddLink(endActionsId, loopId); } diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowTemplateVisitor.cs b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowTemplateVisitor.cs index 065f04aaac..56901762f4 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowTemplateVisitor.cs +++ b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowTemplateVisitor.cs @@ -163,7 +163,7 @@ internal sealed class WorkflowTemplateVisitor : DialogActionVisitor { // Transition to end of inner actions string endActionsId = ForeachExecutor.Steps.End(action.Id); // Loop continuation - this.ContinueWith(new EmptyTemplate(endActionsId, this._rootId, $"{action.Id.FormatName()}.{nameof(ForeachExecutor.ResetAsync)}"), action.Id); + this.ContinueWith(new EmptyTemplate(endActionsId, this._rootId, $"{action.Id.FormatName()}.{nameof(ForeachExecutor.CompleteAsync)}"), action.Id); // Transition to select the next item this._workflowModel.AddLink(endActionsId, loopId); } diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutor.cs b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutor.cs index 2b4c21c86b..258f3c413b 100644 --- a/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutor.cs +++ b/dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutor.cs @@ -37,27 +37,21 @@ internal sealed class ForeachExecutor : DeclarativeActionExecutor protected override async ValueTask ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default) { + Throw.IfNull(this.Model.Items, $"{nameof(this.Model)}.{nameof(this.Model.Items)}"); + this._index = 0; - if (this.Model.Items is null) + EvaluationResult expressionResult = this.Evaluator.GetValue(this.Model.Items); + if (expressionResult.Value is TableDataValue tableValue) { - this._values = []; - this.HasValue = false; + this._values = [.. tableValue.Values.Select(value => value.Properties.Values.First().ToFormula())]; } else { - EvaluationResult expressionResult = this.Evaluator.GetValue(this.Model.Items); - if (expressionResult.Value is TableDataValue tableValue) - { - this._values = [.. tableValue.Values.Select(value => value.Properties.Values.First().ToFormula())]; - } - else - { - this._values = [expressionResult.Value.ToFormula()]; - } + this._values = [expressionResult.Value.ToFormula()]; } - await this.ResetAsync(context, null, cancellationToken).ConfigureAwait(false); + await this.ResetStateAsync(context, cancellationToken).ConfigureAwait(false); return default; } @@ -79,19 +73,24 @@ internal sealed class ForeachExecutor : DeclarativeActionExecutor } } - public async ValueTask ResetAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + public async ValueTask CompleteAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) { try { - await context.QueueStateResetAsync(Throw.IfNull(this.Model.Value), cancellationToken).ConfigureAwait(false); - if (this.Model.Index is not null) - { - await context.QueueStateResetAsync(this.Model.Index, cancellationToken).ConfigureAwait(false); - } + await this.ResetStateAsync(context, cancellationToken).ConfigureAwait(false); } finally { await context.RaiseCompletionEventAsync(this.Model, cancellationToken).ConfigureAwait(false); } } + + private async Task ResetStateAsync(IWorkflowContext context, CancellationToken cancellationToken) + { + await context.QueueStateResetAsync(Throw.IfNull(this.Model.Value), cancellationToken).ConfigureAwait(false); + if (this.Model.Index is not null) + { + await context.QueueStateResetAsync(this.Model.Index, cancellationToken).ConfigureAwait(false); + } + } } diff --git a/dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/GitHubCopilotAgentTests.cs b/dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/GitHubCopilotAgentTests.cs index e80990de1b..8a4d3c1068 100644 --- a/dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/GitHubCopilotAgentTests.cs +++ b/dotnet/tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/GitHubCopilotAgentTests.cs @@ -100,4 +100,125 @@ public sealed class GitHubCopilotAgentTests Assert.NotNull(agent); Assert.NotNull(agent.Id); } + + [Fact] + public void CopySessionConfig_CopiesAllProperties() + { + // Arrange + List tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")]; + var hooks = new SessionHooks(); + var infiniteSessions = new InfiniteSessionConfig(); + var systemMessage = new SystemMessageConfig { Mode = SystemMessageMode.Append, Content = "Be helpful" }; + PermissionHandler permissionHandler = (_, _) => Task.FromResult(new PermissionRequestResult()); + UserInputHandler userInputHandler = (_, _) => Task.FromResult(new UserInputResponse { Answer = "input" }); + var mcpServers = new Dictionary { ["server1"] = new McpLocalServerConfig() }; + + var source = new SessionConfig + { + Model = "gpt-4o", + ReasoningEffort = "high", + Tools = tools, + SystemMessage = systemMessage, + AvailableTools = ["tool1", "tool2"], + ExcludedTools = ["tool3"], + WorkingDirectory = "/workspace", + ConfigDir = "/config", + Hooks = hooks, + InfiniteSessions = infiniteSessions, + OnPermissionRequest = permissionHandler, + OnUserInputRequest = userInputHandler, + McpServers = mcpServers, + DisabledSkills = ["skill1"], + }; + + // Act + SessionConfig result = GitHubCopilotAgent.CopySessionConfig(source); + + // Assert + Assert.Equal("gpt-4o", result.Model); + Assert.Equal("high", result.ReasoningEffort); + Assert.Same(tools, result.Tools); + Assert.Same(systemMessage, result.SystemMessage); + Assert.Equal(new List { "tool1", "tool2" }, result.AvailableTools); + Assert.Equal(new List { "tool3" }, result.ExcludedTools); + Assert.Equal("/workspace", result.WorkingDirectory); + Assert.Equal("/config", result.ConfigDir); + Assert.Same(hooks, result.Hooks); + Assert.Same(infiniteSessions, result.InfiniteSessions); + Assert.Same(permissionHandler, result.OnPermissionRequest); + Assert.Same(userInputHandler, result.OnUserInputRequest); + Assert.Same(mcpServers, result.McpServers); + Assert.Equal(new List { "skill1" }, result.DisabledSkills); + Assert.True(result.Streaming); + } + + [Fact] + public void CopyResumeSessionConfig_CopiesAllProperties() + { + // Arrange + List tools = [AIFunctionFactory.Create(() => "test", "TestFunc", "Test function")]; + var hooks = new SessionHooks(); + var infiniteSessions = new InfiniteSessionConfig(); + var systemMessage = new SystemMessageConfig { Mode = SystemMessageMode.Append, Content = "Be helpful" }; + PermissionHandler permissionHandler = (_, _) => Task.FromResult(new PermissionRequestResult()); + UserInputHandler userInputHandler = (_, _) => Task.FromResult(new UserInputResponse { Answer = "input" }); + var mcpServers = new Dictionary { ["server1"] = new McpLocalServerConfig() }; + + var source = new SessionConfig + { + Model = "gpt-4o", + ReasoningEffort = "high", + Tools = tools, + SystemMessage = systemMessage, + AvailableTools = ["tool1", "tool2"], + ExcludedTools = ["tool3"], + WorkingDirectory = "/workspace", + ConfigDir = "/config", + Hooks = hooks, + InfiniteSessions = infiniteSessions, + OnPermissionRequest = permissionHandler, + OnUserInputRequest = userInputHandler, + McpServers = mcpServers, + DisabledSkills = ["skill1"], + }; + + // Act + ResumeSessionConfig result = GitHubCopilotAgent.CopyResumeSessionConfig(source); + + // Assert + Assert.Equal("gpt-4o", result.Model); + Assert.Equal("high", result.ReasoningEffort); + Assert.Same(tools, result.Tools); + Assert.Same(systemMessage, result.SystemMessage); + Assert.Equal(new List { "tool1", "tool2" }, result.AvailableTools); + Assert.Equal(new List { "tool3" }, result.ExcludedTools); + Assert.Equal("/workspace", result.WorkingDirectory); + Assert.Equal("/config", result.ConfigDir); + Assert.Same(hooks, result.Hooks); + Assert.Same(infiniteSessions, result.InfiniteSessions); + Assert.Same(permissionHandler, result.OnPermissionRequest); + Assert.Same(userInputHandler, result.OnUserInputRequest); + Assert.Same(mcpServers, result.McpServers); + Assert.Equal(new List { "skill1" }, result.DisabledSkills); + Assert.True(result.Streaming); + } + + [Fact] + public void CopyResumeSessionConfig_WithNullSource_ReturnsDefaults() + { + // Act + ResumeSessionConfig result = GitHubCopilotAgent.CopyResumeSessionConfig(null); + + // Assert + Assert.Null(result.Model); + Assert.Null(result.ReasoningEffort); + Assert.Null(result.Tools); + Assert.Null(result.SystemMessage); + Assert.Null(result.OnPermissionRequest); + Assert.Null(result.OnUserInputRequest); + Assert.Null(result.Hooks); + Assert.Null(result.WorkingDirectory); + Assert.Null(result.ConfigDir); + Assert.True(result.Streaming); + } } diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/CodeGen/ForeachTemplateTest.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/CodeGen/ForeachTemplateTest.cs index 9db4493c01..aaafa5bfb3 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/CodeGen/ForeachTemplateTest.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/CodeGen/ForeachTemplateTest.cs @@ -54,7 +54,7 @@ public class ForeachTemplateTest(ITestOutputHelper output) : WorkflowActionTempl AssertGeneratedCode(template.Id, workflowCode); AssertAgentProvider(template.UseAgentProvider, workflowCode); AssertGeneratedMethod(nameof(ForeachExecutor.TakeNextAsync), workflowCode); - AssertGeneratedMethod(nameof(ForeachExecutor.ResetAsync), workflowCode); + AssertGeneratedMethod(nameof(ForeachExecutor.CompleteAsync), workflowCode); } private Foreach CreateModel( diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/DeclarativeWorkflowTest.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/DeclarativeWorkflowTest.cs index 9a2a84f7e7..9b3e4bbdaa 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/DeclarativeWorkflowTest.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/DeclarativeWorkflowTest.cs @@ -52,7 +52,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow { await this.RunWorkflowAsync("LoopBreak.yaml"); this.AssertExecutionCount(expectedCount: 6); - this.AssertExecuted("foreach_loop"); + this.AssertExecuted("foreach_loop", isDiscrete: false); this.AssertExecuted("break_loop_now"); this.AssertExecuted("end_all"); this.AssertNotExecuted("set_variable_inner"); @@ -64,7 +64,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow { await this.RunWorkflowAsync("LoopContinue.yaml"); this.AssertExecutionCount(expectedCount: 22); - this.AssertExecuted("foreach_loop"); + this.AssertExecuted("foreach_loop", isDiscrete: false); this.AssertExecuted("continue_loop_now"); this.AssertExecuted("end_all"); this.AssertNotExecuted("set_variable_inner"); @@ -103,7 +103,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow this.AssertExecuted("conditionGroup_test"); if (input % 2 == 0) { - this.AssertExecuted("conditionItem_even", isScope: true); + this.AssertExecuted("conditionItem_even", isAction: false); this.AssertExecuted("sendActivity_even"); this.AssertNotExecuted("conditionItem_odd"); this.AssertNotExecuted("sendActivity_odd"); @@ -111,7 +111,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow } else { - this.AssertExecuted("conditionItem_odd", isScope: true); + this.AssertExecuted("conditionItem_odd", isAction: false); this.AssertExecuted("sendActivity_odd"); this.AssertNotExecuted("conditionItem_even"); this.AssertNotExecuted("sendActivity_even"); @@ -131,13 +131,13 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow this.AssertExecuted("conditionGroup_test"); if (input % 2 == 0) { - this.AssertExecuted("sendActivity_else", isScope: true); + this.AssertExecuted("sendActivity_else", isAction: false); this.AssertNotExecuted("conditionItem_odd"); this.AssertNotExecuted("sendActivity_odd"); } else { - this.AssertExecuted("conditionItem_odd", isScope: true); + this.AssertExecuted("conditionItem_odd", isAction: false); this.AssertExecuted("sendActivity_odd"); this.AssertNotExecuted("sendActivity_else"); } @@ -152,7 +152,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow await this.RunWorkflowAsync("ConditionFallThrough.yaml", input); this.AssertExecutionCount(expectedActions); this.AssertExecuted("setVariable_test"); - this.AssertExecuted("conditionGroup_test", isScope: true); + this.AssertExecuted("conditionGroup_test", isAction: false); if (input % 2 == 0) { this.AssertNotExecuted("conditionItem_odd"); @@ -160,7 +160,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow } else { - this.AssertExecuted("conditionItem_odd", isScope: true); + this.AssertExecuted("conditionItem_odd", isAction: false); this.AssertExecuted("sendActivity_odd"); this.AssertMessage("ODD"); } @@ -307,14 +307,17 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow Assert.DoesNotContain(this.WorkflowEvents.OfType(), e => e.ExecutorId == executorId); } - private void AssertExecuted(string executorId, bool isScope = false) + private void AssertExecuted(string executorId, bool isAction = true, bool isDiscrete = true) { Assert.Contains(this.WorkflowEvents.OfType(), e => e.ExecutorId == executorId); Assert.Contains(this.WorkflowEvents.OfType(), e => e.ExecutorId == executorId); - if (!isScope) + if (isAction) { Assert.Contains(this.WorkflowEvents.OfType(), e => e.ActionId == executorId); - Assert.Contains(this.WorkflowEvents.OfType(), e => e.ActionId == executorId); + if (isDiscrete) + { + Assert.Contains(this.WorkflowEvents.OfType(), e => e.ActionId == executorId); + } } } diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/ForeachExecutorTest.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/ForeachExecutorTest.cs new file mode 100644 index 0000000000..559ca2a33a --- /dev/null +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/ForeachExecutorTest.cs @@ -0,0 +1,320 @@ +ο»Ώ// Copyright (c) Microsoft. All rights reserved. + +using System.Collections.Generic; +using System.Threading.Tasks; +using Microsoft.Agents.AI.Workflows.Declarative.ObjectModel; +using Microsoft.Agents.ObjectModel; +using Microsoft.PowerFx.Types; +using Xunit.Abstractions; + +namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests.ObjectModel; + +/// +/// Tests for . +/// +public sealed class ForeachExecutorTest(ITestOutputHelper output) : WorkflowActionExecutorTest(output) +{ + [Fact] + public void ForeachThrowsWhenModelInvalid() => + // Arrange, Act & Assert + Assert.Throws(() => new ForeachExecutor(new Foreach(), this.State)); + + [Fact] + public void ForeachNamingConvention() + { + // Arrange + string testId = this.CreateActionId().Value; + + // Act + string startStep = ForeachExecutor.Steps.Start(testId); + string nextStep = ForeachExecutor.Steps.Next(testId); + string endStep = ForeachExecutor.Steps.End(testId); + + // Assert + Assert.Equal($"{testId}_{nameof(ForeachExecutor.Steps.Start)}", startStep); + Assert.Equal($"{testId}_{nameof(ForeachExecutor.Steps.Next)}", nextStep); + Assert.Equal($"{testId}_{nameof(ForeachExecutor.Steps.End)}", endStep); + } + + [Fact] + public async Task ForeachInvokedWithSingleValueAsync() + { + // Arrange + this.SetVariableState("CurrentValue"); + + // Act & Assert + await this.ExecuteTestAsync( + displayName: nameof(ForeachInvokedWithSingleValueAsync), + items: ValueExpression.Literal(new NumberDataValue(42)), + valueName: "CurrentValue", + indexName: null); + } + + [Fact] + public async Task ForeachInvokedWithTableValueAsync() + { + // Arrange + this.SetVariableState("CurrentValue"); + + // Act & Assert + await this.ExecuteTestAsync( + displayName: nameof(ForeachInvokedWithTableValueAsync), + items: ValueExpression.Literal(DataValue.EmptyTable), + valueName: "CurrentValue", + indexName: null); + } + + [Fact] + public async Task ForeachInvokedWithIndexAsync() + { + // Arrange + this.SetVariableState("CurrentValue", "CurrentIndex"); + TableDataValue tableValue = DataValue.TableFromRecords( + DataValue.RecordFromFields(new KeyValuePair("item", new NumberDataValue(1))), + DataValue.RecordFromFields(new KeyValuePair("item", new NumberDataValue(2))), + DataValue.RecordFromFields(new KeyValuePair("item", new NumberDataValue(3)))); + + // Act & Assert + await this.ExecuteTestAsync( + displayName: nameof(ForeachInvokedWithIndexAsync), + items: ValueExpression.Literal(tableValue), + valueName: "CurrentValue", + indexName: "CurrentIndex"); + } + + [Fact] + public async Task ForeachInvokedWithExpressionAsync() + { + // Arrange + this.SetVariableState("CurrentValue"); + this.State.Set("SourceArray", FormulaValue.NewTable(RecordType.Empty())); + + // Act & Assert + await this.ExecuteTestAsync( + displayName: nameof(ForeachInvokedWithExpressionAsync), + items: ValueExpression.Variable(PropertyPath.TopicVariable("SourceArray")), + valueName: "CurrentValue", + indexName: null); + } + + [Fact] + public async Task ForeachTakeNextAsync() + { + // Arrange + this.SetVariableState("CurrentValue"); + this.State.Set( + "SourceArray", + FormulaValue.NewTable( + RecordType.Empty(), + FormulaValue.NewRecordFromFields(new NamedValue("value", FormulaValue.New(10))), + FormulaValue.NewRecordFromFields(new NamedValue("value", FormulaValue.New(20))), + FormulaValue.NewRecordFromFields(new NamedValue("value", FormulaValue.New(30))))); + + // Act & Assert + await this.TakeNextTestAsync( + displayName: nameof(ForeachTakeNextAsync), + items: ValueExpression.Variable(PropertyPath.TopicVariable("SourceArray")), + valueName: "CurrentValue", + indexName: null); + } + + [Fact] + public async Task ForeachTakeNextWithIndexAsync() + { + // Arrange + this.SetVariableState("CurrentValue", "CurrentIndex"); + this.State.Set( + "SourceArray", + FormulaValue.NewTable( + RecordType.Empty(), + FormulaValue.NewRecordFromFields(new NamedValue("value", FormulaValue.New(10))), + FormulaValue.NewRecordFromFields(new NamedValue("value", FormulaValue.New(20))), + FormulaValue.NewRecordFromFields(new NamedValue("value", FormulaValue.New(30))))); + + // Act & Assert + await this.TakeNextTestAsync( + displayName: nameof(ForeachTakeNextWithIndexAsync), + items: ValueExpression.Variable(PropertyPath.TopicVariable("SourceArray")), + valueName: "CurrentValue", + indexName: "CurrentIndex"); + } + + [Fact] + public async Task ForeachTakeLastAsync() + { + // Arrange + this.SetVariableState("CurrentValue"); + this.State.Set( + "SourceArray", + FormulaValue.NewTable( + RecordType.Empty(), + FormulaValue.NewRecordFromFields(new NamedValue("value", FormulaValue.New(10))))); + + // Act & Assert + await this.TakeNextTestAsync( + displayName: nameof(ForeachTakeLastAsync), + items: ValueExpression.Variable(PropertyPath.TopicVariable("SourceArray")), + valueName: "CurrentValue", + indexName: null); + } + + [Fact] + public async Task ForeachTakeNextWhenDoneAsync() + { + // Arrange + this.SetVariableState("CurrentValue"); + + // Act & Assert + await this.TakeNextTestAsync( + displayName: nameof(ForeachTakeNextWhenDoneAsync), + items: ValueExpression.Literal(DataValue.EmptyTable), + valueName: "CurrentValue", + indexName: null, + expectValue: false); + } + + [Fact] + public async Task ForeachCompletedWithoutIndexAsync() + { + // Arrange + this.SetVariableState("CurrentValue"); + + // Act & Assert + await this.CompletedTestAsync( + displayName: nameof(ForeachCompletedWithoutIndexAsync), + valueName: "CurrentValue", + indexName: null); + } + + [Fact] + public async Task ForeachCompletedWithIndexAsync() + { + // Arrange + this.SetVariableState("CurrentValue", "CurrentIndex"); + + // Act & Assert + await this.CompletedTestAsync( + displayName: nameof(ForeachCompletedWithIndexAsync), + valueName: "CurrentValue", + indexName: "CurrentIndex"); + } + + private void SetVariableState(string valueName, string? indexName = null, FormulaValue? valueState = null) + { + this.State.Set(valueName, valueState ?? FormulaValue.New("something")); + if (indexName is not null) + { + this.State.Set(indexName, FormulaValue.New(33)); + } + } + + private async Task ExecuteTestAsync( + string displayName, + ValueExpression items, + string valueName, + string? indexName, + bool expectValue = false) + { + // Arrange + Foreach model = this.CreateModel(displayName, items, valueName, indexName); + ForeachExecutor action = new(model, this.State); + + // Act + WorkflowEvent[] events = await this.ExecuteAsync(action, isDiscrete: false); + + // Assert + VerifyModel(model, action); + VerifyInvocationEvent(events); + + // IsDiscreteAction should be false for Foreach + Assert.Equal( + false, + action.GetType().BaseType? + .GetProperty("IsDiscreteAction", System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)? + .GetValue(action)); + + // Verify HasValue state after execution + Assert.Equal(expectValue, action.HasValue); + + // Verify value was reset at the end + this.VerifyUndefined(valueName); + + // Verify index was reset at the end if it was used + if (indexName is not null) + { + this.VerifyUndefined(indexName); + } + } + + private async Task TakeNextTestAsync( + string displayName, + ValueExpression items, + string valueName, + string? indexName, + bool expectValue = true) + { + // Arrange + Foreach model = this.CreateModel(displayName, items, valueName, indexName); + ForeachExecutor action = new(model, this.State); + + // Act + await this.ExecuteAsync(action, ForeachExecutor.Steps.Next(action.Id), action.TakeNextAsync); + + // Assert + VerifyModel(model, action); + + // Verify HasValue state after execution + Assert.Equal(expectValue, action.HasValue); + } + + private async Task CompletedTestAsync( + string displayName, + string valueName, + string? indexName) + { + // Arrange + Foreach model = this.CreateModel(displayName, ValueExpression.Literal(DataValue.EmptyTable), valueName, indexName); + ForeachExecutor action = new(model, this.State); + + // Act + WorkflowEvent[] events = await this.ExecuteAsync(ForeachExecutor.Steps.End(action.Id), action.CompleteAsync); + + // Assert + VerifyModel(model, action); + VerifyCompletionEvent(events); + + // Verify HasValue state after completion + Assert.False(action.HasValue); + + // Verify value was reset at the end + this.VerifyUndefined(valueName); + + // Verify index was reset at the end if it was used + if (indexName is not null) + { + this.VerifyUndefined(indexName); + } + } + + private Foreach CreateModel( + string displayName, + ValueExpression items, + string valueName, + string? indexName) + { + Foreach.Builder actionBuilder = new() + { + Id = this.CreateActionId(), + DisplayName = this.FormatDisplayName(displayName), + Items = items, + Value = PropertyPath.Create(FormatVariablePath(valueName)), + }; + + if (indexName is not null) + { + actionBuilder.Index = PropertyPath.Create(FormatVariablePath(indexName)); + } + + return AssignParent(actionBuilder); + } +} diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/WorkflowActionExecutorTest.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/WorkflowActionExecutorTest.cs index f7c074f1f5..cff93904b8 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/WorkflowActionExecutorTest.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/WorkflowActionExecutorTest.cs @@ -6,6 +6,7 @@ using System.Threading; using System.Threading.Tasks; using Microsoft.Agents.AI.Workflows.Declarative.Extensions; using Microsoft.Agents.AI.Workflows.Declarative.Interpreter; +using Microsoft.Agents.AI.Workflows.Declarative.Kit; using Microsoft.Agents.AI.Workflows.Declarative.PowerFx; using Microsoft.Agents.ObjectModel; using Microsoft.PowerFx.Types; @@ -25,17 +26,37 @@ public abstract class WorkflowActionExecutorTest(ITestOutputHelper output) : Wor protected string FormatDisplayName(string name) => $"{this.GetType().Name}_{name}"; - internal async Task ExecuteAsync(DeclarativeActionExecutor executor) + internal Task ExecuteAsync(string actionId, DelegateAction executorAction) => + this.ExecuteAsync(new DelegateActionExecutor(actionId, this.State, executorAction), isDiscrete: false); + + internal Task ExecuteAsync(Executor executor, string actionId, DelegateAction executorAction) => + this.ExecuteAsync([executor, new DelegateActionExecutor(actionId, this.State, executorAction)], isDiscrete: false); + + internal Task ExecuteAsync(Executor executor, bool isDiscrete = true) => + this.ExecuteAsync([executor], isDiscrete); + + internal async Task ExecuteAsync(Executor[] executors, bool isDiscrete) { this.State.Bind(); TestWorkflowExecutor workflowExecutor = new(); WorkflowBuilder workflowBuilder = new(workflowExecutor); - workflowBuilder.AddEdge(workflowExecutor, executor); + Executor prevExecutor = workflowExecutor; + foreach (Executor executor in executors) + { + workflowBuilder.AddEdge(prevExecutor, executor); + prevExecutor = executor; + } + await using StreamingRun run = await InProcessExecution.StreamAsync(workflowBuilder.Build(), this.State); WorkflowEvent[] events = await run.WatchStreamAsync().ToArrayAsync(); - Assert.Contains(events, e => e is DeclarativeActionInvokedEvent); - Assert.Contains(events, e => e is DeclarativeActionCompletedEvent); + + if (isDiscrete) + { + VerifyInvocationEvent(events); + VerifyCompletionEvent(events); + } + ExecutorFailedEvent[] failureEvents = events.OfType().ToArray(); switch (failureEvents.Length) { @@ -48,6 +69,7 @@ public abstract class WorkflowActionExecutorTest(ITestOutputHelper output) : Wor throw aggregateException; } + return events; } @@ -57,15 +79,21 @@ public abstract class WorkflowActionExecutorTest(ITestOutputHelper output) : Wor Assert.Equal(model, action.Model); } + protected static void VerifyInvocationEvent(WorkflowEvent[] events) => + Assert.Contains(events, e => e is DeclarativeActionInvokedEvent); + + protected static void VerifyCompletionEvent(WorkflowEvent[] events) => + Assert.Contains(events, e => e is DeclarativeActionCompletedEvent); + protected void VerifyState(string variableName, FormulaValue expectedValue) => this.VerifyState(variableName, WorkflowFormulaState.DefaultScopeName, expectedValue); - internal void VerifyState(string variableName, string scopeName, FormulaValue expectedValue) + protected void VerifyState(string variableName, string scopeName, FormulaValue expectedValue) { FormulaValue actualValue = this.State.Get(variableName, scopeName); Assert.Equal(expectedValue.Format(), actualValue.Format()); } - internal void VerifyUndefined(string variableName, string? scopeName = null) => + protected void VerifyUndefined(string variableName, string? scopeName = null) => Assert.IsType(this.State.Get(variableName, scopeName)); protected static TAction AssignParent(DialogAction.Builder actionBuilder) where TAction : DialogAction diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopBreak.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopBreak.cs index f4ee656e0c..04459394b0 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopBreak.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopBreak.cs @@ -1,4 +1,4 @@ -ο»Ώ// ------------------------------------------------------------------------------ +// ------------------------------------------------------------------------------ // // This code was generated by a tool. // @@ -81,7 +81,7 @@ public static class WorkflowProvider this._values = [evaluatedValue]; } - await this.ResetAsync(context, null, cancellationToken).ConfigureAwait(false); + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); return default; } @@ -99,7 +99,12 @@ public static class WorkflowProvider } } - public async ValueTask ResetAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + public async ValueTask CompleteAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + { + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); + } + + private async ValueTask ResetAsync(IWorkflowContext context, CancellationToken cancellationToken) { await context.QueueStateUpdateAsync(key: "LoopValue", value: UnassignedValue.Instance, scopeName: "Local").ConfigureAwait(false); await context.QueueStateUpdateAsync(key: "LoopIndex", value: UnassignedValue.Instance, scopeName: "Local").ConfigureAwait(false); @@ -160,7 +165,7 @@ public static class WorkflowProvider SetVariableInnerExecutor setVariableInner = new(myWorkflowRoot.Session); SendActivityInnerExecutor sendActivityInner = new(myWorkflowRoot.Session); DelegateExecutor endAll = new(id: "end_all", myWorkflowRoot.Session); - DelegateExecutor foreachLoopEnd = new(id: "foreach_loop_End", myWorkflowRoot.Session, foreachLoop.ResetAsync); + DelegateExecutor foreachLoopEnd = new(id: "foreach_loop_End", myWorkflowRoot.Session, foreachLoop.CompleteAsync); // Define the workflow builder WorkflowBuilder builder = new(myWorkflowRoot); @@ -182,4 +187,4 @@ public static class WorkflowProvider // Build the workflow return builder.Build(validateOrphans: false); } -} +} \ No newline at end of file diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopContinue.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopContinue.cs index 474d69e7ed..d023184476 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopContinue.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopContinue.cs @@ -1,4 +1,4 @@ -ο»Ώ// ------------------------------------------------------------------------------ +// ------------------------------------------------------------------------------ // // This code was generated by a tool. // @@ -81,7 +81,7 @@ public static class WorkflowProvider this._values = [evaluatedValue]; } - await this.ResetAsync(context, null, cancellationToken).ConfigureAwait(false); + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); return default; } @@ -99,7 +99,12 @@ public static class WorkflowProvider } } - public async ValueTask ResetAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + public async ValueTask CompleteAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + { + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); + } + + private async ValueTask ResetAsync(IWorkflowContext context, CancellationToken cancellationToken) { await context.QueueStateUpdateAsync(key: "LoopValue", value: UnassignedValue.Instance, scopeName: "Local").ConfigureAwait(false); await context.QueueStateUpdateAsync(key: "LoopIndex", value: UnassignedValue.Instance, scopeName: "Local").ConfigureAwait(false); @@ -160,7 +165,7 @@ public static class WorkflowProvider SetVariableInnerExecutor setVariableInner = new(myWorkflowRoot.Session); SendActivityInnerExecutor sendActivityInner = new(myWorkflowRoot.Session); DelegateExecutor endAll = new(id: "end_all", myWorkflowRoot.Session); - DelegateExecutor foreachLoopEnd = new(id: "foreach_loop_End", myWorkflowRoot.Session, foreachLoop.ResetAsync); + DelegateExecutor foreachLoopEnd = new(id: "foreach_loop_End", myWorkflowRoot.Session, foreachLoop.CompleteAsync); // Define the workflow builder WorkflowBuilder builder = new(myWorkflowRoot); @@ -182,4 +187,4 @@ public static class WorkflowProvider // Build the workflow return builder.Build(validateOrphans: false); } -} +} \ No newline at end of file diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopEach.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopEach.cs index 06137f222d..a467d42f33 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopEach.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/LoopEach.cs @@ -1,4 +1,4 @@ -ο»Ώ// ------------------------------------------------------------------------------ +// ------------------------------------------------------------------------------ // // This code was generated by a tool. // @@ -81,7 +81,7 @@ public static class WorkflowProvider this._values = [evaluatedValue]; } - await this.ResetAsync(context, null, cancellationToken).ConfigureAwait(false); + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); return default; } @@ -99,7 +99,12 @@ public static class WorkflowProvider } } - public async ValueTask ResetAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + public async ValueTask CompleteAsync(IWorkflowContext context, object? _, CancellationToken cancellationToken) + { + await this.ResetAsync(context, cancellationToken).ConfigureAwait(false); + } + + private async ValueTask ResetAsync(IWorkflowContext context, CancellationToken cancellationToken) { await context.QueueStateUpdateAsync(key: "LoopValue", value: UnassignedValue.Instance, scopeName: "Local").ConfigureAwait(false); await context.QueueStateUpdateAsync(key: "LoopIndex", value: UnassignedValue.Instance, scopeName: "Local").ConfigureAwait(false); @@ -158,7 +163,7 @@ public static class WorkflowProvider SetVariableInnerExecutor setVariableInner = new(myWorkflowRoot.Session); SendActivityInnerExecutor sendActivityInner = new(myWorkflowRoot.Session); DelegateExecutor endAll = new(id: "end_all", myWorkflowRoot.Session); - DelegateExecutor foreachLoopEnd = new(id: "foreach_loop_End", myWorkflowRoot.Session, foreachLoop.ResetAsync); + DelegateExecutor foreachLoopEnd = new(id: "foreach_loop_End", myWorkflowRoot.Session, foreachLoop.CompleteAsync); // Define the workflow builder WorkflowBuilder builder = new(myWorkflowRoot); @@ -178,4 +183,4 @@ public static class WorkflowProvider // Build the workflow return builder.Build(validateOrphans: false); } -} +} \ No newline at end of file diff --git a/python/README.md b/python/README.md index 160a7affb0..ae0b76323b 100644 --- a/python/README.md +++ b/python/README.md @@ -70,7 +70,7 @@ client = AzureOpenAIChatClient( ) ``` -See the following [setup guide](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started) for more information. +See the following [setup guide](samples/01-get-started) for more information. ## 2. Create a Simple Agent @@ -181,7 +181,7 @@ if __name__ == "__main__": asyncio.run(main()) ``` -You can explore additional agent samples [here](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents). +You can explore additional agent samples [here](samples/02-agents). ## 5. Multi-Agent Orchestration @@ -233,14 +233,14 @@ if __name__ == "__main__": asyncio.run(main()) ``` -For more advanced orchestration patterns including Sequential, Concurrent, Group Chat, Handoff, and Magentic orchestrations, see the [orchestration samples](samples/getting_started/orchestrations). +For more advanced orchestration patterns including Sequential, Concurrent, Group Chat, Handoff, and Magentic orchestrations, see the [orchestration samples](samples/02-agents/orchestrations). ## More Examples & Samples -- [Getting Started with Agents](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents): Basic agent creation and tool usage -- [Chat Client Examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/chat_client): Direct chat client usage patterns +- [Getting Started with Agents](samples/02-agents): Basic agent creation and tool usage +- [Chat Client Examples](samples/02-agents/chat_client): Direct chat client usage patterns - [Azure AI Integration](https://github.com/microsoft/agent-framework/tree/main/python/packages/azure-ai): Azure AI integration -- [Workflow Samples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/workflows): Advanced multi-agent patterns +- [Workflow Samples](samples/03-workflows): Advanced multi-agent patterns ## Agent Framework Documentation diff --git a/python/packages/a2a/README.md b/python/packages/a2a/README.md index 29750ff8e2..5ae15e3647 100644 --- a/python/packages/a2a/README.md +++ b/python/packages/a2a/README.md @@ -12,7 +12,7 @@ The A2A agent integration enables communication with remote A2A-compliant agents ### Basic Usage Example -See the [A2A agent examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents/a2a/) which demonstrate: +See the [A2A agent examples](../../samples/04-hosting/a2a/) which demonstrate: - Connecting to remote A2A agents - Sending messages and receiving responses diff --git a/python/packages/anthropic/README.md b/python/packages/anthropic/README.md index f8c8af674f..2507837d2c 100644 --- a/python/packages/anthropic/README.md +++ b/python/packages/anthropic/README.md @@ -12,7 +12,7 @@ The Anthropic integration enables communication with the Anthropic API, allowing ### Basic Usage Example -See the [Anthropic agent examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents/anthropic/) which demonstrate: +See the [Anthropic agent examples](../../samples/02-agents/providers/anthropic/) which demonstrate: - Connecting to a Anthropic endpoint with an agent - Streaming and non-streaming responses diff --git a/python/packages/azure-ai-search/README.md b/python/packages/azure-ai-search/README.md index 06853ae09e..c24677b3b0 100644 --- a/python/packages/azure-ai-search/README.md +++ b/python/packages/azure-ai-search/README.md @@ -15,7 +15,7 @@ The Azure AI Search integration provides context providers for RAG (Retrieval Au ### Basic Usage Example -See the [Azure AI Search context provider examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents/azure_ai/) which demonstrate: +See the [Azure AI Search context provider examples](../../samples/02-agents/providers/azure_ai/) which demonstrate: - Semantic search with hybrid (vector + keyword) queries - Agentic mode with Knowledge Bases for complex multi-hop reasoning diff --git a/python/packages/azurefunctions/tests/integration_tests/conftest.py b/python/packages/azurefunctions/tests/integration_tests/conftest.py index 53a6de926d..cec3758aff 100644 --- a/python/packages/azurefunctions/tests/integration_tests/conftest.py +++ b/python/packages/azurefunctions/tests/integration_tests/conftest.py @@ -300,7 +300,7 @@ def _get_sample_path_from_marker(request: pytest.FixtureRequest) -> tuple[Path | sample_name = marker.args[0] repo_root = _resolve_repo_root() - sample_path = repo_root / "samples" / "getting_started" / "azure_functions" / sample_name + sample_path = repo_root / "samples" / "04-hosting" / "azure_functions" / sample_name if not sample_path.exists(): return None, f"Sample directory does not exist: {sample_path}" diff --git a/python/packages/chatkit/README.md b/python/packages/chatkit/README.md index f52225c1d9..874efaa097 100644 --- a/python/packages/chatkit/README.md +++ b/python/packages/chatkit/README.md @@ -124,4 +124,4 @@ async def chatkit_endpoint(request: Request): return Response(content=result.json, media_type="application/json") # type: ignore[union-attr] ``` -For a complete end-to-end example with a full frontend, see the [weather agent sample](../../samples/demos/chatkit-integration/README.md). +For a complete end-to-end example with a full frontend, see the [weather agent sample](../../samples/05-end-to-end/chatkit-integration/README.md). diff --git a/python/packages/copilotstudio/README.md b/python/packages/copilotstudio/README.md index ea88f22ee4..08cad5331e 100644 --- a/python/packages/copilotstudio/README.md +++ b/python/packages/copilotstudio/README.md @@ -89,7 +89,7 @@ The package uses MSAL (Microsoft Authentication Library) for authentication with ### Examples -For more comprehensive examples, see the [Copilot Studio examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents/copilotstudio/) which demonstrate: +For more comprehensive examples, see the [Copilot Studio examples](../../samples/02-agents/providers/copilotstudio/) which demonstrate: - Basic non-streaming and streaming execution - Explicit settings and manual token acquisition diff --git a/python/packages/core/README.md b/python/packages/core/README.md index b919b229e4..59e113b33c 100644 --- a/python/packages/core/README.md +++ b/python/packages/core/README.md @@ -53,7 +53,7 @@ client = AzureOpenAIChatClient( ) ``` -See the following [setup guide](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started) for more information. +See the following [setup guide](../../samples/01-get-started) for more information. ## 2. Create a Simple Agent @@ -161,7 +161,7 @@ async def main(): asyncio.run(main()) ``` -You can explore additional agent samples [here](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents). +You can explore additional agent samples [here](../../samples/02-agents). ## 5. Multi-Agent Orchestration @@ -213,12 +213,12 @@ if __name__ == "__main__": asyncio.run(main()) ``` -**Note**: Sequential, Concurrent, Group Chat, Handoff, and Magentic orchestrations are available. See examples in [orchestration samples](../../samples/getting_started/orchestrations). +**Note**: Sequential, Concurrent, Group Chat, Handoff, and Magentic orchestrations are available. See examples in [orchestration samples](../../samples/02-agents/orchestrations). ## More Examples & Samples -- [Getting Started with Agents](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents): Basic agent creation and tool usage -- [Chat Client Examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/chat_client): Direct chat client usage patterns +- [Getting Started with Agents](../../samples/02-agents): Basic agent creation and tool usage +- [Chat Client Examples](../../samples/02-agents/chat_client): Direct chat client usage patterns - [Azure AI Integration](https://github.com/microsoft/agent-framework/tree/main/python/packages/azure-ai): Azure AI integration - [.NET Workflows Samples](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/Workflows): Advanced multi-agent patterns (.NET) diff --git a/python/packages/declarative/tests/test_powerfx_yaml_compatibility.py b/python/packages/declarative/tests/test_powerfx_yaml_compatibility.py index 8f0cd39d31..72b2d398c5 100644 --- a/python/packages/declarative/tests/test_powerfx_yaml_compatibility.py +++ b/python/packages/declarative/tests/test_powerfx_yaml_compatibility.py @@ -3,7 +3,7 @@ """Tests to ensure PowerFx evaluation supports all expressions used in declarative YAML workflows. This test suite validates that all PowerFx expressions found in the sample YAML workflows -under samples/getting_started/workflows/declarative/ work correctly with our implementation. +under samples/03-workflows/declarative/ work correctly with our implementation. Coverage includes: - Built-in PowerFx functions: Concat, If, IsBlank, Not, Or, Upper, Find diff --git a/python/packages/devui/README.md b/python/packages/devui/README.md index 6c3745236a..eca7272cfd 100644 --- a/python/packages/devui/README.md +++ b/python/packages/devui/README.md @@ -373,7 +373,7 @@ This restricts developer APIs (reload, deployment, entity details) and requires ## Examples -See working implementations in `python/samples/getting_started/devui/` +See working implementations in `python/samples/02-agents/devui/` ## License diff --git a/python/packages/devui/dev.md b/python/packages/devui/dev.md index 838e3536fc..5a4166112d 100644 --- a/python/packages/devui/dev.md +++ b/python/packages/devui/dev.md @@ -45,7 +45,7 @@ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="your-deployment-name" **Option A: In-Memory Mode (Recommended for quick testing)** ```bash -cd samples/getting_started/devui +cd samples/02-agents/devui python in_memory_mode.py ``` @@ -54,7 +54,7 @@ This runs a simple example with predefined agents and opens your browser automat **Option B: Directory-Based Discovery** ```bash -cd samples/getting_started/devui +cd samples/02-agents/devui devui ``` diff --git a/python/packages/devui/samples/README.md b/python/packages/devui/samples/README.md index 6ed374bcb5..d4ad6f6b83 100644 --- a/python/packages/devui/samples/README.md +++ b/python/packages/devui/samples/README.md @@ -7,7 +7,7 @@ All DevUI samples are now located at: ``` -python/samples/getting_started/devui/ +python/samples/02-agents/devui/ ``` ## Available Samples @@ -22,17 +22,17 @@ python/samples/getting_started/devui/ ## Quick Start ```bash -cd ../../samples/getting_started/devui +cd ../../samples/02-agents/devui python in_memory_mode.py ``` Or for directory discovery: ```bash -cd ../../samples/getting_started/devui +cd ../../samples/02-agents/devui devui ``` ## Learn More -See the [DevUI samples README](../../../samples/getting_started/devui/README.md) for detailed documentation. +See the [DevUI samples README](../../../samples/02-agents/devui/README.md) for detailed documentation. diff --git a/python/packages/devui/tests/devui/capture_messages.py b/python/packages/devui/tests/devui/capture_messages.py index 8026303c20..820fedde57 100644 --- a/python/packages/devui/tests/devui/capture_messages.py +++ b/python/packages/devui/tests/devui/capture_messages.py @@ -28,8 +28,8 @@ def start_server() -> tuple[str, Any]: """Start server with samples directory.""" # Get samples directory - updated path after samples were moved current_dir = Path(__file__).parent - # Samples are now in python/samples/getting_started/devui - samples_dir = current_dir.parent.parent.parent / "samples" / "getting_started" / "devui" + # Samples are now in python/samples/02-agents/devui + samples_dir = current_dir.parent.parent.parent / "samples" / "02-agents" / "devui" if not samples_dir.exists(): raise RuntimeError(f"Samples directory not found: {samples_dir}") diff --git a/python/packages/devui/tests/devui/conftest.py b/python/packages/devui/tests/devui/conftest.py index 1b1fd0610f..14f48617db 100644 --- a/python/packages/devui/tests/devui/conftest.py +++ b/python/packages/devui/tests/devui/conftest.py @@ -413,8 +413,8 @@ def executor_failed_event() -> WorkflowEvent[WorkflowErrorDetails]: def test_entities_dir() -> str: """Use the samples directory which has proper entity structure.""" current_dir = Path(__file__).parent - # Navigate to python/samples/getting_started/devui - samples_dir = current_dir.parent.parent.parent.parent / "samples" / "getting_started" / "devui" + # Navigate to python/samples/02-agents/devui + samples_dir = current_dir.parent.parent.parent.parent / "samples" / "02-agents" / "devui" return str(samples_dir.resolve()) diff --git a/python/packages/devui/tests/devui/test_openai_sdk_integration.py b/python/packages/devui/tests/devui/test_openai_sdk_integration.py index 6957369215..0de4075690 100644 --- a/python/packages/devui/tests/devui/test_openai_sdk_integration.py +++ b/python/packages/devui/tests/devui/test_openai_sdk_integration.py @@ -28,7 +28,7 @@ def devui_server() -> Generator[str, None, None]: """ # Get samples directory current_dir = Path(__file__).parent - samples_dir = current_dir.parent.parent.parent / "samples" / "getting_started" / "devui" + samples_dir = current_dir.parent.parent.parent / "samples" / "02-agents" / "devui" if not samples_dir.exists(): pytest.skip(f"Samples directory not found: {samples_dir}") diff --git a/python/packages/durabletask/tests/integration_tests/conftest.py b/python/packages/durabletask/tests/integration_tests/conftest.py index e6b26e33a1..014128cf37 100644 --- a/python/packages/durabletask/tests/integration_tests/conftest.py +++ b/python/packages/durabletask/tests/integration_tests/conftest.py @@ -382,7 +382,7 @@ def worker_process( pytest.fail("Test class must have @pytest.mark.sample() marker") sample_name: str = cast(str, sample_marker.args[0]) # type: ignore[union-attr] - sample_path: Path = Path(__file__).parents[4] / "samples" / "getting_started" / "durabletask" / sample_name + sample_path: Path = Path(__file__).parents[4] / "samples" / "04-hosting" / "durabletask" / sample_name worker_file: Path = sample_path / "worker.py" if not worker_file.exists(): diff --git a/python/packages/durabletask/tests/integration_tests/test_03_dt_single_agent_streaming.py b/python/packages/durabletask/tests/integration_tests/test_03_dt_single_agent_streaming.py index 2d05280431..a05c81b2f8 100644 --- a/python/packages/durabletask/tests/integration_tests/test_03_dt_single_agent_streaming.py +++ b/python/packages/durabletask/tests/integration_tests/test_03_dt_single_agent_streaming.py @@ -27,7 +27,7 @@ import pytest import redis.asyncio as aioredis # Add sample directory to path to import RedisStreamResponseHandler -SAMPLE_DIR = Path(__file__).parents[4] / "samples" / "getting_started" / "durabletask" / "03_single_agent_streaming" +SAMPLE_DIR = Path(__file__).parents[4] / "samples" / "04-hosting" / "durabletask" / "03_single_agent_streaming" sys.path.insert(0, str(SAMPLE_DIR)) from redis_stream_response_handler import RedisStreamResponseHandler # type: ignore[reportMissingImports] # noqa: E402 diff --git a/python/packages/mem0/README.md b/python/packages/mem0/README.md index a824c7db51..6ca522f4c8 100644 --- a/python/packages/mem0/README.md +++ b/python/packages/mem0/README.md @@ -12,7 +12,7 @@ The Mem0 context provider enables persistent memory capabilities for your agents ### Basic Usage Example -See the [Mem0 basic example](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/context_providers/mem0/mem0_basic.py) which demonstrates: +See the [Mem0 basic example](../../samples/02-agents/context_providers/mem0/mem0_basic.py) which demonstrates: - Setting up an agent with Mem0 context provider - Teaching the agent user preferences diff --git a/python/packages/ollama/README.md b/python/packages/ollama/README.md index f67d538507..d0bdf58cf3 100644 --- a/python/packages/ollama/README.md +++ b/python/packages/ollama/README.md @@ -10,4 +10,4 @@ and see the [README](https://github.com/microsoft/agent-framework/tree/main/pyth # Run samples with the Ollama Conector -You can find samples how to run the connector under the [Getting_started] (./getting_started/README.md) folder +You can find samples how to run the connector in the [Ollama provider samples](../../samples/02-agents/providers/ollama). diff --git a/python/packages/redis/README.md b/python/packages/redis/README.md index 3c6c5bb18c..be36dc8c28 100644 --- a/python/packages/redis/README.md +++ b/python/packages/redis/README.md @@ -14,7 +14,7 @@ The `RedisProvider` enables persistent context & memory capabilities for your ag #### Basic Usage Examples -Review the set of [getting started examples](../../samples/getting_started/context_providers/redis/README.md) for using the Redis context provider. +Review the set of [getting started examples](../../samples/02-agents/context_providers/redis/README.md) for using the Redis context provider. ### Redis Chat Message Store @@ -30,7 +30,7 @@ The `RedisChatMessageStore` provides persistent conversation storage using Redis #### Basic Usage Examples -See the complete [Redis chat message store examples](../../samples/getting_started/threads/redis_chat_message_store_thread.py) including: +See the complete [Redis chat message store examples](../../samples/02-agents/conversations/redis_chat_message_store_thread.py) including: - User session management - Conversation persistence across restarts - Thread serialization and deserialization diff --git a/python/pyrightconfig.samples.json b/python/pyrightconfig.samples.json index 5dae59f141..4e77569f94 100644 --- a/python/pyrightconfig.samples.json +++ b/python/pyrightconfig.samples.json @@ -5,6 +5,8 @@ "**/autogen-migration/**", "**/semantic-kernel-migration/**", "**/demos/**", + "**/_to_delete/**", + "**/05-end-to-end/**", "**/agent_with_foundry_tracing.py", "**/azure_responses_client_with_foundry.py" ], diff --git a/python/samples/01-get-started/01_hello_agent.py b/python/samples/01-get-started/01_hello_agent.py new file mode 100644 index 0000000000..a3353a5e87 --- /dev/null +++ b/python/samples/01-get-started/01_hello_agent.py @@ -0,0 +1,53 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import os + +from agent_framework.azure import AzureOpenAIResponsesClient +from azure.identity import AzureCliCredential + +""" +Hello Agent β€” Simplest possible agent + +This sample creates a minimal agent using AzureOpenAIResponsesClient via an +Azure AI Foundry project endpoint, and runs it in both non-streaming and streaming modes. + +Environment variables: + AZURE_AI_PROJECT_ENDPOINT β€” Your Azure AI Foundry project endpoint + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME β€” Model deployment name (e.g. gpt-4o) +""" + + +async def main() -> None: + # + credential = AzureCliCredential() + client = AzureOpenAIResponsesClient( + project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"], + credential=credential, + ) + + agent = client.as_agent( + name="HelloAgent", + instructions="You are a friendly assistant. Keep your answers brief.", + ) + # + + # + # Non-streaming: get the complete response at once + result = await agent.run("What is the capital of France?") + print(f"Agent: {result}") + # + + # + # Streaming: receive tokens as they are generated + print("Agent (streaming): ", end="", flush=True) + async for chunk in agent.run("Tell me a one-sentence fun fact.", stream=True): + if chunk.text: + print(chunk.text, end="", flush=True) + print() + # + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/01-get-started/02_add_tools.py b/python/samples/01-get-started/02_add_tools.py new file mode 100644 index 0000000000..04045de16c --- /dev/null +++ b/python/samples/01-get-started/02_add_tools.py @@ -0,0 +1,61 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import os +from random import randint +from typing import Annotated + +from agent_framework import tool +from agent_framework.azure import AzureOpenAIResponsesClient +from azure.identity import AzureCliCredential +from pydantic import Field + +""" +Add Tools β€” Give your agent a function tool + +This sample shows how to define a function tool with the @tool decorator +and wire it into an agent so the model can call it. + +Environment variables: + AZURE_AI_PROJECT_ENDPOINT β€” Your Azure AI Foundry project endpoint + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME β€” Model deployment name (e.g. gpt-4o) +""" + + +# +# NOTE: approval_mode="never_require" is for sample brevity. +# Use "always_require" in production for user confirmation before tool execution. +@tool(approval_mode="never_require") +def get_weather( + location: Annotated[str, Field(description="The location to get the weather for.")], +) -> str: + """Get the weather for a given location.""" + conditions = ["sunny", "cloudy", "rainy", "stormy"] + return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}Β°C." +# + + +async def main() -> None: + credential = AzureCliCredential() + client = AzureOpenAIResponsesClient( + project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"], + credential=credential, + ) + + # + agent = client.as_agent( + name="WeatherAgent", + instructions="You are a helpful weather agent. Use the get_weather tool to answer questions.", + tools=get_weather, + ) + # + + # + result = await agent.run("What's the weather like in Seattle?") + print(f"Agent: {result}") + # + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/01-get-started/03_multi_turn.py b/python/samples/01-get-started/03_multi_turn.py new file mode 100644 index 0000000000..f69930619e --- /dev/null +++ b/python/samples/01-get-started/03_multi_turn.py @@ -0,0 +1,51 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import os + +from agent_framework.azure import AzureOpenAIResponsesClient +from azure.identity import AzureCliCredential + +""" +Multi-Turn Conversations β€” Use AgentThread to maintain context + +This sample shows how to keep conversation history across multiple calls +by reusing the same thread object. + +Environment variables: + AZURE_AI_PROJECT_ENDPOINT β€” Your Azure AI Foundry project endpoint + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME β€” Model deployment name (e.g. gpt-4o) +""" + + +async def main() -> None: + # + credential = AzureCliCredential() + client = AzureOpenAIResponsesClient( + project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"], + credential=credential, + ) + + agent = client.as_agent( + name="ConversationAgent", + instructions="You are a friendly assistant. Keep your answers brief.", + ) + # + + # + # Create a thread to maintain conversation history + thread = agent.get_new_thread() + + # First turn + result = await agent.run("My name is Alice and I love hiking.", thread=thread) + print(f"Agent: {result}\n") + + # Second turn β€” the agent should remember the user's name and hobby + result = await agent.run("What do you remember about me?", thread=thread) + print(f"Agent: {result}") + # + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/01-get-started/04_memory.py b/python/samples/01-get-started/04_memory.py new file mode 100644 index 0000000000..08320a6e43 --- /dev/null +++ b/python/samples/01-get-started/04_memory.py @@ -0,0 +1,91 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import os +from collections.abc import MutableSequence +from typing import Any + +from agent_framework import Context, ContextProvider, Message +from agent_framework.azure import AzureOpenAIResponsesClient +from azure.identity import AzureCliCredential + +""" +Agent Memory with Context Providers + +Context providers let you inject dynamic instructions and context into each +agent invocation. This sample defines a simple provider that tracks the user's +name and enriches every request with personalization instructions. + +Environment variables: + AZURE_AI_PROJECT_ENDPOINT β€” Your Azure AI Foundry project endpoint + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME β€” Model deployment name (e.g. gpt-4o) +""" + + +# +class UserNameProvider(ContextProvider): + """A simple context provider that remembers the user's name.""" + + def __init__(self) -> None: + self.user_name: str | None = None + + async def invoking(self, messages: Message | MutableSequence[Message], **kwargs: Any) -> Context: + """Called before each agent invocation β€” add extra instructions.""" + if self.user_name: + return Context(instructions=f"The user's name is {self.user_name}. Always address them by name.") + return Context(instructions="You don't know the user's name yet. Ask for it politely.") + + async def invoked( + self, + request_messages: Message | list[Message] | None = None, + response_messages: "Message | list[Message] | None" = None, + invoke_exception: Exception | None = None, + **kwargs: Any, + ) -> None: + """Called after each agent invocation β€” extract information.""" + msgs = [request_messages] if isinstance(request_messages, Message) else list(request_messages or []) + for msg in msgs: + text = msg.text if hasattr(msg, "text") else "" + if isinstance(text, str) and "my name is" in text.lower(): + # Simple extraction β€” production code should use structured extraction + self.user_name = text.lower().split("my name is")[-1].strip().split()[0].capitalize() +# + + +async def main() -> None: + # + credential = AzureCliCredential() + client = AzureOpenAIResponsesClient( + project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"], + credential=credential, + ) + + memory = UserNameProvider() + + agent = client.as_agent( + name="MemoryAgent", + instructions="You are a friendly assistant.", + context_provider=memory, + ) + # + + thread = agent.get_new_thread() + + # The provider doesn't know the user yet β€” it will ask for a name + result = await agent.run("Hello! What's the square root of 9?", thread=thread) + print(f"Agent: {result}\n") + + # Now provide the name β€” the provider extracts and stores it + result = await agent.run("My name is Alice", thread=thread) + print(f"Agent: {result}\n") + + # Subsequent calls are personalized + result = await agent.run("What is 2 + 2?", thread=thread) + print(f"Agent: {result}\n") + + print(f"[Memory] Stored user name: {memory.user_name}") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/01-get-started/05_first_workflow.py b/python/samples/01-get-started/05_first_workflow.py new file mode 100644 index 0000000000..ffce2e97d8 --- /dev/null +++ b/python/samples/01-get-started/05_first_workflow.py @@ -0,0 +1,72 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio + +from agent_framework import ( + Executor, + WorkflowBuilder, + WorkflowContext, + executor, + handler, +) +from typing_extensions import Never + +""" +First Workflow β€” Chain executors with edges + +This sample builds a minimal workflow with two steps: +1. Convert text to uppercase (class-based executor) +2. Reverse the text (function-based executor) + +No external services are required. +""" + + +# +# Step 1: A class-based executor that converts text to uppercase +class UpperCase(Executor): + def __init__(self, id: str): + super().__init__(id=id) + + @handler + async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None: + """Convert input to uppercase and forward to the next node.""" + await ctx.send_message(text.upper()) + + +# Step 2: A function-based executor that reverses the string and yields output +@executor(id="reverse_text") +async def reverse_text(text: str, ctx: WorkflowContext[Never, str]) -> None: + """Reverse the string and yield the final workflow output.""" + await ctx.yield_output(text[::-1]) + + +def create_workflow(): + """Build the workflow: UpperCase β†’ reverse_text.""" + upper = UpperCase(id="upper_case") + return ( + WorkflowBuilder(start_executor=upper) + .add_edge(upper, reverse_text) + .build() + ) +# + + +async def main() -> None: + # + workflow = create_workflow() + + events = await workflow.run("hello world") + print(f"Output: {events.get_outputs()}") + print(f"Final state: {events.get_final_state()}") + # + + """ + Expected output: + Output: ['DLROW OLLEH'] + Final state: WorkflowRunState.IDLE + """ + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/01-get-started/06_host_your_agent.py b/python/samples/01-get-started/06_host_your_agent.py new file mode 100644 index 0000000000..916944cdb6 --- /dev/null +++ b/python/samples/01-get-started/06_host_your_agent.py @@ -0,0 +1,60 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import os + +from agent_framework.azure import AzureOpenAIResponsesClient +from azure.identity import AzureCliCredential + +""" +Host Your Agent β€” Minimal A2A hosting stub + +This sample shows the pattern for exposing an agent via the Agent-to-Agent +(A2A) protocol. It creates the agent and demonstrates how to wrap it with +the A2A hosting layer. + +Prerequisites: + pip install agent-framework[a2a] --pre + +Environment variables: + AZURE_AI_PROJECT_ENDPOINT β€” Your Azure AI Foundry project endpoint + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME β€” Model deployment name (e.g. gpt-4o) + +To run a full A2A server, see samples/04-hosting/a2a/ for a complete example. +""" + + +async def main() -> None: + # + credential = AzureCliCredential() + client = AzureOpenAIResponsesClient( + project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"], + credential=credential, + ) + + agent = client.as_agent( + name="HostedAgent", + instructions="You are a helpful assistant exposed via A2A.", + ) + # + + # + # The A2A hosting integration wraps your agent behind an HTTP endpoint. + # Import is gated so this sample can run without the a2a extra installed. + try: + from agent_framework.a2a import A2AAgent # noqa: F401 + + print("A2A support is available.") + print("See samples/04-hosting/a2a/ for a runnable A2A server example.") + except ImportError: + print("Install a2a extras: pip install agent-framework[a2a] --pre") + + # Quick smoke-test: run the agent locally to verify it works + result = await agent.run("Hello! What can you do?") + print(f"Agent: {result}") + # + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/01-get-started/README.md b/python/samples/01-get-started/README.md new file mode 100644 index 0000000000..f13eeb26c5 --- /dev/null +++ b/python/samples/01-get-started/README.md @@ -0,0 +1,34 @@ +# Get Started with Agent Framework for Python + +This folder contains a progressive set of samples that introduce the core +concepts of **Agent Framework** one step at a time. + +## Prerequisites + +```bash +pip install agent-framework --pre +``` + +Set the required environment variables: + +```bash +export OPENAI_API_KEY="sk-..." +export OPENAI_RESPONSES_MODEL_ID="gpt-4o" # optional, defaults to gpt-4o +``` + +## Samples + +| # | File | What you'll learn | +|---|------|-------------------| +| 1 | [01_hello_agent.py](01_hello_agent.py) | Create your first agent and run it (streaming and non-streaming). | +| 2 | [02_add_tools.py](02_add_tools.py) | Define a function tool with `@tool` and attach it to an agent. | +| 3 | [03_multi_turn.py](03_multi_turn.py) | Keep conversation history across turns with `AgentThread`. | +| 4 | [04_memory.py](04_memory.py) | Add dynamic context with a custom `ContextProvider`. | +| 5 | [05_first_workflow.py](05_first_workflow.py) | Chain executors into a workflow with edges. | +| 6 | [06_host_your_agent.py](06_host_your_agent.py) | Prepare your agent for A2A hosting. | + +Run any sample with: + +```bash +python 01_hello_agent.py +``` diff --git a/python/samples/getting_started/__init__.py b/python/samples/02-agents/__init__.py similarity index 100% rename from python/samples/getting_started/__init__.py rename to python/samples/02-agents/__init__.py diff --git a/python/samples/concepts/background_responses.py b/python/samples/02-agents/background_responses.py similarity index 100% rename from python/samples/concepts/background_responses.py rename to python/samples/02-agents/background_responses.py diff --git a/python/samples/getting_started/chat_client/README.md b/python/samples/02-agents/chat_client/README.md similarity index 100% rename from python/samples/getting_started/chat_client/README.md rename to python/samples/02-agents/chat_client/README.md diff --git a/python/samples/getting_started/chat_client/azure_ai_chat_client.py b/python/samples/02-agents/chat_client/azure_ai_chat_client.py similarity index 90% rename from python/samples/getting_started/chat_client/azure_ai_chat_client.py rename to python/samples/02-agents/chat_client/azure_ai_chat_client.py index b699add89e..7d07473ba1 100644 --- a/python/samples/getting_started/chat_client/azure_ai_chat_client.py +++ b/python/samples/02-agents/chat_client/azure_ai_chat_client.py @@ -17,7 +17,7 @@ Shows function calling capabilities with custom business logic. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/chat_client/azure_assistants_client.py b/python/samples/02-agents/chat_client/azure_assistants_client.py similarity index 90% rename from python/samples/getting_started/chat_client/azure_assistants_client.py rename to python/samples/02-agents/chat_client/azure_assistants_client.py index 599593f54c..d507b2800e 100644 --- a/python/samples/getting_started/chat_client/azure_assistants_client.py +++ b/python/samples/02-agents/chat_client/azure_assistants_client.py @@ -17,7 +17,7 @@ Shows function calling capabilities and automatic assistant creation. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/chat_client/azure_chat_client.py b/python/samples/02-agents/chat_client/azure_chat_client.py similarity index 90% rename from python/samples/getting_started/chat_client/azure_chat_client.py rename to python/samples/02-agents/chat_client/azure_chat_client.py index 13a299ca30..f1244b2e77 100644 --- a/python/samples/getting_started/chat_client/azure_chat_client.py +++ b/python/samples/02-agents/chat_client/azure_chat_client.py @@ -17,7 +17,7 @@ Shows function calling capabilities with custom business logic. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/chat_client/azure_responses_client.py b/python/samples/02-agents/chat_client/azure_responses_client.py similarity index 93% rename from python/samples/getting_started/chat_client/azure_responses_client.py rename to python/samples/02-agents/chat_client/azure_responses_client.py index e2b9796826..6f41e43e3f 100644 --- a/python/samples/getting_started/chat_client/azure_responses_client.py +++ b/python/samples/02-agents/chat_client/azure_responses_client.py @@ -17,7 +17,7 @@ Shows function calling capabilities with custom business logic. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, "The location to get the weather for."], diff --git a/python/samples/getting_started/chat_client/chat_response_cancellation.py b/python/samples/02-agents/chat_client/chat_response_cancellation.py similarity index 100% rename from python/samples/getting_started/chat_client/chat_response_cancellation.py rename to python/samples/02-agents/chat_client/chat_response_cancellation.py diff --git a/python/samples/getting_started/chat_client/custom_chat_client.py b/python/samples/02-agents/chat_client/custom_chat_client.py similarity index 100% rename from python/samples/getting_started/chat_client/custom_chat_client.py rename to python/samples/02-agents/chat_client/custom_chat_client.py diff --git a/python/samples/getting_started/chat_client/openai_assistants_client.py b/python/samples/02-agents/chat_client/openai_assistants_client.py similarity index 89% rename from python/samples/getting_started/chat_client/openai_assistants_client.py rename to python/samples/02-agents/chat_client/openai_assistants_client.py index 9ff13f39ab..ad80e69ae4 100644 --- a/python/samples/getting_started/chat_client/openai_assistants_client.py +++ b/python/samples/02-agents/chat_client/openai_assistants_client.py @@ -17,7 +17,7 @@ Shows function calling capabilities and automatic assistant creation. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/chat_client/openai_chat_client.py b/python/samples/02-agents/chat_client/openai_chat_client.py similarity index 89% rename from python/samples/getting_started/chat_client/openai_chat_client.py rename to python/samples/02-agents/chat_client/openai_chat_client.py index 279d3eb186..efe06fdd8f 100644 --- a/python/samples/getting_started/chat_client/openai_chat_client.py +++ b/python/samples/02-agents/chat_client/openai_chat_client.py @@ -17,7 +17,7 @@ Shows function calling capabilities with custom business logic. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/chat_client/openai_responses_client.py b/python/samples/02-agents/chat_client/openai_responses_client.py similarity index 89% rename from python/samples/getting_started/chat_client/openai_responses_client.py rename to python/samples/02-agents/chat_client/openai_responses_client.py index ed58c0be29..f2283c7fa4 100644 --- a/python/samples/getting_started/chat_client/openai_responses_client.py +++ b/python/samples/02-agents/chat_client/openai_responses_client.py @@ -17,7 +17,7 @@ Shows function calling capabilities with custom business logic. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/context_providers/README.md b/python/samples/02-agents/context_providers/README.md similarity index 100% rename from python/samples/getting_started/context_providers/README.md rename to python/samples/02-agents/context_providers/README.md diff --git a/python/samples/getting_started/context_providers/aggregate_context_provider.py b/python/samples/02-agents/context_providers/aggregate_context_provider.py similarity index 100% rename from python/samples/getting_started/context_providers/aggregate_context_provider.py rename to python/samples/02-agents/context_providers/aggregate_context_provider.py diff --git a/python/samples/getting_started/context_providers/azure_ai_search/README.md b/python/samples/02-agents/context_providers/azure_ai_search/README.md similarity index 100% rename from python/samples/getting_started/context_providers/azure_ai_search/README.md rename to python/samples/02-agents/context_providers/azure_ai_search/README.md diff --git a/python/samples/getting_started/context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py b/python/samples/02-agents/context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py similarity index 100% rename from python/samples/getting_started/context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py rename to python/samples/02-agents/context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py diff --git a/python/samples/getting_started/context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py b/python/samples/02-agents/context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py similarity index 100% rename from python/samples/getting_started/context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py rename to python/samples/02-agents/context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py diff --git a/python/samples/getting_started/context_providers/mem0/README.md b/python/samples/02-agents/context_providers/mem0/README.md similarity index 100% rename from python/samples/getting_started/context_providers/mem0/README.md rename to python/samples/02-agents/context_providers/mem0/README.md diff --git a/python/samples/getting_started/context_providers/mem0/mem0_basic.py b/python/samples/02-agents/context_providers/mem0/mem0_basic.py similarity index 95% rename from python/samples/getting_started/context_providers/mem0/mem0_basic.py rename to python/samples/02-agents/context_providers/mem0/mem0_basic.py index b82dab0ae1..1252ee2b49 100644 --- a/python/samples/getting_started/context_providers/mem0/mem0_basic.py +++ b/python/samples/02-agents/context_providers/mem0/mem0_basic.py @@ -9,7 +9,7 @@ from agent_framework.mem0 import Mem0Provider from azure.identity.aio import AzureCliCredential -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def retrieve_company_report(company_code: str, detailed: bool) -> str: if company_code != "CNTS": diff --git a/python/samples/getting_started/context_providers/mem0/mem0_oss.py b/python/samples/02-agents/context_providers/mem0/mem0_oss.py similarity index 95% rename from python/samples/getting_started/context_providers/mem0/mem0_oss.py rename to python/samples/02-agents/context_providers/mem0/mem0_oss.py index 84156434b0..b22d76a972 100644 --- a/python/samples/getting_started/context_providers/mem0/mem0_oss.py +++ b/python/samples/02-agents/context_providers/mem0/mem0_oss.py @@ -10,7 +10,7 @@ from azure.identity.aio import AzureCliCredential from mem0 import AsyncMemory -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def retrieve_company_report(company_code: str, detailed: bool) -> str: if company_code != "CNTS": diff --git a/python/samples/getting_started/context_providers/mem0/mem0_threads.py b/python/samples/02-agents/context_providers/mem0/mem0_threads.py similarity index 97% rename from python/samples/getting_started/context_providers/mem0/mem0_threads.py rename to python/samples/02-agents/context_providers/mem0/mem0_threads.py index 15a57ad796..2e564d708c 100644 --- a/python/samples/getting_started/context_providers/mem0/mem0_threads.py +++ b/python/samples/02-agents/context_providers/mem0/mem0_threads.py @@ -9,7 +9,7 @@ from agent_framework.mem0 import Mem0Provider from azure.identity.aio import AzureCliCredential -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_user_preferences(user_id: str) -> str: """Mock function to get user preferences.""" diff --git a/python/samples/getting_started/context_providers/redis/README.md b/python/samples/02-agents/context_providers/redis/README.md similarity index 100% rename from python/samples/getting_started/context_providers/redis/README.md rename to python/samples/02-agents/context_providers/redis/README.md diff --git a/python/samples/getting_started/context_providers/redis/azure_redis_conversation.py b/python/samples/02-agents/context_providers/redis/azure_redis_conversation.py similarity index 100% rename from python/samples/getting_started/context_providers/redis/azure_redis_conversation.py rename to python/samples/02-agents/context_providers/redis/azure_redis_conversation.py diff --git a/python/samples/getting_started/context_providers/redis/redis_basics.py b/python/samples/02-agents/context_providers/redis/redis_basics.py similarity index 98% rename from python/samples/getting_started/context_providers/redis/redis_basics.py rename to python/samples/02-agents/context_providers/redis/redis_basics.py index f984354df7..5dfcbec850 100644 --- a/python/samples/getting_started/context_providers/redis/redis_basics.py +++ b/python/samples/02-agents/context_providers/redis/redis_basics.py @@ -37,7 +37,7 @@ from redisvl.extensions.cache.embeddings import EmbeddingsCache from redisvl.utils.vectorize import OpenAITextVectorizer -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def search_flights(origin_airport_code: str, destination_airport_code: str, detailed: bool = False) -> str: """Simulated flight-search tool to demonstrate tool memory. diff --git a/python/samples/getting_started/context_providers/redis/redis_conversation.py b/python/samples/02-agents/context_providers/redis/redis_conversation.py similarity index 100% rename from python/samples/getting_started/context_providers/redis/redis_conversation.py rename to python/samples/02-agents/context_providers/redis/redis_conversation.py diff --git a/python/samples/getting_started/context_providers/redis/redis_threads.py b/python/samples/02-agents/context_providers/redis/redis_threads.py similarity index 100% rename from python/samples/getting_started/context_providers/redis/redis_threads.py rename to python/samples/02-agents/context_providers/redis/redis_threads.py diff --git a/python/samples/getting_started/context_providers/simple_context_provider.py b/python/samples/02-agents/context_providers/simple_context_provider.py similarity index 100% rename from python/samples/getting_started/context_providers/simple_context_provider.py rename to python/samples/02-agents/context_providers/simple_context_provider.py diff --git a/python/samples/getting_started/threads/custom_chat_message_store_thread.py b/python/samples/02-agents/conversations/custom_chat_message_store_thread.py similarity index 100% rename from python/samples/getting_started/threads/custom_chat_message_store_thread.py rename to python/samples/02-agents/conversations/custom_chat_message_store_thread.py diff --git a/python/samples/getting_started/threads/redis_chat_message_store_thread.py b/python/samples/02-agents/conversations/redis_chat_message_store_thread.py similarity index 100% rename from python/samples/getting_started/threads/redis_chat_message_store_thread.py rename to python/samples/02-agents/conversations/redis_chat_message_store_thread.py diff --git a/python/samples/getting_started/threads/suspend_resume_thread.py b/python/samples/02-agents/conversations/suspend_resume_thread.py similarity index 100% rename from python/samples/getting_started/threads/suspend_resume_thread.py rename to python/samples/02-agents/conversations/suspend_resume_thread.py diff --git a/python/samples/getting_started/declarative/README.md b/python/samples/02-agents/declarative/README.md similarity index 100% rename from python/samples/getting_started/declarative/README.md rename to python/samples/02-agents/declarative/README.md diff --git a/python/samples/getting_started/declarative/azure_openai_responses_agent.py b/python/samples/02-agents/declarative/azure_openai_responses_agent.py similarity index 100% rename from python/samples/getting_started/declarative/azure_openai_responses_agent.py rename to python/samples/02-agents/declarative/azure_openai_responses_agent.py diff --git a/python/samples/getting_started/declarative/get_weather_agent.py b/python/samples/02-agents/declarative/get_weather_agent.py similarity index 100% rename from python/samples/getting_started/declarative/get_weather_agent.py rename to python/samples/02-agents/declarative/get_weather_agent.py diff --git a/python/samples/getting_started/declarative/inline_yaml.py b/python/samples/02-agents/declarative/inline_yaml.py similarity index 100% rename from python/samples/getting_started/declarative/inline_yaml.py rename to python/samples/02-agents/declarative/inline_yaml.py diff --git a/python/samples/getting_started/declarative/mcp_tool_yaml.py b/python/samples/02-agents/declarative/mcp_tool_yaml.py similarity index 100% rename from python/samples/getting_started/declarative/mcp_tool_yaml.py rename to python/samples/02-agents/declarative/mcp_tool_yaml.py diff --git a/python/samples/getting_started/declarative/microsoft_learn_agent.py b/python/samples/02-agents/declarative/microsoft_learn_agent.py similarity index 100% rename from python/samples/getting_started/declarative/microsoft_learn_agent.py rename to python/samples/02-agents/declarative/microsoft_learn_agent.py diff --git a/python/samples/getting_started/declarative/openai_responses_agent.py b/python/samples/02-agents/declarative/openai_responses_agent.py similarity index 100% rename from python/samples/getting_started/declarative/openai_responses_agent.py rename to python/samples/02-agents/declarative/openai_responses_agent.py diff --git a/python/samples/getting_started/devui/.gitignore b/python/samples/02-agents/devui/.gitignore similarity index 100% rename from python/samples/getting_started/devui/.gitignore rename to python/samples/02-agents/devui/.gitignore diff --git a/python/samples/getting_started/devui/README.md b/python/samples/02-agents/devui/README.md similarity index 98% rename from python/samples/getting_started/devui/README.md rename to python/samples/02-agents/devui/README.md index 5c16e1de71..2bdd6d2233 100644 --- a/python/samples/getting_started/devui/README.md +++ b/python/samples/02-agents/devui/README.md @@ -21,7 +21,7 @@ DevUI is a sample application that provides: Run a single sample directly. This demonstrates how to wrap agents and workflows programmatically without needing a directory structure: ```bash -cd python/samples/getting_started/devui +cd python/samples/02-agents/devui python in_memory_mode.py ``` @@ -32,7 +32,7 @@ This opens your browser at http://localhost:8090 with pre-configured agents and Launch DevUI to discover all samples in this folder: ```bash -cd python/samples/getting_started/devui +cd python/samples/02-agents/devui devui ``` diff --git a/python/samples/getting_started/devui/azure_responses_agent/.env.example b/python/samples/02-agents/devui/azure_responses_agent/.env.example similarity index 100% rename from python/samples/getting_started/devui/azure_responses_agent/.env.example rename to python/samples/02-agents/devui/azure_responses_agent/.env.example diff --git a/python/samples/getting_started/devui/azure_responses_agent/__init__.py b/python/samples/02-agents/devui/azure_responses_agent/__init__.py similarity index 100% rename from python/samples/getting_started/devui/azure_responses_agent/__init__.py rename to python/samples/02-agents/devui/azure_responses_agent/__init__.py diff --git a/python/samples/getting_started/devui/azure_responses_agent/agent.py b/python/samples/02-agents/devui/azure_responses_agent/agent.py similarity index 96% rename from python/samples/getting_started/devui/azure_responses_agent/agent.py rename to python/samples/02-agents/devui/azure_responses_agent/agent.py index bf167f55c2..2293367027 100644 --- a/python/samples/getting_started/devui/azure_responses_agent/agent.py +++ b/python/samples/02-agents/devui/azure_responses_agent/agent.py @@ -50,7 +50,7 @@ def analyze_content( return f"Analyzing content for: {query}" -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def summarize_document( length: Annotated[str, "Desired summary length: 'brief', 'medium', or 'detailed'"] = "medium", diff --git a/python/samples/getting_started/devui/declarative/__init__.py b/python/samples/02-agents/devui/declarative/__init__.py similarity index 100% rename from python/samples/getting_started/devui/declarative/__init__.py rename to python/samples/02-agents/devui/declarative/__init__.py diff --git a/python/samples/getting_started/devui/declarative/workflow.py b/python/samples/02-agents/devui/declarative/workflow.py similarity index 100% rename from python/samples/getting_started/devui/declarative/workflow.py rename to python/samples/02-agents/devui/declarative/workflow.py diff --git a/python/samples/getting_started/devui/declarative/workflow.yaml b/python/samples/02-agents/devui/declarative/workflow.yaml similarity index 100% rename from python/samples/getting_started/devui/declarative/workflow.yaml rename to python/samples/02-agents/devui/declarative/workflow.yaml diff --git a/python/samples/getting_started/devui/fanout_workflow/__init__.py b/python/samples/02-agents/devui/fanout_workflow/__init__.py similarity index 100% rename from python/samples/getting_started/devui/fanout_workflow/__init__.py rename to python/samples/02-agents/devui/fanout_workflow/__init__.py diff --git a/python/samples/getting_started/devui/fanout_workflow/workflow.py b/python/samples/02-agents/devui/fanout_workflow/workflow.py similarity index 100% rename from python/samples/getting_started/devui/fanout_workflow/workflow.py rename to python/samples/02-agents/devui/fanout_workflow/workflow.py diff --git a/python/samples/getting_started/devui/foundry_agent/.env.example b/python/samples/02-agents/devui/foundry_agent/.env.example similarity index 100% rename from python/samples/getting_started/devui/foundry_agent/.env.example rename to python/samples/02-agents/devui/foundry_agent/.env.example diff --git a/python/samples/getting_started/devui/foundry_agent/__init__.py b/python/samples/02-agents/devui/foundry_agent/__init__.py similarity index 100% rename from python/samples/getting_started/devui/foundry_agent/__init__.py rename to python/samples/02-agents/devui/foundry_agent/__init__.py diff --git a/python/samples/getting_started/devui/foundry_agent/agent.py b/python/samples/02-agents/devui/foundry_agent/agent.py similarity index 93% rename from python/samples/getting_started/devui/foundry_agent/agent.py rename to python/samples/02-agents/devui/foundry_agent/agent.py index 01a033689b..e4f8c17079 100644 --- a/python/samples/getting_started/devui/foundry_agent/agent.py +++ b/python/samples/02-agents/devui/foundry_agent/agent.py @@ -14,7 +14,7 @@ from azure.identity.aio import AzureCliCredential from pydantic import Field -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/devui/in_memory_mode.py b/python/samples/02-agents/devui/in_memory_mode.py similarity index 95% rename from python/samples/getting_started/devui/in_memory_mode.py rename to python/samples/02-agents/devui/in_memory_mode.py index 5d32861740..983164a484 100644 --- a/python/samples/getting_started/devui/in_memory_mode.py +++ b/python/samples/02-agents/devui/in_memory_mode.py @@ -16,7 +16,7 @@ from agent_framework.devui import serve from typing_extensions import Never -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") # Tool functions for the agent @tool(approval_mode="never_require") diff --git a/python/samples/getting_started/devui/spam_workflow/__init__.py b/python/samples/02-agents/devui/spam_workflow/__init__.py similarity index 100% rename from python/samples/getting_started/devui/spam_workflow/__init__.py rename to python/samples/02-agents/devui/spam_workflow/__init__.py diff --git a/python/samples/getting_started/devui/spam_workflow/workflow.py b/python/samples/02-agents/devui/spam_workflow/workflow.py similarity index 100% rename from python/samples/getting_started/devui/spam_workflow/workflow.py rename to python/samples/02-agents/devui/spam_workflow/workflow.py diff --git a/python/samples/getting_started/devui/weather_agent_azure/.env.example b/python/samples/02-agents/devui/weather_agent_azure/.env.example similarity index 100% rename from python/samples/getting_started/devui/weather_agent_azure/.env.example rename to python/samples/02-agents/devui/weather_agent_azure/.env.example diff --git a/python/samples/getting_started/devui/weather_agent_azure/__init__.py b/python/samples/02-agents/devui/weather_agent_azure/__init__.py similarity index 100% rename from python/samples/getting_started/devui/weather_agent_azure/__init__.py rename to python/samples/02-agents/devui/weather_agent_azure/__init__.py diff --git a/python/samples/getting_started/devui/weather_agent_azure/agent.py b/python/samples/02-agents/devui/weather_agent_azure/agent.py similarity index 97% rename from python/samples/getting_started/devui/weather_agent_azure/agent.py rename to python/samples/02-agents/devui/weather_agent_azure/agent.py index a754d32ead..a4c531b7ce 100644 --- a/python/samples/getting_started/devui/weather_agent_azure/agent.py +++ b/python/samples/02-agents/devui/weather_agent_azure/agent.py @@ -101,7 +101,7 @@ async def atlantis_location_filter_middleware( await call_next() -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, "The location to get the weather for."], diff --git a/python/samples/getting_started/devui/workflow_agents/.env.example b/python/samples/02-agents/devui/workflow_agents/.env.example similarity index 100% rename from python/samples/getting_started/devui/workflow_agents/.env.example rename to python/samples/02-agents/devui/workflow_agents/.env.example diff --git a/python/samples/getting_started/devui/workflow_agents/__init__.py b/python/samples/02-agents/devui/workflow_agents/__init__.py similarity index 100% rename from python/samples/getting_started/devui/workflow_agents/__init__.py rename to python/samples/02-agents/devui/workflow_agents/__init__.py diff --git a/python/samples/getting_started/devui/workflow_agents/workflow.py b/python/samples/02-agents/devui/workflow_agents/workflow.py similarity index 100% rename from python/samples/getting_started/devui/workflow_agents/workflow.py rename to python/samples/02-agents/devui/workflow_agents/workflow.py diff --git a/python/samples/getting_started/mcp/README.md b/python/samples/02-agents/mcp/README.md similarity index 100% rename from python/samples/getting_started/mcp/README.md rename to python/samples/02-agents/mcp/README.md diff --git a/python/samples/getting_started/mcp/agent_as_mcp_server.py b/python/samples/02-agents/mcp/agent_as_mcp_server.py similarity index 92% rename from python/samples/getting_started/mcp/agent_as_mcp_server.py rename to python/samples/02-agents/mcp/agent_as_mcp_server.py index 7d09663625..ad94a0cec6 100644 --- a/python/samples/getting_started/mcp/agent_as_mcp_server.py +++ b/python/samples/02-agents/mcp/agent_as_mcp_server.py @@ -32,7 +32,7 @@ with the following configuration: """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_specials() -> Annotated[str, "Returns the specials from the menu."]: return """ diff --git a/python/samples/getting_started/mcp/mcp_api_key_auth.py b/python/samples/02-agents/mcp/mcp_api_key_auth.py similarity index 100% rename from python/samples/getting_started/mcp/mcp_api_key_auth.py rename to python/samples/02-agents/mcp/mcp_api_key_auth.py diff --git a/python/samples/getting_started/mcp/mcp_github_pat.py b/python/samples/02-agents/mcp/mcp_github_pat.py similarity index 100% rename from python/samples/getting_started/mcp/mcp_github_pat.py rename to python/samples/02-agents/mcp/mcp_github_pat.py diff --git a/python/samples/getting_started/middleware/agent_and_run_level_middleware.py b/python/samples/02-agents/middleware/agent_and_run_level_middleware.py similarity index 98% rename from python/samples/getting_started/middleware/agent_and_run_level_middleware.py rename to python/samples/02-agents/middleware/agent_and_run_level_middleware.py index 1f80c7742f..9ab0eb3692 100644 --- a/python/samples/getting_started/middleware/agent_and_run_level_middleware.py +++ b/python/samples/02-agents/middleware/agent_and_run_level_middleware.py @@ -54,7 +54,7 @@ Agent Middleware Execution Order: """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/middleware/chat_middleware.py b/python/samples/02-agents/middleware/chat_middleware.py similarity index 98% rename from python/samples/getting_started/middleware/chat_middleware.py rename to python/samples/02-agents/middleware/chat_middleware.py index f0c9ef153e..3370d56901 100644 --- a/python/samples/getting_started/middleware/chat_middleware.py +++ b/python/samples/02-agents/middleware/chat_middleware.py @@ -37,7 +37,7 @@ The example covers: """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/middleware/class_based_middleware.py b/python/samples/02-agents/middleware/class_based_middleware.py similarity index 96% rename from python/samples/getting_started/middleware/class_based_middleware.py rename to python/samples/02-agents/middleware/class_based_middleware.py index e3cb884c69..bad4e08a26 100644 --- a/python/samples/getting_started/middleware/class_based_middleware.py +++ b/python/samples/02-agents/middleware/class_based_middleware.py @@ -34,7 +34,7 @@ from object-oriented design patterns. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/middleware/decorator_middleware.py b/python/samples/02-agents/middleware/decorator_middleware.py similarity index 95% rename from python/samples/getting_started/middleware/decorator_middleware.py rename to python/samples/02-agents/middleware/decorator_middleware.py index e432473a30..9d90d6205a 100644 --- a/python/samples/getting_started/middleware/decorator_middleware.py +++ b/python/samples/02-agents/middleware/decorator_middleware.py @@ -42,7 +42,7 @@ Key benefits of decorator approach: """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_current_time() -> str: """Get the current time.""" diff --git a/python/samples/getting_started/middleware/exception_handling_with_middleware.py b/python/samples/02-agents/middleware/exception_handling_with_middleware.py similarity index 94% rename from python/samples/getting_started/middleware/exception_handling_with_middleware.py rename to python/samples/02-agents/middleware/exception_handling_with_middleware.py index 1f7ed59542..d2042424ca 100644 --- a/python/samples/getting_started/middleware/exception_handling_with_middleware.py +++ b/python/samples/02-agents/middleware/exception_handling_with_middleware.py @@ -24,7 +24,7 @@ a helpful message for the user, preventing raw exceptions from reaching the end """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def unstable_data_service( query: Annotated[str, Field(description="The data query to execute.")], diff --git a/python/samples/getting_started/middleware/function_based_middleware.py b/python/samples/02-agents/middleware/function_based_middleware.py similarity index 95% rename from python/samples/getting_started/middleware/function_based_middleware.py rename to python/samples/02-agents/middleware/function_based_middleware.py index 38272a4cd1..0c839775e3 100644 --- a/python/samples/getting_started/middleware/function_based_middleware.py +++ b/python/samples/02-agents/middleware/function_based_middleware.py @@ -31,7 +31,7 @@ can be implemented as async functions that accept context and call_next paramete """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/middleware/middleware_termination.py b/python/samples/02-agents/middleware/middleware_termination.py similarity index 97% rename from python/samples/getting_started/middleware/middleware_termination.py rename to python/samples/02-agents/middleware/middleware_termination.py index ce2db3e376..8d99283782 100644 --- a/python/samples/getting_started/middleware/middleware_termination.py +++ b/python/samples/02-agents/middleware/middleware_termination.py @@ -30,7 +30,7 @@ This is useful for implementing security checks, rate limiting, or early exit co """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/middleware/override_result_with_middleware.py b/python/samples/02-agents/middleware/override_result_with_middleware.py similarity index 97% rename from python/samples/getting_started/middleware/override_result_with_middleware.py rename to python/samples/02-agents/middleware/override_result_with_middleware.py index d05ec1b4f3..0d02d7dbb6 100644 --- a/python/samples/getting_started/middleware/override_result_with_middleware.py +++ b/python/samples/02-agents/middleware/override_result_with_middleware.py @@ -39,7 +39,7 @@ it creates a custom async generator that yields the override message in chunks. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/middleware/runtime_context_delegation.py b/python/samples/02-agents/middleware/runtime_context_delegation.py similarity index 98% rename from python/samples/getting_started/middleware/runtime_context_delegation.py rename to python/samples/02-agents/middleware/runtime_context_delegation.py index d839960da7..409202db0f 100644 --- a/python/samples/getting_started/middleware/runtime_context_delegation.py +++ b/python/samples/02-agents/middleware/runtime_context_delegation.py @@ -81,7 +81,7 @@ class SessionContextContainer: runtime_context = SessionContextContainer() -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def send_email( to: Annotated[str, Field(description="Recipient email address")], diff --git a/python/samples/getting_started/middleware/shared_state_middleware.py b/python/samples/02-agents/middleware/shared_state_middleware.py similarity index 96% rename from python/samples/getting_started/middleware/shared_state_middleware.py rename to python/samples/02-agents/middleware/shared_state_middleware.py index a3aae59ccd..d4953e782e 100644 --- a/python/samples/getting_started/middleware/shared_state_middleware.py +++ b/python/samples/02-agents/middleware/shared_state_middleware.py @@ -27,7 +27,7 @@ This approach shows how middleware can work together by sharing state within the """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/middleware/thread_behavior_middleware.py b/python/samples/02-agents/middleware/thread_behavior_middleware.py similarity index 95% rename from python/samples/getting_started/middleware/thread_behavior_middleware.py rename to python/samples/02-agents/middleware/thread_behavior_middleware.py index 680fd01d50..b09e50a5c0 100644 --- a/python/samples/getting_started/middleware/thread_behavior_middleware.py +++ b/python/samples/02-agents/middleware/thread_behavior_middleware.py @@ -32,7 +32,7 @@ Key behaviors demonstrated: """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/multimodal_input/README.md b/python/samples/02-agents/multimodal_input/README.md similarity index 100% rename from python/samples/getting_started/multimodal_input/README.md rename to python/samples/02-agents/multimodal_input/README.md diff --git a/python/samples/getting_started/multimodal_input/azure_chat_multimodal.py b/python/samples/02-agents/multimodal_input/azure_chat_multimodal.py similarity index 100% rename from python/samples/getting_started/multimodal_input/azure_chat_multimodal.py rename to python/samples/02-agents/multimodal_input/azure_chat_multimodal.py diff --git a/python/samples/getting_started/multimodal_input/azure_responses_multimodal.py b/python/samples/02-agents/multimodal_input/azure_responses_multimodal.py similarity index 97% rename from python/samples/getting_started/multimodal_input/azure_responses_multimodal.py rename to python/samples/02-agents/multimodal_input/azure_responses_multimodal.py index decf27aefe..7a71553f1e 100644 --- a/python/samples/getting_started/multimodal_input/azure_responses_multimodal.py +++ b/python/samples/02-agents/multimodal_input/azure_responses_multimodal.py @@ -7,7 +7,7 @@ from agent_framework import Content, Message from agent_framework.azure import AzureOpenAIResponsesClient from azure.identity import AzureCliCredential -ASSETS_DIR = Path(__file__).resolve().parent.parent / "sample_assets" +ASSETS_DIR = Path(__file__).resolve().parents[2] / "shared" / "sample_assets" def load_sample_pdf() -> bytes: diff --git a/python/samples/getting_started/multimodal_input/openai_chat_multimodal.py b/python/samples/02-agents/multimodal_input/openai_chat_multimodal.py similarity index 97% rename from python/samples/getting_started/multimodal_input/openai_chat_multimodal.py rename to python/samples/02-agents/multimodal_input/openai_chat_multimodal.py index f34576c00f..f752d8a52c 100644 --- a/python/samples/getting_started/multimodal_input/openai_chat_multimodal.py +++ b/python/samples/02-agents/multimodal_input/openai_chat_multimodal.py @@ -8,7 +8,7 @@ from pathlib import Path from agent_framework import Content, Message from agent_framework.openai import OpenAIChatClient -ASSETS_DIR = Path(__file__).resolve().parent.parent / "sample_assets" +ASSETS_DIR = Path(__file__).resolve().parents[2] / "shared" / "sample_assets" def load_sample_pdf() -> bytes: diff --git a/python/samples/getting_started/observability/.env.example b/python/samples/02-agents/observability/.env.example similarity index 100% rename from python/samples/getting_started/observability/.env.example rename to python/samples/02-agents/observability/.env.example diff --git a/python/samples/getting_started/observability/README.md b/python/samples/02-agents/observability/README.md similarity index 99% rename from python/samples/getting_started/observability/README.md rename to python/samples/02-agents/observability/README.md index d42162b23c..d0e4ea06d1 100644 --- a/python/samples/getting_started/observability/README.md +++ b/python/samples/02-agents/observability/README.md @@ -212,7 +212,7 @@ This folder contains different samples demonstrating how to use telemetry in var ### Running the samples -1. Open a terminal and navigate to this folder: `python/samples/getting_started/observability/`. This is necessary for the `.env` file to be read correctly. +1. Open a terminal and navigate to this folder: `python/samples/02-agents/observability/`. This is necessary for the `.env` file to be read correctly. 2. Create a `.env` file if one doesn't already exist in this folder. Please refer to the [example file](./.env.example). > **Note**: You can start with just `ENABLE_INSTRUMENTATION=true` and add `OTEL_EXPORTER_OTLP_ENDPOINT` or other configuration as needed. If no exporters are configured, you can set `ENABLE_CONSOLE_EXPORTERS=true` for console output. 3. Activate your python virtual environment, and then run `python configure_otel_providers_with_env_var.py` or others. diff --git a/python/samples/getting_started/observability/__init__.py b/python/samples/02-agents/observability/__init__.py similarity index 100% rename from python/samples/getting_started/observability/__init__.py rename to python/samples/02-agents/observability/__init__.py diff --git a/python/samples/getting_started/observability/advanced_manual_setup_console_output.py b/python/samples/02-agents/observability/advanced_manual_setup_console_output.py similarity index 96% rename from python/samples/getting_started/observability/advanced_manual_setup_console_output.py rename to python/samples/02-agents/observability/advanced_manual_setup_console_output.py index 0b6a908b0d..36e15539ae 100644 --- a/python/samples/getting_started/observability/advanced_manual_setup_console_output.py +++ b/python/samples/02-agents/observability/advanced_manual_setup_console_output.py @@ -66,7 +66,7 @@ def setup_metrics(): set_meter_provider(meter_provider) -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/observability/advanced_zero_code.py b/python/samples/02-agents/observability/advanced_zero_code.py similarity index 89% rename from python/samples/getting_started/observability/advanced_zero_code.py rename to python/samples/02-agents/observability/advanced_zero_code.py index ef4fe3b202..b4ee48bdc4 100644 --- a/python/samples/getting_started/observability/advanced_zero_code.py +++ b/python/samples/02-agents/observability/advanced_zero_code.py @@ -31,16 +31,16 @@ opentelemetry-enable_instrumentation \ --metrics_exporter otlp \ --service_name agent_framework \ --exporter_otlp_endpoint http://localhost:4317 \ - python samples/getting_started/observability/advanced_zero_code.py + python python/samples/02-agents/observability/advanced_zero_code.py ``` -(or use uv run in front when you have did the install within your uv virtual environment) +(or use uv run in front when you've done the install within your uv virtual environment) You can also set the environment variables instead of passing them as CLI arguments. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], @@ -65,7 +65,7 @@ async def run_chat_client(client: "SupportsChatGetResponse", stream: bool = Fals Remarks: When function calling is outside the open telemetry loop - each of the call to the model is handled as a seperate span, + each of the call to the model is handled as a separate span, while when the open telemetry is put last, a single span is shown, which might include one or more rounds of function calling. diff --git a/python/samples/getting_started/observability/agent_observability.py b/python/samples/02-agents/observability/agent_observability.py similarity index 92% rename from python/samples/getting_started/observability/agent_observability.py rename to python/samples/02-agents/observability/agent_observability.py index 606b633a1c..46bc92b74a 100644 --- a/python/samples/getting_started/observability/agent_observability.py +++ b/python/samples/02-agents/observability/agent_observability.py @@ -17,7 +17,7 @@ same observability setup function. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/observability/agent_with_foundry_tracing.py b/python/samples/02-agents/observability/agent_with_foundry_tracing.py similarity index 94% rename from python/samples/getting_started/observability/agent_with_foundry_tracing.py rename to python/samples/02-agents/observability/agent_with_foundry_tracing.py index 2b67ba9ea6..bd46e81fef 100644 --- a/python/samples/getting_started/observability/agent_with_foundry_tracing.py +++ b/python/samples/02-agents/observability/agent_with_foundry_tracing.py @@ -5,7 +5,7 @@ # ] # /// # Run with any PEP 723 compatible runner, e.g.: -# uv run samples/getting_started/observability/agent_with_foundry_tracing.py +# uv run python/samples/02-agents/observability/agent_with_foundry_tracing.py # Copyright (c) Microsoft. All rights reserved. @@ -41,7 +41,7 @@ dotenv.load_dotenv() logger = logging.getLogger(__name__) -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/observability/azure_ai_agent_observability.py b/python/samples/02-agents/observability/azure_ai_agent_observability.py similarity index 92% rename from python/samples/getting_started/observability/azure_ai_agent_observability.py rename to python/samples/02-agents/observability/azure_ai_agent_observability.py index e7036cd9e4..90946ad026 100644 --- a/python/samples/getting_started/observability/azure_ai_agent_observability.py +++ b/python/samples/02-agents/observability/azure_ai_agent_observability.py @@ -16,7 +16,7 @@ from opentelemetry.trace.span import format_trace_id from pydantic import Field """ -This sample shows you can can setup telemetry for an Azure AI agent. +This sample shows you can setup telemetry for an Azure AI agent. It uses the Azure AI client to setup the telemetry, this calls out to Azure AI for the connection string of the attached Application Insights instance. @@ -29,7 +29,7 @@ for this sample to work. dotenv.load_dotenv() -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/observability/configure_otel_providers_with_env_var.py b/python/samples/02-agents/observability/configure_otel_providers_with_env_var.py similarity index 93% rename from python/samples/getting_started/observability/configure_otel_providers_with_env_var.py rename to python/samples/02-agents/observability/configure_otel_providers_with_env_var.py index 379f5c95f6..50f066fce1 100644 --- a/python/samples/getting_started/observability/configure_otel_providers_with_env_var.py +++ b/python/samples/02-agents/observability/configure_otel_providers_with_env_var.py @@ -17,7 +17,7 @@ if TYPE_CHECKING: from agent_framework import SupportsChatGetResponse """ -This sample, show how you can configure observability of an application via the +This sample shows how you can configure observability of an application via the `configure_otel_providers` function with environment variables. When you run this sample with an OTLP endpoint or an Application Insights connection string, @@ -31,7 +31,7 @@ output traces, logs, and metrics to the console. SCENARIOS = ["client", "client_stream", "tool", "all"] -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], @@ -104,7 +104,7 @@ async def main(scenario: Literal["client", "client_stream", "tool", "all"] = "al # based on environment variables. See the .env.example file for the available configuration options. configure_otel_providers() - with get_tracer().start_as_current_span("Sample Scenario's", kind=trace.SpanKind.CLIENT) as current_span: + with get_tracer().start_as_current_span("Sample Scenarios", kind=trace.SpanKind.CLIENT) as current_span: print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}") client = OpenAIResponsesClient() diff --git a/python/samples/getting_started/observability/configure_otel_providers_with_parameters.py b/python/samples/02-agents/observability/configure_otel_providers_with_parameters.py similarity index 95% rename from python/samples/getting_started/observability/configure_otel_providers_with_parameters.py rename to python/samples/02-agents/observability/configure_otel_providers_with_parameters.py index f04bd2cd22..b75fd42325 100644 --- a/python/samples/getting_started/observability/configure_otel_providers_with_parameters.py +++ b/python/samples/02-agents/observability/configure_otel_providers_with_parameters.py @@ -31,7 +31,7 @@ Use this approach when you need custom exporter configuration beyond what enviro SCENARIOS = ["client", "client_stream", "tool", "all"] -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], @@ -139,7 +139,7 @@ async def main(scenario: Literal["client", "client_stream", "tool", "all"] = "al exporters=custom_exporters, ) - with get_tracer().start_as_current_span("Sample Scenario's", kind=trace.SpanKind.CLIENT) as current_span: + with get_tracer().start_as_current_span("Sample Scenarios", kind=trace.SpanKind.CLIENT) as current_span: print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}") client = OpenAIResponsesClient() diff --git a/python/samples/getting_started/observability/workflow_observability.py b/python/samples/02-agents/observability/workflow_observability.py similarity index 100% rename from python/samples/getting_started/observability/workflow_observability.py rename to python/samples/02-agents/observability/workflow_observability.py diff --git a/python/samples/02-agents/orchestrations/README.md b/python/samples/02-agents/orchestrations/README.md new file mode 100644 index 0000000000..cebfcf2891 --- /dev/null +++ b/python/samples/02-agents/orchestrations/README.md @@ -0,0 +1,67 @@ +# Orchestration Getting Started Samples + +## Installation + +The orchestrations package is included when you install `agent-framework` (which pulls in all optional packages): + +```bash +pip install agent-framework +``` + +Or install the orchestrations package directly: + +```bash +pip install agent-framework-orchestrations +``` + +Orchestration builders are available via the `agent_framework.orchestrations` submodule: + +```python +from agent_framework.orchestrations import ( + SequentialBuilder, + ConcurrentBuilder, + HandoffBuilder, + GroupChatBuilder, + MagenticBuilder, +) +``` + +## Samples Overview + +| Sample | File | Concepts | +| ------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| Concurrent Orchestration (Default Aggregator) | [concurrent_agents.py](./concurrent_agents.py) | Fan-out to multiple agents; fan-in with default aggregator returning combined Messages | +| Concurrent Orchestration (Custom Aggregator) | [concurrent_custom_aggregator.py](./concurrent_custom_aggregator.py) | Override aggregator via callback; summarize results with an LLM | +| Concurrent Orchestration (Custom Agent Executors) | [concurrent_custom_agent_executors.py](./concurrent_custom_agent_executors.py) | Child executors own Agents; concurrent fan-out/fan-in via ConcurrentBuilder | +| Group Chat with Agent Manager | [group_chat_agent_manager.py](./group_chat_agent_manager.py) | Agent-based manager using `with_orchestrator(agent=)` to select next speaker | +| Group Chat Philosophical Debate | [group_chat_philosophical_debate.py](./group_chat_philosophical_debate.py) | Agent manager moderates long-form, multi-round debate across diverse participants | +| Group Chat with Simple Function Selector | [group_chat_simple_selector.py](./group_chat_simple_selector.py) | Group chat with a simple function selector for next speaker | +| Handoff (Simple) | [handoff_simple.py](./handoff_simple.py) | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response | +| Handoff (Autonomous) | [handoff_autonomous.py](./handoff_autonomous.py) | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_autonomous_mode()` | +| Handoff with Code Interpreter | [handoff_with_code_interpreter_file.py](./handoff_with_code_interpreter_file.py) | Retrieve file IDs from code interpreter output in handoff workflow | +| Magentic Workflow (Multi-Agent) | [magentic.py](./magentic.py) | Orchestrate multiple agents with Magentic manager and streaming | +| Magentic + Human Plan Review | [magentic_human_plan_review.py](./magentic_human_plan_review.py) | Human reviews/updates the plan before execution | +| Magentic + Checkpoint Resume | [magentic_checkpoint.py](./magentic_checkpoint.py) | Resume Magentic orchestration from saved checkpoints | +| Sequential Orchestration (Agents) | [sequential_agents.py](./sequential_agents.py) | Chain agents sequentially with shared conversation context | +| Sequential Orchestration (Custom Executor) | [sequential_custom_executors.py](./sequential_custom_executors.py) | Mix agents with a summarizer that appends a compact summary | + +## Tips + +**Magentic checkpointing tip**: Treat `MagenticBuilder.participants` keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast. + +**Handoff workflow tip**: Handoff workflows maintain the full conversation history including any `Message.additional_properties` emitted by your agents. This ensures routing metadata remains intact across all agent transitions. For specialist-to-specialist handoffs, use `.add_handoff(source, targets)` to configure which agents can route to which others with a fluent, type-safe API. + +**Sequential orchestration note**: Sequential orchestration uses a few small adapter nodes for plumbing: +- `input-conversation` normalizes input to `list[Message]` +- `to-conversation:` converts agent responses into the shared conversation +- `complete` publishes the final output event (type='output') + +These may appear in event streams (executor_invoked/executor_completed). They're analogous to concurrent's dispatcher and aggregator and can be ignored if you only care about agent activity. + +## Environment Variables + +- **AzureOpenAIChatClient**: Set Azure OpenAI environment variables as documented [here](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/chat_client/README.md#environment-variables). + +- **OpenAI** (used in some orchestration samples): + - [OpenAIChatClient env vars](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/openai/README.md) + - [OpenAIResponsesClient env vars](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/openai/README.md) diff --git a/python/samples/getting_started/orchestrations/concurrent/concurrent_agents.py b/python/samples/02-agents/orchestrations/concurrent_agents.py similarity index 89% rename from python/samples/getting_started/orchestrations/concurrent/concurrent_agents.py rename to python/samples/02-agents/orchestrations/concurrent_agents.py index 8a2cccd7d2..2d216a131b 100644 --- a/python/samples/getting_started/orchestrations/concurrent/concurrent_agents.py +++ b/python/samples/02-agents/orchestrations/concurrent_agents.py @@ -1,11 +1,10 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import Any from agent_framework import Message -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import ConcurrentBuilder from azure.identity import AzureCliCredential @@ -23,19 +22,14 @@ Demonstrates: - Workflow completion when idle with no pending work Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Azure OpenAI access configured for AzureOpenAIResponsesClient (use az login + env vars) +- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars) - Familiarity with Workflow events (WorkflowEvent) """ async def main() -> None: - # 1) Create three domain agents using AzureOpenAIResponsesClient - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + # 1) Create three domain agents using AzureOpenAIChatClient + client = AzureOpenAIChatClient(credential=AzureCliCredential()) researcher = client.as_agent( instructions=( diff --git a/python/samples/getting_started/orchestrations/concurrent/concurrent_custom_agent_executors.py b/python/samples/02-agents/orchestrations/concurrent_custom_agent_executors.py similarity index 89% rename from python/samples/getting_started/orchestrations/concurrent/concurrent_custom_agent_executors.py rename to python/samples/02-agents/orchestrations/concurrent_custom_agent_executors.py index 99c0093831..bd3b8b93a5 100644 --- a/python/samples/getting_started/orchestrations/concurrent/concurrent_custom_agent_executors.py +++ b/python/samples/02-agents/orchestrations/concurrent_custom_agent_executors.py @@ -1,7 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import Any from agent_framework import ( @@ -13,7 +12,7 @@ from agent_framework import ( WorkflowContext, handler, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import ConcurrentBuilder from azure.identity import AzureCliCredential @@ -26,22 +25,21 @@ and emit AgentExecutorResponse outputs, which allows reuse of the high-level ConcurrentBuilder API and the default aggregator. Demonstrates: -- Executors that create their Agent in __init__ (via AzureOpenAIResponsesClient) +- Executors that create their Agent in __init__ (via AzureOpenAIChatClient) - A @handler that converts AgentExecutorRequest -> AgentExecutorResponse - ConcurrentBuilder(participants=[...]) to build fan-out/fan-in - Default aggregator returning list[Message] (one user + one assistant per agent) - Workflow completion when all participants become idle Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Azure OpenAI configured for AzureOpenAIResponsesClient (az login + required env vars) +- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars) """ class ResearcherExec(Executor): agent: Agent - def __init__(self, client: AzureOpenAIResponsesClient, id: str = "researcher"): + def __init__(self, client: AzureOpenAIChatClient, id: str = "researcher"): self.agent = client.as_agent( instructions=( "You're an expert market and product researcher. Given a prompt, provide concise, factual insights," @@ -61,7 +59,7 @@ class ResearcherExec(Executor): class MarketerExec(Executor): agent: Agent - def __init__(self, client: AzureOpenAIResponsesClient, id: str = "marketer"): + def __init__(self, client: AzureOpenAIChatClient, id: str = "marketer"): self.agent = client.as_agent( instructions=( "You're a creative marketing strategist. Craft compelling value propositions and target messaging" @@ -81,7 +79,7 @@ class MarketerExec(Executor): class LegalExec(Executor): agent: Agent - def __init__(self, client: AzureOpenAIResponsesClient, id: str = "legal"): + def __init__(self, client: AzureOpenAIChatClient, id: str = "legal"): self.agent = client.as_agent( instructions=( "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns" @@ -99,11 +97,7 @@ class LegalExec(Executor): async def main() -> None: - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) researcher = ResearcherExec(client) marketer = MarketerExec(client) diff --git a/python/samples/getting_started/orchestrations/concurrent/concurrent_custom_aggregator.py b/python/samples/02-agents/orchestrations/concurrent_custom_aggregator.py similarity index 88% rename from python/samples/getting_started/orchestrations/concurrent/concurrent_custom_aggregator.py rename to python/samples/02-agents/orchestrations/concurrent_custom_aggregator.py index f7870814dc..17b1496e0b 100644 --- a/python/samples/getting_started/orchestrations/concurrent/concurrent_custom_aggregator.py +++ b/python/samples/02-agents/orchestrations/concurrent_custom_aggregator.py @@ -1,11 +1,10 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import Any from agent_framework import Message -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import ConcurrentBuilder from azure.identity import AzureCliCredential @@ -14,7 +13,7 @@ Sample: Concurrent Orchestration with Custom Aggregator Build a concurrent workflow with ConcurrentBuilder that fans out one prompt to multiple domain agents and fans in their responses. Override the default -aggregator with a custom async callback that uses AzureOpenAIResponsesClient.get_response() +aggregator with a custom async callback that uses AzureOpenAIChatClient.get_response() to synthesize a concise, consolidated summary from the experts' outputs. The workflow completes when all participants become idle. @@ -25,17 +24,12 @@ Demonstrates: - Workflow output yielded with the synthesized summary string Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Azure OpenAI configured for AzureOpenAIResponsesClient (az login + required env vars) +- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars) """ async def main() -> None: - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) researcher = client.as_agent( instructions=( @@ -92,7 +86,9 @@ async def main() -> None: # β€’ Default aggregator -> returns list[Message] (one user + one assistant per agent) # β€’ Custom callback -> return value becomes workflow output (string here) # The callback can be sync or async; it receives list[AgentExecutorResponse]. - workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).with_aggregator(summarize_results).build() + workflow = ( + ConcurrentBuilder(participants=[researcher, marketer, legal]).with_aggregator(summarize_results).build() + ) events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.") outputs = events.get_outputs() diff --git a/python/samples/getting_started/orchestrations/group-chat/group_chat_agent_manager.py b/python/samples/02-agents/orchestrations/group_chat_agent_manager.py similarity index 67% rename from python/samples/getting_started/orchestrations/group-chat/group_chat_agent_manager.py rename to python/samples/02-agents/orchestrations/group_chat_agent_manager.py index baeaa79197..78eb8535ae 100644 --- a/python/samples/getting_started/orchestrations/group-chat/group_chat_agent_manager.py +++ b/python/samples/02-agents/orchestrations/group_chat_agent_manager.py @@ -1,7 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import cast from agent_framework import ( @@ -9,7 +8,7 @@ from agent_framework import ( AgentResponseUpdate, Message, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import GroupChatBuilder from azure.identity import AzureCliCredential @@ -22,8 +21,7 @@ What it does: - Coordinates a researcher and writer agent to solve tasks collaboratively Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Environment variables configured for AzureOpenAIResponsesClient +- OpenAI environment variables configured for OpenAIChatClient """ ORCHESTRATOR_AGENT_INSTRUCTIONS = """ @@ -38,11 +36,7 @@ Guidelines: async def main() -> None: # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) # Orchestrator agent that manages the conversation # Note: This agent (and the underlying chat client) must support structured outputs. @@ -94,35 +88,26 @@ async def main() -> None: print(f"TASK: {task}\n") print("=" * 80) - # Track current speaker for readable streaming output. - pending_speaker: str | None = None - current_speaker: str | None = None + # Keep track of the last response to format output nicely in streaming mode + last_response_id: str | None = None async for event in workflow.run(task, stream=True): - if event.type != "output": - continue - - data = event.data - if isinstance(data, AgentResponseUpdate): - if data.author_name: - pending_speaker = data.author_name - if not data.text: - continue - - speaker = data.author_name or pending_speaker or "assistant" - if speaker != current_speaker: - if current_speaker is not None: - print("\n") - print(f"{speaker}:", end=" ", flush=True) - current_speaker = speaker - print(data.text, end="", flush=True) - continue - - # The output of the group chat workflow is a collection of chat messages from all participants - outputs = cast(list[Message], data) - print("\n" + "=" * 80) - print("\nFinal Conversation Transcript:\n") - for message in outputs: - print(f"{message.author_name or message.role}: {message.text}\n") + if event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + rid = data.response_id + if rid != last_response_id: + if last_response_id is not None: + print("\n") + print(f"{data.author_name}:", end=" ", flush=True) + last_response_id = rid + print(data.text, end="", flush=True) + elif event.type == "output": + # The output of the group chat workflow is a collection of chat messages from all participants + outputs = cast(list[Message], event.data) + print("\n" + "=" * 80) + print("\nFinal Conversation Transcript:\n") + for message in outputs: + print(f"{message.author_name or message.role}: {message.text}\n") if __name__ == "__main__": diff --git a/python/samples/getting_started/orchestrations/group-chat/group_chat_philosophical_debate.py b/python/samples/02-agents/orchestrations/group_chat_philosophical_debate.py similarity index 90% rename from python/samples/getting_started/orchestrations/group-chat/group_chat_philosophical_debate.py rename to python/samples/02-agents/orchestrations/group_chat_philosophical_debate.py index 7cb522fb25..e4723c01e0 100644 --- a/python/samples/getting_started/orchestrations/group-chat/group_chat_philosophical_debate.py +++ b/python/samples/02-agents/orchestrations/group_chat_philosophical_debate.py @@ -2,7 +2,6 @@ import asyncio import logging -import os from typing import cast from agent_framework import ( @@ -10,7 +9,7 @@ from agent_framework import ( AgentResponseUpdate, Message, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import GroupChatBuilder from azure.identity import AzureCliCredential @@ -38,17 +37,12 @@ Participants represent: - Doctor from Scandinavia (public health, equity, societal support) Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Environment variables configured for AzureOpenAIResponsesClient +- OpenAI environment variables configured for OpenAIChatClient """ -def _get_chat_client() -> AzureOpenAIResponsesClient: - return AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) +def _get_chat_client() -> AzureOpenAIChatClient: + return AzureOpenAIChatClient(credential=AzureCliCredential()) async def main() -> None: @@ -246,35 +240,26 @@ Share your perspective authentically. Feel free to: print("DISCUSSION BEGINS") print("=" * 80 + "\n") - # Track current speaker for readable streaming output. - pending_speaker: str | None = None - current_speaker: str | None = None + # Keep track of the last response to format output nicely in streaming mode + last_response_id: str | None = None async for event in workflow.run(f"Please begin the discussion on: {topic}", stream=True): - if event.type != "output": - continue - - data = event.data - if isinstance(data, AgentResponseUpdate): - if data.author_name: - pending_speaker = data.author_name - if not data.text: - continue - - speaker = data.author_name or pending_speaker or "assistant" - if speaker != current_speaker: - if current_speaker is not None: - print("\n") - print(f"{speaker}:", end=" ", flush=True) - current_speaker = speaker - print(data.text, end="", flush=True) - continue - - # The output of the group chat workflow is a collection of chat messages from all participants - outputs = cast(list[Message], data) - print("\n" + "=" * 80) - print("\nFinal Conversation Transcript:\n") - for message in outputs: - print(f"{message.author_name or message.role}: {message.text}\n") + if event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + rid = data.response_id + if rid != last_response_id: + if last_response_id is not None: + print("\n") + print(f"{data.author_name}:", end=" ", flush=True) + last_response_id = rid + print(data.text, end="", flush=True) + elif event.type == "output": + # The output of the group chat workflow is a collection of chat messages from all participants + outputs = cast(list[Message], event.data) + print("\n" + "=" * 80) + print("\nFinal Conversation Transcript:\n") + for message in outputs: + print(f"{message.author_name or message.role}: {message.text}\n") """ Sample Output: diff --git a/python/samples/getting_started/orchestrations/group-chat/group_chat_simple_selector.py b/python/samples/02-agents/orchestrations/group_chat_simple_selector.py similarity index 92% rename from python/samples/getting_started/orchestrations/group-chat/group_chat_simple_selector.py rename to python/samples/02-agents/orchestrations/group_chat_simple_selector.py index b57f00cc1b..13cd3d3e5a 100644 --- a/python/samples/getting_started/orchestrations/group-chat/group_chat_simple_selector.py +++ b/python/samples/02-agents/orchestrations/group_chat_simple_selector.py @@ -1,7 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import cast from agent_framework import ( @@ -9,7 +8,7 @@ from agent_framework import ( AgentResponseUpdate, Message, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import GroupChatBuilder, GroupChatState from azure.identity import AzureCliCredential @@ -21,8 +20,7 @@ What it does: - Uses a pure Python function to control speaker selection based on conversation state Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Environment variables configured for AzureOpenAIResponsesClient +- OpenAI environment variables configured for OpenAIChatClient """ @@ -35,11 +33,7 @@ def round_robin_selector(state: GroupChatState) -> str: async def main() -> None: # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) # Participant agents expert = Agent( diff --git a/python/samples/getting_started/orchestrations/handoff/handoff_autonomous.py b/python/samples/02-agents/orchestrations/handoff_autonomous.py similarity index 92% rename from python/samples/getting_started/orchestrations/handoff/handoff_autonomous.py rename to python/samples/02-agents/orchestrations/handoff_autonomous.py index 2d30144742..997d854ef2 100644 --- a/python/samples/getting_started/orchestrations/handoff/handoff_autonomous.py +++ b/python/samples/02-agents/orchestrations/handoff_autonomous.py @@ -2,7 +2,6 @@ import asyncio import logging -import os from typing import cast from agent_framework import ( @@ -11,7 +10,7 @@ from agent_framework import ( Message, resolve_agent_id, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import HandoffBuilder from azure.identity import AzureCliCredential @@ -28,9 +27,8 @@ Routing Pattern: User -> Coordinator -> Specialist (iterates N times) -> Handoff -> Final Output Prerequisites: - - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. - `az login` (Azure CLI authentication) - - Environment variables for AzureOpenAIResponsesClient (AZURE_AI_MODEL_DEPLOYMENT_NAME) + - Environment variables for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.) Key Concepts: - Autonomous interaction mode: agents iterate until they handoff @@ -39,7 +37,7 @@ Key Concepts: def create_agents( - client: AzureOpenAIResponsesClient, + client: AzureOpenAIChatClient, ) -> tuple[Agent, Agent, Agent]: """Create coordinator and specialists for autonomous iteration.""" coordinator = client.as_agent( @@ -75,11 +73,7 @@ def create_agents( async def main() -> None: """Run an autonomous handoff workflow with specialist iteration enabled.""" - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) coordinator, research_agent, summary_agent = create_agents(client) # Build the workflow with autonomous mode diff --git a/python/samples/02-agents/orchestrations/handoff_simple.py b/python/samples/02-agents/orchestrations/handoff_simple.py new file mode 100644 index 0000000000..33468f1cd9 --- /dev/null +++ b/python/samples/02-agents/orchestrations/handoff_simple.py @@ -0,0 +1,296 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Annotated, cast + +from agent_framework import ( + Agent, + AgentResponse, + Message, + WorkflowEvent, + WorkflowRunState, + tool, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder +from azure.identity import AzureCliCredential + +"""Sample: Simple handoff workflow. + +A handoff workflow defines a pattern that assembles agents in a mesh topology, allowing +them to transfer control to each other based on the conversation context. + +Prerequisites: + - `az login` (Azure CLI authentication) + - Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.) + +Key Concepts: + - Auto-registered handoff tools: HandoffBuilder automatically creates handoff tools + for each participant, allowing the coordinator to transfer control to specialists + - Termination condition: Controls when the workflow stops requesting user input + - Request/response cycle: Workflow requests input, user responds, cycle continues +""" + + +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; +# See: +# samples/02-agents/tools/function_tool_with_approval.py +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. +@tool(approval_mode="never_require") +def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str: + """Simulated function to process a refund for a given order number.""" + return f"Refund processed successfully for order {order_number}." + + +@tool(approval_mode="never_require") +def check_order_status(order_number: Annotated[str, "Order number to check status for"]) -> str: + """Simulated function to check the status of a given order number.""" + return f"Order {order_number} is currently being processed and will ship in 2 business days." + + +@tool(approval_mode="never_require") +def process_return(order_number: Annotated[str, "Order number to process return for"]) -> str: + """Simulated function to process a return for a given order number.""" + return f"Return initiated successfully for order {order_number}. You will receive return instructions via email." + + +def create_agents(client: AzureOpenAIChatClient) -> tuple[Agent, Agent, Agent, Agent]: + """Create and configure the triage and specialist agents. + + Args: + client: The AzureOpenAIChatClient to use for creating agents. + + Returns: + Tuple of (triage_agent, refund_agent, order_agent, return_agent) + """ + # Triage agent: Acts as the frontline dispatcher + triage_agent = client.as_agent( + instructions=( + "You are frontline support triage. Route customer issues to the appropriate specialist agents " + "based on the problem described." + ), + name="triage_agent", + ) + + # Refund specialist: Handles refund requests + refund_agent = client.as_agent( + instructions="You process refund requests.", + name="refund_agent", + # In a real application, an agent can have multiple tools; here we keep it simple + tools=[process_refund], + ) + + # Order/shipping specialist: Resolves delivery issues + order_agent = client.as_agent( + instructions="You handle order and shipping inquiries.", + name="order_agent", + # In a real application, an agent can have multiple tools; here we keep it simple + tools=[check_order_status], + ) + + # Return specialist: Handles return requests + return_agent = client.as_agent( + instructions="You manage product return requests.", + name="return_agent", + # In a real application, an agent can have multiple tools; here we keep it simple + tools=[process_return], + ) + + return triage_agent, refund_agent, order_agent, return_agent + + +def _handle_events(events: list[WorkflowEvent]) -> list[WorkflowEvent[HandoffAgentUserRequest]]: + """Process workflow events and extract any pending user input requests. + + This function inspects each event type and: + - Prints workflow status changes (IDLE, IDLE_WITH_PENDING_REQUESTS, etc.) + - Displays final conversation snapshots when workflow completes + - Prints user input request prompts + - Collects all request_info events for response handling + + Args: + events: List of WorkflowEvent to process + + Returns: + List of WorkflowEvent[HandoffAgentUserRequest] representing pending user input requests + """ + requests: list[WorkflowEvent[HandoffAgentUserRequest]] = [] + + for event in events: + if event.type == "handoff_sent": + # handoff_sent event: Indicates a handoff has been initiated + print(f"\n[Handoff from {event.data.source} to {event.data.target} initiated.]") + elif event.type == "status" and event.state in { + WorkflowRunState.IDLE, + WorkflowRunState.IDLE_WITH_PENDING_REQUESTS, + }: + # Status event: Indicates workflow state changes + print(f"\n[Workflow Status] {event.state}") + elif event.type == "output": + # Output event: Contains contents generated by the workflow + data = event.data + if isinstance(data, AgentResponse): + for message in data.messages: + if not message.text: + # Skip messages without text (e.g., tool calls) + continue + speaker = message.author_name or message.role + print(f"- {speaker}: {message.text}") + elif event.type == "output": + # The output of the handoff workflow is a collection of chat messages from all participants + conversation = cast(list[Message], event.data) + if isinstance(conversation, list): + print("\n=== Final Conversation Snapshot ===") + for message in conversation: + speaker = message.author_name or message.role + print(f"- {speaker}: {message.text or [content.type for content in message.contents]}") + print("===================================") + elif event.type == "request_info" and isinstance(event.data, HandoffAgentUserRequest): + _print_handoff_agent_user_request(event.data.agent_response) + requests.append(cast(WorkflowEvent[HandoffAgentUserRequest], event)) + + return requests + + +def _print_handoff_agent_user_request(response: AgentResponse) -> None: + """Display the agent's response messages when requesting user input. + + This will happen when an agent generates a response that doesn't trigger + a handoff, i.e., the agent is asking the user for more information. + + Args: + response: The AgentResponse from the agent requesting user input + """ + if not response.messages: + raise RuntimeError("Cannot print agent responses: response has no messages.") + + print("\n[Agent is requesting your input...]") + + # Print agent responses + for message in response.messages: + if not message.text: + # Skip messages without text (e.g., tool calls) + continue + speaker = message.author_name or message.role + print(f"- {speaker}: {message.text}") + + +async def main() -> None: + """Main entry point for the handoff workflow demo. + + This function demonstrates: + 1. Creating triage and specialist agents + 2. Building a handoff workflow with custom termination condition + 3. Running the workflow with scripted user responses + 4. Processing events and handling user input requests + + The workflow uses scripted responses instead of interactive input to make + the demo reproducible and testable. In a production application, you would + replace the scripted_responses with actual user input collection. + """ + # Initialize the Azure OpenAI chat client + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + + # Create all agents: triage + specialists + triage, refund, order, support = create_agents(client) + + # Build the handoff workflow + # - participants: All agents that can participate in the workflow + # - with_start_agent: The triage agent is designated as the start agent, which means + # it receives all user input first and orchestrates handoffs to specialists + # - termination_condition: Custom logic to stop the request/response loop. + # Without this, the default behavior continues requesting user input until max_turns + # is reached. Here we use a custom condition that checks if the conversation has ended + # naturally (when one of the agents says something like "you're welcome"). + workflow = ( + HandoffBuilder( + name="customer_support_handoff", + participants=[triage, refund, order, support], + # Custom termination: Check if one of the agents has provided a closing message. + # This looks for the last message containing "welcome", which indicates the + # conversation has concluded naturally. + termination_condition=lambda conversation: ( + len(conversation) > 0 and "welcome" in conversation[-1].text.lower() + ), + ) + .with_start_agent(triage) + .build() + ) + + # Scripted user responses for reproducible demo + # In a console application, replace this with: + # user_input = input("Your response: ") + # or integrate with a UI/chat interface + scripted_responses = [ + "My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.", + "Please also process a refund for order 1234.", + "Thanks for resolving this.", + ] + + # Start the workflow with the initial user message + # run(..., stream=True) returns an async iterator of WorkflowEvent + print("[Starting workflow with initial user message...]\n") + initial_message = "Hello, I need assistance with my recent purchase." + print(f"- User: {initial_message}") + workflow_result = workflow.run(initial_message, stream=True) + pending_requests = _handle_events([event async for event in workflow_result]) + + # Process the request/response cycle + # The workflow will continue requesting input until: + # 1. The termination condition is met, OR + # 2. We run out of scripted responses + while pending_requests: + if not scripted_responses: + # No more scripted responses; terminate the workflow + responses = {req.request_id: HandoffAgentUserRequest.terminate() for req in pending_requests} + else: + # Get the next scripted response + user_response = scripted_responses.pop(0) + print(f"\n- User: {user_response}") + + # Send response(s) to all pending requests + # In this demo, there's typically one request per cycle, but the API supports multiple + responses = { + req.request_id: HandoffAgentUserRequest.create_response(user_response) for req in pending_requests + } + + # Send responses and get new events + # We use run(responses=...) to get events from the workflow, allowing us to + # display agent responses and handle new requests as they arrive + events = await workflow.run(responses=responses) + pending_requests = _handle_events(events) + + """ + Sample Output: + + [Starting workflow with initial user message...] + + - User: Hello, I need assistance with my recent purchase. + - triage_agent: Could you please provide more details about the issue you're experiencing with your recent purchase? This will help me route you to the appropriate specialist. + + [Workflow Status] IDLE_WITH_PENDING_REQUESTS + + - User: My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it. + - triage_agent: I've directed your request to our return agent, who will assist you with returning the damaged order. Thank you for your patience! + - return_agent: The return for your order 1234 has been successfully initiated. You will receive return instructions via email shortly. If you have any other questions or need further assistance, feel free to ask! + + [Workflow Status] IDLE_WITH_PENDING_REQUESTS + + - User: Thanks for resolving this. + + === Final Conversation Snapshot === + - user: Hello, I need assistance with my recent purchase. + - triage_agent: Could you please provide more details about the issue you're experiencing with your recent purchase? This will help me route you to the appropriate specialist. + - user: My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it. + - triage_agent: I've directed your request to our return agent, who will assist you with returning the damaged order. Thank you for your patience! + - return_agent: The return for your order 1234 has been successfully initiated. You will receive return instructions via email shortly. If you have any other questions or need further assistance, feel free to ask! + - user: Thanks for resolving this. + - triage_agent: You're welcome! If you have any more questions or need assistance in the future, feel free to reach out. Have a great day! + =================================== + + [Workflow Status] IDLE + """ # noqa: E501 + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/02-agents/orchestrations/handoff_with_code_interpreter_file.py b/python/samples/02-agents/orchestrations/handoff_with_code_interpreter_file.py new file mode 100644 index 0000000000..bc65e3bb20 --- /dev/null +++ b/python/samples/02-agents/orchestrations/handoff_with_code_interpreter_file.py @@ -0,0 +1,241 @@ +# Copyright (c) Microsoft. All rights reserved. + +""" +Handoff Workflow with Code Interpreter File Generation Sample + +This sample demonstrates retrieving file IDs from code interpreter output +in a handoff workflow context. A triage agent routes to a code specialist +that generates a text file, and we verify the file_id is captured correctly +from the streaming workflow events. + +Verifies GitHub issue #2718: files generated by code interpreter in +HandoffBuilder workflows can be properly retrieved. + +Toggle USE_V2_CLIENT to switch between: + - V1: AzureAIAgentClient (azure-ai-agents SDK) + - V2: AzureAIClient (azure-ai-projects 2.x with Responses API) + +IMPORTANT: When using V2 AzureAIClient with HandoffBuilder, each agent must +have its own client instance. The V2 client binds to a single server-side +agent name, so sharing a client between agents causes routing issues. + +Prerequisites: + - `az login` (Azure CLI authentication) + - V1: AZURE_AI_AGENT_PROJECT_CONNECTION_STRING + - V2: AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME +""" + +import asyncio +from collections.abc import AsyncIterable, AsyncIterator +from contextlib import asynccontextmanager +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, + WorkflowEvent, + WorkflowRunState, +) +from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder +from azure.identity.aio import AzureCliCredential + +# Toggle between V1 (AzureAIAgentClient) and V2 (AzureAIClient) +USE_V2_CLIENT = False + + +async def _drain(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]: + """Collect all events from an async stream.""" + return [event async for event in stream] + + +def _handle_events(events: list[WorkflowEvent]) -> tuple[list[WorkflowEvent[HandoffAgentUserRequest]], list[str]]: + """Process workflow events and extract file IDs and pending requests. + + Returns: + Tuple of (pending_requests, file_ids_found) + """ + + requests: list[WorkflowEvent[HandoffAgentUserRequest]] = [] + file_ids: list[str] = [] + + for event in events: + if event.type == "handoff_sent": + print(f"\n[Handoff from {event.data.source} to {event.data.target} initiated.]") + elif event.type == "status" and event.state in { + WorkflowRunState.IDLE, + WorkflowRunState.IDLE_WITH_PENDING_REQUESTS, + }: + print(f"[status] {event.state.name}") + elif event.type == "request_info" and isinstance(event.data, HandoffAgentUserRequest): + requests.append(cast(WorkflowEvent[HandoffAgentUserRequest], event)) + elif event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + for content in data.contents: + if content.type == "hosted_file": + file_ids.append(content.file_id) # type: ignore + print(f"[Found HostedFileContent: file_id={content.file_id}]") + elif content.type == "text" and content.annotations: + for annotation in content.annotations: + file_id = annotation["file_id"] # type: ignore + file_ids.append(file_id) + print(f"[Found file annotation: file_id={file_id}]") + elif event.type == "output": + conversation = cast(list[Message], event.data) + if isinstance(conversation, list): + print("\n=== Final Conversation Snapshot ===") + for message in conversation: + speaker = message.author_name or message.role + print(f"- {speaker}: {message.text or [content.type for content in message.contents]}") + print("===================================") + + return requests, file_ids + + +@asynccontextmanager +async def create_agents_v1(credential: AzureCliCredential) -> AsyncIterator[tuple[Agent, Agent]]: + """Create agents using V1 AzureAIAgentClient.""" + from agent_framework.azure import AzureAIAgentClient + + async with AzureAIAgentClient(credential=credential) as client: + triage = client.as_agent( + name="triage_agent", + instructions=( + "You are a triage agent. Route code-related requests to the code_specialist. " + "When the user asks to create or generate files, hand off to code_specialist " + "by calling handoff_to_code_specialist." + ), + ) + + # Create code interpreter tool using instance method + code_interpreter_tool = client.get_code_interpreter_tool() + + code_specialist = client.as_agent( + name="code_specialist", + instructions=( + "You are a Python code specialist. Use the code interpreter to execute Python code " + "and create files when requested. Always save files to /mnt/data/ directory." + ), + tools=[code_interpreter_tool], + ) + + yield triage, code_specialist # type: ignore + + +@asynccontextmanager +async def create_agents_v2(credential: AzureCliCredential) -> AsyncIterator[tuple[Agent, Agent]]: + """Create agents using V2 AzureAIClient. + + Each agent needs its own client instance because the V2 client binds + to a single server-side agent name. + """ + from agent_framework.azure import AzureAIClient + + async with ( + AzureAIClient(credential=credential) as triage_client, + AzureAIClient(credential=credential) as code_client, + ): + triage = triage_client.as_agent( + name="TriageAgent", + instructions="You are a triage agent. Your ONLY job is to route requests to the appropriate specialist.", + ) + + # Create code interpreter tool using instance method + code_interpreter_tool = code_client.get_code_interpreter_tool() + + code_specialist = code_client.as_agent( + name="CodeSpecialist", + instructions=( + "You are a Python code specialist. You have access to a code interpreter tool. " + "Use the code interpreter to execute Python code and create files. " + "Always save files to /mnt/data/ directory. " + "Do NOT discuss handoffs or routing - just complete the coding task directly." + ), + tools=[code_interpreter_tool], + ) + + yield triage, code_specialist + + +async def main() -> None: + """Run a simple handoff workflow with code interpreter file generation.""" + client_version = "V2 (AzureAIClient)" if USE_V2_CLIENT else "V1 (AzureAIAgentClient)" + print(f"=== Handoff Workflow with Code Interpreter File Generation [{client_version}] ===\n") + + async with AzureCliCredential() as credential: + create_agents = create_agents_v2 if USE_V2_CLIENT else create_agents_v1 + + async with create_agents(credential) as (triage, code_specialist): + workflow = ( + HandoffBuilder( + termination_condition=lambda conv: sum(1 for msg in conv if msg.role == "user") >= 2, + ) + .participants([triage, code_specialist]) + .with_start_agent(triage) + .build() + ) + + user_inputs = [ + "Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it.", + "exit", + ] + input_index = 0 + all_file_ids: list[str] = [] + + print(f"User: {user_inputs[0]}") + events = await _drain(workflow.run(user_inputs[0], stream=True)) + requests, file_ids = _handle_events(events) + all_file_ids.extend(file_ids) + input_index += 1 + + while requests: + request = requests[0] + if input_index >= len(user_inputs): + break + user_input = user_inputs[input_index] + print(f"\nUser: {user_input}") + + responses = {request.request_id: HandoffAgentUserRequest.create_response(user_input)} + events = await _drain(workflow.run(stream=True, responses=responses)) + requests, file_ids = _handle_events(events) + all_file_ids.extend(file_ids) + input_index += 1 + + print("\n" + "=" * 50) + if all_file_ids: + print(f"SUCCESS: Found {len(all_file_ids)} file ID(s) in handoff workflow:") + for fid in all_file_ids: + print(f" - {fid}") + else: + print("WARNING: No file IDs captured from the handoff workflow.") + print("=" * 50) + + """ + Sample Output: + + User: Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it. + [Found HostedFileContent: file_id=assistant-JT1sA...] + + === Conversation So Far === + - user: Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it. + - triage_agent: I am handing off your request to create the text file "hello.txt" with the specified content to the code specialist. They will assist you shortly. + - code_specialist: The file "hello.txt" has been created with the content "Hello from handoff workflow!". You can download it using the link below: + + [hello.txt](sandbox:/mnt/data/hello.txt) + =========================== + + [status] IDLE_WITH_PENDING_REQUESTS + + User: exit + [status] IDLE + + ================================================== + SUCCESS: Found 1 file ID(s) in handoff workflow: + - assistant-JT1sA... + ================================================== + """ # noqa: E501 + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/orchestrations/magentic/magentic.py b/python/samples/02-agents/orchestrations/magentic.py similarity index 85% rename from python/samples/getting_started/orchestrations/magentic/magentic.py rename to python/samples/02-agents/orchestrations/magentic.py index 52d12b4ce1..7ff0a08b1b 100644 --- a/python/samples/getting_started/orchestrations/magentic/magentic.py +++ b/python/samples/02-agents/orchestrations/magentic.py @@ -3,7 +3,6 @@ import asyncio import json import logging -import os from typing import cast from agent_framework import ( @@ -12,9 +11,8 @@ from agent_framework import ( Message, WorkflowEvent, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient from agent_framework.orchestrations import GroupChatRequestSentEvent, MagenticBuilder, MagenticProgressLedger -from azure.identity import AzureCliCredential logging.basicConfig(level=logging.WARNING) logger = logging.getLogger(__name__) @@ -40,8 +38,7 @@ energy efficiency and CO2 emissions of several ML models, streams intermediate events, and prints the final answer. The workflow completes when idle. Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- OpenAI credentials configured for `AzureOpenAIResponsesClient` and `AzureOpenAIResponsesClient`. +- OpenAI credentials configured for `OpenAIChatClient` and `OpenAIResponsesClient`. """ @@ -53,19 +50,11 @@ async def main() -> None: "You are a Researcher. You find information without additional computation or quantitative analysis." ), # This agent requires the gpt-4o-search-preview model to perform web searches. - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=OpenAIChatClient(model_id="gpt-4o-search-preview"), ) # Create code interpreter tool using instance method - coder_client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + coder_client = OpenAIResponsesClient() code_interpreter_tool = coder_client.get_code_interpreter_tool() coder_agent = Agent( @@ -81,11 +70,7 @@ async def main() -> None: name="MagenticManager", description="Orchestrator that coordinates the research and coding workflow", instructions="You coordinate a team to complete complex tasks efficiently.", - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=OpenAIChatClient(), ) print("\nBuilding Magentic Workflow...") diff --git a/python/samples/02-agents/orchestrations/magentic_checkpoint.py b/python/samples/02-agents/orchestrations/magentic_checkpoint.py new file mode 100644 index 0000000000..05437a8601 --- /dev/null +++ b/python/samples/02-agents/orchestrations/magentic_checkpoint.py @@ -0,0 +1,309 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import json +from pathlib import Path +from typing import cast + +from agent_framework import ( + Agent, + FileCheckpointStorage, + Message, + WorkflowCheckpoint, + WorkflowEvent, + WorkflowRunState, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest +from azure.identity._credentials import AzureCliCredential + +""" +Sample: Magentic Orchestration + Checkpointing + +The goal of this sample is to show the exact mechanics needed to pause a Magentic +workflow that requires human plan review, persist the outstanding request via a +checkpoint, and later resume the workflow by feeding in the saved response. + +Concepts highlighted here: +1. **Deterministic executor IDs** - the orchestrator and plan-review request executor + must keep stable IDs so the checkpoint state aligns when we rebuild the graph. +2. **Executor snapshotting** - checkpoints capture the pending plan-review request + map, at superstep boundaries. +3. **Resume with responses** - `Workflow.run(responses=...)` accepts a + `responses` mapping so we can inject the stored human reply during restoration. + +Prerequisites: +- OpenAI environment variables configured for `OpenAIChatClient`. +""" + +TASK = ( + "Draft a concise internal brief describing how our research and implementation teams should collaborate " + "to launch a beta feature for data-driven email summarization. Highlight the key milestones, " + "risks, and communication cadence." +) + +# Dedicated folder for captured checkpoints. Keeping it under the sample directory +# makes it easy to inspect the JSON blobs produced by each run. +CHECKPOINT_DIR = Path(__file__).parent / "tmp" / "magentic_checkpoints" + + +def build_workflow(checkpoint_storage: FileCheckpointStorage): + """Construct the Magentic workflow graph with checkpointing enabled.""" + + # Two vanilla ChatAgents act as participants in the orchestration. They do not need + # extra state handling because their inputs/outputs are fully described by chat messages. + researcher = Agent( + name="ResearcherAgent", + description="Collects background facts and references for the project.", + instructions=("You are the research lead. Gather crisp bullet points the team should know."), + client=AzureOpenAIChatClient(credential=AzureCliCredential()), + ) + + writer = Agent( + name="WriterAgent", + description="Synthesizes the final brief for stakeholders.", + instructions=("You convert the research notes into a structured brief with milestones and risks."), + client=AzureOpenAIChatClient(credential=AzureCliCredential()), + ) + + # Create a manager agent for orchestration + manager_agent = Agent( + name="MagenticManager", + description="Orchestrator that coordinates the research and writing workflow", + instructions="You coordinate a team to complete complex tasks efficiently.", + client=AzureOpenAIChatClient(credential=AzureCliCredential()), + ) + + # The builder wires in the Magentic orchestrator, sets the plan review path, and + # stores the checkpoint backend so the runtime knows where to persist snapshots. + return MagenticBuilder( + participants=[researcher, writer], + enable_plan_review=True, + checkpoint_storage=checkpoint_storage, + manager_agent=manager_agent, + max_round_count=10, + max_stall_count=3, + ).build() + + +async def main() -> None: + # Stage 0: make sure the checkpoint folder is empty so we inspect only checkpoints + # written by this invocation. This prevents stale files from previous runs from + # confusing the analysis. + CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True) + for file in CHECKPOINT_DIR.glob("*.json"): + file.unlink() + + checkpoint_storage = FileCheckpointStorage(CHECKPOINT_DIR) + + print("\n=== Stage 1: run until plan review request (checkpointing active) ===") + workflow = build_workflow(checkpoint_storage) + + # Run the workflow until the first is surfaced. The event carries the + # request_id we must reuse on resume. In a real system this is where the UI would present + # the plan for human review. + plan_review_request: MagenticPlanReviewRequest | None = None + async for event in workflow.run(TASK, stream=True): + if event.type == "request_info" and event.request_type is MagenticPlanReviewRequest: + plan_review_request = event.data + print(f"Captured plan review request: {event.request_id}") + + if event.type == "status" and event.state is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS: + break + + if plan_review_request is None: + print("No plan review request emitted; nothing to resume.") + return + + checkpoints = await checkpoint_storage.list_checkpoints(workflow.id) + if not checkpoints: + print("No checkpoints persisted.") + return + + resume_checkpoint = max( + checkpoints, + key=lambda cp: (cp.iteration_count, cp.timestamp), + ) + print(f"Using checkpoint {resume_checkpoint.checkpoint_id} at iteration {resume_checkpoint.iteration_count}") + + # Show that the checkpoint JSON indeed contains the pending plan-review request record. + checkpoint_path = checkpoint_storage.storage_path / f"{resume_checkpoint.checkpoint_id}.json" + if checkpoint_path.exists(): + with checkpoint_path.open() as f: + snapshot = json.load(f) + request_map = snapshot.get("pending_request_info_events", {}) + print(f"Pending plan-review requests persisted in checkpoint: {list(request_map.keys())}") + + print("\n=== Stage 2: resume from checkpoint and approve plan ===") + resumed_workflow = build_workflow(checkpoint_storage) + + # Construct an approval reply to supply when the plan review request is re-emitted. + approval = plan_review_request.approve() + + # Resume execution and capture the re-emitted plan review request. + request_info_event: WorkflowEvent | None = None + async for event in resumed_workflow.run(checkpoint_id=resume_checkpoint.checkpoint_id, stream=True): + if event.type == "request_info" and isinstance(event.data, MagenticPlanReviewRequest): + request_info_event = event + + if request_info_event is None: + print("No plan review request re-emitted on resume; cannot approve.") + return + print(f"Resumed plan review request: {request_info_event.request_id}") + + # Supply the approval and continue to run to completion. + final_event: WorkflowEvent | None = None + async for event in resumed_workflow.run(stream=True, responses={request_info_event.request_id: approval}): + if event.type == "output": + final_event = event + + if final_event is None: + print("Workflow did not complete after resume.") + return + + # Final sanity check: display the assistant's answer as proof the orchestration reached + # a natural completion after resuming from the checkpoint. + result = final_event.data + if not result: + print("No result data from workflow.") + return + output_messages = cast(list[Message], result) + print("\n=== Final Answer ===") + # The output of the Magentic workflow is a list of ChatMessages with only one final message + # generated by the orchestrator. + print(output_messages[-1].text) + + # ------------------------------------------------------------------ + # Stage 3: demonstrate resuming from a later checkpoint (post-plan) + # ------------------------------------------------------------------ + + def _pending_message_count(cp: WorkflowCheckpoint) -> int: + return sum(len(msg_list) for msg_list in cp.messages.values() if isinstance(msg_list, list)) + + all_checkpoints = await checkpoint_storage.list_checkpoints(resume_checkpoint.workflow_id) + later_checkpoints_with_messages = [ + cp + for cp in all_checkpoints + if cp.iteration_count > resume_checkpoint.iteration_count and _pending_message_count(cp) > 0 + ] + + if later_checkpoints_with_messages: + post_plan_checkpoint = max( + later_checkpoints_with_messages, + key=lambda cp: (cp.iteration_count, cp.timestamp), + ) + else: + later_checkpoints = [cp for cp in all_checkpoints if cp.iteration_count > resume_checkpoint.iteration_count] + + if not later_checkpoints: + print("\nNo additional checkpoints recorded beyond plan approval; sample complete.") + return + + post_plan_checkpoint = max( + later_checkpoints, + key=lambda cp: (cp.iteration_count, cp.timestamp), + ) + print("\n=== Stage 3: resume from post-plan checkpoint ===") + pending_messages = _pending_message_count(post_plan_checkpoint) + print( + f"Resuming from checkpoint {post_plan_checkpoint.checkpoint_id} at iteration " + f"{post_plan_checkpoint.iteration_count} (pending messages: {pending_messages})" + ) + if pending_messages == 0: + print("Checkpoint has no pending messages; no additional work expected on resume.") + + final_event_post: WorkflowEvent | None = None + post_emitted_events = False + post_plan_workflow = build_workflow(checkpoint_storage) + async for event in post_plan_workflow.run(checkpoint_id=post_plan_checkpoint.checkpoint_id, stream=True): + post_emitted_events = True + if event.type == "output": + final_event_post = event + + if final_event_post is None: + if not post_emitted_events: + print("No new events were emitted; checkpoint already captured a completed run.") + print("\n=== Final Answer (post-plan resume) ===") + print(output_messages[-1].text) + return + print("Workflow did not complete after post-plan resume.") + return + + post_result = final_event_post.data + if not post_result: + print("No result data from post-plan resume.") + return + + output_messages = cast(list[Message], post_result) + print("\n=== Final Answer (post-plan resume) ===") + # The output of the Magentic workflow is a list of ChatMessages with only one final message + # generated by the orchestrator. + print(output_messages[-1].text) + + """ + Sample Output: + + === Stage 1: run until plan review request (checkpointing active) === + Captured plan review request: 3a1a4a09-4ed1-4c90-9cf6-9ac488d452c0 + Using checkpoint 4c76d77a-6ff8-4d2b-84f6-824771ffac7e at iteration 1 + Pending plan-review requests persisted in checkpoint: ['3a1a4a09-4ed1-4c90-9cf6-9ac488d452c0'] + + === Stage 2: resume from checkpoint and approve plan === + + === Final Answer === + Certainly! Here's your concise internal brief on how the research and implementation teams should collaborate for + the beta launch of the data-driven email summarization feature: + + --- + + **Internal Brief: Collaboration Plan for Data-driven Email Summarization Beta Launch** + + **Collaboration Approach** + - **Joint Kickoff:** Research and Implementation teams hold a project kickoff to align on objectives, requirements, + and success metrics. + - **Ongoing Coordination:** Teams collaborate closely; researchers share model developments and insights, while + implementation ensures smooth integration and user experience. + - **Real-time Feedback Loop:** Implementation provides early feedback on technical integration and UX, while + Research evaluates initial performance and user engagement signals post-integration. + + **Key Milestones** + 1. **Requirement Finalization & Scoping** - Define MVP feature set and success criteria. + 2. **Model Prototyping & Evaluation** - Researchers develop and validate summarization models with agreed metrics. + 3. **Integration & Internal Testing** - Implementation team integrates the model; internal alpha testing and + compliance checks. + 4. **Beta User Onboarding** - Recruit a select cohort of beta users and guide them through onboarding. + 5. **Beta Launch & Monitoring** - Soft-launch for beta group, with active monitoring of usage, feedback, + and performance. + 6. **Iterative Improvements** - Address issues, refine features, and prepare for possible broader rollout. + + **Top Risks** + - **Data Privacy & Compliance:** Strict protocols and compliance reviews to prevent data leakage. + - **Model Quality (Bias, Hallucination):** Careful monitoring of summary accuracy; rapid iterations if critical + errors occur. + - **User Adoption:** Ensuring the beta solves genuine user needs, collecting actionable feedback early. + - **Feedback Quality & Quantity:** Proactively schedule user outreach to ensure substantive beta feedback. + + **Communication Cadence** + - **Weekly Team Syncs:** Short all-hands progress and blockers meeting. + - **Bi-Weekly Stakeholder Check-ins:** Leadership and project leads address escalations and strategic decisions. + - **Dedicated Slack Channel:** For real-time queries and updates. + - **Documentation Hub:** Up-to-date project docs and FAQs on a shared internal wiki. + - **Post-Milestone Retrospectives:** After critical phases (e.g., alpha, beta), reviewing what worked and what needs + improvement. + + **Summary** + Clear alignment, consistent communication, and iterative feedback are key to a successful beta. All team members are + expected to surface issues quickly and keep documentation current as we drive toward launch. + --- + + === Stage 3: resume from post-plan checkpoint === + Resuming from checkpoint 9a3b... at iteration 3 (pending messages: 0) + No new events were emitted; checkpoint already captured a completed run. + + === Final Answer (post-plan resume) === + (same brief as above) + """ + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/orchestrations/magentic/magentic_human_plan_review.py b/python/samples/02-agents/orchestrations/magentic_human_plan_review.py similarity index 84% rename from python/samples/getting_started/orchestrations/magentic/magentic_human_plan_review.py rename to python/samples/02-agents/orchestrations/magentic_human_plan_review.py index 53f2d59df8..95f8de5f46 100644 --- a/python/samples/getting_started/orchestrations/magentic/magentic_human_plan_review.py +++ b/python/samples/02-agents/orchestrations/magentic_human_plan_review.py @@ -2,7 +2,6 @@ import asyncio import json -import os from collections.abc import AsyncIterable from typing import cast @@ -12,9 +11,8 @@ from agent_framework import ( Message, WorkflowEvent, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.openai import OpenAIChatClient from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest, MagenticPlanReviewResponse -from azure.identity import AzureCliCredential """ Sample: Magentic Orchestration with Human Plan Review @@ -33,8 +31,7 @@ Plan review options: - revise(feedback): Provide textual feedback to modify the plan Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- OpenAI credentials configured for `AzureOpenAIResponsesClient`. +- OpenAI credentials configured for `OpenAIChatClient`. """ # Keep track of the last response to format output nicely in streaming mode @@ -99,33 +96,21 @@ async def main() -> None: name="ResearcherAgent", description="Specialist in research and information gathering", instructions="You are a Researcher. You find information and gather facts.", - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=OpenAIChatClient(model_id="gpt-4o"), ) analyst_agent = Agent( name="AnalystAgent", description="Data analyst who processes and summarizes research findings", instructions="You are an Analyst. You analyze findings and create summaries.", - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=OpenAIChatClient(model_id="gpt-4o"), ) manager_agent = Agent( name="MagenticManager", description="Orchestrator that coordinates the workflow", instructions="You coordinate a team to complete tasks efficiently.", - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=OpenAIChatClient(model_id="gpt-4o"), ) print("\nBuilding Magentic Workflow with Human Plan Review...") diff --git a/python/samples/getting_started/orchestrations/sequential/sequential_agents.py b/python/samples/02-agents/orchestrations/sequential_agents.py similarity index 85% rename from python/samples/getting_started/orchestrations/sequential/sequential_agents.py rename to python/samples/02-agents/orchestrations/sequential_agents.py index 083b2e42ed..7d77ef35c6 100644 --- a/python/samples/getting_started/orchestrations/sequential/sequential_agents.py +++ b/python/samples/02-agents/orchestrations/sequential_agents.py @@ -1,11 +1,10 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import cast from agent_framework import Message -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import SequentialBuilder from azure.identity import AzureCliCredential @@ -25,18 +24,13 @@ Note on internal adapters: You can safely ignore them when focusing on agent progress. Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Azure OpenAI access configured for AzureOpenAIResponsesClient (use az login + env vars) +- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars) """ async def main() -> None: # 1) Create agents - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) writer = client.as_agent( instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."), diff --git a/python/samples/getting_started/orchestrations/sequential/sequential_custom_executors.py b/python/samples/02-agents/orchestrations/sequential_custom_executors.py similarity index 89% rename from python/samples/getting_started/orchestrations/sequential/sequential_custom_executors.py rename to python/samples/02-agents/orchestrations/sequential_custom_executors.py index 9110a828d8..7f3e61fe2e 100644 --- a/python/samples/getting_started/orchestrations/sequential/sequential_custom_executors.py +++ b/python/samples/02-agents/orchestrations/sequential_custom_executors.py @@ -1,7 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import Any from agent_framework import ( @@ -11,7 +10,7 @@ from agent_framework import ( WorkflowContext, handler, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import SequentialBuilder from azure.identity import AzureCliCredential @@ -29,8 +28,7 @@ Custom executor contract: - Emit the updated conversation via ctx.send_message([...]) Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Azure OpenAI access configured for AzureOpenAIResponsesClient (use az login + env vars) +- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars) """ @@ -60,11 +58,7 @@ class Summarizer(Executor): async def main() -> None: # 1) Create a content agent - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) content = client.as_agent( instructions="Produce a concise paragraph answering the user's request.", name="content", diff --git a/python/samples/getting_started/agents/anthropic/README.md b/python/samples/02-agents/providers/anthropic/README.md similarity index 100% rename from python/samples/getting_started/agents/anthropic/README.md rename to python/samples/02-agents/providers/anthropic/README.md diff --git a/python/samples/getting_started/agents/anthropic/anthropic_advanced.py b/python/samples/02-agents/providers/anthropic/anthropic_advanced.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_advanced.py rename to python/samples/02-agents/providers/anthropic/anthropic_advanced.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_basic.py b/python/samples/02-agents/providers/anthropic/anthropic_basic.py similarity index 91% rename from python/samples/getting_started/agents/anthropic/anthropic_basic.py rename to python/samples/02-agents/providers/anthropic/anthropic_basic.py index 1600d725b6..2cde199d35 100644 --- a/python/samples/getting_started/agents/anthropic/anthropic_basic.py +++ b/python/samples/02-agents/providers/anthropic/anthropic_basic.py @@ -14,7 +14,7 @@ This sample demonstrates using Anthropic with an agent and a single custom tool. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, "The location to get the weather for."], diff --git a/python/samples/getting_started/agents/anthropic/anthropic_claude_basic.py b/python/samples/02-agents/providers/anthropic/anthropic_claude_basic.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_claude_basic.py rename to python/samples/02-agents/providers/anthropic/anthropic_claude_basic.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_claude_with_mcp.py b/python/samples/02-agents/providers/anthropic/anthropic_claude_with_mcp.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_claude_with_mcp.py rename to python/samples/02-agents/providers/anthropic/anthropic_claude_with_mcp.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_claude_with_multiple_permissions.py b/python/samples/02-agents/providers/anthropic/anthropic_claude_with_multiple_permissions.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_claude_with_multiple_permissions.py rename to python/samples/02-agents/providers/anthropic/anthropic_claude_with_multiple_permissions.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_claude_with_session.py b/python/samples/02-agents/providers/anthropic/anthropic_claude_with_session.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_claude_with_session.py rename to python/samples/02-agents/providers/anthropic/anthropic_claude_with_session.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_claude_with_shell.py b/python/samples/02-agents/providers/anthropic/anthropic_claude_with_shell.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_claude_with_shell.py rename to python/samples/02-agents/providers/anthropic/anthropic_claude_with_shell.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_claude_with_tools.py b/python/samples/02-agents/providers/anthropic/anthropic_claude_with_tools.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_claude_with_tools.py rename to python/samples/02-agents/providers/anthropic/anthropic_claude_with_tools.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_claude_with_url.py b/python/samples/02-agents/providers/anthropic/anthropic_claude_with_url.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_claude_with_url.py rename to python/samples/02-agents/providers/anthropic/anthropic_claude_with_url.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_foundry.py b/python/samples/02-agents/providers/anthropic/anthropic_foundry.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_foundry.py rename to python/samples/02-agents/providers/anthropic/anthropic_foundry.py diff --git a/python/samples/getting_started/agents/anthropic/anthropic_skills.py b/python/samples/02-agents/providers/anthropic/anthropic_skills.py similarity index 100% rename from python/samples/getting_started/agents/anthropic/anthropic_skills.py rename to python/samples/02-agents/providers/anthropic/anthropic_skills.py diff --git a/python/samples/getting_started/agents/azure_ai/README.md b/python/samples/02-agents/providers/azure_ai/README.md similarity index 100% rename from python/samples/getting_started/agents/azure_ai/README.md rename to python/samples/02-agents/providers/azure_ai/README.md diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_basic.py b/python/samples/02-agents/providers/azure_ai/azure_ai_basic.py similarity index 95% rename from python/samples/getting_started/agents/azure_ai/azure_ai_basic.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_basic.py index 01ce5fbef8..7a76cbb500 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_basic.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_basic.py @@ -18,8 +18,8 @@ Shows both streaming and non-streaming responses with function tools. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_provider_methods.py b/python/samples/02-agents/providers/azure_ai/azure_ai_provider_methods.py similarity index 98% rename from python/samples/getting_started/agents/azure_ai/azure_ai_provider_methods.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_provider_methods.py index 1cef3be3e5..579377921d 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_provider_methods.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_provider_methods.py @@ -28,8 +28,8 @@ Each method returns a Agent that can be used for conversations. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_use_latest_version.py b/python/samples/02-agents/providers/azure_ai/azure_ai_use_latest_version.py similarity index 94% rename from python/samples/getting_started/agents/azure_ai/azure_ai_use_latest_version.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_use_latest_version.py index 79d4e2c9a3..7394fca31c 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_use_latest_version.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_use_latest_version.py @@ -19,8 +19,8 @@ while subsequent calls with `get_agent()` reuse the latest agent version. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_agent_as_tool.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_agent_as_tool.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_agent_as_tool.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_agent_as_tool.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_agent_to_agent.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_agent_to_agent.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_agent_to_agent.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_agent_to_agent.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_application_endpoint.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_application_endpoint.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_application_endpoint.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_application_endpoint.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_azure_ai_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_azure_ai_search.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_bing_custom_search.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_bing_custom_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_bing_custom_search.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_bing_custom_search.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_bing_grounding.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_bing_grounding.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_browser_automation.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_browser_automation.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_browser_automation.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_browser_automation.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_code_interpreter.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_code_interpreter.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter_file_download.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_code_interpreter_file_download.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter_file_download.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_code_interpreter_file_download.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter_file_generation.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_code_interpreter_file_generation.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter_file_generation.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_code_interpreter_file_generation.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_content_filtering.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_content_filtering.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_content_filtering.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_content_filtering.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_agent.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_existing_agent.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_agent.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_existing_agent.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_existing_conversation.py similarity index 96% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_existing_conversation.py index 190ff54c7d..cb18a7d46e 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_with_existing_conversation.py @@ -18,8 +18,8 @@ This sample demonstrates usage of AzureAIProjectAgentProvider with existing conv # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_explicit_settings.py similarity index 92% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_explicit_settings.py index 16468dd482..3b6d3b4b03 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_with_explicit_settings.py @@ -19,8 +19,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_file_search.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_file_search.py similarity index 96% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_file_search.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_file_search.py index cadb87e2b2..13f238a97e 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_with_file_search.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_with_file_search.py @@ -35,7 +35,7 @@ async def main() -> None: ): try: # 1. Upload file and create vector store - pdf_file_path = Path(__file__).parent.parent / "resources" / "employees.pdf" + pdf_file_path = Path(__file__).parents[2] / "shared" / "resources" / "employees.pdf" print(f"Uploading file from: {pdf_file_path}") file = await agents_client.files.upload_and_poll(file_path=str(pdf_file_path), purpose="assistants") diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_hosted_mcp.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_hosted_mcp.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_image_generation.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_image_generation.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_image_generation.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_image_generation.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_local_mcp.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_local_mcp.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_local_mcp.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_local_mcp.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_memory_search.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_memory_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_memory_search.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_memory_search.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_microsoft_fabric.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_microsoft_fabric.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_microsoft_fabric.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_microsoft_fabric.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_openapi.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_openapi.py similarity index 95% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_openapi.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_openapi.py index 260a5a0206..73b8cf5102 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_with_openapi.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_with_openapi.py @@ -20,7 +20,7 @@ Prerequisites: async def main() -> None: # Load the OpenAPI specification - resources_path = Path(__file__).parent.parent / "resources" / "countries.json" + resources_path = Path(__file__).parents[2] / "shared" / "resources" / "countries.json" with open(resources_path) as f: openapi_countries = json.load(f) diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_reasoning.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_reasoning.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_reasoning.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_reasoning.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_response_format.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_response_format.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_response_format.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_response_format.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_runtime_json_schema.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_runtime_json_schema.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_runtime_json_schema.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_runtime_json_schema.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_sharepoint.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_sharepoint.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_sharepoint.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_sharepoint.py diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_thread.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_thread.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_thread.py index 790c5be1a6..2abc053b71 100644 --- a/python/samples/getting_started/agents/azure_ai/azure_ai_with_thread.py +++ b/python/samples/02-agents/providers/azure_ai/azure_ai_with_thread.py @@ -19,8 +19,8 @@ persistent conversation capabilities using service-managed threads as well as st # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production # See: -# samples/getting_started/tools/function_tool_with_approval.py -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# samples/02-agents/tools/function_tool_with_approval.py +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai/azure_ai_with_web_search.py b/python/samples/02-agents/providers/azure_ai/azure_ai_with_web_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai/azure_ai_with_web_search.py rename to python/samples/02-agents/providers/azure_ai/azure_ai_with_web_search.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/README.md b/python/samples/02-agents/providers/azure_ai_agent/README.md similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/README.md rename to python/samples/02-agents/providers/azure_ai_agent/README.md diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_basic.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_basic.py similarity index 94% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_basic.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_basic.py index 34bd782a9b..5e6dae68fc 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_basic.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_basic.py @@ -17,7 +17,7 @@ lifecycle management. Shows both streaming and non-streaming responses with func """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_provider_methods.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_provider_methods.py similarity index 96% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_provider_methods.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_provider_methods.py index 5dd06f16f0..debaf1ac45 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_provider_methods.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_provider_methods.py @@ -21,7 +21,7 @@ This sample demonstrates the methods available on the AzureAIAgentsProvider clas """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_azure_ai_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_azure_ai_search.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_bing_custom_search.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_bing_custom_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_bing_custom_search.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_bing_custom_search.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_bing_grounding.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_bing_grounding.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding_citations.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_bing_grounding_citations.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding_citations.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_bing_grounding_citations.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_code_interpreter.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_code_interpreter.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_existing_agent.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_existing_agent.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_existing_agent.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_existing_agent.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_existing_thread.py similarity index 93% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_existing_thread.py index f270fdbd60..9d6148ad59 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_existing_thread.py @@ -20,8 +20,8 @@ by providing thread IDs for thread reuse patterns. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_explicit_settings.py similarity index 92% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_explicit_settings.py index 53116ea114..e8c61b836b 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_explicit_settings.py @@ -19,8 +19,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_file_search.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_file_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_file_search.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_file_search.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_function_tools.py similarity index 97% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_function_tools.py index 37ca63f3f3..f51a458ae5 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_function_tools.py @@ -19,8 +19,8 @@ showing both agent-level and query-level tool configuration patterns. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_hosted_mcp.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_hosted_mcp.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_hosted_mcp.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_hosted_mcp.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_local_mcp.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_local_mcp.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_local_mcp.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_local_mcp.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_multiple_tools.py similarity index 96% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_multiple_tools.py index af189311a8..35e6650748 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_multiple_tools.py @@ -34,8 +34,8 @@ To set up Bing Grounding: # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_time() -> str: """Get the current UTC time.""" diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_openapi_tools.py similarity index 97% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_openapi_tools.py index 24fd8eba9a..125b982834 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_openapi_tools.py @@ -23,7 +23,7 @@ USER_INPUTS = [ def load_openapi_specs() -> tuple[dict[str, Any], dict[str, Any]]: """Load OpenAPI specification files.""" - resources_path = Path(__file__).parent.parent / "resources" + resources_path = Path(__file__).parents[2] / "shared" / "resources" with open(resources_path / "weather.json") as weather_file: weather_spec = json.load(weather_file) diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_response_format.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_response_format.py similarity index 100% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_response_format.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_response_format.py diff --git a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_thread.py b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_thread.py rename to python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_thread.py index bf70f9014e..e5957905ae 100644 --- a/python/samples/getting_started/agents/azure_ai_agent/azure_ai_with_thread.py +++ b/python/samples/02-agents/providers/azure_ai_agent/azure_ai_with_thread.py @@ -18,8 +18,8 @@ automatic thread creation with explicit thread management for persistent context # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/README.md b/python/samples/02-agents/providers/azure_openai/README.md similarity index 100% rename from python/samples/getting_started/agents/azure_openai/README.md rename to python/samples/02-agents/providers/azure_openai/README.md diff --git a/python/samples/getting_started/agents/azure_openai/azure_assistants_basic.py b/python/samples/02-agents/providers/azure_openai/azure_assistants_basic.py similarity index 93% rename from python/samples/getting_started/agents/azure_openai/azure_assistants_basic.py rename to python/samples/02-agents/providers/azure_openai/azure_assistants_basic.py index 2bc74ef83c..d8a7715533 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_assistants_basic.py +++ b/python/samples/02-agents/providers/azure_openai/azure_assistants_basic.py @@ -17,7 +17,7 @@ assistant lifecycle management, showing both streaming and non-streaming respons """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_code_interpreter.py b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_code_interpreter.py similarity index 100% rename from python/samples/getting_started/agents/azure_openai/azure_assistants_with_code_interpreter.py rename to python/samples/02-agents/providers/azure_openai/azure_assistants_with_code_interpreter.py diff --git a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_existing_assistant.py similarity index 93% rename from python/samples/getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py rename to python/samples/02-agents/providers/azure_openai/azure_assistants_with_existing_assistant.py index c1c2ed0666..107f9ff7a7 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py +++ b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_existing_assistant.py @@ -20,8 +20,8 @@ using existing assistant IDs rather than creating new ones. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_explicit_settings.py similarity index 92% rename from python/samples/getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py rename to python/samples/02-agents/providers/azure_openai/azure_assistants_with_explicit_settings.py index d49bf9a27c..edf8c79f9a 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py +++ b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_explicit_settings.py @@ -19,8 +19,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_function_tools.py b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_function_tools.py similarity index 97% rename from python/samples/getting_started/agents/azure_openai/azure_assistants_with_function_tools.py rename to python/samples/02-agents/providers/azure_openai/azure_assistants_with_function_tools.py index 67a5c72f67..7f75c881e0 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_function_tools.py +++ b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_function_tools.py @@ -19,8 +19,8 @@ showing both agent-level and query-level tool configuration patterns. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_thread.py b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/azure_openai/azure_assistants_with_thread.py rename to python/samples/02-agents/providers/azure_openai/azure_assistants_with_thread.py index e9cbff23af..dce9699a96 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_assistants_with_thread.py +++ b/python/samples/02-agents/providers/azure_openai/azure_assistants_with_thread.py @@ -18,8 +18,8 @@ automatic thread creation with explicit thread management for persistent context # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_chat_client_basic.py b/python/samples/02-agents/providers/azure_openai/azure_chat_client_basic.py similarity index 94% rename from python/samples/getting_started/agents/azure_openai/azure_chat_client_basic.py rename to python/samples/02-agents/providers/azure_openai/azure_chat_client_basic.py index b52d514813..3043a0790d 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_chat_client_basic.py +++ b/python/samples/02-agents/providers/azure_openai/azure_chat_client_basic.py @@ -18,8 +18,8 @@ interactions, showing both streaming and non-streaming responses. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py b/python/samples/02-agents/providers/azure_openai/azure_chat_client_with_explicit_settings.py similarity index 91% rename from python/samples/getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py rename to python/samples/02-agents/providers/azure_openai/azure_chat_client_with_explicit_settings.py index 7b69168093..a6d6b42c55 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py +++ b/python/samples/02-agents/providers/azure_openai/azure_chat_client_with_explicit_settings.py @@ -19,8 +19,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py b/python/samples/02-agents/providers/azure_openai/azure_chat_client_with_function_tools.py similarity index 97% rename from python/samples/getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py rename to python/samples/02-agents/providers/azure_openai/azure_chat_client_with_function_tools.py index 4c12fe7d5b..182a2d8bda 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py +++ b/python/samples/02-agents/providers/azure_openai/azure_chat_client_with_function_tools.py @@ -19,8 +19,8 @@ showing both agent-level and query-level tool configuration patterns. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_chat_client_with_thread.py b/python/samples/02-agents/providers/azure_openai/azure_chat_client_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/azure_openai/azure_chat_client_with_thread.py rename to python/samples/02-agents/providers/azure_openai/azure_chat_client_with_thread.py index 24fa8272b6..bdad0faa3f 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_chat_client_with_thread.py +++ b/python/samples/02-agents/providers/azure_openai/azure_chat_client_with_thread.py @@ -18,8 +18,8 @@ automatic thread creation with explicit thread management for persistent context # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_basic.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_basic.py similarity index 94% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_basic.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_basic.py index 095cfadfa7..98353c63a7 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_responses_client_basic.py +++ b/python/samples/02-agents/providers/azure_openai/azure_responses_client_basic.py @@ -18,8 +18,8 @@ response generation, showing both streaming and non-streaming responses. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_code_interpreter_files.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_code_interpreter_files.py similarity index 100% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_code_interpreter_files.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_code_interpreter_files.py diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_image_analysis.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_image_analysis.py similarity index 100% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_image_analysis.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_image_analysis.py diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_code_interpreter.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_code_interpreter.py similarity index 100% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_code_interpreter.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_code_interpreter.py diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_explicit_settings.py similarity index 92% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_explicit_settings.py index b89458df12..ee27fa8160 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py +++ b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_explicit_settings.py @@ -19,8 +19,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_file_search.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_file_search.py similarity index 100% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_file_search.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_file_search.py diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_foundry.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_foundry.py similarity index 95% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_foundry.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_foundry.py index 7020121db9..ecc53e6f3f 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_foundry.py +++ b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_foundry.py @@ -28,7 +28,7 @@ This requires: load_dotenv() # Load environment variables from .env file if present -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_function_tools.py similarity index 97% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_function_tools.py index 265ccff98f..dacdf69c63 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py +++ b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_function_tools.py @@ -19,8 +19,8 @@ showing both agent-level and query-level tool configuration patterns. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_hosted_mcp.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_hosted_mcp.py similarity index 100% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_hosted_mcp.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_hosted_mcp.py diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_local_mcp.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_local_mcp.py similarity index 100% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_local_mcp.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_local_mcp.py diff --git a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_thread.py b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/azure_openai/azure_responses_client_with_thread.py rename to python/samples/02-agents/providers/azure_openai/azure_responses_client_with_thread.py index 028f583ddb..f27af60e88 100644 --- a/python/samples/getting_started/agents/azure_openai/azure_responses_client_with_thread.py +++ b/python/samples/02-agents/providers/azure_openai/azure_responses_client_with_thread.py @@ -18,8 +18,8 @@ automatic thread creation with explicit thread management for persistent context # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/copilotstudio/README.md b/python/samples/02-agents/providers/copilotstudio/README.md similarity index 100% rename from python/samples/getting_started/agents/copilotstudio/README.md rename to python/samples/02-agents/providers/copilotstudio/README.md diff --git a/python/samples/getting_started/agents/copilotstudio/copilotstudio_basic.py b/python/samples/02-agents/providers/copilotstudio/copilotstudio_basic.py similarity index 100% rename from python/samples/getting_started/agents/copilotstudio/copilotstudio_basic.py rename to python/samples/02-agents/providers/copilotstudio/copilotstudio_basic.py diff --git a/python/samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py b/python/samples/02-agents/providers/copilotstudio/copilotstudio_with_explicit_settings.py similarity index 100% rename from python/samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py rename to python/samples/02-agents/providers/copilotstudio/copilotstudio_with_explicit_settings.py diff --git a/python/samples/getting_started/agents/custom/README.md b/python/samples/02-agents/providers/custom/README.md similarity index 100% rename from python/samples/getting_started/agents/custom/README.md rename to python/samples/02-agents/providers/custom/README.md diff --git a/python/samples/getting_started/agents/custom/custom_agent.py b/python/samples/02-agents/providers/custom/custom_agent.py similarity index 100% rename from python/samples/getting_started/agents/custom/custom_agent.py rename to python/samples/02-agents/providers/custom/custom_agent.py diff --git a/python/samples/getting_started/agents/github_copilot/README.md b/python/samples/02-agents/providers/github_copilot/README.md similarity index 100% rename from python/samples/getting_started/agents/github_copilot/README.md rename to python/samples/02-agents/providers/github_copilot/README.md diff --git a/python/samples/getting_started/agents/github_copilot/github_copilot_basic.py b/python/samples/02-agents/providers/github_copilot/github_copilot_basic.py similarity index 95% rename from python/samples/getting_started/agents/github_copilot/github_copilot_basic.py rename to python/samples/02-agents/providers/github_copilot/github_copilot_basic.py index 0e2fa722b6..9d5aa78b5c 100644 --- a/python/samples/getting_started/agents/github_copilot/github_copilot_basic.py +++ b/python/samples/02-agents/providers/github_copilot/github_copilot_basic.py @@ -22,7 +22,7 @@ from agent_framework.github import GitHubCopilotAgent from pydantic import Field -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/github_copilot/github_copilot_with_file_operations.py b/python/samples/02-agents/providers/github_copilot/github_copilot_with_file_operations.py similarity index 100% rename from python/samples/getting_started/agents/github_copilot/github_copilot_with_file_operations.py rename to python/samples/02-agents/providers/github_copilot/github_copilot_with_file_operations.py diff --git a/python/samples/getting_started/agents/github_copilot/github_copilot_with_mcp.py b/python/samples/02-agents/providers/github_copilot/github_copilot_with_mcp.py similarity index 100% rename from python/samples/getting_started/agents/github_copilot/github_copilot_with_mcp.py rename to python/samples/02-agents/providers/github_copilot/github_copilot_with_mcp.py diff --git a/python/samples/getting_started/agents/github_copilot/github_copilot_with_multiple_permissions.py b/python/samples/02-agents/providers/github_copilot/github_copilot_with_multiple_permissions.py similarity index 100% rename from python/samples/getting_started/agents/github_copilot/github_copilot_with_multiple_permissions.py rename to python/samples/02-agents/providers/github_copilot/github_copilot_with_multiple_permissions.py diff --git a/python/samples/getting_started/agents/github_copilot/github_copilot_with_session.py b/python/samples/02-agents/providers/github_copilot/github_copilot_with_session.py similarity index 96% rename from python/samples/getting_started/agents/github_copilot/github_copilot_with_session.py rename to python/samples/02-agents/providers/github_copilot/github_copilot_with_session.py index fa1c2e4640..e103cdbde3 100644 --- a/python/samples/getting_started/agents/github_copilot/github_copilot_with_session.py +++ b/python/samples/02-agents/providers/github_copilot/github_copilot_with_session.py @@ -17,7 +17,7 @@ from agent_framework.github import GitHubCopilotAgent from pydantic import Field -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/github_copilot/github_copilot_with_shell.py b/python/samples/02-agents/providers/github_copilot/github_copilot_with_shell.py similarity index 100% rename from python/samples/getting_started/agents/github_copilot/github_copilot_with_shell.py rename to python/samples/02-agents/providers/github_copilot/github_copilot_with_shell.py diff --git a/python/samples/getting_started/agents/github_copilot/github_copilot_with_url.py b/python/samples/02-agents/providers/github_copilot/github_copilot_with_url.py similarity index 100% rename from python/samples/getting_started/agents/github_copilot/github_copilot_with_url.py rename to python/samples/02-agents/providers/github_copilot/github_copilot_with_url.py diff --git a/python/samples/getting_started/agents/ollama/README.md b/python/samples/02-agents/providers/ollama/README.md similarity index 100% rename from python/samples/getting_started/agents/ollama/README.md rename to python/samples/02-agents/providers/ollama/README.md diff --git a/python/samples/getting_started/agents/ollama/ollama_agent_basic.py b/python/samples/02-agents/providers/ollama/ollama_agent_basic.py similarity index 92% rename from python/samples/getting_started/agents/ollama/ollama_agent_basic.py rename to python/samples/02-agents/providers/ollama/ollama_agent_basic.py index 6477e620f0..698a7f9009 100644 --- a/python/samples/getting_started/agents/ollama/ollama_agent_basic.py +++ b/python/samples/02-agents/providers/ollama/ollama_agent_basic.py @@ -19,7 +19,7 @@ https://ollama.com/ """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_time(location: str) -> str: """Get the current time.""" diff --git a/python/samples/getting_started/agents/ollama/ollama_agent_reasoning.py b/python/samples/02-agents/providers/ollama/ollama_agent_reasoning.py similarity index 100% rename from python/samples/getting_started/agents/ollama/ollama_agent_reasoning.py rename to python/samples/02-agents/providers/ollama/ollama_agent_reasoning.py diff --git a/python/samples/getting_started/agents/ollama/ollama_chat_client.py b/python/samples/02-agents/providers/ollama/ollama_chat_client.py similarity index 88% rename from python/samples/getting_started/agents/ollama/ollama_chat_client.py rename to python/samples/02-agents/providers/ollama/ollama_chat_client.py index 07dd5cc368..88f887479b 100644 --- a/python/samples/getting_started/agents/ollama/ollama_chat_client.py +++ b/python/samples/02-agents/providers/ollama/ollama_chat_client.py @@ -19,7 +19,7 @@ https://ollama.com/ """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_time(): """Get the current time.""" diff --git a/python/samples/getting_started/agents/ollama/ollama_chat_multimodal.py b/python/samples/02-agents/providers/ollama/ollama_chat_multimodal.py similarity index 100% rename from python/samples/getting_started/agents/ollama/ollama_chat_multimodal.py rename to python/samples/02-agents/providers/ollama/ollama_chat_multimodal.py diff --git a/python/samples/getting_started/agents/ollama/ollama_with_openai_chat_client.py b/python/samples/02-agents/providers/ollama/ollama_with_openai_chat_client.py similarity index 93% rename from python/samples/getting_started/agents/ollama/ollama_with_openai_chat_client.py rename to python/samples/02-agents/providers/ollama/ollama_with_openai_chat_client.py index da2468cb22..200549b76e 100644 --- a/python/samples/getting_started/agents/ollama/ollama_with_openai_chat_client.py +++ b/python/samples/02-agents/providers/ollama/ollama_with_openai_chat_client.py @@ -21,7 +21,7 @@ Environment Variables: """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, "The location to get the weather for."], diff --git a/python/samples/getting_started/agents/openai/README.md b/python/samples/02-agents/providers/openai/README.md similarity index 100% rename from python/samples/getting_started/agents/openai/README.md rename to python/samples/02-agents/providers/openai/README.md diff --git a/python/samples/getting_started/agents/openai/openai_assistants_basic.py b/python/samples/02-agents/providers/openai/openai_assistants_basic.py similarity index 95% rename from python/samples/getting_started/agents/openai/openai_assistants_basic.py rename to python/samples/02-agents/providers/openai/openai_assistants_basic.py index 0ad7697b2f..768631ea98 100644 --- a/python/samples/getting_started/agents/openai/openai_assistants_basic.py +++ b/python/samples/02-agents/providers/openai/openai_assistants_basic.py @@ -19,8 +19,8 @@ assistant lifecycle management, showing both streaming and non-streaming respons # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_assistants_provider_methods.py b/python/samples/02-agents/providers/openai/openai_assistants_provider_methods.py similarity index 97% rename from python/samples/getting_started/agents/openai/openai_assistants_provider_methods.py rename to python/samples/02-agents/providers/openai/openai_assistants_provider_methods.py index 8b5b7ed5ce..588c2f48dc 100644 --- a/python/samples/getting_started/agents/openai/openai_assistants_provider_methods.py +++ b/python/samples/02-agents/providers/openai/openai_assistants_provider_methods.py @@ -21,8 +21,8 @@ This sample demonstrates the methods available on the OpenAIAssistantProvider cl # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_assistants_with_code_interpreter.py b/python/samples/02-agents/providers/openai/openai_assistants_with_code_interpreter.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_assistants_with_code_interpreter.py rename to python/samples/02-agents/providers/openai/openai_assistants_with_code_interpreter.py diff --git a/python/samples/getting_started/agents/openai/openai_assistants_with_existing_assistant.py b/python/samples/02-agents/providers/openai/openai_assistants_with_existing_assistant.py similarity index 95% rename from python/samples/getting_started/agents/openai/openai_assistants_with_existing_assistant.py rename to python/samples/02-agents/providers/openai/openai_assistants_with_existing_assistant.py index b004253796..b1751885ce 100644 --- a/python/samples/getting_started/agents/openai/openai_assistants_with_existing_assistant.py +++ b/python/samples/02-agents/providers/openai/openai_assistants_with_existing_assistant.py @@ -18,7 +18,7 @@ using the provider's get_agent() and as_agent() methods. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_assistants_with_explicit_settings.py b/python/samples/02-agents/providers/openai/openai_assistants_with_explicit_settings.py similarity index 92% rename from python/samples/getting_started/agents/openai/openai_assistants_with_explicit_settings.py rename to python/samples/02-agents/providers/openai/openai_assistants_with_explicit_settings.py index 15ac03c574..2ef830da78 100644 --- a/python/samples/getting_started/agents/openai/openai_assistants_with_explicit_settings.py +++ b/python/samples/02-agents/providers/openai/openai_assistants_with_explicit_settings.py @@ -19,8 +19,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_assistants_with_file_search.py b/python/samples/02-agents/providers/openai/openai_assistants_with_file_search.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_assistants_with_file_search.py rename to python/samples/02-agents/providers/openai/openai_assistants_with_file_search.py diff --git a/python/samples/getting_started/agents/openai/openai_assistants_with_function_tools.py b/python/samples/02-agents/providers/openai/openai_assistants_with_function_tools.py similarity index 96% rename from python/samples/getting_started/agents/openai/openai_assistants_with_function_tools.py rename to python/samples/02-agents/providers/openai/openai_assistants_with_function_tools.py index fe4b3d3b4e..aa0e6dc289 100644 --- a/python/samples/getting_started/agents/openai/openai_assistants_with_function_tools.py +++ b/python/samples/02-agents/providers/openai/openai_assistants_with_function_tools.py @@ -19,7 +19,7 @@ showing both agent-level and query-level tool configuration patterns. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_assistants_with_response_format.py b/python/samples/02-agents/providers/openai/openai_assistants_with_response_format.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_assistants_with_response_format.py rename to python/samples/02-agents/providers/openai/openai_assistants_with_response_format.py diff --git a/python/samples/getting_started/agents/openai/openai_assistants_with_thread.py b/python/samples/02-agents/providers/openai/openai_assistants_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/openai/openai_assistants_with_thread.py rename to python/samples/02-agents/providers/openai/openai_assistants_with_thread.py index d21ee82b5b..2214736dc0 100644 --- a/python/samples/getting_started/agents/openai/openai_assistants_with_thread.py +++ b/python/samples/02-agents/providers/openai/openai_assistants_with_thread.py @@ -19,8 +19,8 @@ persistent conversation threads and context preservation across interactions. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_chat_client_basic.py b/python/samples/02-agents/providers/openai/openai_chat_client_basic.py similarity index 93% rename from python/samples/getting_started/agents/openai/openai_chat_client_basic.py rename to python/samples/02-agents/providers/openai/openai_chat_client_basic.py index d5d238c5a9..167cdb6f4c 100644 --- a/python/samples/getting_started/agents/openai/openai_chat_client_basic.py +++ b/python/samples/02-agents/providers/openai/openai_chat_client_basic.py @@ -16,8 +16,8 @@ interactions, showing both streaming and non-streaming responses. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, "The location to get the weather for."], diff --git a/python/samples/getting_started/agents/openai/openai_chat_client_with_explicit_settings.py b/python/samples/02-agents/providers/openai/openai_chat_client_with_explicit_settings.py similarity index 90% rename from python/samples/getting_started/agents/openai/openai_chat_client_with_explicit_settings.py rename to python/samples/02-agents/providers/openai/openai_chat_client_with_explicit_settings.py index 4090263c8a..a1dc84fb02 100644 --- a/python/samples/getting_started/agents/openai/openai_chat_client_with_explicit_settings.py +++ b/python/samples/02-agents/providers/openai/openai_chat_client_with_explicit_settings.py @@ -18,8 +18,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_chat_client_with_function_tools.py b/python/samples/02-agents/providers/openai/openai_chat_client_with_function_tools.py similarity index 96% rename from python/samples/getting_started/agents/openai/openai_chat_client_with_function_tools.py rename to python/samples/02-agents/providers/openai/openai_chat_client_with_function_tools.py index 47fb4ef678..c8e5f20f7d 100644 --- a/python/samples/getting_started/agents/openai/openai_chat_client_with_function_tools.py +++ b/python/samples/02-agents/providers/openai/openai_chat_client_with_function_tools.py @@ -18,8 +18,8 @@ showing both agent-level and query-level tool configuration patterns. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_chat_client_with_local_mcp.py b/python/samples/02-agents/providers/openai/openai_chat_client_with_local_mcp.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_chat_client_with_local_mcp.py rename to python/samples/02-agents/providers/openai/openai_chat_client_with_local_mcp.py diff --git a/python/samples/getting_started/agents/openai/openai_chat_client_with_runtime_json_schema.py b/python/samples/02-agents/providers/openai/openai_chat_client_with_runtime_json_schema.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_chat_client_with_runtime_json_schema.py rename to python/samples/02-agents/providers/openai/openai_chat_client_with_runtime_json_schema.py diff --git a/python/samples/getting_started/agents/openai/openai_chat_client_with_thread.py b/python/samples/02-agents/providers/openai/openai_chat_client_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/openai/openai_chat_client_with_thread.py rename to python/samples/02-agents/providers/openai/openai_chat_client_with_thread.py index 0982ab7299..9486baa5f3 100644 --- a/python/samples/getting_started/agents/openai/openai_chat_client_with_thread.py +++ b/python/samples/02-agents/providers/openai/openai_chat_client_with_thread.py @@ -17,8 +17,8 @@ conversation threads and message history preservation across interactions. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_chat_client_with_web_search.py b/python/samples/02-agents/providers/openai/openai_chat_client_with_web_search.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_chat_client_with_web_search.py rename to python/samples/02-agents/providers/openai/openai_chat_client_with_web_search.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_basic.py b/python/samples/02-agents/providers/openai/openai_responses_client_basic.py similarity index 96% rename from python/samples/getting_started/agents/openai/openai_responses_client_basic.py rename to python/samples/02-agents/providers/openai/openai_responses_client_basic.py index c1b94cc35a..42eddc694f 100644 --- a/python/samples/getting_started/agents/openai/openai_responses_client_basic.py +++ b/python/samples/02-agents/providers/openai/openai_responses_client_basic.py @@ -67,8 +67,8 @@ async def security_and_override_middleware( # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_image_analysis.py b/python/samples/02-agents/providers/openai/openai_responses_client_image_analysis.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_image_analysis.py rename to python/samples/02-agents/providers/openai/openai_responses_client_image_analysis.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_image_generation.py b/python/samples/02-agents/providers/openai/openai_responses_client_image_generation.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_image_generation.py rename to python/samples/02-agents/providers/openai/openai_responses_client_image_generation.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_reasoning.py b/python/samples/02-agents/providers/openai/openai_responses_client_reasoning.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_reasoning.py rename to python/samples/02-agents/providers/openai/openai_responses_client_reasoning.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_streaming_image_generation.py b/python/samples/02-agents/providers/openai/openai_responses_client_streaming_image_generation.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_streaming_image_generation.py rename to python/samples/02-agents/providers/openai/openai_responses_client_streaming_image_generation.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_agent_as_tool.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_agent_as_tool.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_agent_as_tool.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_agent_as_tool.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_code_interpreter.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_code_interpreter.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter_files.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_code_interpreter_files.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter_files.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_code_interpreter_files.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_explicit_settings.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_explicit_settings.py similarity index 90% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_explicit_settings.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_explicit_settings.py index c8fdb24ffb..428e6dbb79 100644 --- a/python/samples/getting_started/agents/openai/openai_responses_client_with_explicit_settings.py +++ b/python/samples/02-agents/providers/openai/openai_responses_client_with_explicit_settings.py @@ -18,8 +18,8 @@ settings rather than relying on environment variable defaults. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_file_search.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_file_search.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_file_search.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_file_search.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_function_tools.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_function_tools.py similarity index 96% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_function_tools.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_function_tools.py index ccdf2b0dc0..faba202798 100644 --- a/python/samples/getting_started/agents/openai/openai_responses_client_with_function_tools.py +++ b/python/samples/02-agents/providers/openai/openai_responses_client_with_function_tools.py @@ -18,8 +18,8 @@ showing both agent-level and query-level tool configuration patterns. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_hosted_mcp.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_hosted_mcp.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_hosted_mcp.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_hosted_mcp.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_local_mcp.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_local_mcp.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_local_mcp.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_local_mcp.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_runtime_json_schema.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_runtime_json_schema.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_runtime_json_schema.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_runtime_json_schema.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_structured_output.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_structured_output.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_structured_output.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_structured_output.py diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_thread.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_thread.py similarity index 97% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_thread.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_thread.py index ae1a48a743..f3e6024e17 100644 --- a/python/samples/getting_started/agents/openai/openai_responses_client_with_thread.py +++ b/python/samples/02-agents/providers/openai/openai_responses_client_with_thread.py @@ -17,8 +17,8 @@ persistent conversation context and simplified response handling. # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/agents/openai/openai_responses_client_with_web_search.py b/python/samples/02-agents/providers/openai/openai_responses_client_with_web_search.py similarity index 100% rename from python/samples/getting_started/agents/openai/openai_responses_client_with_web_search.py rename to python/samples/02-agents/providers/openai/openai_responses_client_with_web_search.py diff --git a/python/samples/concepts/response_stream.py b/python/samples/02-agents/response_stream.py similarity index 100% rename from python/samples/concepts/response_stream.py rename to python/samples/02-agents/response_stream.py diff --git a/python/samples/getting_started/tools/function_invocation_configuration.py b/python/samples/02-agents/tools/function_invocation_configuration.py similarity index 90% rename from python/samples/getting_started/tools/function_invocation_configuration.py rename to python/samples/02-agents/tools/function_invocation_configuration.py index b6cb27a7bc..b116e53197 100644 --- a/python/samples/getting_started/tools/function_invocation_configuration.py +++ b/python/samples/02-agents/tools/function_invocation_configuration.py @@ -14,7 +14,7 @@ This behavior is the same for all chat client types. """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def add( x: Annotated[int, "First number"], diff --git a/python/samples/getting_started/tools/function_tool_declaration_only.py b/python/samples/02-agents/tools/function_tool_declaration_only.py similarity index 100% rename from python/samples/getting_started/tools/function_tool_declaration_only.py rename to python/samples/02-agents/tools/function_tool_declaration_only.py diff --git a/python/samples/getting_started/tools/function_tool_from_dict_with_dependency_injection.py b/python/samples/02-agents/tools/function_tool_from_dict_with_dependency_injection.py similarity index 100% rename from python/samples/getting_started/tools/function_tool_from_dict_with_dependency_injection.py rename to python/samples/02-agents/tools/function_tool_from_dict_with_dependency_injection.py diff --git a/python/samples/getting_started/tools/function_tool_recover_from_failures.py b/python/samples/02-agents/tools/function_tool_recover_from_failures.py similarity index 95% rename from python/samples/getting_started/tools/function_tool_recover_from_failures.py rename to python/samples/02-agents/tools/function_tool_recover_from_failures.py index 8c38a81e77..f3ce9f1adc 100644 --- a/python/samples/getting_started/tools/function_tool_recover_from_failures.py +++ b/python/samples/02-agents/tools/function_tool_recover_from_failures.py @@ -14,7 +14,7 @@ The LLM decides whether to retry the call or to respond with something else, bas """ -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def greet(name: Annotated[str, "Name to greet"]) -> str: """Greet someone.""" diff --git a/python/samples/getting_started/tools/function_tool_with_approval.py b/python/samples/02-agents/tools/function_tool_with_approval.py similarity index 97% rename from python/samples/getting_started/tools/function_tool_with_approval.py rename to python/samples/02-agents/tools/function_tool_with_approval.py index e149289091..21cd8bfe24 100644 --- a/python/samples/getting_started/tools/function_tool_with_approval.py +++ b/python/samples/02-agents/tools/function_tool_with_approval.py @@ -20,7 +20,7 @@ It shows how to handle function call approvals without using threads. conditions = ["sunny", "cloudy", "raining", "snowing", "clear"] -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather(location: Annotated[str, "The city and state, e.g. San Francisco, CA"]) -> str: """Get the current weather for a given location.""" diff --git a/python/samples/getting_started/tools/function_tool_with_approval_and_threads.py b/python/samples/02-agents/tools/function_tool_with_approval_and_threads.py similarity index 100% rename from python/samples/getting_started/tools/function_tool_with_approval_and_threads.py rename to python/samples/02-agents/tools/function_tool_with_approval_and_threads.py diff --git a/python/samples/getting_started/tools/function_tool_with_explicit_schema.py b/python/samples/02-agents/tools/function_tool_with_explicit_schema.py similarity index 100% rename from python/samples/getting_started/tools/function_tool_with_explicit_schema.py rename to python/samples/02-agents/tools/function_tool_with_explicit_schema.py diff --git a/python/samples/getting_started/tools/function_tool_with_kwargs.py b/python/samples/02-agents/tools/function_tool_with_kwargs.py similarity index 90% rename from python/samples/getting_started/tools/function_tool_with_kwargs.py rename to python/samples/02-agents/tools/function_tool_with_kwargs.py index 59225c0832..400d9f65f1 100644 --- a/python/samples/getting_started/tools/function_tool_with_kwargs.py +++ b/python/samples/02-agents/tools/function_tool_with_kwargs.py @@ -20,7 +20,7 @@ or provide. # Define the function tool with **kwargs to accept injected arguments -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/tools/function_tool_with_max_exceptions.py b/python/samples/02-agents/tools/function_tool_with_max_exceptions.py similarity index 100% rename from python/samples/getting_started/tools/function_tool_with_max_exceptions.py rename to python/samples/02-agents/tools/function_tool_with_max_exceptions.py diff --git a/python/samples/getting_started/tools/function_tool_with_max_invocations.py b/python/samples/02-agents/tools/function_tool_with_max_invocations.py similarity index 100% rename from python/samples/getting_started/tools/function_tool_with_max_invocations.py rename to python/samples/02-agents/tools/function_tool_with_max_invocations.py diff --git a/python/samples/getting_started/tools/function_tool_with_thread_injection.py b/python/samples/02-agents/tools/function_tool_with_thread_injection.py similarity index 90% rename from python/samples/getting_started/tools/function_tool_with_thread_injection.py rename to python/samples/02-agents/tools/function_tool_with_thread_injection.py index 0a02ef09d7..b73212774b 100644 --- a/python/samples/getting_started/tools/function_tool_with_thread_injection.py +++ b/python/samples/02-agents/tools/function_tool_with_thread_injection.py @@ -16,7 +16,7 @@ and accessing that thread in AI function. # Define the function tool with **kwargs -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") async def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/tools/tool_in_class.py b/python/samples/02-agents/tools/tool_in_class.py similarity index 100% rename from python/samples/getting_started/tools/tool_in_class.py rename to python/samples/02-agents/tools/tool_in_class.py diff --git a/python/samples/concepts/typed_options.py b/python/samples/02-agents/typed_options.py similarity index 100% rename from python/samples/concepts/typed_options.py rename to python/samples/02-agents/typed_options.py diff --git a/python/samples/getting_started/workflows/README.md b/python/samples/03-workflows/README.md similarity index 96% rename from python/samples/getting_started/workflows/README.md rename to python/samples/03-workflows/README.md index 1e132f9475..9ee6f517e9 100644 --- a/python/samples/getting_started/workflows/README.md +++ b/python/samples/03-workflows/README.md @@ -50,7 +50,7 @@ Once comfortable with these, explore the rest of the samples below. | Checkpoint & Resume | [checkpoint/checkpoint_with_resume.py](./checkpoint/checkpoint_with_resume.py) | Create checkpoints, inspect them, and resume execution | | Checkpoint & HITL Resume | [checkpoint/checkpoint_with_human_in_the_loop.py](./checkpoint/checkpoint_with_human_in_the_loop.py) | Combine checkpointing with human approvals and resume pending HITL requests | | Checkpointed Sub-Workflow | [checkpoint/sub_workflow_checkpoint.py](./checkpoint/sub_workflow_checkpoint.py) | Save and resume a sub-workflow that pauses for human approval | -| Handoff + Tool Approval Resume | Moved to orchestration samples | Handoff workflow that captures tool-call approvals in checkpoints and resumes with human decisions | +| Handoff + Tool Approval Resume | [orchestrations/handoff_with_tool_approval_checkpoint_resume.py](./orchestrations/handoff_with_tool_approval_checkpoint_resume.py) | Handoff workflow that captures tool-call approvals in checkpoints and resumes with human decisions | | Workflow as Agent Checkpoint | [checkpoint/workflow_as_agent_checkpoint.py](./checkpoint/workflow_as_agent_checkpoint.py) | Enable checkpointing when using workflow.as_agent() with checkpoint_storage parameter | ### composition @@ -95,12 +95,12 @@ Builder-based tool approval samples are maintained in the orchestration sample s | ------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Executor I/O Observation | [observability/executor_io_observation.py](./observability/executor_io_observation.py) | Observe executor input/output data via executor_invoked events (type='executor_invoked') and executor_completed events (type='executor_completed') without modifying executor code | -For additional observability samples in Agent Framework, see the [observability getting started samples](../observability/README.md). The [sample](../observability/workflow_observability.py) demonstrates integrating observability into workflows. +For additional observability samples in Agent Framework, see the [observability concept samples](../02-agents/observability/README.md). The [workflow observability sample](../02-agents/observability/workflow_observability.py) demonstrates integrating observability into workflows. ### orchestration Orchestration-focused samples (Sequential, Concurrent, Handoff, GroupChat, Magentic), including builder-based -`workflow.as_agent(...)` variants, are documented in the [orchestrations](../orchestrations/README.md) directory. +`workflow.as_agent(...)` variants, are documented in the [orchestrations](./orchestrations/README.md) directory. ### parallelism diff --git a/python/samples/getting_started/workflows/_start-here/step1_executors_and_edges.py b/python/samples/03-workflows/_start-here/step1_executors_and_edges.py similarity index 100% rename from python/samples/getting_started/workflows/_start-here/step1_executors_and_edges.py rename to python/samples/03-workflows/_start-here/step1_executors_and_edges.py diff --git a/python/samples/getting_started/workflows/_start-here/step2_agents_in_a_workflow.py b/python/samples/03-workflows/_start-here/step2_agents_in_a_workflow.py similarity index 100% rename from python/samples/getting_started/workflows/_start-here/step2_agents_in_a_workflow.py rename to python/samples/03-workflows/_start-here/step2_agents_in_a_workflow.py diff --git a/python/samples/getting_started/workflows/_start-here/step3_streaming.py b/python/samples/03-workflows/_start-here/step3_streaming.py similarity index 100% rename from python/samples/getting_started/workflows/_start-here/step3_streaming.py rename to python/samples/03-workflows/_start-here/step3_streaming.py diff --git a/python/samples/getting_started/workflows/agents/azure_ai_agents_streaming.py b/python/samples/03-workflows/agents/azure_ai_agents_streaming.py similarity index 100% rename from python/samples/getting_started/workflows/agents/azure_ai_agents_streaming.py rename to python/samples/03-workflows/agents/azure_ai_agents_streaming.py diff --git a/python/samples/getting_started/workflows/agents/azure_ai_agents_with_shared_thread.py b/python/samples/03-workflows/agents/azure_ai_agents_with_shared_thread.py similarity index 100% rename from python/samples/getting_started/workflows/agents/azure_ai_agents_with_shared_thread.py rename to python/samples/03-workflows/agents/azure_ai_agents_with_shared_thread.py diff --git a/python/samples/getting_started/workflows/agents/azure_chat_agents_and_executor.py b/python/samples/03-workflows/agents/azure_chat_agents_and_executor.py similarity index 100% rename from python/samples/getting_started/workflows/agents/azure_chat_agents_and_executor.py rename to python/samples/03-workflows/agents/azure_chat_agents_and_executor.py diff --git a/python/samples/getting_started/workflows/agents/azure_chat_agents_streaming.py b/python/samples/03-workflows/agents/azure_chat_agents_streaming.py similarity index 100% rename from python/samples/getting_started/workflows/agents/azure_chat_agents_streaming.py rename to python/samples/03-workflows/agents/azure_chat_agents_streaming.py diff --git a/python/samples/getting_started/workflows/agents/azure_chat_agents_tool_calls_with_feedback.py b/python/samples/03-workflows/agents/azure_chat_agents_tool_calls_with_feedback.py similarity index 98% rename from python/samples/getting_started/workflows/agents/azure_chat_agents_tool_calls_with_feedback.py rename to python/samples/03-workflows/agents/azure_chat_agents_tool_calls_with_feedback.py index 10afd3304f..96f25f65f7 100644 --- a/python/samples/getting_started/workflows/agents/azure_chat_agents_tool_calls_with_feedback.py +++ b/python/samples/03-workflows/agents/azure_chat_agents_tool_calls_with_feedback.py @@ -51,8 +51,8 @@ Prerequisites: # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py and -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py and +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def fetch_product_brief( product_name: Annotated[str, Field(description="Product name to look up.")], diff --git a/python/samples/getting_started/orchestrations/concurrent/concurrent_workflow_as_agent.py b/python/samples/03-workflows/agents/concurrent_workflow_as_agent.py similarity index 100% rename from python/samples/getting_started/orchestrations/concurrent/concurrent_workflow_as_agent.py rename to python/samples/03-workflows/agents/concurrent_workflow_as_agent.py diff --git a/python/samples/getting_started/workflows/agents/custom_agent_executors.py b/python/samples/03-workflows/agents/custom_agent_executors.py similarity index 100% rename from python/samples/getting_started/workflows/agents/custom_agent_executors.py rename to python/samples/03-workflows/agents/custom_agent_executors.py diff --git a/python/samples/getting_started/orchestrations/group-chat/group_chat_workflow_as_agent.py b/python/samples/03-workflows/agents/group_chat_workflow_as_agent.py similarity index 100% rename from python/samples/getting_started/orchestrations/group-chat/group_chat_workflow_as_agent.py rename to python/samples/03-workflows/agents/group_chat_workflow_as_agent.py diff --git a/python/samples/getting_started/orchestrations/handoff/handoff_workflow_as_agent.py b/python/samples/03-workflows/agents/handoff_workflow_as_agent.py similarity index 98% rename from python/samples/getting_started/orchestrations/handoff/handoff_workflow_as_agent.py rename to python/samples/03-workflows/agents/handoff_workflow_as_agent.py index 0a209f1884..0154ed4ce3 100644 --- a/python/samples/getting_started/orchestrations/handoff/handoff_workflow_as_agent.py +++ b/python/samples/03-workflows/agents/handoff_workflow_as_agent.py @@ -39,8 +39,8 @@ Key Concepts: # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; # See: -# samples/getting_started/tools/function_tool_with_approval.py -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# samples/02-agents/tools/function_tool_with_approval.py +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str: """Simulated function to process a refund for a given order number.""" diff --git a/python/samples/getting_started/orchestrations/magentic/magentic_workflow_as_agent.py b/python/samples/03-workflows/agents/magentic_workflow_as_agent.py similarity index 100% rename from python/samples/getting_started/orchestrations/magentic/magentic_workflow_as_agent.py rename to python/samples/03-workflows/agents/magentic_workflow_as_agent.py diff --git a/python/samples/getting_started/orchestrations/sequential/sequential_workflow_as_agent.py b/python/samples/03-workflows/agents/sequential_workflow_as_agent.py similarity index 100% rename from python/samples/getting_started/orchestrations/sequential/sequential_workflow_as_agent.py rename to python/samples/03-workflows/agents/sequential_workflow_as_agent.py diff --git a/python/samples/getting_started/workflows/agents/workflow_as_agent_human_in_the_loop.py b/python/samples/03-workflows/agents/workflow_as_agent_human_in_the_loop.py similarity index 95% rename from python/samples/getting_started/workflows/agents/workflow_as_agent_human_in_the_loop.py rename to python/samples/03-workflows/agents/workflow_as_agent_human_in_the_loop.py index d0a679455a..dfe510762d 100644 --- a/python/samples/getting_started/workflows/agents/workflow_as_agent_human_in_the_loop.py +++ b/python/samples/03-workflows/agents/workflow_as_agent_human_in_the_loop.py @@ -11,10 +11,14 @@ from typing import Any from agent_framework.azure import AzureOpenAIResponsesClient from azure.identity import AzureCliCredential -# Ensure local getting_started package can be imported when running as a script. +# Ensure local package can be imported when running as a script. _SAMPLES_ROOT = Path(__file__).resolve().parents[3] if str(_SAMPLES_ROOT) not in sys.path: sys.path.insert(0, str(_SAMPLES_ROOT)) +# Also add the current directory for sibling imports +_CURRENT_DIR = str(Path(__file__).resolve().parent) +if _CURRENT_DIR not in sys.path: + sys.path.insert(0, _CURRENT_DIR) from agent_framework import ( # noqa: E402 Content, @@ -26,7 +30,7 @@ from agent_framework import ( # noqa: E402 handler, response_handler, ) -from getting_started.workflows.agents.workflow_as_agent_reflection_pattern import ( # noqa: E402 +from workflow_as_agent_reflection_pattern import ( # noqa: E402 ReviewRequest, ReviewResponse, Worker, diff --git a/python/samples/getting_started/workflows/agents/workflow_as_agent_kwargs.py b/python/samples/03-workflows/agents/workflow_as_agent_kwargs.py similarity index 96% rename from python/samples/getting_started/workflows/agents/workflow_as_agent_kwargs.py rename to python/samples/03-workflows/agents/workflow_as_agent_kwargs.py index a6fb51f8d8..df61734cb8 100644 --- a/python/samples/getting_started/workflows/agents/workflow_as_agent_kwargs.py +++ b/python/samples/03-workflows/agents/workflow_as_agent_kwargs.py @@ -37,8 +37,8 @@ Prerequisites: # Define tools that accept custom context via **kwargs # NOTE: approval_mode="never_require" is for sample brevity. -# Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_user_data( query: Annotated[str, Field(description="What user data to retrieve")], diff --git a/python/samples/getting_started/workflows/agents/workflow_as_agent_reflection_pattern.py b/python/samples/03-workflows/agents/workflow_as_agent_reflection_pattern.py similarity index 100% rename from python/samples/getting_started/workflows/agents/workflow_as_agent_reflection_pattern.py rename to python/samples/03-workflows/agents/workflow_as_agent_reflection_pattern.py diff --git a/python/samples/getting_started/workflows/agents/workflow_as_agent_with_thread.py b/python/samples/03-workflows/agents/workflow_as_agent_with_thread.py similarity index 100% rename from python/samples/getting_started/workflows/agents/workflow_as_agent_with_thread.py rename to python/samples/03-workflows/agents/workflow_as_agent_with_thread.py diff --git a/python/samples/getting_started/workflows/checkpoint/checkpoint_with_human_in_the_loop.py b/python/samples/03-workflows/checkpoint/checkpoint_with_human_in_the_loop.py similarity index 100% rename from python/samples/getting_started/workflows/checkpoint/checkpoint_with_human_in_the_loop.py rename to python/samples/03-workflows/checkpoint/checkpoint_with_human_in_the_loop.py diff --git a/python/samples/getting_started/workflows/checkpoint/checkpoint_with_resume.py b/python/samples/03-workflows/checkpoint/checkpoint_with_resume.py similarity index 100% rename from python/samples/getting_started/workflows/checkpoint/checkpoint_with_resume.py rename to python/samples/03-workflows/checkpoint/checkpoint_with_resume.py diff --git a/python/samples/getting_started/workflows/checkpoint/sub_workflow_checkpoint.py b/python/samples/03-workflows/checkpoint/sub_workflow_checkpoint.py similarity index 100% rename from python/samples/getting_started/workflows/checkpoint/sub_workflow_checkpoint.py rename to python/samples/03-workflows/checkpoint/sub_workflow_checkpoint.py diff --git a/python/samples/getting_started/workflows/checkpoint/workflow_as_agent_checkpoint.py b/python/samples/03-workflows/checkpoint/workflow_as_agent_checkpoint.py similarity index 100% rename from python/samples/getting_started/workflows/checkpoint/workflow_as_agent_checkpoint.py rename to python/samples/03-workflows/checkpoint/workflow_as_agent_checkpoint.py diff --git a/python/samples/getting_started/workflows/composition/sub_workflow_basics.py b/python/samples/03-workflows/composition/sub_workflow_basics.py similarity index 100% rename from python/samples/getting_started/workflows/composition/sub_workflow_basics.py rename to python/samples/03-workflows/composition/sub_workflow_basics.py diff --git a/python/samples/getting_started/workflows/composition/sub_workflow_kwargs.py b/python/samples/03-workflows/composition/sub_workflow_kwargs.py similarity index 97% rename from python/samples/getting_started/workflows/composition/sub_workflow_kwargs.py rename to python/samples/03-workflows/composition/sub_workflow_kwargs.py index bd1c60ecfa..71e5ae54ad 100644 --- a/python/samples/getting_started/workflows/composition/sub_workflow_kwargs.py +++ b/python/samples/03-workflows/composition/sub_workflow_kwargs.py @@ -35,8 +35,8 @@ Prerequisites: # Define tools that access custom context via **kwargs # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py and -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py and +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_authenticated_data( resource: Annotated[str, "The resource to fetch"], diff --git a/python/samples/getting_started/workflows/composition/sub_workflow_parallel_requests.py b/python/samples/03-workflows/composition/sub_workflow_parallel_requests.py similarity index 100% rename from python/samples/getting_started/workflows/composition/sub_workflow_parallel_requests.py rename to python/samples/03-workflows/composition/sub_workflow_parallel_requests.py diff --git a/python/samples/getting_started/workflows/composition/sub_workflow_request_interception.py b/python/samples/03-workflows/composition/sub_workflow_request_interception.py similarity index 100% rename from python/samples/getting_started/workflows/composition/sub_workflow_request_interception.py rename to python/samples/03-workflows/composition/sub_workflow_request_interception.py diff --git a/python/samples/getting_started/workflows/control-flow/edge_condition.py b/python/samples/03-workflows/control-flow/edge_condition.py similarity index 100% rename from python/samples/getting_started/workflows/control-flow/edge_condition.py rename to python/samples/03-workflows/control-flow/edge_condition.py diff --git a/python/samples/getting_started/workflows/control-flow/multi_selection_edge_group.py b/python/samples/03-workflows/control-flow/multi_selection_edge_group.py similarity index 100% rename from python/samples/getting_started/workflows/control-flow/multi_selection_edge_group.py rename to python/samples/03-workflows/control-flow/multi_selection_edge_group.py diff --git a/python/samples/getting_started/workflows/control-flow/sequential_executors.py b/python/samples/03-workflows/control-flow/sequential_executors.py similarity index 100% rename from python/samples/getting_started/workflows/control-flow/sequential_executors.py rename to python/samples/03-workflows/control-flow/sequential_executors.py diff --git a/python/samples/getting_started/workflows/control-flow/sequential_streaming.py b/python/samples/03-workflows/control-flow/sequential_streaming.py similarity index 100% rename from python/samples/getting_started/workflows/control-flow/sequential_streaming.py rename to python/samples/03-workflows/control-flow/sequential_streaming.py diff --git a/python/samples/getting_started/workflows/control-flow/simple_loop.py b/python/samples/03-workflows/control-flow/simple_loop.py similarity index 100% rename from python/samples/getting_started/workflows/control-flow/simple_loop.py rename to python/samples/03-workflows/control-flow/simple_loop.py diff --git a/python/samples/getting_started/workflows/control-flow/switch_case_edge_group.py b/python/samples/03-workflows/control-flow/switch_case_edge_group.py similarity index 100% rename from python/samples/getting_started/workflows/control-flow/switch_case_edge_group.py rename to python/samples/03-workflows/control-flow/switch_case_edge_group.py diff --git a/python/samples/getting_started/workflows/control-flow/workflow_cancellation.py b/python/samples/03-workflows/control-flow/workflow_cancellation.py similarity index 100% rename from python/samples/getting_started/workflows/control-flow/workflow_cancellation.py rename to python/samples/03-workflows/control-flow/workflow_cancellation.py diff --git a/python/samples/getting_started/workflows/declarative/README.md b/python/samples/03-workflows/declarative/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/README.md rename to python/samples/03-workflows/declarative/README.md diff --git a/python/samples/getting_started/workflows/declarative/__init__.py b/python/samples/03-workflows/declarative/__init__.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/__init__.py rename to python/samples/03-workflows/declarative/__init__.py diff --git a/python/samples/getting_started/workflows/declarative/conditional_workflow/README.md b/python/samples/03-workflows/declarative/conditional_workflow/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/conditional_workflow/README.md rename to python/samples/03-workflows/declarative/conditional_workflow/README.md diff --git a/python/samples/getting_started/workflows/declarative/conditional_workflow/main.py b/python/samples/03-workflows/declarative/conditional_workflow/main.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/conditional_workflow/main.py rename to python/samples/03-workflows/declarative/conditional_workflow/main.py diff --git a/python/samples/getting_started/workflows/declarative/conditional_workflow/workflow.yaml b/python/samples/03-workflows/declarative/conditional_workflow/workflow.yaml similarity index 100% rename from python/samples/getting_started/workflows/declarative/conditional_workflow/workflow.yaml rename to python/samples/03-workflows/declarative/conditional_workflow/workflow.yaml diff --git a/python/samples/getting_started/workflows/declarative/customer_support/README.md b/python/samples/03-workflows/declarative/customer_support/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/customer_support/README.md rename to python/samples/03-workflows/declarative/customer_support/README.md diff --git a/python/samples/demos/chatkit-integration/__init__.py b/python/samples/03-workflows/declarative/customer_support/__init__.py similarity index 100% rename from python/samples/demos/chatkit-integration/__init__.py rename to python/samples/03-workflows/declarative/customer_support/__init__.py diff --git a/python/samples/getting_started/workflows/declarative/customer_support/main.py b/python/samples/03-workflows/declarative/customer_support/main.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/customer_support/main.py rename to python/samples/03-workflows/declarative/customer_support/main.py diff --git a/python/samples/getting_started/workflows/declarative/customer_support/ticketing_plugin.py b/python/samples/03-workflows/declarative/customer_support/ticketing_plugin.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/customer_support/ticketing_plugin.py rename to python/samples/03-workflows/declarative/customer_support/ticketing_plugin.py diff --git a/python/samples/getting_started/workflows/declarative/customer_support/workflow.yaml b/python/samples/03-workflows/declarative/customer_support/workflow.yaml similarity index 100% rename from python/samples/getting_started/workflows/declarative/customer_support/workflow.yaml rename to python/samples/03-workflows/declarative/customer_support/workflow.yaml diff --git a/python/samples/getting_started/workflows/declarative/deep_research/README.md b/python/samples/03-workflows/declarative/deep_research/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/deep_research/README.md rename to python/samples/03-workflows/declarative/deep_research/README.md diff --git a/python/samples/getting_started/workflows/declarative/customer_support/__init__.py b/python/samples/03-workflows/declarative/deep_research/__init__.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/customer_support/__init__.py rename to python/samples/03-workflows/declarative/deep_research/__init__.py diff --git a/python/samples/getting_started/workflows/declarative/deep_research/main.py b/python/samples/03-workflows/declarative/deep_research/main.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/deep_research/main.py rename to python/samples/03-workflows/declarative/deep_research/main.py diff --git a/python/samples/getting_started/workflows/declarative/function_tools/README.md b/python/samples/03-workflows/declarative/function_tools/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/function_tools/README.md rename to python/samples/03-workflows/declarative/function_tools/README.md diff --git a/python/samples/getting_started/workflows/declarative/function_tools/main.py b/python/samples/03-workflows/declarative/function_tools/main.py similarity index 96% rename from python/samples/getting_started/workflows/declarative/function_tools/main.py rename to python/samples/03-workflows/declarative/function_tools/main.py index e6169b68e3..4bda15b655 100644 --- a/python/samples/getting_started/workflows/declarative/function_tools/main.py +++ b/python/samples/03-workflows/declarative/function_tools/main.py @@ -39,7 +39,7 @@ MENU_ITEMS = [ ] -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_menu() -> list[dict[str, Any]]: """Get all menu items.""" diff --git a/python/samples/getting_started/workflows/declarative/function_tools/workflow.yaml b/python/samples/03-workflows/declarative/function_tools/workflow.yaml similarity index 100% rename from python/samples/getting_started/workflows/declarative/function_tools/workflow.yaml rename to python/samples/03-workflows/declarative/function_tools/workflow.yaml diff --git a/python/samples/getting_started/workflows/declarative/human_in_loop/README.md b/python/samples/03-workflows/declarative/human_in_loop/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/human_in_loop/README.md rename to python/samples/03-workflows/declarative/human_in_loop/README.md diff --git a/python/samples/getting_started/workflows/declarative/human_in_loop/main.py b/python/samples/03-workflows/declarative/human_in_loop/main.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/human_in_loop/main.py rename to python/samples/03-workflows/declarative/human_in_loop/main.py diff --git a/python/samples/getting_started/workflows/declarative/human_in_loop/workflow.yaml b/python/samples/03-workflows/declarative/human_in_loop/workflow.yaml similarity index 100% rename from python/samples/getting_started/workflows/declarative/human_in_loop/workflow.yaml rename to python/samples/03-workflows/declarative/human_in_loop/workflow.yaml diff --git a/python/samples/getting_started/workflows/declarative/marketing/README.md b/python/samples/03-workflows/declarative/marketing/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/marketing/README.md rename to python/samples/03-workflows/declarative/marketing/README.md diff --git a/python/samples/getting_started/workflows/declarative/marketing/main.py b/python/samples/03-workflows/declarative/marketing/main.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/marketing/main.py rename to python/samples/03-workflows/declarative/marketing/main.py diff --git a/python/samples/getting_started/workflows/declarative/marketing/workflow.yaml b/python/samples/03-workflows/declarative/marketing/workflow.yaml similarity index 100% rename from python/samples/getting_started/workflows/declarative/marketing/workflow.yaml rename to python/samples/03-workflows/declarative/marketing/workflow.yaml diff --git a/python/samples/getting_started/workflows/declarative/simple_workflow/README.md b/python/samples/03-workflows/declarative/simple_workflow/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/simple_workflow/README.md rename to python/samples/03-workflows/declarative/simple_workflow/README.md diff --git a/python/samples/getting_started/workflows/declarative/simple_workflow/main.py b/python/samples/03-workflows/declarative/simple_workflow/main.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/simple_workflow/main.py rename to python/samples/03-workflows/declarative/simple_workflow/main.py diff --git a/python/samples/getting_started/workflows/declarative/simple_workflow/workflow.yaml b/python/samples/03-workflows/declarative/simple_workflow/workflow.yaml similarity index 100% rename from python/samples/getting_started/workflows/declarative/simple_workflow/workflow.yaml rename to python/samples/03-workflows/declarative/simple_workflow/workflow.yaml diff --git a/python/samples/getting_started/workflows/declarative/student_teacher/README.md b/python/samples/03-workflows/declarative/student_teacher/README.md similarity index 100% rename from python/samples/getting_started/workflows/declarative/student_teacher/README.md rename to python/samples/03-workflows/declarative/student_teacher/README.md diff --git a/python/samples/getting_started/workflows/declarative/student_teacher/main.py b/python/samples/03-workflows/declarative/student_teacher/main.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/student_teacher/main.py rename to python/samples/03-workflows/declarative/student_teacher/main.py diff --git a/python/samples/getting_started/workflows/declarative/student_teacher/workflow.yaml b/python/samples/03-workflows/declarative/student_teacher/workflow.yaml similarity index 100% rename from python/samples/getting_started/workflows/declarative/student_teacher/workflow.yaml rename to python/samples/03-workflows/declarative/student_teacher/workflow.yaml diff --git a/python/samples/getting_started/workflows/human-in-the-loop/agents_with_HITL.py b/python/samples/03-workflows/human-in-the-loop/agents_with_HITL.py similarity index 100% rename from python/samples/getting_started/workflows/human-in-the-loop/agents_with_HITL.py rename to python/samples/03-workflows/human-in-the-loop/agents_with_HITL.py diff --git a/python/samples/getting_started/workflows/human-in-the-loop/agents_with_approval_requests.py b/python/samples/03-workflows/human-in-the-loop/agents_with_approval_requests.py similarity index 98% rename from python/samples/getting_started/workflows/human-in-the-loop/agents_with_approval_requests.py rename to python/samples/03-workflows/human-in-the-loop/agents_with_approval_requests.py index 1a70ff977d..4fcf279b9c 100644 --- a/python/samples/getting_started/workflows/human-in-the-loop/agents_with_approval_requests.py +++ b/python/samples/03-workflows/human-in-the-loop/agents_with_approval_requests.py @@ -56,8 +56,8 @@ Prerequisites: # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; # See: -# samples/getting_started/tools/function_tool_with_approval.py -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# samples/02-agents/tools/function_tool_with_approval.py +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_current_date() -> str: """Get the current date in YYYY-MM-DD format.""" diff --git a/python/samples/getting_started/workflows/human-in-the-loop/agents_with_declaration_only_tools.py b/python/samples/03-workflows/human-in-the-loop/agents_with_declaration_only_tools.py similarity index 100% rename from python/samples/getting_started/workflows/human-in-the-loop/agents_with_declaration_only_tools.py rename to python/samples/03-workflows/human-in-the-loop/agents_with_declaration_only_tools.py diff --git a/python/samples/getting_started/orchestrations/concurrent/concurrent_request_info.py b/python/samples/03-workflows/human-in-the-loop/concurrent_request_info.py similarity index 100% rename from python/samples/getting_started/orchestrations/concurrent/concurrent_request_info.py rename to python/samples/03-workflows/human-in-the-loop/concurrent_request_info.py diff --git a/python/samples/getting_started/orchestrations/group-chat/group_chat_request_info.py b/python/samples/03-workflows/human-in-the-loop/group_chat_request_info.py similarity index 100% rename from python/samples/getting_started/orchestrations/group-chat/group_chat_request_info.py rename to python/samples/03-workflows/human-in-the-loop/group_chat_request_info.py diff --git a/python/samples/getting_started/workflows/human-in-the-loop/guessing_game_with_human_input.py b/python/samples/03-workflows/human-in-the-loop/guessing_game_with_human_input.py similarity index 100% rename from python/samples/getting_started/workflows/human-in-the-loop/guessing_game_with_human_input.py rename to python/samples/03-workflows/human-in-the-loop/guessing_game_with_human_input.py diff --git a/python/samples/getting_started/orchestrations/sequential/sequential_request_info.py b/python/samples/03-workflows/human-in-the-loop/sequential_request_info.py similarity index 100% rename from python/samples/getting_started/orchestrations/sequential/sequential_request_info.py rename to python/samples/03-workflows/human-in-the-loop/sequential_request_info.py diff --git a/python/samples/getting_started/workflows/observability/executor_io_observation.py b/python/samples/03-workflows/observability/executor_io_observation.py similarity index 100% rename from python/samples/getting_started/workflows/observability/executor_io_observation.py rename to python/samples/03-workflows/observability/executor_io_observation.py diff --git a/python/samples/03-workflows/orchestrations/README.md b/python/samples/03-workflows/orchestrations/README.md new file mode 100644 index 0000000000..3ce85cd1ab --- /dev/null +++ b/python/samples/03-workflows/orchestrations/README.md @@ -0,0 +1,102 @@ +# Orchestration Getting Started Samples + +## Installation + +The orchestrations package is included when you install `agent-framework` (which pulls in all optional packages): + +```bash +pip install agent-framework +``` + +Or install the orchestrations package directly: + +```bash +pip install agent-framework-orchestrations +``` + +Orchestration builders are available via the `agent_framework.orchestrations` submodule: + +```python +from agent_framework.orchestrations import ( + SequentialBuilder, + ConcurrentBuilder, + HandoffBuilder, + GroupChatBuilder, + MagenticBuilder, +) +``` + +## Samples Overview (by directory) + +### concurrent + +| Sample | File | Concepts | +| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| Concurrent Orchestration (Default Aggregator) | [concurrent_agents.py](./concurrent_agents.py) | Fan-out to multiple agents; fan-in with default aggregator returning combined Messages | +| Concurrent Orchestration (Custom Aggregator) | [concurrent_custom_aggregator.py](./concurrent_custom_aggregator.py) | Override aggregator via callback; summarize results with an LLM | +| Concurrent Orchestration (Custom Agent Executors) | [concurrent_custom_agent_executors.py](./concurrent_custom_agent_executors.py) | Child executors own Agents; concurrent fan-out/fan-in via ConcurrentBuilder | +| Concurrent Orchestration as Agent | [concurrent_workflow_as_agent.py](../agents/concurrent_workflow_as_agent.py) | Build a ConcurrentBuilder workflow and expose it as an agent via `workflow.as_agent(...)` | +| Tool Approval with ConcurrentBuilder | [concurrent_builder_tool_approval.py](../tool-approval/concurrent_builder_tool_approval.py) | Require human approval for sensitive tools across concurrent participants | +| ConcurrentBuilder Request Info | [concurrent_request_info.py](../human-in-the-loop/concurrent_request_info.py) | Review concurrent agent outputs before aggregation using `.with_request_info()` | + +### sequential + +| Sample | File | Concepts | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| Sequential Orchestration (Agents) | [sequential_agents.py](./sequential_agents.py) | Chain agents sequentially with shared conversation context | +| Sequential Orchestration (Custom Executor) | [sequential_custom_executors.py](./sequential_custom_executors.py) | Mix agents with a summarizer that appends a compact summary | +| Sequential Orchestration as Agent | [sequential_workflow_as_agent.py](../agents/sequential_workflow_as_agent.py) | Build a SequentialBuilder workflow and expose it as an agent via `workflow.as_agent(...)` | +| Tool Approval with SequentialBuilder | [sequential_builder_tool_approval.py](../tool-approval/sequential_builder_tool_approval.py) | Require human approval for sensitive tools in SequentialBuilder workflows | +| SequentialBuilder Request Info | [sequential_request_info.py](../human-in-the-loop/sequential_request_info.py) | Request info for agent responses mid-orchestration using `.with_request_info()` | + +### group-chat + +| Sample | File | Concepts | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | +| Group Chat with Agent Manager | [group_chat_agent_manager.py](./group_chat_agent_manager.py) | Agent-based manager using `with_orchestrator(agent=)` to select next speaker | +| Group Chat Philosophical Debate | [group_chat_philosophical_debate.py](./group_chat_philosophical_debate.py) | Agent manager moderates long-form, multi-round debate across diverse participants | +| Group Chat with Simple Selector | [group_chat_simple_selector.py](./group_chat_simple_selector.py) | Group chat with a simple function selector for next speaker | +| Group Chat Orchestration as Agent | [group_chat_workflow_as_agent.py](../agents/group_chat_workflow_as_agent.py) | Build a GroupChatBuilder workflow and wrap it as an agent for composition | +| Tool Approval with GroupChatBuilder | [group_chat_builder_tool_approval.py](../tool-approval/group_chat_builder_tool_approval.py) | Require human approval for sensitive tools in group chat orchestration | +| GroupChatBuilder Request Info | [group_chat_request_info.py](../human-in-the-loop/group_chat_request_info.py) | Steer group discussions with periodic guidance using `.with_request_info()` | + +### handoff + +| Sample | File | Concepts | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| Handoff (Simple) | [handoff_simple.py](./handoff_simple.py) | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response | +| Handoff (Autonomous) | [handoff_autonomous.py](./handoff_autonomous.py) | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_autonomous_mode()` | +| Handoff with Code Interpreter | [handoff_with_code_interpreter_file.py](./handoff_with_code_interpreter_file.py) | Retrieve file IDs from code interpreter output in handoff workflow | +| Handoff with Tool Approval + Checkpoint | [handoff_with_tool_approval_checkpoint_resume.py](./handoff_with_tool_approval_checkpoint_resume.py) | Capture tool-approval decisions in checkpoints and resume from persisted state | +| Handoff Orchestration as Agent | [handoff_workflow_as_agent.py](../agents/handoff_workflow_as_agent.py) | Build a HandoffBuilder workflow and expose it as an agent, including HITL request/response flow | + +### magentic + +| Sample | File | Concepts | +| ---------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | +| Magentic Workflow | [magentic.py](./magentic.py) | Orchestrate multiple agents with a Magentic manager and streaming | +| Magentic + Human Plan Review | [magentic_human_plan_review.py](./magentic_human_plan_review.py) | Human reviews or updates the plan before execution | +| Magentic + Checkpoint Resume | [magentic_checkpoint.py](./magentic_checkpoint.py) | Resume Magentic orchestration from saved checkpoints | +| Magentic Orchestration as Agent | [magentic_workflow_as_agent.py](../agents/magentic_workflow_as_agent.py) | Build a MagenticBuilder workflow and reuse it as an agent | + +## Tips + +**Magentic checkpointing tip**: Treat `MagenticBuilder.participants` keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast. + +**Handoff workflow tip**: Handoff workflows maintain the full conversation history including any `Message.additional_properties` emitted by your agents. This ensures routing metadata remains intact across all agent transitions. For specialist-to-specialist handoffs, use `.add_handoff(source, targets)` to configure which agents can route to which others with a fluent, type-safe API. + +**Sequential orchestration note**: Sequential orchestration uses a few small adapter nodes for plumbing: +- `input-conversation` normalizes input to `list[Message]` +- `to-conversation:` converts agent responses into the shared conversation +- `complete` publishes the final output event (type='output') + +These may appear in event streams (executor_invoked/executor_completed). They're analogous to concurrent's dispatcher and aggregator and can be ignored if you only care about agent activity. + +## Environment Variables + +Orchestration samples that use `AzureOpenAIResponsesClient` expect: + +- `AZURE_AI_PROJECT_ENDPOINT` (Azure AI Foundry Agent Service (V2) project endpoint) +- `AZURE_AI_MODEL_DEPLOYMENT_NAME` (model deployment name) + +These values are passed directly into the client constructor via `os.getenv()` in sample code. diff --git a/python/samples/03-workflows/orchestrations/concurrent_agents.py b/python/samples/03-workflows/orchestrations/concurrent_agents.py new file mode 100644 index 0000000000..2d216a131b --- /dev/null +++ b/python/samples/03-workflows/orchestrations/concurrent_agents.py @@ -0,0 +1,130 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Any + +from agent_framework import Message +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import ConcurrentBuilder +from azure.identity import AzureCliCredential + +""" +Sample: Concurrent fan-out/fan-in (agent-only API) with default aggregator + +Build a high-level concurrent workflow using ConcurrentBuilder and three domain agents. +The default dispatcher fans out the same user prompt to all agents in parallel. +The default aggregator fans in their results and yields output containing +a list[Message] representing the concatenated conversations from all agents. + +Demonstrates: +- Minimal wiring with ConcurrentBuilder(participants=[...]).build() +- Fan-out to multiple agents, fan-in aggregation of final ChatMessages +- Workflow completion when idle with no pending work + +Prerequisites: +- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars) +- Familiarity with Workflow events (WorkflowEvent) +""" + + +async def main() -> None: + # 1) Create three domain agents using AzureOpenAIChatClient + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + + researcher = client.as_agent( + instructions=( + "You're an expert market and product researcher. Given a prompt, provide concise, factual insights," + " opportunities, and risks." + ), + name="researcher", + ) + + marketer = client.as_agent( + instructions=( + "You're a creative marketing strategist. Craft compelling value propositions and target messaging" + " aligned to the prompt." + ), + name="marketer", + ) + + legal = client.as_agent( + instructions=( + "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns" + " based on the prompt." + ), + name="legal", + ) + + # 2) Build a concurrent workflow + # Participants are either Agents (type of SupportsAgentRun) or Executors + workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).build() + + # 3) Run with a single prompt and pretty-print the final combined messages + events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.") + outputs = events.get_outputs() + + if outputs: + print("===== Final Aggregated Conversation (messages) =====") + for output in outputs: + messages: list[Message] | Any = output + for i, msg in enumerate(messages, start=1): + name = msg.author_name if msg.author_name else "user" + print(f"{'-' * 60}\n\n{i:02d} [{name}]:\n{msg.text}") + + """ + Sample Output: + + ===== Final Aggregated Conversation (messages) ===== + ------------------------------------------------------------ + + 01 [user]: + We are launching a new budget-friendly electric bike for urban commuters. + ------------------------------------------------------------ + + 02 [researcher]: + **Insights:** + + - **Target Demographic:** Urban commuters seeking affordable, eco-friendly transport; + likely to include students, young professionals, and price-sensitive urban residents. + - **Market Trends:** E-bike sales are growing globally, with increasing urbanization, + higher fuel costs, and sustainability concerns driving adoption. + - **Competitive Landscape:** Key competitors include brands like Rad Power Bikes, Aventon, + Lectric, and domestic budget-focused manufacturers in North America, Europe, and Asia. + - **Feature Expectations:** Customers expect reliability, ease-of-use, theft protection, + lightweight design, sufficient battery range for daily city commutes (typically 25-40 miles), + and low-maintenance components. + + **Opportunities:** + + - **First-time Buyers:** Capture newcomers to e-biking by emphasizing affordability, ease of + operation, and cost savings vs. public transit/car ownership. + ... + ------------------------------------------------------------ + + 03 [marketer]: + **Value Proposition:** + "Empowering your city commute: Our new electric bike combines affordability, reliability, and + sustainable designβ€”helping you conquer urban journeys without breaking the bank." + + **Target Messaging:** + + *For Young Professionals:* + ... + ------------------------------------------------------------ + + 04 [legal]: + **Constraints, Disclaimers, & Policy Concerns for Launching a Budget-Friendly Electric Bike for Urban Commuters:** + + **1. Regulatory Compliance** + - Verify that the electric bike meets all applicable federal, state, and local regulations + regarding e-bike classification, speed limits, power output, and safety features. + - Ensure necessary certifications (e.g., UL certification for batteries, CE markings if sold internationally) are obtained. + + **2. Product Safety** + - Include consumer safety warnings regarding use, battery handling, charging protocols, and age restrictions. + ... + """ # noqa: E501 + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/concurrent_custom_agent_executors.py b/python/samples/03-workflows/orchestrations/concurrent_custom_agent_executors.py new file mode 100644 index 0000000000..bd3b8b93a5 --- /dev/null +++ b/python/samples/03-workflows/orchestrations/concurrent_custom_agent_executors.py @@ -0,0 +1,174 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Any + +from agent_framework import ( + Agent, + AgentExecutorRequest, + AgentExecutorResponse, + Executor, + Message, + WorkflowContext, + handler, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import ConcurrentBuilder +from azure.identity import AzureCliCredential + +""" +Sample: Concurrent Orchestration with Custom Agent Executors + +This sample shows a concurrent fan-out/fan-in pattern using child Executor classes +that each own their Agent. The executors accept AgentExecutorRequest inputs +and emit AgentExecutorResponse outputs, which allows reuse of the high-level +ConcurrentBuilder API and the default aggregator. + +Demonstrates: +- Executors that create their Agent in __init__ (via AzureOpenAIChatClient) +- A @handler that converts AgentExecutorRequest -> AgentExecutorResponse +- ConcurrentBuilder(participants=[...]) to build fan-out/fan-in +- Default aggregator returning list[Message] (one user + one assistant per agent) +- Workflow completion when all participants become idle + +Prerequisites: +- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars) +""" + + +class ResearcherExec(Executor): + agent: Agent + + def __init__(self, client: AzureOpenAIChatClient, id: str = "researcher"): + self.agent = client.as_agent( + instructions=( + "You're an expert market and product researcher. Given a prompt, provide concise, factual insights," + " opportunities, and risks." + ), + name=id, + ) + super().__init__(id=id) + + @handler + async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None: + response = await self.agent.run(request.messages) + full_conversation = list(request.messages) + list(response.messages) + await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation)) + + +class MarketerExec(Executor): + agent: Agent + + def __init__(self, client: AzureOpenAIChatClient, id: str = "marketer"): + self.agent = client.as_agent( + instructions=( + "You're a creative marketing strategist. Craft compelling value propositions and target messaging" + " aligned to the prompt." + ), + name=id, + ) + super().__init__(id=id) + + @handler + async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None: + response = await self.agent.run(request.messages) + full_conversation = list(request.messages) + list(response.messages) + await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation)) + + +class LegalExec(Executor): + agent: Agent + + def __init__(self, client: AzureOpenAIChatClient, id: str = "legal"): + self.agent = client.as_agent( + instructions=( + "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns" + " based on the prompt." + ), + name=id, + ) + super().__init__(id=id) + + @handler + async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None: + response = await self.agent.run(request.messages) + full_conversation = list(request.messages) + list(response.messages) + await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation)) + + +async def main() -> None: + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + + researcher = ResearcherExec(client) + marketer = MarketerExec(client) + legal = LegalExec(client) + + workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).build() + + events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.") + outputs = events.get_outputs() + + if outputs: + print("===== Final Aggregated Conversation (messages) =====") + messages: list[Message] | Any = outputs[0] # Get the first (and typically only) output + for i, msg in enumerate(messages, start=1): + name = msg.author_name if msg.author_name else "user" + print(f"{'-' * 60}\n\n{i:02d} [{name}]:\n{msg.text}") + + """ + Sample Output: + + ===== Final Aggregated Conversation (messages) ===== + ------------------------------------------------------------ + + 01 [user]: + We are launching a new budget-friendly electric bike for urban commuters. + ------------------------------------------------------------ + + 02 [researcher]: + **Insights:** + + - **Target Demographic:** Urban commuters seeking affordable, eco-friendly transport; + likely to include students, young professionals, and price-sensitive urban residents. + - **Market Trends:** E-bike sales are growing globally, with increasing urbanization, + higher fuel costs, and sustainability concerns driving adoption. + - **Competitive Landscape:** Key competitors include brands like Rad Power Bikes, Aventon, + Lectric, and domestic budget-focused manufacturers in North America, Europe, and Asia. + - **Feature Expectations:** Customers expect reliability, ease-of-use, theft protection, + lightweight design, sufficient battery range for daily city commutes (typically 25-40 miles), + and low-maintenance components. + + **Opportunities:** + + - **First-time Buyers:** Capture newcomers to e-biking by emphasizing affordability, ease of + operation, and cost savings vs. public transit/car ownership. + ... + ------------------------------------------------------------ + + 03 [marketer]: + **Value Proposition:** + "Empowering your city commute: Our new electric bike combines affordability, reliability, and + sustainable designβ€”helping you conquer urban journeys without breaking the bank." + + **Target Messaging:** + + *For Young Professionals:* + ... + ------------------------------------------------------------ + + 04 [legal]: + **Constraints, Disclaimers, & Policy Concerns for Launching a Budget-Friendly Electric Bike for Urban Commuters:** + + **1. Regulatory Compliance** + - Verify that the electric bike meets all applicable federal, state, and local regulations + regarding e-bike classification, speed limits, power output, and safety features. + - Ensure necessary certifications (e.g., UL certification for batteries, CE markings if sold internationally) are obtained. + + **2. Product Safety** + - Include consumer safety warnings regarding use, battery handling, charging protocols, and age restrictions. + ... + """ # noqa: E501 + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/concurrent_custom_aggregator.py b/python/samples/03-workflows/orchestrations/concurrent_custom_aggregator.py new file mode 100644 index 0000000000..17b1496e0b --- /dev/null +++ b/python/samples/03-workflows/orchestrations/concurrent_custom_aggregator.py @@ -0,0 +1,124 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Any + +from agent_framework import Message +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import ConcurrentBuilder +from azure.identity import AzureCliCredential + +""" +Sample: Concurrent Orchestration with Custom Aggregator + +Build a concurrent workflow with ConcurrentBuilder that fans out one prompt to +multiple domain agents and fans in their responses. Override the default +aggregator with a custom async callback that uses AzureOpenAIChatClient.get_response() +to synthesize a concise, consolidated summary from the experts' outputs. +The workflow completes when all participants become idle. + +Demonstrates: +- ConcurrentBuilder(participants=[...]).with_aggregator(callback) +- Fan-out to agents and fan-in at an aggregator +- Aggregation implemented via an LLM call (client.get_response) +- Workflow output yielded with the synthesized summary string + +Prerequisites: +- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars) +""" + + +async def main() -> None: + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + + researcher = client.as_agent( + instructions=( + "You're an expert market and product researcher. Given a prompt, provide concise, factual insights," + " opportunities, and risks." + ), + name="researcher", + ) + marketer = client.as_agent( + instructions=( + "You're a creative marketing strategist. Craft compelling value propositions and target messaging" + " aligned to the prompt." + ), + name="marketer", + ) + legal = client.as_agent( + instructions=( + "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns" + " based on the prompt." + ), + name="legal", + ) + + # Define a custom aggregator callback that uses the chat client to summarize + async def summarize_results(results: list[Any]) -> str: + # Extract one final assistant message per agent + expert_sections: list[str] = [] + for r in results: + try: + messages = getattr(r.agent_response, "messages", []) + final_text = messages[-1].text if messages and hasattr(messages[-1], "text") else "(no content)" + expert_sections.append(f"{getattr(r, 'executor_id', 'expert')}:\n{final_text}") + except Exception as e: + expert_sections.append(f"{getattr(r, 'executor_id', 'expert')}: (error: {type(e).__name__}: {e})") + + # Ask the model to synthesize a concise summary of the experts' outputs + system_msg = Message( + "system", + text=( + "You are a helpful assistant that consolidates multiple domain expert outputs " + "into one cohesive, concise summary with clear takeaways. Keep it under 200 words." + ), + ) + user_msg = Message("user", text="\n\n".join(expert_sections)) + + response = await client.get_response([system_msg, user_msg]) + # Return the model's final assistant text as the completion result + return response.messages[-1].text if response.messages else "" + + # Build with a custom aggregator callback function + # - participants([...]) accepts SupportsAgentRun (agents) or Executor instances. + # Each participant becomes a parallel branch (fan-out) from an internal dispatcher. + # - with_aggregator(...) overrides the default aggregator: + # β€’ Default aggregator -> returns list[Message] (one user + one assistant per agent) + # β€’ Custom callback -> return value becomes workflow output (string here) + # The callback can be sync or async; it receives list[AgentExecutorResponse]. + workflow = ( + ConcurrentBuilder(participants=[researcher, marketer, legal]).with_aggregator(summarize_results).build() + ) + + events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.") + outputs = events.get_outputs() + + if outputs: + print("===== Final Consolidated Output =====") + print(outputs[0]) # Get the first (and typically only) output + + """ + Sample Output: + + ===== Final Consolidated Output ===== + Urban e-bike demand is rising rapidly due to eco-awareness, urban congestion, and high fuel costs, + with market growth projected at a ~10% CAGR through 2030. Key customer concerns are affordability, + easy maintenance, convenient charging, compact design, and theft protection. Differentiation opportunities + include integrating smart features (GPS, app connectivity), offering subscription or leasing options, and + developing portable, space-saving designs. Partnering with local governments and bike shops can boost visibility. + + Risks include price wars eroding margins, regulatory hurdles, battery quality concerns, and heightened expectations + for after-sales support. Accurate, substantiated product claims and transparent marketing (with range disclaimers) + are essential. All e-bikes must comply with local and federal regulations on speed, wattage, safety certification, + and labeling. Clear warranty, safety instructions (especially regarding batteries), and inclusive, accessible + marketing are required. For connected features, data privacy policies and user consents are mandatory. + + Effective messaging should target young professionals, students, eco-conscious commuters, and first-time buyers, + emphasizing affordability, convenience, and sustainability. Slogan suggestion: β€œCharge Aheadβ€”City Commutes Made + Affordable.” Legal review in each target market, compliance vetting, and robust customer support policies are + critical before launch. + """ + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/group_chat_agent_manager.py b/python/samples/03-workflows/orchestrations/group_chat_agent_manager.py new file mode 100644 index 0000000000..78eb8535ae --- /dev/null +++ b/python/samples/03-workflows/orchestrations/group_chat_agent_manager.py @@ -0,0 +1,114 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import GroupChatBuilder +from azure.identity import AzureCliCredential + +""" +Sample: Group Chat with Agent-Based Manager + +What it does: +- Demonstrates the new set_manager() API for agent-based coordination +- Manager is a full Agent with access to tools, context, and observability +- Coordinates a researcher and writer agent to solve tasks collaboratively + +Prerequisites: +- OpenAI environment variables configured for OpenAIChatClient +""" + +ORCHESTRATOR_AGENT_INSTRUCTIONS = """ +You coordinate a team conversation to solve the user's task. + +Guidelines: +- Start with Researcher to gather information +- Then have Writer synthesize the final answer +- Only finish after both have contributed meaningfully +""" + + +async def main() -> None: + # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + + # Orchestrator agent that manages the conversation + # Note: This agent (and the underlying chat client) must support structured outputs. + # The group chat workflow relies on this to parse the orchestrator's decisions. + # `response_format` is set internally by the GroupChat workflow when the agent is invoked. + orchestrator_agent = Agent( + name="Orchestrator", + description="Coordinates multi-agent collaboration by selecting speakers", + instructions=ORCHESTRATOR_AGENT_INSTRUCTIONS, + client=client, + ) + + # Participant agents + researcher = Agent( + name="Researcher", + description="Collects relevant background information", + instructions="Gather concise facts that help a teammate answer the question.", + client=client, + ) + + writer = Agent( + name="Writer", + description="Synthesizes polished answers from gathered information", + instructions="Compose clear and structured answers using any notes provided.", + client=client, + ) + + # Build the group chat workflow + # termination_condition: stop after 4 assistant messages + # (The agent orchestrator will intelligently decide when to end before this limit but just in case) + # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds + # (Intermediate outputs will be emitted as WorkflowOutputEvent events) + workflow = ( + GroupChatBuilder( + participants=[researcher, writer], + termination_condition=lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 4, + intermediate_outputs=True, + orchestrator_agent=orchestrator_agent, + ) + # Set a hard termination condition: stop after 4 assistant messages + # The agent orchestrator will intelligently decide when to end before this limit but just in case + .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 4) + .build() + ) + + task = "What are the key benefits of using async/await in Python? Provide a concise summary." + + print("\nStarting Group Chat with Agent-Based Manager...\n") + print(f"TASK: {task}\n") + print("=" * 80) + + # Keep track of the last response to format output nicely in streaming mode + last_response_id: str | None = None + async for event in workflow.run(task, stream=True): + if event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + rid = data.response_id + if rid != last_response_id: + if last_response_id is not None: + print("\n") + print(f"{data.author_name}:", end=" ", flush=True) + last_response_id = rid + print(data.text, end="", flush=True) + elif event.type == "output": + # The output of the group chat workflow is a collection of chat messages from all participants + outputs = cast(list[Message], event.data) + print("\n" + "=" * 80) + print("\nFinal Conversation Transcript:\n") + for message in outputs: + print(f"{message.author_name or message.role}: {message.text}\n") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/group_chat_philosophical_debate.py b/python/samples/03-workflows/orchestrations/group_chat_philosophical_debate.py new file mode 100644 index 0000000000..e4723c01e0 --- /dev/null +++ b/python/samples/03-workflows/orchestrations/group_chat_philosophical_debate.py @@ -0,0 +1,364 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import logging +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import GroupChatBuilder +from azure.identity import AzureCliCredential + +logging.basicConfig(level=logging.WARNING) + +""" +Sample: Philosophical Debate with Agent-Based Manager + +What it does: +- Creates a diverse group of agents representing different global perspectives +- Uses an agent-based manager to guide a philosophical discussion +- Demonstrates longer, multi-round discourse with natural conversation flow +- Manager decides when discussion has reached meaningful conclusion + +Topic: "What does a good life mean to you personally?" + +Participants represent: +- Farmer from Southeast Asia (tradition, sustainability, land connection) +- Software Developer from United States (innovation, technology, work-life balance) +- History Teacher from Eastern Europe (legacy, learning, cultural continuity) +- Activist from South America (social justice, environmental rights) +- Spiritual Leader from Middle East (morality, community service) +- Artist from Africa (creative expression, storytelling) +- Immigrant Entrepreneur from Asia in Canada (tradition + adaptation) +- Doctor from Scandinavia (public health, equity, societal support) + +Prerequisites: +- OpenAI environment variables configured for OpenAIChatClient +""" + + +def _get_chat_client() -> AzureOpenAIChatClient: + return AzureOpenAIChatClient(credential=AzureCliCredential()) + + +async def main() -> None: + # Create debate moderator with structured output for speaker selection + # Note: Participant names and descriptions are automatically injected by the orchestrator + moderator = Agent( + name="Moderator", + description="Guides philosophical discussion by selecting next speaker", + instructions=""" +You are a thoughtful moderator guiding a philosophical discussion on the topic handed to you by the user. + +Your participants bring diverse global perspectives. Select speakers strategically to: +- Create natural conversation flow and responses to previous points +- Ensure all voices are heard throughout the discussion +- Build on themes and contrasts that emerge +- Allow for respectful challenges and counterpoints +- Guide toward meaningful conclusions + +Select speakers who can: +1. Respond directly to points just made +2. Introduce fresh perspectives when needed +3. Bridge or contrast different viewpoints +4. Deepen the philosophical exploration + +Finish when: +- Multiple rounds have occurred (at least 6-8 exchanges) +- Key themes have been explored from different angles +- Natural conclusion or synthesis has emerged +- Diminishing returns in new insights + +In your final_message, provide a brief synthesis highlighting key themes that emerged. +""", + client=_get_chat_client(), + ) + + farmer = Agent( + name="Farmer", + description="A rural farmer from Southeast Asia", + instructions=""" +You're a farmer from Southeast Asia. Your life is deeply connected to land and family. +You value tradition and sustainability. You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use concrete examples from your experience +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + developer = Agent( + name="Developer", + description="An urban software developer from the United States", + instructions=""" +You're a software developer from the United States. Your life is fast-paced and technology-driven. +You value innovation, freedom, and work-life balance. You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use concrete examples from your experience +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + teacher = Agent( + name="Teacher", + description="A retired history teacher from Eastern Europe", + instructions=""" +You're a retired history teacher from Eastern Europe. You bring historical and philosophical +perspectives to discussions. You value legacy, learning, and cultural continuity. +You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use concrete examples from history or your teaching experience +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + activist = Agent( + name="Activist", + description="A young activist from South America", + instructions=""" +You're a young activist from South America. You focus on social justice, environmental rights, +and generational change. You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use concrete examples from your activism +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + spiritual_leader = Agent( + name="SpiritualLeader", + description="A spiritual leader from the Middle East", + instructions=""" +You're a spiritual leader from the Middle East. You provide insights grounded in religion, +morality, and community service. You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use examples from spiritual teachings or community work +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + artist = Agent( + name="Artist", + description="An artist from Africa", + instructions=""" +You're an artist from Africa. You view life through creative expression, storytelling, +and collective memory. You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use examples from your art or cultural traditions +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + immigrant = Agent( + name="Immigrant", + description="An immigrant entrepreneur from Asia living in Canada", + instructions=""" +You're an immigrant entrepreneur from Asia living in Canada. You balance tradition with adaptation. +You focus on family success, risk, and opportunity. You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use examples from your immigrant and entrepreneurial journey +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + doctor = Agent( + name="Doctor", + description="A doctor from Scandinavia", + instructions=""" +You're a doctor from Scandinavia. Your perspective is shaped by public health, equity, +and structured societal support. You are in a philosophical debate. + +Share your perspective authentically. Feel free to: +- Challenge other participants respectfully +- Build on points others have made +- Use examples from healthcare and societal systems +- Keep responses thoughtful but concise (2-4 sentences) +""", + client=_get_chat_client(), + ) + + # termination_condition: stop after 10 assistant messages + # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds + # (Intermediate outputs will be emitted as WorkflowOutputEvent events) + workflow = ( + GroupChatBuilder( + participants=[farmer, developer, teacher, activist, spiritual_leader, artist, immigrant, doctor], + termination_condition=lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 10, + intermediate_outputs=True, + orchestrator_agent=moderator, + ) + .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 10) + .build() + ) + + topic = "What does a good life mean to you personally?" + + print("\n" + "=" * 80) + print("PHILOSOPHICAL DEBATE: Perspectives on a Good Life") + print("=" * 80) + print(f"\nTopic: {topic}") + print("\nParticipants:") + print(" - Farmer (Southeast Asia)") + print(" - Developer (United States)") + print(" - Teacher (Eastern Europe)") + print(" - Activist (South America)") + print(" - SpiritualLeader (Middle East)") + print(" - Artist (Africa)") + print(" - Immigrant (Asia β†’ Canada)") + print(" - Doctor (Scandinavia)") + print("\n" + "=" * 80) + print("DISCUSSION BEGINS") + print("=" * 80 + "\n") + + # Keep track of the last response to format output nicely in streaming mode + last_response_id: str | None = None + async for event in workflow.run(f"Please begin the discussion on: {topic}", stream=True): + if event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + rid = data.response_id + if rid != last_response_id: + if last_response_id is not None: + print("\n") + print(f"{data.author_name}:", end=" ", flush=True) + last_response_id = rid + print(data.text, end="", flush=True) + elif event.type == "output": + # The output of the group chat workflow is a collection of chat messages from all participants + outputs = cast(list[Message], event.data) + print("\n" + "=" * 80) + print("\nFinal Conversation Transcript:\n") + for message in outputs: + print(f"{message.author_name or message.role}: {message.text}\n") + + """ + Sample Output: + + ================================================================================ + PHILOSOPHICAL DEBATE: Perspectives on a Good Life + ================================================================================ + + Topic: What does a good life mean to you personally? + + Participants: + - Farmer (Southeast Asia) + - Developer (United States) + - Teacher (Eastern Europe) + - Activist (South America) + - SpiritualLeader (Middle East) + - Artist (Africa) + - Immigrant (Asia β†’ Canada) + - Doctor (Scandinavia) + + ================================================================================ + DISCUSSION BEGINS + ================================================================================ + + [Farmer] + To me, a good life is deeply intertwined with the rhythm of the land and the nurturing of relationships with my + family and community. It means cultivating crops that respect our environment, ensuring sustainability for future + generations, and sharing meals made from our harvests around the dinner table. The joy found in everyday + tasksβ€”planting rice or tending to our livestockβ€”creates a sense of fulfillment that cannot be measured by material + wealth. It's the simple moments, like sharing stories with my children under the stars, that truly define a good + life. What good is progress if it isolates us from those we love and the land that sustains us? + + [Developer] + As a software developer in an urban environment, a good life for me hinges on the intersection of innovation, + creativity, and balance. It's about having the freedom to explore new technologies that can solve real-world + problems while ensuring that my work doesn't encroach on my personal life. For instance, I value remote work + flexibility, which allows me to maintain connections with family and friends, similar to how the Farmer values + community. While our lifestyles may differ markedly, both of us seek fulfillmentβ€”whether through meaningful work or + rich personal experiences. The challenge is finding harmony between technological progress and preserving the + intimate human connections that truly enrich our lives. + + [SpiritualLeader] + From my spiritual perspective, a good life embodies a balance between personal fulfillment and service to others, + rooted in compassion and community. In our teachings, we emphasize that true happiness comes from helping those in + need and fostering strong connections with our families and neighbors. Whether it's the Farmer nurturing the earth + or the Developer creating tools to enhance lives, both contribute to the greater good. The essence of a good life + lies in our intentions and actionsβ€”finding ways to serve our communities, spread kindness, and live harmoniously + with those around us. Ultimately, as we align our personal beliefs with our communal responsibilities, we cultivate + a richness that transcends material wealth. + + [Activist] + As a young activist in South America, a good life for me is about advocating for social justice and environmental + sustainability. It means living in a society where everyone's rights are respected and where marginalized voices, + particularly those of Indigenous communities, are amplified. I see a good life as one where we work collectively to + dismantle oppressive systemsβ€”such as deforestation and inequalityβ€”while nurturing our planet. For instance, through + my activism, I've witnessed the transformative power of community organizing, where collective efforts lead to real + change, like resisting destructive mining practices that threaten our rivers and lands. A good life, therefore, is + not just lived for oneself but is deeply tied to the well-being of our communities and the health of our + environment. How can we, regardless of our backgrounds, collaborate to foster these essential changes? + + [Teacher] + As a retired history teacher from Eastern Europe, my understanding of a good life is deeply rooted in the lessons + drawn from history and the struggle for freedom and dignity. Historical events, such as the fall of the Iron + Curtain, remind us of the profound importance of liberty and collective resilience. A good life, therefore, is about + cherishing our freedoms and working towards a society where everyone has a voice, much as my students and I + discussed the impacts of totalitarian regimes. Additionally, I believe it involves fostering cultural continuity, + where we honor our heritage while embracing progressive values. We must learn from the pastβ€”especially the + consequences of neglecting empathy and solidarityβ€”so that we can cultivate a future that values every individual's + contributions to the rich tapestry of our shared humanity. How can we ensure that the lessons of history inform a + more compassionate and just society moving forward? + + [Artist] + As an artist from Africa, I define a good life as one steeped in cultural expression, storytelling, and the + celebration of our collective memories. Art is a powerful medium through which we capture our histories, struggles, + and triumphs, creating a tapestry that connects generations. For instance, in my work, I often draw from folktales + and traditional music, weaving narratives that reflect the human experience, much like how the retired teacher + emphasizes learning from history. A good life involves not only personal fulfillment but also the responsibility to + share our narratives and use our creativity to inspire change, whether addressing social injustices or environmental + issues. It's in this interplay of art and activism that we can transcend individual existence and contribute to a + collective good, fostering empathy and understanding among diverse communities. How can we harness art to bridge + differences and amplify marginalized voices in our pursuit of a good life? + + ================================================================================ + DISCUSSION SUMMARY + ================================================================================ + + As our discussion unfolds, several key themes have gracefully emerged, reflecting the richness of diverse + perspectives on what constitutes a good life. From the rural farmer's integration with the land to the developer's + search for balance between technology and personal connection, each viewpoint validates that fulfillment, at its + core, transcends material wealth. The spiritual leader and the activist highlight the importance of community and + social justice, while the history teacher and the artist remind us of the lessons and narratives that shape our + cultural and personal identities. + + Ultimately, the good life seems to revolve around meaningful relationships, honoring our legacies while striving for + progress, and nurturing both our inner selves and external communities. This dialogue demonstrates that despite our + varied backgrounds and experiences, the quest for a good life binds us together, urging cooperation and empathy in + our shared human journey. + """ + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/group_chat_simple_selector.py b/python/samples/03-workflows/orchestrations/group_chat_simple_selector.py new file mode 100644 index 0000000000..13cd3d3e5a --- /dev/null +++ b/python/samples/03-workflows/orchestrations/group_chat_simple_selector.py @@ -0,0 +1,135 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import GroupChatBuilder, GroupChatState +from azure.identity import AzureCliCredential + +""" +Sample: Group Chat with a round-robin speaker selector + +What it does: +- Demonstrates the selection_func parameter for GroupChat orchestration +- Uses a pure Python function to control speaker selection based on conversation state + +Prerequisites: +- OpenAI environment variables configured for OpenAIChatClient +""" + + +def round_robin_selector(state: GroupChatState) -> str: + """A round-robin selector function that picks the next speaker based on the current round index.""" + + participant_names = list(state.participants.keys()) + return participant_names[state.current_round % len(participant_names)] + + +async def main() -> None: + # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + + # Participant agents + expert = Agent( + name="PythonExpert", + instructions=( + "You are an expert in Python in a workgroup. " + "Your job is to answer Python related questions and refine your answer " + "based on feedback from all the other participants." + ), + client=client, + ) + + verifier = Agent( + name="AnswerVerifier", + instructions=( + "You are a programming expert in a workgroup. " + f"Your job is to review the answer provided by {expert.name} and point " + "out statements that are technically true but practically dangerous." + "If there is nothing woth pointing out, respond with 'The answer looks good to me.'" + ), + client=client, + ) + + clarifier = Agent( + name="AnswerClarifier", + instructions=( + "You are an accessibility expert in a workgroup. " + f"Your job is to review the answer provided by {expert.name} and point " + "out jargons or complex terms that may be difficult for a beginner to understand." + "If there is nothing worth pointing out, respond with 'The answer looks clear to me.'" + ), + client=client, + ) + + skeptic = Agent( + name="Skeptic", + instructions=( + "You are a devil's advocate in a workgroup. " + f"Your job is to review the answer provided by {expert.name} and point " + "out caveats, exceptions, and alternative perspectives." + "If there is nothing worth pointing out, respond with 'I have no further questions.'" + ), + client=client, + ) + + # Build the group chat workflow + # termination_condition: stop after 6 messages (user task + one full rounds + 1) + # One round is expert -> verifier -> clarifier -> skeptic, after which the expert gets to respond again. + # This will end the conversation after the expert has spoken 2 times (one iteration loop) + # Note: it's possible that the expert gets it right the first time and the other participants + # have nothing to add, but for demo purposes we want to see at least one full round of interaction. + # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds + # (Intermediate outputs will be emitted as WorkflowOutputEvent events) + workflow = ( + GroupChatBuilder( + participants=[expert, verifier, clarifier, skeptic], + termination_condition=lambda conversation: len(conversation) >= 6, + intermediate_outputs=True, + selection_func=round_robin_selector, + ) + # Set a hard termination condition: stop after 6 messages (user task + one full rounds + 1) + # One round is expert -> verifier -> clarifier -> skeptic, after which the expert gets to respond again. + # This will end the conversation after the expert has spoken 2 times (one iteration loop) + # Note: it's possible that the expert gets it right the first time and the other participants + # have nothing to add, but for demo purposes we want to see at least one full round of interaction. + .with_termination_condition(lambda conversation: len(conversation) >= 6) + .build() + ) + + task = "How does Python’s Protocol differ from abstract base classes?" + + print("\nStarting Group Chat with round-robin speaker selector...\n") + print(f"TASK: {task}\n") + print("=" * 80) + + # Keep track of the last response to format output nicely in streaming mode + last_response_id: str | None = None + async for event in workflow.run(task, stream=True): + if event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + rid = data.response_id + if rid != last_response_id: + if last_response_id is not None: + print("\n") + print(f"{data.author_name}:", end=" ", flush=True) + last_response_id = rid + print(data.text, end="", flush=True) + elif event.type == "output": + # The output of the group chat workflow is a collection of chat messages from all participants + outputs = cast(list[Message], event.data) + print("\n" + "=" * 80) + print("\nFinal Conversation Transcript:\n") + for message in outputs: + print(f"{message.author_name or message.role}: {message.text}\n") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/handoff_autonomous.py b/python/samples/03-workflows/orchestrations/handoff_autonomous.py new file mode 100644 index 0000000000..997d854ef2 --- /dev/null +++ b/python/samples/03-workflows/orchestrations/handoff_autonomous.py @@ -0,0 +1,151 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import logging +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, + resolve_agent_id, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import HandoffBuilder +from azure.identity import AzureCliCredential + +logging.basicConfig(level=logging.ERROR) + +"""Sample: Autonomous handoff workflow with agent iteration. + +This sample demonstrates `.with_autonomous_mode()`, where agents continue +iterating on their task until they explicitly invoke a handoff tool. This allows +specialists to perform long-running autonomous work (research, coding, analysis) +without prematurely returning control to the coordinator or user. + +Routing Pattern: + User -> Coordinator -> Specialist (iterates N times) -> Handoff -> Final Output + +Prerequisites: + - `az login` (Azure CLI authentication) + - Environment variables for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.) + +Key Concepts: + - Autonomous interaction mode: agents iterate until they handoff + - Turn limits: use `.with_autonomous_mode(turn_limits={agent_name: N})` to cap iterations per agent +""" + + +def create_agents( + client: AzureOpenAIChatClient, +) -> tuple[Agent, Agent, Agent]: + """Create coordinator and specialists for autonomous iteration.""" + coordinator = client.as_agent( + instructions=( + "You are a coordinator. You break down a user query into a research task and a summary task. " + "Assign the two tasks to the appropriate specialists, one after the other." + ), + name="coordinator", + ) + + research_agent = client.as_agent( + instructions=( + "You are a research specialist that explores topics thoroughly using web search. " + "When given a research task, break it down into multiple aspects and explore each one. " + "Continue your research across multiple responses - don't try to finish everything in one " + "response. After each response, think about what else needs to be explored. When you have " + "covered the topic comprehensively (at least 3-4 different aspects), return control to the " + "coordinator. Keep each individual response focused on one aspect." + ), + name="research_agent", + ) + + summary_agent = client.as_agent( + instructions=( + "You summarize research findings. Provide a concise, well-organized summary. When done, return " + "control to the coordinator." + ), + name="summary_agent", + ) + + return coordinator, research_agent, summary_agent + + +async def main() -> None: + """Run an autonomous handoff workflow with specialist iteration enabled.""" + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + coordinator, research_agent, summary_agent = create_agents(client) + + # Build the workflow with autonomous mode + # In autonomous mode, agents continue iterating until they invoke a handoff tool + # termination_condition: Terminate after coordinator provides 5 assistant responses + workflow = ( + HandoffBuilder( + name="autonomous_iteration_handoff", + participants=[coordinator, research_agent, summary_agent], + termination_condition=lambda conv: ( + sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role == "assistant") >= 5 + ), + ) + .with_start_agent(coordinator) + .add_handoff(coordinator, [research_agent, summary_agent]) + .add_handoff(research_agent, [coordinator]) # Research can hand back to coordinator + .add_handoff(summary_agent, [coordinator]) + .with_autonomous_mode( + # You can set turn limits per agent to allow some agents to go longer. + # If a limit is not set, the agent will get an default limit: 50. + # Internally, handoff prefers agent names as the agent identifiers if set. + # Otherwise, it falls back to agent IDs. + turn_limits={ + resolve_agent_id(coordinator): 5, + resolve_agent_id(research_agent): 10, + resolve_agent_id(summary_agent): 5, + } + ) + .build() + ) + + request = "Perform a comprehensive research on Microsoft Agent Framework." + print("Request:", request) + + last_response_id: str | None = None + async for event in workflow.run(request, stream=True): + if event.type == "handoff_sent": + print(f"\nHandoff Event: from {event.data.source} to {event.data.target}\n") + elif event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + if not data.text: + # Skip updates that don't have text content + # These can be tool calls or other non-text events + continue + rid = data.response_id + if rid != last_response_id: + if last_response_id is not None: + print("\n") + print(f"{data.author_name}:", end=" ", flush=True) + last_response_id = rid + print(data.text, end="", flush=True) + elif event.type == "output": + # The output of the handoff workflow is a collection of chat messages from all participants + outputs = cast(list[Message], event.data) + print("\n" + "=" * 80) + print("\nFinal Conversation Transcript:\n") + for message in outputs: + print(f"{message.author_name or message.role}: {message.text}\n") + + """ + Expected behavior: + - Coordinator routes to research_agent. + - Research agent iterates multiple times, exploring different aspects of Microsoft Agent Framework. + - Each iteration adds to the conversation without returning to coordinator. + - After thorough research, research_agent calls handoff to coordinator. + - Coordinator routes to summary_agent for final summary. + + In autonomous mode, agents continue working until they invoke a handoff tool, + allowing the research_agent to perform 3-4+ responses before handing off. + """ + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/orchestrations/handoff/handoff_simple.py b/python/samples/03-workflows/orchestrations/handoff_simple.py similarity index 95% rename from python/samples/getting_started/orchestrations/handoff/handoff_simple.py rename to python/samples/03-workflows/orchestrations/handoff_simple.py index 23c957e5d7..b2f40f438f 100644 --- a/python/samples/getting_started/orchestrations/handoff/handoff_simple.py +++ b/python/samples/03-workflows/orchestrations/handoff_simple.py @@ -1,7 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. import asyncio -import os from typing import Annotated, cast from agent_framework import ( @@ -12,7 +11,7 @@ from agent_framework import ( WorkflowRunState, tool, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder from azure.identity import AzureCliCredential @@ -22,9 +21,8 @@ A handoff workflow defines a pattern that assembles agents in a mesh topology, a them to transfer control to each other based on the conversation context. Prerequisites: - - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. - `az login` (Azure CLI authentication) - - Environment variables configured for AzureOpenAIResponsesClient (AZURE_AI_MODEL_DEPLOYMENT_NAME) + - Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.) Key Concepts: - Auto-registered handoff tools: HandoffBuilder automatically creates handoff tools @@ -56,11 +54,11 @@ def process_return(order_number: Annotated[str, "Order number to process return return f"Return initiated successfully for order {order_number}. You will receive return instructions via email." -def create_agents(client: AzureOpenAIResponsesClient) -> tuple[Agent, Agent, Agent, Agent]: +def create_agents(client: AzureOpenAIChatClient) -> tuple[Agent, Agent, Agent, Agent]: """Create and configure the triage and specialist agents. Args: - client: The AzureOpenAIResponsesClient to use for creating agents. + client: The AzureOpenAIChatClient to use for creating agents. Returns: Tuple of (triage_agent, refund_agent, order_agent, return_agent) @@ -191,11 +189,7 @@ async def main() -> None: replace the scripted_responses with actual user input collection. """ # Initialize the Azure OpenAI chat client - client = AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ) + client = AzureOpenAIChatClient(credential=AzureCliCredential()) # Create all agents: triage + specialists triage, refund, order, support = create_agents(client) diff --git a/python/samples/03-workflows/orchestrations/handoff_with_code_interpreter_file.py b/python/samples/03-workflows/orchestrations/handoff_with_code_interpreter_file.py new file mode 100644 index 0000000000..bc65e3bb20 --- /dev/null +++ b/python/samples/03-workflows/orchestrations/handoff_with_code_interpreter_file.py @@ -0,0 +1,241 @@ +# Copyright (c) Microsoft. All rights reserved. + +""" +Handoff Workflow with Code Interpreter File Generation Sample + +This sample demonstrates retrieving file IDs from code interpreter output +in a handoff workflow context. A triage agent routes to a code specialist +that generates a text file, and we verify the file_id is captured correctly +from the streaming workflow events. + +Verifies GitHub issue #2718: files generated by code interpreter in +HandoffBuilder workflows can be properly retrieved. + +Toggle USE_V2_CLIENT to switch between: + - V1: AzureAIAgentClient (azure-ai-agents SDK) + - V2: AzureAIClient (azure-ai-projects 2.x with Responses API) + +IMPORTANT: When using V2 AzureAIClient with HandoffBuilder, each agent must +have its own client instance. The V2 client binds to a single server-side +agent name, so sharing a client between agents causes routing issues. + +Prerequisites: + - `az login` (Azure CLI authentication) + - V1: AZURE_AI_AGENT_PROJECT_CONNECTION_STRING + - V2: AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME +""" + +import asyncio +from collections.abc import AsyncIterable, AsyncIterator +from contextlib import asynccontextmanager +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, + WorkflowEvent, + WorkflowRunState, +) +from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder +from azure.identity.aio import AzureCliCredential + +# Toggle between V1 (AzureAIAgentClient) and V2 (AzureAIClient) +USE_V2_CLIENT = False + + +async def _drain(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]: + """Collect all events from an async stream.""" + return [event async for event in stream] + + +def _handle_events(events: list[WorkflowEvent]) -> tuple[list[WorkflowEvent[HandoffAgentUserRequest]], list[str]]: + """Process workflow events and extract file IDs and pending requests. + + Returns: + Tuple of (pending_requests, file_ids_found) + """ + + requests: list[WorkflowEvent[HandoffAgentUserRequest]] = [] + file_ids: list[str] = [] + + for event in events: + if event.type == "handoff_sent": + print(f"\n[Handoff from {event.data.source} to {event.data.target} initiated.]") + elif event.type == "status" and event.state in { + WorkflowRunState.IDLE, + WorkflowRunState.IDLE_WITH_PENDING_REQUESTS, + }: + print(f"[status] {event.state.name}") + elif event.type == "request_info" and isinstance(event.data, HandoffAgentUserRequest): + requests.append(cast(WorkflowEvent[HandoffAgentUserRequest], event)) + elif event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + for content in data.contents: + if content.type == "hosted_file": + file_ids.append(content.file_id) # type: ignore + print(f"[Found HostedFileContent: file_id={content.file_id}]") + elif content.type == "text" and content.annotations: + for annotation in content.annotations: + file_id = annotation["file_id"] # type: ignore + file_ids.append(file_id) + print(f"[Found file annotation: file_id={file_id}]") + elif event.type == "output": + conversation = cast(list[Message], event.data) + if isinstance(conversation, list): + print("\n=== Final Conversation Snapshot ===") + for message in conversation: + speaker = message.author_name or message.role + print(f"- {speaker}: {message.text or [content.type for content in message.contents]}") + print("===================================") + + return requests, file_ids + + +@asynccontextmanager +async def create_agents_v1(credential: AzureCliCredential) -> AsyncIterator[tuple[Agent, Agent]]: + """Create agents using V1 AzureAIAgentClient.""" + from agent_framework.azure import AzureAIAgentClient + + async with AzureAIAgentClient(credential=credential) as client: + triage = client.as_agent( + name="triage_agent", + instructions=( + "You are a triage agent. Route code-related requests to the code_specialist. " + "When the user asks to create or generate files, hand off to code_specialist " + "by calling handoff_to_code_specialist." + ), + ) + + # Create code interpreter tool using instance method + code_interpreter_tool = client.get_code_interpreter_tool() + + code_specialist = client.as_agent( + name="code_specialist", + instructions=( + "You are a Python code specialist. Use the code interpreter to execute Python code " + "and create files when requested. Always save files to /mnt/data/ directory." + ), + tools=[code_interpreter_tool], + ) + + yield triage, code_specialist # type: ignore + + +@asynccontextmanager +async def create_agents_v2(credential: AzureCliCredential) -> AsyncIterator[tuple[Agent, Agent]]: + """Create agents using V2 AzureAIClient. + + Each agent needs its own client instance because the V2 client binds + to a single server-side agent name. + """ + from agent_framework.azure import AzureAIClient + + async with ( + AzureAIClient(credential=credential) as triage_client, + AzureAIClient(credential=credential) as code_client, + ): + triage = triage_client.as_agent( + name="TriageAgent", + instructions="You are a triage agent. Your ONLY job is to route requests to the appropriate specialist.", + ) + + # Create code interpreter tool using instance method + code_interpreter_tool = code_client.get_code_interpreter_tool() + + code_specialist = code_client.as_agent( + name="CodeSpecialist", + instructions=( + "You are a Python code specialist. You have access to a code interpreter tool. " + "Use the code interpreter to execute Python code and create files. " + "Always save files to /mnt/data/ directory. " + "Do NOT discuss handoffs or routing - just complete the coding task directly." + ), + tools=[code_interpreter_tool], + ) + + yield triage, code_specialist + + +async def main() -> None: + """Run a simple handoff workflow with code interpreter file generation.""" + client_version = "V2 (AzureAIClient)" if USE_V2_CLIENT else "V1 (AzureAIAgentClient)" + print(f"=== Handoff Workflow with Code Interpreter File Generation [{client_version}] ===\n") + + async with AzureCliCredential() as credential: + create_agents = create_agents_v2 if USE_V2_CLIENT else create_agents_v1 + + async with create_agents(credential) as (triage, code_specialist): + workflow = ( + HandoffBuilder( + termination_condition=lambda conv: sum(1 for msg in conv if msg.role == "user") >= 2, + ) + .participants([triage, code_specialist]) + .with_start_agent(triage) + .build() + ) + + user_inputs = [ + "Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it.", + "exit", + ] + input_index = 0 + all_file_ids: list[str] = [] + + print(f"User: {user_inputs[0]}") + events = await _drain(workflow.run(user_inputs[0], stream=True)) + requests, file_ids = _handle_events(events) + all_file_ids.extend(file_ids) + input_index += 1 + + while requests: + request = requests[0] + if input_index >= len(user_inputs): + break + user_input = user_inputs[input_index] + print(f"\nUser: {user_input}") + + responses = {request.request_id: HandoffAgentUserRequest.create_response(user_input)} + events = await _drain(workflow.run(stream=True, responses=responses)) + requests, file_ids = _handle_events(events) + all_file_ids.extend(file_ids) + input_index += 1 + + print("\n" + "=" * 50) + if all_file_ids: + print(f"SUCCESS: Found {len(all_file_ids)} file ID(s) in handoff workflow:") + for fid in all_file_ids: + print(f" - {fid}") + else: + print("WARNING: No file IDs captured from the handoff workflow.") + print("=" * 50) + + """ + Sample Output: + + User: Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it. + [Found HostedFileContent: file_id=assistant-JT1sA...] + + === Conversation So Far === + - user: Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it. + - triage_agent: I am handing off your request to create the text file "hello.txt" with the specified content to the code specialist. They will assist you shortly. + - code_specialist: The file "hello.txt" has been created with the content "Hello from handoff workflow!". You can download it using the link below: + + [hello.txt](sandbox:/mnt/data/hello.txt) + =========================== + + [status] IDLE_WITH_PENDING_REQUESTS + + User: exit + [status] IDLE + + ================================================== + SUCCESS: Found 1 file ID(s) in handoff workflow: + - assistant-JT1sA... + ================================================== + """ # noqa: E501 + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/orchestrations/handoff/handoff_with_tool_approval_checkpoint_resume.py b/python/samples/03-workflows/orchestrations/handoff_with_tool_approval_checkpoint_resume.py similarity index 100% rename from python/samples/getting_started/orchestrations/handoff/handoff_with_tool_approval_checkpoint_resume.py rename to python/samples/03-workflows/orchestrations/handoff_with_tool_approval_checkpoint_resume.py diff --git a/python/samples/03-workflows/orchestrations/magentic.py b/python/samples/03-workflows/orchestrations/magentic.py new file mode 100644 index 0000000000..7ff0a08b1b --- /dev/null +++ b/python/samples/03-workflows/orchestrations/magentic.py @@ -0,0 +1,144 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import json +import logging +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, + WorkflowEvent, +) +from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient +from agent_framework.orchestrations import GroupChatRequestSentEvent, MagenticBuilder, MagenticProgressLedger + +logging.basicConfig(level=logging.WARNING) +logger = logging.getLogger(__name__) + +""" +Sample: Magentic Orchestration (multi-agent) + +What it does: +- Orchestrates multiple agents using `MagenticBuilder` with streaming callbacks. + +- ResearcherAgent (Agent backed by an OpenAI chat client) for + finding information. +- CoderAgent (Agent backed by OpenAI Assistants with the hosted + code interpreter tool) for analysis and computation. + +The workflow is configured with: +- A Standard Magentic manager (uses a chat client for planning and progress). +- Callbacks for final results, per-message agent responses, and streaming + token updates. + +When run, the script builds the workflow, submits a task about estimating the +energy efficiency and CO2 emissions of several ML models, streams intermediate +events, and prints the final answer. The workflow completes when idle. + +Prerequisites: +- OpenAI credentials configured for `OpenAIChatClient` and `OpenAIResponsesClient`. +""" + + +async def main() -> None: + researcher_agent = Agent( + name="ResearcherAgent", + description="Specialist in research and information gathering", + instructions=( + "You are a Researcher. You find information without additional computation or quantitative analysis." + ), + # This agent requires the gpt-4o-search-preview model to perform web searches. + client=OpenAIChatClient(model_id="gpt-4o-search-preview"), + ) + + # Create code interpreter tool using instance method + coder_client = OpenAIResponsesClient() + code_interpreter_tool = coder_client.get_code_interpreter_tool() + + coder_agent = Agent( + name="CoderAgent", + description="A helpful assistant that writes and executes code to process and analyze data.", + instructions="You solve questions using code. Please provide detailed analysis and computation process.", + client=coder_client, + tools=code_interpreter_tool, + ) + + # Create a manager agent for orchestration + manager_agent = Agent( + name="MagenticManager", + description="Orchestrator that coordinates the research and coding workflow", + instructions="You coordinate a team to complete complex tasks efficiently.", + client=OpenAIChatClient(), + ) + + print("\nBuilding Magentic Workflow...") + + # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds + # (Intermediate outputs will be emitted as WorkflowOutputEvent events) + workflow = MagenticBuilder( + participants=[researcher_agent, coder_agent], + intermediate_outputs=True, + manager_agent=manager_agent, + max_round_count=10, + max_stall_count=3, + max_reset_count=2, + ).build() + + task = ( + "I am preparing a report on the energy efficiency of different machine learning model architectures. " + "Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 " + "on standard datasets (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2). " + "Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 " + "VM for 24 hours. Provide tables for clarity, and recommend the most energy-efficient model " + "per task type (image classification, text classification, and text generation)." + ) + + print(f"\nTask: {task}") + print("\nStarting workflow execution...") + + # Keep track of the last executor to format output nicely in streaming mode + last_response_id: str | None = None + output_event: WorkflowEvent | None = None + async for event in workflow.run(task, stream=True): + if event.type == "output" and isinstance(event.data, AgentResponseUpdate): + response_id = event.data.response_id + if response_id != last_response_id: + if last_response_id is not None: + print("\n") + print(f"- {event.executor_id}:", end=" ", flush=True) + last_response_id = response_id + print(event.data, end="", flush=True) + + elif event.type == "magentic_orchestrator": + print(f"\n[Magentic Orchestrator Event] Type: {event.data.event_type.name}") + if isinstance(event.data.content, Message): + print(f"Please review the plan:\n{event.data.content.text}") + elif isinstance(event.data.content, MagenticProgressLedger): + print(f"Please review progress ledger:\n{json.dumps(event.data.content.to_dict(), indent=2)}") + else: + print(f"Unknown data type in MagenticOrchestratorEvent: {type(event.data.content)}") + + # Block to allow user to read the plan/progress before continuing + # Note: this is for demonstration only and is not the recommended way to handle human interaction. + # Please refer to `with_plan_review` for proper human interaction during planning phases. + await asyncio.get_event_loop().run_in_executor(None, input, "Press Enter to continue...") + + elif event.type == "group_chat" and isinstance(event.data, GroupChatRequestSentEvent): + print(f"\n[REQUEST SENT ({event.data.round_index})] to agent: {event.data.participant_name}") + + elif event.type == "output": + output_event = event + + if output_event: + # The output of the magentic workflow is a collection of chat messages from all participants + outputs = cast(list[Message], output_event.data) + print("\n" + "=" * 80) + print("\nFinal Conversation Transcript:\n") + for message in outputs: + print(f"{message.author_name or message.role}: {message.text}\n") + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/orchestrations/magentic/magentic_checkpoint.py b/python/samples/03-workflows/orchestrations/magentic_checkpoint.py similarity index 93% rename from python/samples/getting_started/orchestrations/magentic/magentic_checkpoint.py rename to python/samples/03-workflows/orchestrations/magentic_checkpoint.py index 87442598b4..adce878f0d 100644 --- a/python/samples/getting_started/orchestrations/magentic/magentic_checkpoint.py +++ b/python/samples/03-workflows/orchestrations/magentic_checkpoint.py @@ -2,7 +2,6 @@ import asyncio import json -import os from datetime import datetime from pathlib import Path from typing import cast @@ -15,9 +14,9 @@ from agent_framework import ( WorkflowEvent, WorkflowRunState, ) -from agent_framework.azure import AzureOpenAIResponsesClient +from agent_framework.azure import AzureOpenAIChatClient from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest -from azure.identity import AzureCliCredential +from azure.identity._credentials import AzureCliCredential """ Sample: Magentic Orchestration + Checkpointing @@ -35,8 +34,7 @@ Concepts highlighted here: `responses` mapping so we can inject the stored human reply during restoration. Prerequisites: -- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint. -- Environment variables configured for `AzureOpenAIResponsesClient`. +- OpenAI environment variables configured for `OpenAIChatClient`. """ TASK = ( @@ -59,22 +57,14 @@ def build_workflow(checkpoint_storage: FileCheckpointStorage): name="ResearcherAgent", description="Collects background facts and references for the project.", instructions=("You are the research lead. Gather crisp bullet points the team should know."), - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=AzureOpenAIChatClient(credential=AzureCliCredential()), ) writer = Agent( name="WriterAgent", description="Synthesizes the final brief for stakeholders.", instructions=("You convert the research notes into a structured brief with milestones and risks."), - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=AzureOpenAIChatClient(credential=AzureCliCredential()), ) # Create a manager agent for orchestration @@ -82,11 +72,7 @@ def build_workflow(checkpoint_storage: FileCheckpointStorage): name="MagenticManager", description="Orchestrator that coordinates the research and writing workflow", instructions="You coordinate a team to complete complex tasks efficiently.", - client=AzureOpenAIResponsesClient( - project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], - deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], - credential=AzureCliCredential(), - ), + client=AzureOpenAIChatClient(credential=AzureCliCredential()), ) # The builder wires in the Magentic orchestrator, sets the plan review path, and diff --git a/python/samples/03-workflows/orchestrations/magentic_human_plan_review.py b/python/samples/03-workflows/orchestrations/magentic_human_plan_review.py new file mode 100644 index 0000000000..95f8de5f46 --- /dev/null +++ b/python/samples/03-workflows/orchestrations/magentic_human_plan_review.py @@ -0,0 +1,150 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +import json +from collections.abc import AsyncIterable +from typing import cast + +from agent_framework import ( + Agent, + AgentResponseUpdate, + Message, + WorkflowEvent, +) +from agent_framework.openai import OpenAIChatClient +from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest, MagenticPlanReviewResponse + +""" +Sample: Magentic Orchestration with Human Plan Review + +This sample demonstrates how humans can review and provide feedback on plans +generated by the Magentic workflow orchestrator. When plan review is enabled, +the workflow requests human approval or revision before executing each plan. + +Key concepts: +- with_plan_review(): Enables human review of generated plans +- MagenticPlanReviewRequest: The event type for plan review requests +- Human can choose to: approve the plan or provide revision feedback + +Plan review options: +- approve(): Accept the proposed plan and continue execution +- revise(feedback): Provide textual feedback to modify the plan + +Prerequisites: +- OpenAI credentials configured for `OpenAIChatClient`. +""" + +# Keep track of the last response to format output nicely in streaming mode +last_response_id: str | None = None + + +async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, MagenticPlanReviewResponse] | None: + """Process events from the workflow stream to capture human feedback requests.""" + global last_response_id + + requests: dict[str, MagenticPlanReviewRequest] = {} + async for event in stream: + if event.type == "request_info" and event.request_type is MagenticPlanReviewRequest: + requests[event.request_id] = cast(MagenticPlanReviewRequest, event.data) + + if event.type == "output": + data = event.data + if isinstance(data, AgentResponseUpdate): + rid = data.response_id + if rid != last_response_id: + if last_response_id is not None: + print("\n") + print(f"{data.author_name}:", end=" ", flush=True) + last_response_id = rid + print(data.text, end="", flush=True) + else: + # The output of the workflow comes from the orchestrator and it's a list of messages + print("\n" + "=" * 60) + print("DISCUSSION COMPLETE") + print("=" * 60) + print("Final discussion summary:") + # To make the type checker happy, we cast event.data to the expected type + outputs = cast(list[Message], event.data) + for msg in outputs: + speaker = msg.author_name or msg.role + print(f"[{speaker}]: {msg.text}") + + responses: dict[str, MagenticPlanReviewResponse] = {} + if requests: + for request_id, request in requests.items(): + print("\n\n[Magentic Plan Review Request]") + if request.current_progress is not None: + print("Current Progress Ledger:") + print(json.dumps(request.current_progress.to_dict(), indent=2)) + print() + print(f"Proposed Plan:\n{request.plan.text}\n") + print("Please provide your feedback (press Enter to approve):") + + reply = input("> ") # noqa: ASYNC250 + if reply.strip() == "": + print("Plan approved.\n") + responses[request_id] = request.approve() + else: + print("Plan revised by human.\n") + responses[request_id] = request.revise(reply) + + return responses if responses else None + + +async def main() -> None: + researcher_agent = Agent( + name="ResearcherAgent", + description="Specialist in research and information gathering", + instructions="You are a Researcher. You find information and gather facts.", + client=OpenAIChatClient(model_id="gpt-4o"), + ) + + analyst_agent = Agent( + name="AnalystAgent", + description="Data analyst who processes and summarizes research findings", + instructions="You are an Analyst. You analyze findings and create summaries.", + client=OpenAIChatClient(model_id="gpt-4o"), + ) + + manager_agent = Agent( + name="MagenticManager", + description="Orchestrator that coordinates the workflow", + instructions="You coordinate a team to complete tasks efficiently.", + client=OpenAIChatClient(model_id="gpt-4o"), + ) + + print("\nBuilding Magentic Workflow with Human Plan Review...") + + # enable_plan_review=True: Request human input for plan review + # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds + # (Intermediate outputs will be emitted as WorkflowOutputEvent events) + workflow = MagenticBuilder( + participants=[researcher_agent, analyst_agent], + enable_plan_review=True, + intermediate_outputs=True, + manager_agent=manager_agent, + max_round_count=10, + max_stall_count=1, + max_reset_count=2, + ).build() + + task = "Research sustainable aviation fuel technology and summarize the findings." + + print(f"\nTask: {task}") + print("\nStarting workflow execution...") + print("=" * 60) + + # Initiate the first run of the workflow. + # Runs are not isolated; state is preserved across multiple calls to run. + stream = workflow.run(task, stream=True) + + pending_responses = await process_event_stream(stream) + while pending_responses is not None: + # Run the workflow until there is no more human feedback to provide, + # in which case this workflow completes. + stream = workflow.run(stream=True, responses=pending_responses) + pending_responses = await process_event_stream(stream) + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/sequential_agents.py b/python/samples/03-workflows/orchestrations/sequential_agents.py new file mode 100644 index 0000000000..7d77ef35c6 --- /dev/null +++ b/python/samples/03-workflows/orchestrations/sequential_agents.py @@ -0,0 +1,79 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import cast + +from agent_framework import Message +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import SequentialBuilder +from azure.identity import AzureCliCredential + +""" +Sample: Sequential workflow (agent-focused API) with shared conversation context + +Build a high-level sequential workflow using SequentialBuilder and two domain agents. +The shared conversation (list[Message]) flows through each participant. Each agent +appends its assistant message to the context. The workflow outputs the final conversation +list when complete. + +Note on internal adapters: +- Sequential orchestration includes small adapter nodes for input normalization + ("input-conversation"), agent-response conversion ("to-conversation:"), + and completion ("complete"). These may appear as ExecutorInvoke/Completed events in + the streamβ€”similar to how concurrent orchestration includes a dispatcher/aggregator. + You can safely ignore them when focusing on agent progress. + +Prerequisites: +- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars) +""" + + +async def main() -> None: + # 1) Create agents + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + + writer = client.as_agent( + instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."), + name="writer", + ) + + reviewer = client.as_agent( + instructions=("You are a thoughtful reviewer. Give brief feedback on the previous assistant message."), + name="reviewer", + ) + + # 2) Build sequential workflow: writer -> reviewer + workflow = SequentialBuilder(participants=[writer, reviewer]).build() + + # 3) Run and collect outputs + outputs: list[list[Message]] = [] + async for event in workflow.run("Write a tagline for a budget-friendly eBike.", stream=True): + if event.type == "output": + outputs.append(cast(list[Message], event.data)) + + if outputs: + print("===== Final Conversation =====") + for i, msg in enumerate(outputs[-1], start=1): + name = msg.author_name or ("assistant" if msg.role == "assistant" else "user") + print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}") + + """ + Sample Output: + + ===== Final Conversation ===== + ------------------------------------------------------------ + 01 [user] + Write a tagline for a budget-friendly eBike. + ------------------------------------------------------------ + 02 [writer] + Ride farther, spend lessβ€”your affordable eBike adventure starts here. + ------------------------------------------------------------ + 03 [reviewer] + This tagline clearly communicates affordability and the benefit of extended travel, making it + appealing to budget-conscious consumers. It has a friendly and motivating tone, though it could + be slightly shorter for more punch. Overall, a strong and effective suggestion! + """ + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/03-workflows/orchestrations/sequential_custom_executors.py b/python/samples/03-workflows/orchestrations/sequential_custom_executors.py new file mode 100644 index 0000000000..7f3e61fe2e --- /dev/null +++ b/python/samples/03-workflows/orchestrations/sequential_custom_executors.py @@ -0,0 +1,103 @@ +# Copyright (c) Microsoft. All rights reserved. + +import asyncio +from typing import Any + +from agent_framework import ( + AgentExecutorResponse, + Executor, + Message, + WorkflowContext, + handler, +) +from agent_framework.azure import AzureOpenAIChatClient +from agent_framework.orchestrations import SequentialBuilder +from azure.identity import AzureCliCredential + +""" +Sample: Sequential workflow mixing agents and a custom summarizer executor + +This demonstrates how SequentialBuilder chains participants with a shared +conversation context (list[Message]). An agent produces content; a custom +executor appends a compact summary to the conversation. The workflow completes +after all participants have executed in sequence, and the final output contains +the complete conversation. + +Custom executor contract: +- Provide at least one @handler accepting AgentExecutorResponse and a WorkflowContext[list[Message]] +- Emit the updated conversation via ctx.send_message([...]) + +Prerequisites: +- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars) +""" + + +class Summarizer(Executor): + """Simple summarizer: consumes full conversation and appends an assistant summary.""" + + @handler + async def summarize(self, agent_response: AgentExecutorResponse, ctx: WorkflowContext[list[Message]]) -> None: + """Append a summary message to a copy of the full conversation. + + Note: A custom executor must be able to handle the message type from the prior participant, and produce + the message type expected by the next participant. In this case, the prior participant is an agent thus + the input is AgentExecutorResponse (an agent will be wrapped in an AgentExecutor, which produces + `AgentExecutorResponse`). If the next participant is also an agent or this is the final participant, + the output must be `list[Message]`. + """ + if not agent_response.full_conversation: + await ctx.send_message([Message("assistant", ["No conversation to summarize."])]) + return + + users = sum(1 for m in agent_response.full_conversation if m.role == "user") + assistants = sum(1 for m in agent_response.full_conversation if m.role == "assistant") + summary = Message("assistant", [f"Summary -> users:{users} assistants:{assistants}"]) + final_conversation = list(agent_response.full_conversation) + [summary] + await ctx.send_message(final_conversation) + + +async def main() -> None: + # 1) Create a content agent + client = AzureOpenAIChatClient(credential=AzureCliCredential()) + content = client.as_agent( + instructions="Produce a concise paragraph answering the user's request.", + name="content", + ) + + # 2) Build sequential workflow: content -> summarizer + summarizer = Summarizer(id="summarizer") + workflow = SequentialBuilder(participants=[content, summarizer]).build() + + # 3) Run workflow and extract final conversation + events = await workflow.run("Explain the benefits of budget eBikes for commuters.") + outputs = events.get_outputs() + + if outputs: + print("===== Final Conversation =====") + messages: list[Message] | Any = outputs[0] + for i, msg in enumerate(messages, start=1): + name = msg.author_name or ("assistant" if msg.role == "assistant" else "user") + print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}") + + """ + Sample Output: + + ------------------------------------------------------------ + 01 [user] + Explain the benefits of budget eBikes for commuters. + ------------------------------------------------------------ + 02 [content] + Budget eBikes offer commuters an affordable, eco-friendly alternative to cars and public transport. + Their electric assistance reduces physical strain and allows riders to cover longer distances quickly, + minimizing travel time and fatigue. Budget models are low-cost to maintain and operate, making them accessible + for a wider range of people. Additionally, eBikes help reduce traffic congestion and carbon emissions, + supporting greener urban environments. Overall, budget eBikes provide cost-effective, efficient, and + sustainable transportation for daily commuting needs. + ------------------------------------------------------------ + 03 [assistant] + Summary -> users:1 assistants:1 + """ + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/getting_started/workflows/parallelism/aggregate_results_of_different_types.py b/python/samples/03-workflows/parallelism/aggregate_results_of_different_types.py similarity index 100% rename from python/samples/getting_started/workflows/parallelism/aggregate_results_of_different_types.py rename to python/samples/03-workflows/parallelism/aggregate_results_of_different_types.py diff --git a/python/samples/getting_started/workflows/parallelism/fan_out_fan_in_edges.py b/python/samples/03-workflows/parallelism/fan_out_fan_in_edges.py similarity index 100% rename from python/samples/getting_started/workflows/parallelism/fan_out_fan_in_edges.py rename to python/samples/03-workflows/parallelism/fan_out_fan_in_edges.py diff --git a/python/samples/getting_started/workflows/parallelism/map_reduce_and_visualization.py b/python/samples/03-workflows/parallelism/map_reduce_and_visualization.py similarity index 100% rename from python/samples/getting_started/workflows/parallelism/map_reduce_and_visualization.py rename to python/samples/03-workflows/parallelism/map_reduce_and_visualization.py diff --git a/python/samples/getting_started/workflows/resources/ambiguous_email.txt b/python/samples/03-workflows/resources/ambiguous_email.txt similarity index 100% rename from python/samples/getting_started/workflows/resources/ambiguous_email.txt rename to python/samples/03-workflows/resources/ambiguous_email.txt diff --git a/python/samples/getting_started/workflows/resources/email.txt b/python/samples/03-workflows/resources/email.txt similarity index 100% rename from python/samples/getting_started/workflows/resources/email.txt rename to python/samples/03-workflows/resources/email.txt diff --git a/python/samples/getting_started/workflows/resources/long_text.txt b/python/samples/03-workflows/resources/long_text.txt similarity index 100% rename from python/samples/getting_started/workflows/resources/long_text.txt rename to python/samples/03-workflows/resources/long_text.txt diff --git a/python/samples/getting_started/workflows/resources/spam.txt b/python/samples/03-workflows/resources/spam.txt similarity index 100% rename from python/samples/getting_started/workflows/resources/spam.txt rename to python/samples/03-workflows/resources/spam.txt diff --git a/python/samples/getting_started/workflows/state-management/state_with_agents.py b/python/samples/03-workflows/state-management/state_with_agents.py similarity index 100% rename from python/samples/getting_started/workflows/state-management/state_with_agents.py rename to python/samples/03-workflows/state-management/state_with_agents.py diff --git a/python/samples/getting_started/workflows/state-management/workflow_kwargs.py b/python/samples/03-workflows/state-management/workflow_kwargs.py similarity index 97% rename from python/samples/getting_started/workflows/state-management/workflow_kwargs.py rename to python/samples/03-workflows/state-management/workflow_kwargs.py index 3728ae6ff9..8835ee365b 100644 --- a/python/samples/getting_started/workflows/state-management/workflow_kwargs.py +++ b/python/samples/03-workflows/state-management/workflow_kwargs.py @@ -31,8 +31,8 @@ Prerequisites: # Define tools that accept custom context via **kwargs # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_user_data( query: Annotated[str, Field(description="What user data to retrieve")], diff --git a/python/samples/getting_started/orchestrations/concurrent/concurrent_builder_tool_approval.py b/python/samples/03-workflows/tool-approval/concurrent_builder_tool_approval.py similarity index 98% rename from python/samples/getting_started/orchestrations/concurrent/concurrent_builder_tool_approval.py rename to python/samples/03-workflows/tool-approval/concurrent_builder_tool_approval.py index 80e06d9d2b..227306eff0 100644 --- a/python/samples/getting_started/orchestrations/concurrent/concurrent_builder_tool_approval.py +++ b/python/samples/03-workflows/tool-approval/concurrent_builder_tool_approval.py @@ -49,8 +49,8 @@ Prerequisites: # 1. Define market data tools (no approval required) # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; # See: -# samples/getting_started/tools/function_tool_with_approval.py -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# samples/02-agents/tools/function_tool_with_approval.py +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_stock_price(symbol: Annotated[str, "The stock ticker symbol"]) -> str: """Get the current stock price for a given symbol.""" diff --git a/python/samples/getting_started/orchestrations/group-chat/group_chat_builder_tool_approval.py b/python/samples/03-workflows/tool-approval/group_chat_builder_tool_approval.py similarity index 98% rename from python/samples/getting_started/orchestrations/group-chat/group_chat_builder_tool_approval.py rename to python/samples/03-workflows/tool-approval/group_chat_builder_tool_approval.py index 2ac0738e66..e877abdd3c 100644 --- a/python/samples/getting_started/orchestrations/group-chat/group_chat_builder_tool_approval.py +++ b/python/samples/03-workflows/tool-approval/group_chat_builder_tool_approval.py @@ -47,8 +47,8 @@ Prerequisites: # 1. Define tools for different agents # NOTE: approval_mode="never_require" is for sample brevity. -# Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py -# and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py +# and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def run_tests(test_suite: Annotated[str, "Name of the test suite to run"]) -> str: """Run automated tests for the application.""" diff --git a/python/samples/getting_started/orchestrations/sequential/sequential_builder_tool_approval.py b/python/samples/03-workflows/tool-approval/sequential_builder_tool_approval.py similarity index 97% rename from python/samples/getting_started/orchestrations/sequential/sequential_builder_tool_approval.py rename to python/samples/03-workflows/tool-approval/sequential_builder_tool_approval.py index 554cca926f..10a05343a6 100644 --- a/python/samples/getting_started/orchestrations/sequential/sequential_builder_tool_approval.py +++ b/python/samples/03-workflows/tool-approval/sequential_builder_tool_approval.py @@ -57,8 +57,8 @@ def execute_database_query( # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; -# see samples/getting_started/tools/function_tool_with_approval.py and -# samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# see samples/02-agents/tools/function_tool_with_approval.py and +# samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_database_schema() -> str: """Get the current database schema. Does not require approval.""" diff --git a/python/samples/getting_started/workflows/visualization/concurrent_with_visualization.py b/python/samples/03-workflows/visualization/concurrent_with_visualization.py similarity index 100% rename from python/samples/getting_started/workflows/visualization/concurrent_with_visualization.py rename to python/samples/03-workflows/visualization/concurrent_with_visualization.py diff --git a/python/samples/getting_started/agents/a2a/README.md b/python/samples/04-hosting/a2a/README.md similarity index 93% rename from python/samples/getting_started/agents/a2a/README.md rename to python/samples/04-hosting/a2a/README.md index d774b3c877..dd09aaaa1a 100644 --- a/python/samples/getting_started/agents/a2a/README.md +++ b/python/samples/04-hosting/a2a/README.md @@ -2,7 +2,7 @@ This folder contains examples demonstrating how to create and use agents with the A2A (Agent2Agent) protocol from the `agent_framework` package to communicate with remote A2A agents. -By default the A2AAgent waits for the remote agent to finish before returning (`background=False`), so long-running A2A tasks are handled transparently. For advanced scenarios where you need to poll or resubscribe to in-progress tasks using continuation tokens, see the [background responses sample](../../../concepts/background_responses.py). +By default the A2AAgent waits for the remote agent to finish before returning (`background=False`), so long-running A2A tasks are handled transparently. For advanced scenarios where you need to poll or resubscribe to in-progress tasks using continuation tokens, see the [background responses sample](../../02-agents/background_responses.py). For more information about the A2A protocol specification, visit: https://a2a-protocol.org/latest/ diff --git a/python/samples/getting_started/agents/a2a/agent_with_a2a.py b/python/samples/04-hosting/a2a/agent_with_a2a.py similarity index 100% rename from python/samples/getting_started/agents/a2a/agent_with_a2a.py rename to python/samples/04-hosting/a2a/agent_with_a2a.py diff --git a/python/samples/getting_started/azure_functions/01_single_agent/README.md b/python/samples/04-hosting/azure_functions/01_single_agent/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/01_single_agent/README.md rename to python/samples/04-hosting/azure_functions/01_single_agent/README.md diff --git a/python/samples/getting_started/azure_functions/01_single_agent/demo.http b/python/samples/04-hosting/azure_functions/01_single_agent/demo.http similarity index 100% rename from python/samples/getting_started/azure_functions/01_single_agent/demo.http rename to python/samples/04-hosting/azure_functions/01_single_agent/demo.http diff --git a/python/samples/getting_started/azure_functions/01_single_agent/function_app.py b/python/samples/04-hosting/azure_functions/01_single_agent/function_app.py similarity index 100% rename from python/samples/getting_started/azure_functions/01_single_agent/function_app.py rename to python/samples/04-hosting/azure_functions/01_single_agent/function_app.py diff --git a/python/samples/getting_started/azure_functions/01_single_agent/host.json b/python/samples/04-hosting/azure_functions/01_single_agent/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/01_single_agent/host.json rename to python/samples/04-hosting/azure_functions/01_single_agent/host.json diff --git a/python/samples/getting_started/azure_functions/01_single_agent/local.settings.json.template b/python/samples/04-hosting/azure_functions/01_single_agent/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/01_single_agent/local.settings.json.template rename to python/samples/04-hosting/azure_functions/01_single_agent/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/01_single_agent/requirements.txt b/python/samples/04-hosting/azure_functions/01_single_agent/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/01_single_agent/requirements.txt rename to python/samples/04-hosting/azure_functions/01_single_agent/requirements.txt diff --git a/python/samples/getting_started/azure_functions/02_multi_agent/README.md b/python/samples/04-hosting/azure_functions/02_multi_agent/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/02_multi_agent/README.md rename to python/samples/04-hosting/azure_functions/02_multi_agent/README.md diff --git a/python/samples/getting_started/azure_functions/02_multi_agent/demo.http b/python/samples/04-hosting/azure_functions/02_multi_agent/demo.http similarity index 100% rename from python/samples/getting_started/azure_functions/02_multi_agent/demo.http rename to python/samples/04-hosting/azure_functions/02_multi_agent/demo.http diff --git a/python/samples/getting_started/azure_functions/02_multi_agent/function_app.py b/python/samples/04-hosting/azure_functions/02_multi_agent/function_app.py similarity index 95% rename from python/samples/getting_started/azure_functions/02_multi_agent/function_app.py rename to python/samples/04-hosting/azure_functions/02_multi_agent/function_app.py index 15e034dd22..2a3bd0d420 100644 --- a/python/samples/getting_started/azure_functions/02_multi_agent/function_app.py +++ b/python/samples/04-hosting/azure_functions/02_multi_agent/function_app.py @@ -20,7 +20,7 @@ from azure.identity import AzureCliCredential logger = logging.getLogger(__name__) -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather(location: str) -> dict[str, Any]: """Get current weather for a location.""" diff --git a/python/samples/getting_started/azure_functions/02_multi_agent/host.json b/python/samples/04-hosting/azure_functions/02_multi_agent/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/02_multi_agent/host.json rename to python/samples/04-hosting/azure_functions/02_multi_agent/host.json diff --git a/python/samples/getting_started/azure_functions/02_multi_agent/local.settings.json.template b/python/samples/04-hosting/azure_functions/02_multi_agent/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/02_multi_agent/local.settings.json.template rename to python/samples/04-hosting/azure_functions/02_multi_agent/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/02_multi_agent/requirements.txt b/python/samples/04-hosting/azure_functions/02_multi_agent/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/02_multi_agent/requirements.txt rename to python/samples/04-hosting/azure_functions/02_multi_agent/requirements.txt diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/README.md b/python/samples/04-hosting/azure_functions/03_reliable_streaming/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/README.md rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/README.md diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/demo.http b/python/samples/04-hosting/azure_functions/03_reliable_streaming/demo.http similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/demo.http rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/demo.http diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/function_app.py b/python/samples/04-hosting/azure_functions/03_reliable_streaming/function_app.py similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/function_app.py rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/function_app.py diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/host.json b/python/samples/04-hosting/azure_functions/03_reliable_streaming/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/host.json rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/host.json diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/local.settings.json.template b/python/samples/04-hosting/azure_functions/03_reliable_streaming/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/local.settings.json.template rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/redis_stream_response_handler.py b/python/samples/04-hosting/azure_functions/03_reliable_streaming/redis_stream_response_handler.py similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/redis_stream_response_handler.py rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/redis_stream_response_handler.py diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/requirements.txt b/python/samples/04-hosting/azure_functions/03_reliable_streaming/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/requirements.txt rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/requirements.txt diff --git a/python/samples/getting_started/azure_functions/03_reliable_streaming/tools.py b/python/samples/04-hosting/azure_functions/03_reliable_streaming/tools.py similarity index 100% rename from python/samples/getting_started/azure_functions/03_reliable_streaming/tools.py rename to python/samples/04-hosting/azure_functions/03_reliable_streaming/tools.py diff --git a/python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/README.md b/python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/README.md rename to python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/README.md diff --git a/python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/demo.http b/python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/demo.http similarity index 100% rename from python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/demo.http rename to python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/demo.http diff --git a/python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/function_app.py b/python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/function_app.py similarity index 100% rename from python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/function_app.py rename to python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/function_app.py diff --git a/python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/host.json b/python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/host.json rename to python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/host.json diff --git a/python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/local.settings.json.template b/python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/local.settings.json.template rename to python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/requirements.txt b/python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/requirements.txt rename to python/samples/04-hosting/azure_functions/04_single_agent_orchestration_chaining/requirements.txt diff --git a/python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/README.md b/python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/README.md rename to python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/README.md diff --git a/python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/demo.http b/python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/demo.http similarity index 100% rename from python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/demo.http rename to python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/demo.http diff --git a/python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/function_app.py b/python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/function_app.py similarity index 100% rename from python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/function_app.py rename to python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/function_app.py diff --git a/python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/host.json b/python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/host.json rename to python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/host.json diff --git a/python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/local.settings.json.template b/python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/local.settings.json.template rename to python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/requirements.txt b/python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/requirements.txt rename to python/samples/04-hosting/azure_functions/05_multi_agent_orchestration_concurrency/requirements.txt diff --git a/python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/README.md b/python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/README.md rename to python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/README.md diff --git a/python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/demo.http b/python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/demo.http similarity index 100% rename from python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/demo.http rename to python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/demo.http diff --git a/python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/function_app.py b/python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/function_app.py similarity index 100% rename from python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/function_app.py rename to python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/function_app.py diff --git a/python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/host.json b/python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/host.json rename to python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/host.json diff --git a/python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/local.settings.json.template b/python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/local.settings.json.template rename to python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/requirements.txt b/python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/requirements.txt rename to python/samples/04-hosting/azure_functions/06_multi_agent_orchestration_conditionals/requirements.txt diff --git a/python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/README.md b/python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/README.md rename to python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/README.md diff --git a/python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/demo.http b/python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/demo.http similarity index 100% rename from python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/demo.http rename to python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/demo.http diff --git a/python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/function_app.py b/python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/function_app.py similarity index 100% rename from python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/function_app.py rename to python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/function_app.py diff --git a/python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/host.json b/python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/host.json rename to python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/host.json diff --git a/python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/local.settings.json.template b/python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/local.settings.json.template rename to python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/requirements.txt b/python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/requirements.txt rename to python/samples/04-hosting/azure_functions/07_single_agent_orchestration_hitl/requirements.txt diff --git a/python/samples/getting_started/azure_functions/08_mcp_server/README.md b/python/samples/04-hosting/azure_functions/08_mcp_server/README.md similarity index 98% rename from python/samples/getting_started/azure_functions/08_mcp_server/README.md rename to python/samples/04-hosting/azure_functions/08_mcp_server/README.md index a475823a1a..80fb2370b8 100644 --- a/python/samples/getting_started/azure_functions/08_mcp_server/README.md +++ b/python/samples/04-hosting/azure_functions/08_mcp_server/README.md @@ -46,7 +46,7 @@ Update your `local.settings.json` with your Azure OpenAI credentials: 1. **Start the Function App**: ```bash - cd python/samples/getting_started/azure_functions/08_mcp_server + cd python/samples/04-hosting/azure_functions/08_mcp_server func start ``` diff --git a/python/samples/getting_started/azure_functions/08_mcp_server/function_app.py b/python/samples/04-hosting/azure_functions/08_mcp_server/function_app.py similarity index 100% rename from python/samples/getting_started/azure_functions/08_mcp_server/function_app.py rename to python/samples/04-hosting/azure_functions/08_mcp_server/function_app.py diff --git a/python/samples/getting_started/azure_functions/08_mcp_server/host.json b/python/samples/04-hosting/azure_functions/08_mcp_server/host.json similarity index 100% rename from python/samples/getting_started/azure_functions/08_mcp_server/host.json rename to python/samples/04-hosting/azure_functions/08_mcp_server/host.json diff --git a/python/samples/getting_started/azure_functions/08_mcp_server/local.settings.json.template b/python/samples/04-hosting/azure_functions/08_mcp_server/local.settings.json.template similarity index 100% rename from python/samples/getting_started/azure_functions/08_mcp_server/local.settings.json.template rename to python/samples/04-hosting/azure_functions/08_mcp_server/local.settings.json.template diff --git a/python/samples/getting_started/azure_functions/08_mcp_server/requirements.txt b/python/samples/04-hosting/azure_functions/08_mcp_server/requirements.txt similarity index 100% rename from python/samples/getting_started/azure_functions/08_mcp_server/requirements.txt rename to python/samples/04-hosting/azure_functions/08_mcp_server/requirements.txt diff --git a/python/samples/getting_started/azure_functions/README.md b/python/samples/04-hosting/azure_functions/README.md similarity index 100% rename from python/samples/getting_started/azure_functions/README.md rename to python/samples/04-hosting/azure_functions/README.md diff --git a/python/samples/getting_started/durabletask/01_single_agent/README.md b/python/samples/04-hosting/durabletask/01_single_agent/README.md similarity index 97% rename from python/samples/getting_started/durabletask/01_single_agent/README.md rename to python/samples/04-hosting/durabletask/01_single_agent/README.md index ffe3b1484a..62a150e216 100644 --- a/python/samples/getting_started/durabletask/01_single_agent/README.md +++ b/python/samples/04-hosting/durabletask/01_single_agent/README.md @@ -20,7 +20,7 @@ With the environment setup, you can run the sample using the combined approach o **Option 1: Combined (Recommended for Testing)** ```bash -cd samples/getting_started/durabletask/01_single_agent +cd samples/04-hosting/durabletask/01_single_agent python sample.py ``` diff --git a/python/samples/getting_started/durabletask/01_single_agent/client.py b/python/samples/04-hosting/durabletask/01_single_agent/client.py similarity index 100% rename from python/samples/getting_started/durabletask/01_single_agent/client.py rename to python/samples/04-hosting/durabletask/01_single_agent/client.py diff --git a/python/samples/getting_started/durabletask/01_single_agent/requirements.txt b/python/samples/04-hosting/durabletask/01_single_agent/requirements.txt similarity index 100% rename from python/samples/getting_started/durabletask/01_single_agent/requirements.txt rename to python/samples/04-hosting/durabletask/01_single_agent/requirements.txt diff --git a/python/samples/getting_started/durabletask/01_single_agent/sample.py b/python/samples/04-hosting/durabletask/01_single_agent/sample.py similarity index 100% rename from python/samples/getting_started/durabletask/01_single_agent/sample.py rename to python/samples/04-hosting/durabletask/01_single_agent/sample.py diff --git a/python/samples/getting_started/durabletask/01_single_agent/worker.py b/python/samples/04-hosting/durabletask/01_single_agent/worker.py similarity index 100% rename from python/samples/getting_started/durabletask/01_single_agent/worker.py rename to python/samples/04-hosting/durabletask/01_single_agent/worker.py diff --git a/python/samples/getting_started/durabletask/02_multi_agent/README.md b/python/samples/04-hosting/durabletask/02_multi_agent/README.md similarity index 97% rename from python/samples/getting_started/durabletask/02_multi_agent/README.md rename to python/samples/04-hosting/durabletask/02_multi_agent/README.md index e9b2a36e19..aad51ba014 100644 --- a/python/samples/getting_started/durabletask/02_multi_agent/README.md +++ b/python/samples/04-hosting/durabletask/02_multi_agent/README.md @@ -20,7 +20,7 @@ With the environment setup, you can run the sample using the combined approach o **Option 1: Combined (Recommended for Testing)** ```bash -cd samples/getting_started/durabletask/02_multi_agent +cd samples/04-hosting/durabletask/02_multi_agent python sample.py ``` diff --git a/python/samples/getting_started/durabletask/02_multi_agent/client.py b/python/samples/04-hosting/durabletask/02_multi_agent/client.py similarity index 100% rename from python/samples/getting_started/durabletask/02_multi_agent/client.py rename to python/samples/04-hosting/durabletask/02_multi_agent/client.py diff --git a/python/samples/getting_started/durabletask/02_multi_agent/requirements.txt b/python/samples/04-hosting/durabletask/02_multi_agent/requirements.txt similarity index 100% rename from python/samples/getting_started/durabletask/02_multi_agent/requirements.txt rename to python/samples/04-hosting/durabletask/02_multi_agent/requirements.txt diff --git a/python/samples/getting_started/durabletask/02_multi_agent/sample.py b/python/samples/04-hosting/durabletask/02_multi_agent/sample.py similarity index 100% rename from python/samples/getting_started/durabletask/02_multi_agent/sample.py rename to python/samples/04-hosting/durabletask/02_multi_agent/sample.py diff --git a/python/samples/getting_started/durabletask/02_multi_agent/worker.py b/python/samples/04-hosting/durabletask/02_multi_agent/worker.py similarity index 100% rename from python/samples/getting_started/durabletask/02_multi_agent/worker.py rename to python/samples/04-hosting/durabletask/02_multi_agent/worker.py diff --git a/python/samples/getting_started/durabletask/03_single_agent_streaming/README.md b/python/samples/04-hosting/durabletask/03_single_agent_streaming/README.md similarity index 98% rename from python/samples/getting_started/durabletask/03_single_agent_streaming/README.md rename to python/samples/04-hosting/durabletask/03_single_agent_streaming/README.md index 6e9f1428bf..8bd4191fe8 100644 --- a/python/samples/getting_started/durabletask/03_single_agent_streaming/README.md +++ b/python/samples/04-hosting/durabletask/03_single_agent_streaming/README.md @@ -37,7 +37,7 @@ With the environment setup, you can run the sample using the combined approach o **Option 1: Combined (Recommended for Testing)** ```bash -cd samples/getting_started/durabletask/03_single_agent_streaming +cd samples/04-hosting/durabletask/03_single_agent_streaming python sample.py ``` diff --git a/python/samples/getting_started/durabletask/03_single_agent_streaming/client.py b/python/samples/04-hosting/durabletask/03_single_agent_streaming/client.py similarity index 100% rename from python/samples/getting_started/durabletask/03_single_agent_streaming/client.py rename to python/samples/04-hosting/durabletask/03_single_agent_streaming/client.py diff --git a/python/samples/getting_started/durabletask/03_single_agent_streaming/redis_stream_response_handler.py b/python/samples/04-hosting/durabletask/03_single_agent_streaming/redis_stream_response_handler.py similarity index 100% rename from python/samples/getting_started/durabletask/03_single_agent_streaming/redis_stream_response_handler.py rename to python/samples/04-hosting/durabletask/03_single_agent_streaming/redis_stream_response_handler.py diff --git a/python/samples/getting_started/durabletask/03_single_agent_streaming/requirements.txt b/python/samples/04-hosting/durabletask/03_single_agent_streaming/requirements.txt similarity index 100% rename from python/samples/getting_started/durabletask/03_single_agent_streaming/requirements.txt rename to python/samples/04-hosting/durabletask/03_single_agent_streaming/requirements.txt diff --git a/python/samples/getting_started/durabletask/03_single_agent_streaming/sample.py b/python/samples/04-hosting/durabletask/03_single_agent_streaming/sample.py similarity index 100% rename from python/samples/getting_started/durabletask/03_single_agent_streaming/sample.py rename to python/samples/04-hosting/durabletask/03_single_agent_streaming/sample.py diff --git a/python/samples/getting_started/durabletask/03_single_agent_streaming/tools.py b/python/samples/04-hosting/durabletask/03_single_agent_streaming/tools.py similarity index 100% rename from python/samples/getting_started/durabletask/03_single_agent_streaming/tools.py rename to python/samples/04-hosting/durabletask/03_single_agent_streaming/tools.py diff --git a/python/samples/getting_started/durabletask/03_single_agent_streaming/worker.py b/python/samples/04-hosting/durabletask/03_single_agent_streaming/worker.py similarity index 100% rename from python/samples/getting_started/durabletask/03_single_agent_streaming/worker.py rename to python/samples/04-hosting/durabletask/03_single_agent_streaming/worker.py diff --git a/python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/README.md b/python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/README.md similarity index 96% rename from python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/README.md rename to python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/README.md index 3a5605b3dd..2c277423f1 100644 --- a/python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/README.md +++ b/python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/README.md @@ -20,7 +20,7 @@ With the environment setup, you can run the sample using the combined approach o **Option 1: Combined (Recommended for Testing)** ```bash -cd samples/getting_started/durabletask/04_single_agent_orchestration_chaining +cd samples/04-hosting/durabletask/04_single_agent_orchestration_chaining python sample.py ``` diff --git a/python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/client.py b/python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/client.py similarity index 100% rename from python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/client.py rename to python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/client.py diff --git a/python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/requirements.txt b/python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/requirements.txt similarity index 100% rename from python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/requirements.txt rename to python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/requirements.txt diff --git a/python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/sample.py b/python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/sample.py similarity index 100% rename from python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/sample.py rename to python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/sample.py diff --git a/python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/worker.py b/python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/worker.py similarity index 100% rename from python/samples/getting_started/durabletask/04_single_agent_orchestration_chaining/worker.py rename to python/samples/04-hosting/durabletask/04_single_agent_orchestration_chaining/worker.py diff --git a/python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/README.md b/python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/README.md similarity index 96% rename from python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/README.md rename to python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/README.md index 0edf244d78..e2843f4798 100644 --- a/python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/README.md +++ b/python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/README.md @@ -20,7 +20,7 @@ With the environment setup, you can run the sample using the combined approach o **Option 1: Combined (Recommended for Testing)** ```bash -cd samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency +cd samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency python sample.py ``` diff --git a/python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/client.py b/python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/client.py similarity index 100% rename from python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/client.py rename to python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/client.py diff --git a/python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/requirements.txt b/python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/requirements.txt similarity index 100% rename from python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/requirements.txt rename to python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/requirements.txt diff --git a/python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/sample.py b/python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/sample.py similarity index 100% rename from python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/sample.py rename to python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/sample.py diff --git a/python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/worker.py b/python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/worker.py similarity index 100% rename from python/samples/getting_started/durabletask/05_multi_agent_orchestration_concurrency/worker.py rename to python/samples/04-hosting/durabletask/05_multi_agent_orchestration_concurrency/worker.py diff --git a/python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/README.md b/python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/README.md similarity index 97% rename from python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/README.md rename to python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/README.md index f6a40c087b..dcd4a617c3 100644 --- a/python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/README.md +++ b/python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/README.md @@ -21,7 +21,7 @@ With the environment setup, you can run the sample using the combined approach o **Option 1: Combined (Recommended for Testing)** ```bash -cd samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals +cd samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals python sample.py ``` diff --git a/python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/client.py b/python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/client.py similarity index 100% rename from python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/client.py rename to python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/client.py diff --git a/python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/requirements.txt b/python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/requirements.txt similarity index 100% rename from python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/requirements.txt rename to python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/requirements.txt diff --git a/python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/sample.py b/python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/sample.py similarity index 100% rename from python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/sample.py rename to python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/sample.py diff --git a/python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/worker.py b/python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/worker.py similarity index 100% rename from python/samples/getting_started/durabletask/06_multi_agent_orchestration_conditionals/worker.py rename to python/samples/04-hosting/durabletask/06_multi_agent_orchestration_conditionals/worker.py diff --git a/python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/README.md b/python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/README.md similarity index 97% rename from python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/README.md rename to python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/README.md index fbfe905d59..5e3f8eea27 100644 --- a/python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/README.md +++ b/python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/README.md @@ -23,7 +23,7 @@ With the environment setup, you can run the sample using the combined approach o **Option 1: Combined (Recommended for Testing)** ```bash -cd samples/getting_started/durabletask/07_single_agent_orchestration_hitl +cd samples/04-hosting/durabletask/07_single_agent_orchestration_hitl python sample.py ``` diff --git a/python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/client.py b/python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/client.py similarity index 100% rename from python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/client.py rename to python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/client.py diff --git a/python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/requirements.txt b/python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/requirements.txt similarity index 100% rename from python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/requirements.txt rename to python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/requirements.txt diff --git a/python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/sample.py b/python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/sample.py similarity index 100% rename from python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/sample.py rename to python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/sample.py diff --git a/python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/worker.py b/python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/worker.py similarity index 100% rename from python/samples/getting_started/durabletask/07_single_agent_orchestration_hitl/worker.py rename to python/samples/04-hosting/durabletask/07_single_agent_orchestration_hitl/worker.py diff --git a/python/samples/getting_started/durabletask/README.md b/python/samples/04-hosting/durabletask/README.md similarity index 99% rename from python/samples/getting_started/durabletask/README.md rename to python/samples/04-hosting/durabletask/README.md index 8700380a14..fc38a1f19e 100644 --- a/python/samples/getting_started/durabletask/README.md +++ b/python/samples/04-hosting/durabletask/README.md @@ -106,7 +106,7 @@ $env:AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="your-deployment-name" Navigate to the sample directory and install dependencies. For example: ```bash -cd samples/getting_started/durabletask/01_single_agent +cd samples/04-hosting/durabletask/01_single_agent pip install -r requirements.txt ``` diff --git a/python/samples/demos/chatkit-integration/.gitignore b/python/samples/05-end-to-end/chatkit-integration/.gitignore similarity index 100% rename from python/samples/demos/chatkit-integration/.gitignore rename to python/samples/05-end-to-end/chatkit-integration/.gitignore diff --git a/python/samples/demos/chatkit-integration/README.md b/python/samples/05-end-to-end/chatkit-integration/README.md similarity index 99% rename from python/samples/demos/chatkit-integration/README.md rename to python/samples/05-end-to-end/chatkit-integration/README.md index d688eb3a6c..692145196e 100644 --- a/python/samples/demos/chatkit-integration/README.md +++ b/python/samples/05-end-to-end/chatkit-integration/README.md @@ -168,7 +168,7 @@ For **production deployment**: 1. **Install Python packages:** ```bash -cd python/samples/demos/chatkit-integration +cd python/samples/05-end-to-end/chatkit-integration pip install agent-framework-chatkit fastapi uvicorn azure-identity ``` diff --git a/python/samples/getting_started/workflows/declarative/deep_research/__init__.py b/python/samples/05-end-to-end/chatkit-integration/__init__.py similarity index 100% rename from python/samples/getting_started/workflows/declarative/deep_research/__init__.py rename to python/samples/05-end-to-end/chatkit-integration/__init__.py diff --git a/python/samples/demos/chatkit-integration/app.py b/python/samples/05-end-to-end/chatkit-integration/app.py similarity index 99% rename from python/samples/demos/chatkit-integration/app.py rename to python/samples/05-end-to-end/chatkit-integration/app.py index 8167bb74b6..ab96a9bf26 100644 --- a/python/samples/demos/chatkit-integration/app.py +++ b/python/samples/05-end-to-end/chatkit-integration/app.py @@ -141,7 +141,7 @@ async def stream_widget( yield ThreadItemDoneEvent(type="thread.item.done", item=widget_item) -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/demos/chatkit-integration/attachment_store.py b/python/samples/05-end-to-end/chatkit-integration/attachment_store.py similarity index 100% rename from python/samples/demos/chatkit-integration/attachment_store.py rename to python/samples/05-end-to-end/chatkit-integration/attachment_store.py diff --git a/python/samples/demos/chatkit-integration/frontend/index.html b/python/samples/05-end-to-end/chatkit-integration/frontend/index.html similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/index.html rename to python/samples/05-end-to-end/chatkit-integration/frontend/index.html diff --git a/python/samples/demos/chatkit-integration/frontend/package-lock.json b/python/samples/05-end-to-end/chatkit-integration/frontend/package-lock.json similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/package-lock.json rename to python/samples/05-end-to-end/chatkit-integration/frontend/package-lock.json diff --git a/python/samples/demos/chatkit-integration/frontend/package.json b/python/samples/05-end-to-end/chatkit-integration/frontend/package.json similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/package.json rename to python/samples/05-end-to-end/chatkit-integration/frontend/package.json diff --git a/python/samples/demos/chatkit-integration/frontend/src/App.tsx b/python/samples/05-end-to-end/chatkit-integration/frontend/src/App.tsx similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/src/App.tsx rename to python/samples/05-end-to-end/chatkit-integration/frontend/src/App.tsx diff --git a/python/samples/demos/chatkit-integration/frontend/src/main.tsx b/python/samples/05-end-to-end/chatkit-integration/frontend/src/main.tsx similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/src/main.tsx rename to python/samples/05-end-to-end/chatkit-integration/frontend/src/main.tsx diff --git a/python/samples/demos/chatkit-integration/frontend/src/vite-env.d.ts b/python/samples/05-end-to-end/chatkit-integration/frontend/src/vite-env.d.ts similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/src/vite-env.d.ts rename to python/samples/05-end-to-end/chatkit-integration/frontend/src/vite-env.d.ts diff --git a/python/samples/demos/chatkit-integration/frontend/tsconfig.json b/python/samples/05-end-to-end/chatkit-integration/frontend/tsconfig.json similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/tsconfig.json rename to python/samples/05-end-to-end/chatkit-integration/frontend/tsconfig.json diff --git a/python/samples/demos/chatkit-integration/frontend/tsconfig.node.json b/python/samples/05-end-to-end/chatkit-integration/frontend/tsconfig.node.json similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/tsconfig.node.json rename to python/samples/05-end-to-end/chatkit-integration/frontend/tsconfig.node.json diff --git a/python/samples/demos/chatkit-integration/frontend/vite.config.ts b/python/samples/05-end-to-end/chatkit-integration/frontend/vite.config.ts similarity index 100% rename from python/samples/demos/chatkit-integration/frontend/vite.config.ts rename to python/samples/05-end-to-end/chatkit-integration/frontend/vite.config.ts diff --git a/python/samples/demos/chatkit-integration/store.py b/python/samples/05-end-to-end/chatkit-integration/store.py similarity index 100% rename from python/samples/demos/chatkit-integration/store.py rename to python/samples/05-end-to-end/chatkit-integration/store.py diff --git a/python/samples/demos/chatkit-integration/weather_widget.py b/python/samples/05-end-to-end/chatkit-integration/weather_widget.py similarity index 100% rename from python/samples/demos/chatkit-integration/weather_widget.py rename to python/samples/05-end-to-end/chatkit-integration/weather_widget.py diff --git a/python/samples/getting_started/evaluation/red_teaming/.env.example b/python/samples/05-end-to-end/evaluation/red_teaming/.env.example similarity index 100% rename from python/samples/getting_started/evaluation/red_teaming/.env.example rename to python/samples/05-end-to-end/evaluation/red_teaming/.env.example diff --git a/python/samples/getting_started/evaluation/red_teaming/README.md b/python/samples/05-end-to-end/evaluation/red_teaming/README.md similarity index 100% rename from python/samples/getting_started/evaluation/red_teaming/README.md rename to python/samples/05-end-to-end/evaluation/red_teaming/README.md diff --git a/python/samples/getting_started/evaluation/red_teaming/red_team_agent_sample.py b/python/samples/05-end-to-end/evaluation/red_teaming/red_team_agent_sample.py similarity index 100% rename from python/samples/getting_started/evaluation/red_teaming/red_team_agent_sample.py rename to python/samples/05-end-to-end/evaluation/red_teaming/red_team_agent_sample.py diff --git a/python/samples/getting_started/evaluation/self_reflection/.env.example b/python/samples/05-end-to-end/evaluation/self_reflection/.env.example similarity index 100% rename from python/samples/getting_started/evaluation/self_reflection/.env.example rename to python/samples/05-end-to-end/evaluation/self_reflection/.env.example diff --git a/python/samples/getting_started/evaluation/self_reflection/README.md b/python/samples/05-end-to-end/evaluation/self_reflection/README.md similarity index 100% rename from python/samples/getting_started/evaluation/self_reflection/README.md rename to python/samples/05-end-to-end/evaluation/self_reflection/README.md diff --git a/python/samples/getting_started/evaluation/self_reflection/resources/suboptimal_groundedness_prompts.jsonl b/python/samples/05-end-to-end/evaluation/self_reflection/resources/suboptimal_groundedness_prompts.jsonl similarity index 100% rename from python/samples/getting_started/evaluation/self_reflection/resources/suboptimal_groundedness_prompts.jsonl rename to python/samples/05-end-to-end/evaluation/self_reflection/resources/suboptimal_groundedness_prompts.jsonl diff --git a/python/samples/getting_started/evaluation/self_reflection/self_reflection.py b/python/samples/05-end-to-end/evaluation/self_reflection/self_reflection.py similarity index 100% rename from python/samples/getting_started/evaluation/self_reflection/self_reflection.py rename to python/samples/05-end-to-end/evaluation/self_reflection/self_reflection.py diff --git a/python/samples/demos/hosted_agents/agent_with_hosted_mcp/Dockerfile b/python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/Dockerfile similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_hosted_mcp/Dockerfile rename to python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/Dockerfile diff --git a/python/samples/demos/hosted_agents/agent_with_hosted_mcp/agent.yaml b/python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/agent.yaml similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_hosted_mcp/agent.yaml rename to python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/agent.yaml diff --git a/python/samples/demos/hosted_agents/agent_with_hosted_mcp/main.py b/python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/main.py similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_hosted_mcp/main.py rename to python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/main.py diff --git a/python/samples/demos/hosted_agents/agent_with_hosted_mcp/requirements.txt b/python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/requirements.txt similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_hosted_mcp/requirements.txt rename to python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/requirements.txt diff --git a/python/samples/demos/hosted_agents/agent_with_text_search_rag/Dockerfile b/python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/Dockerfile similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_text_search_rag/Dockerfile rename to python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/Dockerfile diff --git a/python/samples/demos/hosted_agents/agent_with_text_search_rag/agent.yaml b/python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/agent.yaml similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_text_search_rag/agent.yaml rename to python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/agent.yaml diff --git a/python/samples/demos/hosted_agents/agent_with_text_search_rag/main.py b/python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/main.py similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_text_search_rag/main.py rename to python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/main.py diff --git a/python/samples/demos/hosted_agents/agent_with_text_search_rag/requirements.txt b/python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/requirements.txt similarity index 100% rename from python/samples/demos/hosted_agents/agent_with_text_search_rag/requirements.txt rename to python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/requirements.txt diff --git a/python/samples/demos/hosted_agents/agents_in_workflow/Dockerfile b/python/samples/05-end-to-end/hosted_agents/agents_in_workflow/Dockerfile similarity index 100% rename from python/samples/demos/hosted_agents/agents_in_workflow/Dockerfile rename to python/samples/05-end-to-end/hosted_agents/agents_in_workflow/Dockerfile diff --git a/python/samples/demos/hosted_agents/agents_in_workflow/agent.yaml b/python/samples/05-end-to-end/hosted_agents/agents_in_workflow/agent.yaml similarity index 100% rename from python/samples/demos/hosted_agents/agents_in_workflow/agent.yaml rename to python/samples/05-end-to-end/hosted_agents/agents_in_workflow/agent.yaml diff --git a/python/samples/demos/hosted_agents/agents_in_workflow/main.py b/python/samples/05-end-to-end/hosted_agents/agents_in_workflow/main.py similarity index 100% rename from python/samples/demos/hosted_agents/agents_in_workflow/main.py rename to python/samples/05-end-to-end/hosted_agents/agents_in_workflow/main.py diff --git a/python/samples/demos/hosted_agents/agents_in_workflow/requirements.txt b/python/samples/05-end-to-end/hosted_agents/agents_in_workflow/requirements.txt similarity index 100% rename from python/samples/demos/hosted_agents/agents_in_workflow/requirements.txt rename to python/samples/05-end-to-end/hosted_agents/agents_in_workflow/requirements.txt diff --git a/python/samples/demos/m365-agent/.env.example b/python/samples/05-end-to-end/m365-agent/.env.example similarity index 100% rename from python/samples/demos/m365-agent/.env.example rename to python/samples/05-end-to-end/m365-agent/.env.example diff --git a/python/samples/demos/m365-agent/README.md b/python/samples/05-end-to-end/m365-agent/README.md similarity index 100% rename from python/samples/demos/m365-agent/README.md rename to python/samples/05-end-to-end/m365-agent/README.md diff --git a/python/samples/demos/m365-agent/m365_agent_demo/app.py b/python/samples/05-end-to-end/m365-agent/m365_agent_demo/app.py similarity index 97% rename from python/samples/demos/m365-agent/m365_agent_demo/app.py rename to python/samples/05-end-to-end/m365-agent/m365_agent_demo/app.py index d4c6460652..81e28936bc 100644 --- a/python/samples/demos/m365-agent/m365_agent_demo/app.py +++ b/python/samples/05-end-to-end/m365-agent/m365_agent_demo/app.py @@ -79,7 +79,7 @@ def load_app_config() -> AppConfig: return AppConfig(use_anonymous_mode=use_anonymous_mode, port=port, agents_sdk_config=agents_sdk_config) -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. +# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather( location: Annotated[str, Field(description="The location to get the weather for.")], diff --git a/python/samples/getting_started/purview_agent/README.md b/python/samples/05-end-to-end/purview_agent/README.md similarity index 99% rename from python/samples/getting_started/purview_agent/README.md rename to python/samples/05-end-to-end/purview_agent/README.md index 175839e9d3..3d13478616 100644 --- a/python/samples/getting_started/purview_agent/README.md +++ b/python/samples/05-end-to-end/purview_agent/README.md @@ -54,7 +54,7 @@ Certificate steps (summary): create / register entra app, generate certificate, From repo root: ```powershell -cd python/samples/getting_started/purview_agent +cd python/samples/05-end-to-end/purview_agent python sample_purview_agent.py ``` diff --git a/python/samples/getting_started/purview_agent/sample_purview_agent.py b/python/samples/05-end-to-end/purview_agent/sample_purview_agent.py similarity index 100% rename from python/samples/getting_started/purview_agent/sample_purview_agent.py rename to python/samples/05-end-to-end/purview_agent/sample_purview_agent.py diff --git a/python/samples/demos/workflow_evaluation/.env.example b/python/samples/05-end-to-end/workflow_evaluation/.env.example similarity index 100% rename from python/samples/demos/workflow_evaluation/.env.example rename to python/samples/05-end-to-end/workflow_evaluation/.env.example diff --git a/python/samples/demos/workflow_evaluation/README.md b/python/samples/05-end-to-end/workflow_evaluation/README.md similarity index 100% rename from python/samples/demos/workflow_evaluation/README.md rename to python/samples/05-end-to-end/workflow_evaluation/README.md diff --git a/python/samples/demos/workflow_evaluation/_tools.py b/python/samples/05-end-to-end/workflow_evaluation/_tools.py similarity index 100% rename from python/samples/demos/workflow_evaluation/_tools.py rename to python/samples/05-end-to-end/workflow_evaluation/_tools.py diff --git a/python/samples/demos/workflow_evaluation/create_workflow.py b/python/samples/05-end-to-end/workflow_evaluation/create_workflow.py similarity index 100% rename from python/samples/demos/workflow_evaluation/create_workflow.py rename to python/samples/05-end-to-end/workflow_evaluation/create_workflow.py diff --git a/python/samples/demos/workflow_evaluation/run_evaluation.py b/python/samples/05-end-to-end/workflow_evaluation/run_evaluation.py similarity index 100% rename from python/samples/demos/workflow_evaluation/run_evaluation.py rename to python/samples/05-end-to-end/workflow_evaluation/run_evaluation.py diff --git a/python/samples/AGENTS.md b/python/samples/AGENTS.md new file mode 100644 index 0000000000..09674da7d9 --- /dev/null +++ b/python/samples/AGENTS.md @@ -0,0 +1,116 @@ +# Samples Structure & Design Choices β€” Python + +> This file documents the structure and conventions of the Python samples so that +> agents (AI or human) can maintain them without rediscovering decisions. + +## Directory layout + +``` +python/samples/ +β”œβ”€β”€ 01-get-started/ # Progressive tutorial (steps 01–06) +β”œβ”€β”€ 02-agents/ # Deep-dive concept samples +β”‚ β”œβ”€β”€ tools/ # Tool patterns (function, approval, schema, etc.) +β”‚ β”œβ”€β”€ middleware/ # One file per middleware concept +β”‚ β”œβ”€β”€ conversations/ # Thread, storage, suspend/resume +β”‚ β”œβ”€β”€ providers/ # One sub-folder per provider (azure_ai/, openai/, etc.) +β”‚ β”œβ”€β”€ context_providers/ # Memory & context injection +β”‚ β”œβ”€β”€ orchestrations/ # Multi-agent orchestration patterns +β”‚ β”œβ”€β”€ observability/ # Tracing, telemetry +β”‚ β”œβ”€β”€ declarative/ # Declarative agent definitions +β”‚ β”œβ”€β”€ chat_client/ # Raw chat client usage +β”‚ β”œβ”€β”€ mcp/ # MCP server/client patterns +β”‚ β”œβ”€β”€ multimodal_input/ # Image, audio inputs +β”‚ └── devui/ # DevUI agent/workflow samples +β”œβ”€β”€ 03-workflows/ # Workflow samples (preserved from upstream) +β”‚ β”œβ”€β”€ _start-here/ # Introductory workflow samples +β”‚ β”œβ”€β”€ agents/ # Agents in workflows +β”‚ β”œβ”€β”€ checkpoint/ # Checkpointing & resume +β”‚ β”œβ”€β”€ composition/ # Sub-workflows +β”‚ β”œβ”€β”€ control-flow/ # Edges, conditions, loops +β”‚ β”œβ”€β”€ declarative/ # YAML-based workflows +β”‚ β”œβ”€β”€ human-in-the-loop/ # HITL patterns +β”‚ β”œβ”€β”€ observability/ # Workflow telemetry +β”‚ β”œβ”€β”€ parallelism/ # Fan-out, map-reduce +β”‚ β”œβ”€β”€ state-management/ # State isolation, kwargs +β”‚ β”œβ”€β”€ tool-approval/ # Tool approval in workflows +β”‚ └── visualization/ # Workflow visualization +β”œβ”€β”€ 04-hosting/ # Deployment & hosting +β”‚ β”œβ”€β”€ a2a/ # Agent-to-Agent protocol +β”‚ β”œβ”€β”€ azure-functions/ # Azure Functions samples +β”‚ └── durabletask/ # Durable task framework +β”œβ”€β”€ 05-end-to-end/ # Complete applications +β”‚ β”œβ”€β”€ chatkit-integration/ +β”‚ β”œβ”€β”€ evaluation/ +β”‚ β”œβ”€β”€ hosted_agents/ +β”‚ β”œβ”€β”€ m365-agent/ +β”‚ β”œβ”€β”€ purview_agent/ +β”‚ └── workflow_evaluation/ +β”œβ”€β”€ autogen-migration/ # Migration guides (do not restructure) +β”œβ”€β”€ semantic-kernel-migration/ +└── _to_delete/ # Old samples awaiting review +``` + +## Design principles + +1. **Progressive complexity**: Sections 01β†’05 build from "hello world" to + production. Within 01-get-started, files are numbered 01–06 and each step + adds exactly one concept. + +2. **One concept per file** in 01-get-started and flat files in 02-agents/. + +3. **Workflows preserved**: 03-workflows/ keeps the upstream folder names + and file names intact. Do not rename or restructure workflow samples. + +4. **Single-file for 01-03**: Only 04-hosting and 05-end-to-end use multi-file + projects with their own README. + +## Default provider + +All canonical samples (01-get-started) use **Azure OpenAI Responses** via `AzureOpenAIResponsesClient` +with an Azure AI Foundry project endpoint: + +```python +import os +from agent_framework.azure import AzureOpenAIResponsesClient +from azure.identity import AzureCliCredential + +credential = AzureCliCredential() +client = AzureOpenAIResponsesClient( + project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"], + credential=credential, +) +agent = client.as_agent(name="...", instructions="...") +``` + +Environment variables: +- `AZURE_AI_PROJECT_ENDPOINT` β€” Your Azure AI Foundry project endpoint +- `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME` β€” Model deployment name (e.g. gpt-4o) + +For authentication, run `az login` before running samples. + +## Snippet tags for docs integration + +Samples embed named snippet regions for future `:::code` integration: + +```python +# +code here +# +``` + +## Package install + +```bash +pip install agent-framework --pre +``` + +The `--pre` flag is needed during preview. `openai` is a core dependency. + +## Current API notes + +- `Agent` class renamed from `ChatAgent` (use `from agent_framework import Agent`) +- `Message` class renamed from `ChatMessage` (use `from agent_framework import Message`) +- `call_next` in middleware takes NO arguments: `await call_next()` (not `await call_next(context)`) +- Prefer `client.as_agent(...)` over `Agent(client=client, ...)` +- Tool methods on hosted tools are now functions, not classes (e.g. `hosted_mcp_tool(...)` not `HostedMCPTool(...)`) diff --git a/python/samples/README.md b/python/samples/README.md index eb234cdc3e..328ba9aa2e 100644 --- a/python/samples/README.md +++ b/python/samples/README.md @@ -2,322 +2,45 @@ This directory contains samples demonstrating the capabilities of Microsoft Agent Framework for Python. -## Agents +## Structure -### A2A (Agent-to-Agent) - -| File | Description | -|------|-------------| -| [`getting_started/agents/a2a/agent_with_a2a.py`](./getting_started/agents/a2a/agent_with_a2a.py) | Agent2Agent (A2A) Protocol Integration Sample | - -### Anthropic - -| File | Description | -|------|-------------| -| [`getting_started/agents/anthropic/anthropic_basic.py`](./getting_started/agents/anthropic/anthropic_basic.py) | Agent with Anthropic Client | -| [`getting_started/agents/anthropic/anthropic_advanced.py`](./getting_started/agents/anthropic/anthropic_advanced.py) | Advanced sample with `thinking` and hosted tools. | - -### Azure AI (based on `azure-ai-agents` V1 package) - -| File | Description | -|------|-------------| -| [`getting_started/agents/azure_ai_agent/azure_ai_basic.py`](./getting_started/agents/azure_ai_agent/azure_ai_basic.py) | Azure AI Agent Basic Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py) | Azure AI Agent with Azure AI Search Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py) | Azure AI agent with Bing Grounding search for real-time web information | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py) | Azure AI Agent with Code Interpreter Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter_file_generation.py) | Azure AI Agent with Code Interpreter File Generation Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_existing_agent.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_existing_agent.py) | Azure AI Agent with Existing Agent Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py) | Azure AI Agent with Existing Thread Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py) | Azure AI Agent with Explicit Settings Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_file_search.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_file_search.py) | Azure AI agent with File Search capabilities | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py) | Azure AI Agent with Function Tools Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_hosted_mcp.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_hosted_mcp.py) | Azure AI Agent with Hosted MCP Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_local_mcp.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_local_mcp.py) | Azure AI Agent with Local MCP Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py) | Azure AI Agent with Multiple Tools Example | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py) | Azure AI agent with OpenAPI tools | -| [`getting_started/agents/azure_ai_agent/azure_ai_with_thread.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_thread.py) | Azure AI Agent with Thread Management Example | - -### Azure AI (based on `azure-ai-projects` V2 package) - -| File | Description | -|------|-------------| -| [`getting_started/agents/azure_ai/azure_ai_basic.py`](./getting_started/agents/azure_ai/azure_ai_basic.py) | Azure AI Agent Basic Example | -| [`getting_started/agents/azure_ai/azure_ai_use_latest_version.py`](./getting_started/agents/azure_ai/azure_ai_use_latest_version.py) | Azure AI Agent latest version reuse example | -| [`getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py`](./getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py) | Azure AI Agent with Azure AI Search Example | -| [`getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py`](./getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py) | Azure AI Agent with Bing Grounding Example | -| [`getting_started/agents/azure_ai/azure_ai_with_bing_custom_search.py`](./getting_started/agents/azure_ai/azure_ai_with_bing_custom_search.py) | Azure AI Agent with Bing Custom Search Example | -| [`getting_started/agents/azure_ai/azure_ai_with_browser_automation.py`](./getting_started/agents/azure_ai/azure_ai_with_browser_automation.py) | Azure AI Agent with Browser Automation Example | -| [`getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py`](./getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py) | Azure AI Agent with Code Interpreter Example | -| [`getting_started/agents/azure_ai/azure_ai_with_code_interpreter_file_generation.py`](./getting_started/agents/azure_ai/azure_ai_with_code_interpreter_file_generation.py) | Azure AI Agent with Code Interpreter File Generation Example | -| [`getting_started/agents/azure_ai/azure_ai_with_existing_agent.py`](./getting_started/agents/azure_ai/azure_ai_with_existing_agent.py) | Azure AI Agent with Existing Agent Example | -| [`getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py`](./getting_started/agents/azure_ai/azure_ai_with_existing_conversation.py) | Azure AI Agent with Existing Conversation Example | -| [`getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py`](./getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py) | Azure AI Agent with Explicit Settings Example | -| [`getting_started/agents/azure_ai/azure_ai_with_file_search.py`](./getting_started/agents/azure_ai/azure_ai_with_file_search.py) | Azure AI Agent with File Search Example | -| [`getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py`](./getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py) | Azure AI Agent with Hosted MCP Example | -| [`getting_started/agents/azure_ai/azure_ai_with_response_format.py`](./getting_started/agents/azure_ai/azure_ai_with_response_format.py) | Azure AI Agent with Structured Output Example | -| [`getting_started/agents/azure_ai/azure_ai_with_thread.py`](./getting_started/agents/azure_ai/azure_ai_with_thread.py) | Azure AI Agent with Thread Management Example | -| [`getting_started/agents/azure_ai/azure_ai_with_image_generation.py`](./getting_started/agents/azure_ai/azure_ai_with_image_generation.py) | Azure AI Agent with Image Generation Example | -| [`getting_started/agents/azure_ai/azure_ai_with_microsoft_fabric.py`](./getting_started/agents/azure_ai/azure_ai_with_microsoft_fabric.py) | Azure AI Agent with Microsoft Fabric Example | -| [`getting_started/agents/azure_ai/azure_ai_with_web_search.py`](./getting_started/agents/azure_ai/azure_ai_with_web_search.py) | Azure AI Agent with Web Search Example | - -### Azure OpenAI - -| File | Description | -|------|-------------| -| [`getting_started/agents/azure_openai/azure_assistants_basic.py`](./getting_started/agents/azure_openai/azure_assistants_basic.py) | Azure OpenAI Assistants Basic Example | -| [`getting_started/agents/azure_openai/azure_assistants_with_code_interpreter.py`](./getting_started/agents/azure_openai/azure_assistants_with_code_interpreter.py) | Azure OpenAI Assistants with Code Interpreter Example | -| [`getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py`](./getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py) | Azure OpenAI Assistants with Existing Assistant Example | -| [`getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py`](./getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py) | Azure OpenAI Assistants with Explicit Settings Example | -| [`getting_started/agents/azure_openai/azure_assistants_with_function_tools.py`](./getting_started/agents/azure_openai/azure_assistants_with_function_tools.py) | Azure OpenAI Assistants with Function Tools Example | -| [`getting_started/agents/azure_openai/azure_assistants_with_thread.py`](./getting_started/agents/azure_openai/azure_assistants_with_thread.py) | Azure OpenAI Assistants with Thread Management Example | -| [`getting_started/agents/azure_openai/azure_chat_client_basic.py`](./getting_started/agents/azure_openai/azure_chat_client_basic.py) | Azure OpenAI Chat Client Basic Example | -| [`getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py`](./getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py) | Azure OpenAI Chat Client with Explicit Settings Example | -| [`getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py`](./getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py) | Azure OpenAI Chat Client with Function Tools Example | -| [`getting_started/agents/azure_openai/azure_chat_client_with_thread.py`](./getting_started/agents/azure_openai/azure_chat_client_with_thread.py) | Azure OpenAI Chat Client with Thread Management Example | -| [`getting_started/agents/azure_openai/azure_responses_client_basic.py`](./getting_started/agents/azure_openai/azure_responses_client_basic.py) | Azure OpenAI Responses Client Basic Example | -| [`getting_started/agents/azure_openai/azure_responses_client_image_analysis.py`](./getting_started/agents/azure_openai/azure_responses_client_image_analysis.py) | Azure OpenAI Responses Client with Image Analysis Example | -| [`getting_started/agents/azure_openai/azure_responses_client_with_code_interpreter.py`](./getting_started/agents/azure_openai/azure_responses_client_with_code_interpreter.py) | Azure OpenAI Responses Client with Code Interpreter Example | -| [`getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py`](./getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py) | Azure OpenAI Responses Client with Explicit Settings Example | -| [`getting_started/agents/azure_openai/azure_responses_client_with_foundry.py`](./getting_started/agents/azure_openai/azure_responses_client_with_foundry.py) | Azure OpenAI Responses Client with Foundry Project Example | -| [`getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py`](./getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py) | Azure OpenAI Responses Client with Function Tools Example | -| [`getting_started/agents/azure_openai/azure_responses_client_with_hosted_mcp.py`](./getting_started/agents/azure_openai/azure_responses_client_with_hosted_mcp.py) | Azure OpenAI Responses Client with Hosted Model Context Protocol (MCP) Example | -| [`getting_started/agents/azure_openai/azure_responses_client_with_local_mcp.py`](./getting_started/agents/azure_openai/azure_responses_client_with_local_mcp.py) | Azure OpenAI Responses Client with local Model Context Protocol (MCP) Example | -| [`getting_started/agents/azure_openai/azure_responses_client_with_thread.py`](./getting_started/agents/azure_openai/azure_responses_client_with_thread.py) | Azure OpenAI Responses Client with Thread Management Example | - -### Copilot Studio - -| File | Description | -|------|-------------| -| [`getting_started/agents/copilotstudio/copilotstudio_basic.py`](./getting_started/agents/copilotstudio/copilotstudio_basic.py) | Copilot Studio Agent Basic Example | -| [`getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py`](./getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py) | Copilot Studio Agent with Explicit Settings Example | - -### Custom - -| File | Description | -|------|-------------| -| [`getting_started/agents/custom/custom_agent.py`](./getting_started/agents/custom/custom_agent.py) | Custom Agent Implementation Example | -| [`getting_started/chat_client/custom_chat_client.py`](./getting_started/chat_client/custom_chat_client.py) | Custom Chat Client Implementation Example | - -### Ollama - -The recommended way to use Ollama is via the native `OllamaChatClient` from the `agent-framework-ollama` package. - -| File | Description | -|------|-------------| -| [`getting_started/agents/ollama/ollama_agent_basic.py`](./getting_started/agents/ollama/ollama_agent_basic.py) | Basic Ollama Agent with native Ollama Chat Client | -| [`getting_started/agents/ollama/ollama_agent_reasoning.py`](./getting_started/agents/ollama/ollama_agent_reasoning.py) | Ollama Agent with reasoning capabilities | -| [`getting_started/agents/ollama/ollama_chat_client.py`](./getting_started/agents/ollama/ollama_chat_client.py) | Direct usage of Ollama Chat Client | -| [`getting_started/agents/ollama/ollama_chat_multimodal.py`](./getting_started/agents/ollama/ollama_chat_multimodal.py) | Ollama Chat Client with multimodal (image) input | -| [`getting_started/agents/ollama/ollama_with_openai_chat_client.py`](./getting_started/agents/ollama/ollama_with_openai_chat_client.py) | Alternative: Ollama via OpenAI Chat Client | - -### OpenAI - -| File | Description | -|------|-------------| -| [`getting_started/agents/openai/openai_assistants_basic.py`](./getting_started/agents/openai/openai_assistants_basic.py) | OpenAI Assistants Basic Example | -| [`getting_started/agents/openai/openai_assistants_with_code_interpreter.py`](./getting_started/agents/openai/openai_assistants_with_code_interpreter.py) | OpenAI Assistants with Code Interpreter Example | -| [`getting_started/agents/openai/openai_assistants_with_existing_assistant.py`](./getting_started/agents/openai/openai_assistants_with_existing_assistant.py) | OpenAI Assistants with Existing Assistant Example | -| [`getting_started/agents/openai/openai_assistants_with_explicit_settings.py`](./getting_started/agents/openai/openai_assistants_with_explicit_settings.py) | OpenAI Assistants with Explicit Settings Example | -| [`getting_started/agents/openai/openai_assistants_with_file_search.py`](./getting_started/agents/openai/openai_assistants_with_file_search.py) | OpenAI Assistants with File Search Example | -| [`getting_started/agents/openai/openai_assistants_with_function_tools.py`](./getting_started/agents/openai/openai_assistants_with_function_tools.py) | OpenAI Assistants with Function Tools Example | -| [`getting_started/agents/openai/openai_assistants_with_thread.py`](./getting_started/agents/openai/openai_assistants_with_thread.py) | OpenAI Assistants with Thread Management Example | -| [`getting_started/agents/openai/openai_chat_client_basic.py`](./getting_started/agents/openai/openai_chat_client_basic.py) | OpenAI Chat Client Basic Example | -| [`getting_started/agents/openai/openai_chat_client_with_explicit_settings.py`](./getting_started/agents/openai/openai_chat_client_with_explicit_settings.py) | OpenAI Chat Client with Explicit Settings Example | -| [`getting_started/agents/openai/openai_chat_client_with_function_tools.py`](./getting_started/agents/openai/openai_chat_client_with_function_tools.py) | OpenAI Chat Client with Function Tools Example | -| [`getting_started/agents/openai/openai_chat_client_with_local_mcp.py`](./getting_started/agents/openai/openai_chat_client_with_local_mcp.py) | OpenAI Chat Client with Local MCP Example | -| [`getting_started/agents/openai/openai_chat_client_with_thread.py`](./getting_started/agents/openai/openai_chat_client_with_thread.py) | OpenAI Chat Client with Thread Management Example | -| [`getting_started/agents/openai/openai_chat_client_with_web_search.py`](./getting_started/agents/openai/openai_chat_client_with_web_search.py) | OpenAI Chat Client with Web Search Example | -| [`getting_started/agents/openai/openai_chat_client_with_runtime_json_schema.py`](./getting_started/agents/openai/openai_chat_client_with_runtime_json_schema.py) | OpenAI Chat Client with runtime JSON Schema for structured output without a Pydantic model | -| [`getting_started/agents/openai/openai_responses_client_basic.py`](./getting_started/agents/openai/openai_responses_client_basic.py) | OpenAI Responses Client Basic Example | -| [`getting_started/agents/openai/openai_responses_client_image_analysis.py`](./getting_started/agents/openai/openai_responses_client_image_analysis.py) | OpenAI Responses Client Image Analysis Example | -| [`getting_started/agents/openai/openai_responses_client_image_generation.py`](./getting_started/agents/openai/openai_responses_client_image_generation.py) | OpenAI Responses Client Image Generation Example | -| [`getting_started/agents/openai/openai_responses_client_reasoning.py`](./getting_started/agents/openai/openai_responses_client_reasoning.py) | OpenAI Responses Client Reasoning Example | -| [`getting_started/agents/openai/openai_responses_client_with_code_interpreter.py`](./getting_started/agents/openai/openai_responses_client_with_code_interpreter.py) | OpenAI Responses Client with Code Interpreter Example | -| [`getting_started/agents/openai/openai_responses_client_with_explicit_settings.py`](./getting_started/agents/openai/openai_responses_client_with_explicit_settings.py) | OpenAI Responses Client with Explicit Settings Example | -| [`getting_started/agents/openai/openai_responses_client_with_file_search.py`](./getting_started/agents/openai/openai_responses_client_with_file_search.py) | OpenAI Responses Client with File Search Example | -| [`getting_started/agents/openai/openai_responses_client_with_function_tools.py`](./getting_started/agents/openai/openai_responses_client_with_function_tools.py) | OpenAI Responses Client with Function Tools Example | -| [`getting_started/agents/openai/openai_responses_client_with_hosted_mcp.py`](./getting_started/agents/openai/openai_responses_client_with_hosted_mcp.py) | OpenAI Responses Client with Hosted MCP Example | -| [`getting_started/agents/openai/openai_responses_client_with_local_mcp.py`](./getting_started/agents/openai/openai_responses_client_with_local_mcp.py) | OpenAI Responses Client with Local MCP Example | -| [`getting_started/agents/openai/openai_responses_client_with_structured_output.py`](./getting_started/agents/openai/openai_responses_client_with_structured_output.py) | OpenAI Responses Client with Structured Output Example | -| [`getting_started/agents/openai/openai_responses_client_with_thread.py`](./getting_started/agents/openai/openai_responses_client_with_thread.py) | OpenAI Responses Client with Thread Management Example | -| [`getting_started/agents/openai/openai_responses_client_with_web_search.py`](./getting_started/agents/openai/openai_responses_client_with_web_search.py) | OpenAI Responses Client with Web Search Example | - -## Chat Client - -| File | Description | -|------|-------------| -| [`getting_started/chat_client/azure_ai_chat_client.py`](./getting_started/chat_client/azure_ai_chat_client.py) | Azure AI Chat Client Direct Usage Example | -| [`getting_started/chat_client/azure_assistants_client.py`](./getting_started/chat_client/azure_assistants_client.py) | Azure OpenAI Assistants Client Direct Usage Example | -| [`getting_started/chat_client/azure_chat_client.py`](./getting_started/chat_client/azure_chat_client.py) | Azure Chat Client Direct Usage Example | -| [`getting_started/chat_client/azure_responses_client.py`](./getting_started/chat_client/azure_responses_client.py) | Azure OpenAI Responses Client Direct Usage Example | -| [`getting_started/chat_client/chat_response_cancellation.py`](./getting_started/chat_client/chat_response_cancellation.py) | Chat Response Cancellation Example | -| [`getting_started/chat_client/openai_assistants_client.py`](./getting_started/chat_client/openai_assistants_client.py) | OpenAI Assistants Client Direct Usage Example | -| [`getting_started/chat_client/openai_chat_client.py`](./getting_started/chat_client/openai_chat_client.py) | OpenAI Chat Client Direct Usage Example | -| [`getting_started/chat_client/openai_responses_client.py`](./getting_started/chat_client/openai_responses_client.py) | OpenAI Responses Client Direct Usage Example | - - -## Context Providers - -### Mem0 - -| File | Description | -|------|-------------| -| [`getting_started/context_providers/mem0/mem0_basic.py`](./getting_started/context_providers/mem0/mem0_basic.py) | Basic Mem0 integration example | -| [`getting_started/context_providers/mem0/mem0_oss.py`](./getting_started/context_providers/mem0/mem0_oss.py) | Mem0 OSS (Open Source) integration example | -| [`getting_started/context_providers/mem0/mem0_threads.py`](./getting_started/context_providers/mem0/mem0_threads.py) | Mem0 with thread management example | - -### Redis - -| File | Description | -|------|-------------| -| [`getting_started/context_providers/redis/redis_basics.py`](./getting_started/context_providers/redis/redis_basics.py) | Basic Redis provider example | -| [`getting_started/context_providers/redis/redis_conversation.py`](./getting_started/context_providers/redis/redis_conversation.py) | Redis conversation context management example | -| [`getting_started/context_providers/redis/redis_threads.py`](./getting_started/context_providers/redis/redis_threads.py) | Redis with thread management example | - -### Other - -| File | Description | -|------|-------------| -| [`getting_started/context_providers/simple_context_provider.py`](./getting_started/context_providers/simple_context_provider.py) | Simple context provider implementation example | -| [`getting_started/context_providers/aggregate_context_provider.py`](./getting_started/context_providers/aggregate_context_provider.py) | Shows how to combine multiple context providers using an AggregateContextProvider | - -## Declarative - -| File | Description | -|------|-------------| -| [`getting_started/declarative/azure_openai_responses_agent.py`](./getting_started/declarative/azure_openai_responses_agent.py) | Basic agent using Azure OpenAI with structured responses | -| [`getting_started/declarative/get_weather_agent.py`](./getting_started/declarative/get_weather_agent.py) | Agent with custom function tools using declarative bindings | -| [`getting_started/declarative/inline_yaml.py`](./getting_started/declarative/inline_yaml.py) | Agent created from inline YAML string | -| [`getting_started/declarative/mcp_tool_yaml.py`](./getting_started/declarative/mcp_tool_yaml.py) | MCP tool configuration with API key and Azure Foundry connection auth | -| [`getting_started/declarative/microsoft_learn_agent.py`](./getting_started/declarative/microsoft_learn_agent.py) | Agent with MCP server integration for Microsoft Learn documentation | -| [`getting_started/declarative/openai_responses_agent.py`](./getting_started/declarative/openai_responses_agent.py) | Basic agent using OpenAI directly | - -## DevUI - -| File | Description | -|------|-------------| -| [`getting_started/devui/fanout_workflow/workflow.py`](./getting_started/devui/fanout_workflow/workflow.py) | Complex fan-out/fan-in workflow example | -| [`getting_started/devui/foundry_agent/agent.py`](./getting_started/devui/foundry_agent/agent.py) | Azure AI Foundry agent example | -| [`getting_started/devui/in_memory_mode.py`](./getting_started/devui/in_memory_mode.py) | In-memory mode example for DevUI | -| [`getting_started/devui/spam_workflow/workflow.py`](./getting_started/devui/spam_workflow/workflow.py) | Spam detection workflow example | -| [`getting_started/devui/weather_agent_azure/agent.py`](./getting_started/devui/weather_agent_azure/agent.py) | Weather agent using Azure OpenAI example | -| [`getting_started/devui/workflow_agents/workflow.py`](./getting_started/devui/workflow_agents/workflow.py) | Workflow with multiple agents example | - -## Evaluation - -| File | Description | -|------|-------------| -| [`getting_started/evaluation/red_teaming/red_team_agent_sample.py`](./getting_started/evaluation/red_teaming/red_team_agent_sample.py) | Red team agent evaluation sample for Azure AI Foundry | -| [`getting_started/evaluation/self_reflection/self_reflection.py`](./getting_started/evaluation/self_reflection/self_reflection.py) | LLM self-reflection with AI Foundry graders example | -| [`demos/workflow_evaluation/run_evaluation.py`](./demos/workflow_evaluation/run_evaluation.py) | Multi-agent workflow evaluation demo with travel planning agents evaluated using Azure AI Foundry evaluators | - -## MCP (Model Context Protocol) - -| File | Description | -|------|-------------| -| [`getting_started/mcp/agent_as_mcp_server.py`](./getting_started/mcp/agent_as_mcp_server.py) | Agent as MCP Server Example | -| [`getting_started/mcp/mcp_api_key_auth.py`](./getting_started/mcp/mcp_api_key_auth.py) | MCP Authentication Example | - -## Middleware - -| File | Description | -|------|-------------| -| [`getting_started/middleware/agent_and_run_level_middleware.py`](./getting_started/middleware/agent_and_run_level_middleware.py) | Agent and run-level middleware example | -| [`getting_started/middleware/chat_middleware.py`](./getting_started/middleware/chat_middleware.py) | Chat middleware example | -| [`getting_started/middleware/class_based_middleware.py`](./getting_started/middleware/class_based_middleware.py) | Class-based middleware implementation example | -| [`getting_started/middleware/decorator_middleware.py`](./getting_started/middleware/decorator_middleware.py) | Decorator-based middleware example | -| [`getting_started/middleware/exception_handling_with_middleware.py`](./getting_started/middleware/exception_handling_with_middleware.py) | Exception handling with middleware example | -| [`getting_started/middleware/function_based_middleware.py`](./getting_started/middleware/function_based_middleware.py) | Function-based middleware example | -| [`getting_started/middleware/middleware_termination.py`](./getting_started/middleware/middleware_termination.py) | Middleware termination example | -| [`getting_started/middleware/override_result_with_middleware.py`](./getting_started/middleware/override_result_with_middleware.py) | Override result with middleware example | -| [`getting_started/middleware/runtime_context_delegation.py`](./getting_started/middleware/runtime_context_delegation.py) | Runtime context delegation example demonstrating how to pass API tokens, session data, and other context through hierarchical agent delegation | -| [`getting_started/middleware/shared_state_middleware.py`](./getting_started/middleware/shared_state_middleware.py) | Shared state middleware example | -| [`getting_started/middleware/thread_behavior_middleware.py`](./getting_started/middleware/thread_behavior_middleware.py) | Thread behavior middleware example demonstrating how to track conversation state across multiple agent runs | - -## Multimodal Input - -| File | Description | -|------|-------------| -| [`getting_started/multimodal_input/azure_chat_multimodal.py`](./getting_started/multimodal_input/azure_chat_multimodal.py) | Azure OpenAI Chat with multimodal (image) input example | -| [`getting_started/multimodal_input/azure_responses_multimodal.py`](./getting_started/multimodal_input/azure_responses_multimodal.py) | Azure OpenAI Responses with multimodal (image) input example | -| [`getting_started/multimodal_input/openai_chat_multimodal.py`](./getting_started/multimodal_input/openai_chat_multimodal.py) | OpenAI Chat with multimodal (image) input example | - - -## Azure Functions - -| Sample | Description | +| Folder | Description | |--------|-------------| -| [`getting_started/azure_functions/01_single_agent/`](./getting_started/azure_functions/01_single_agent/) | Host a single agent in Azure Functions with Durable Extension HTTP endpoints and per-session state. | -| [`getting_started/azure_functions/02_multi_agent/`](./getting_started/azure_functions/02_multi_agent/) | Register multiple agents in one function app with dedicated run routes and a health check endpoint. | -| [`getting_started/azure_functions/03_reliable_streaming/`](./getting_started/azure_functions/03_reliable_streaming/) | Implement reliable streaming for durable agents using Redis Streams with cursor-based resumption. | -| [`getting_started/azure_functions/04_single_agent_orchestration_chaining/`](./getting_started/azure_functions/04_single_agent_orchestration_chaining/) | Chain sequential agent executions inside a durable orchestration while preserving the shared thread context. | -| [`getting_started/azure_functions/05_multi_agent_orchestration_concurrency/`](./getting_started/azure_functions/05_multi_agent_orchestration_concurrency/) | Run two agents concurrently within a durable orchestration and combine their domain-specific outputs. | -| [`getting_started/azure_functions/06_multi_agent_orchestration_conditionals/`](./getting_started/azure_functions/06_multi_agent_orchestration_conditionals/) | Route orchestration logic based on structured agent responses for spam detection and reply drafting. | -| [`getting_started/azure_functions/07_single_agent_orchestration_hitl/`](./getting_started/azure_functions/07_single_agent_orchestration_hitl/) | Implement a human-in-the-loop approval loop that iterates on agent output inside a durable orchestration. | -| [`getting_started/azure_functions/08_mcp_server/`](./getting_started/azure_functions/08_mcp_server/) | Configure agents as both HTTP endpoints and MCP tools for flexible integration patterns. | +| [`01-get-started/`](./01-get-started/) | Progressive tutorial: hello agent β†’ hosting | +| [`02-agents/`](./02-agents/) | Deep-dive by concept: tools, middleware, providers, orchestrations | +| [`03-workflows/`](./03-workflows/) | Workflow patterns: sequential, concurrent, state, declarative | +| [`04-hosting/`](./04-hosting/) | Deployment: Azure Functions, Durable Tasks, A2A | +| [`05-end-to-end/`](./05-end-to-end/) | Full applications, evaluation, demos | -## Durable Task +## Getting Started -These samples demonstrate durable agent hosting using the Durable Task Scheduler with a worker-client architecture pattern, enabling distributed agent execution with persistent conversation state. +Start with `01-get-started/` and work through the numbered files: -| Sample | Description | -|--------|-------------| -| [`getting_started/durabletask/01_single_agent/`](./getting_started/durabletask/01_single_agent/) | Host a single conversational agent with worker-client architecture and agent state management. | -| [`getting_started/durabletask/02_multi_agent/`](./getting_started/durabletask/02_multi_agent/) | Host multiple domain-specific agents and route requests based on question topic. | -| [`getting_started/durabletask/03_single_agent_streaming/`](./getting_started/durabletask/03_single_agent_streaming/) | Implement reliable streaming using Redis Streams with cursor-based resumption for durable agents. | -| [`getting_started/durabletask/04_single_agent_orchestration_chaining/`](./getting_started/durabletask/04_single_agent_orchestration_chaining/) | Chain multiple agent invocations using durable orchestration while preserving conversation context. | -| [`getting_started/durabletask/05_multi_agent_orchestration_concurrency/`](./getting_started/durabletask/05_multi_agent_orchestration_concurrency/) | Run multiple agents concurrently within an orchestration and aggregate their responses. | -| [`getting_started/durabletask/06_multi_agent_orchestration_conditionals/`](./getting_started/durabletask/06_multi_agent_orchestration_conditionals/) | Implement conditional branching with spam detection using structured outputs and activity functions. | -| [`getting_started/durabletask/07_single_agent_orchestration_hitl/`](./getting_started/durabletask/07_single_agent_orchestration_hitl/) | Human-in-the-loop pattern with external event handling, timeouts, and iterative refinement. | +1. **[01_hello_agent.py](./01-get-started/01_hello_agent.py)** β€” Create and run your first agent +2. **[02_add_tools.py](./01-get-started/02_add_tools.py)** β€” Add function tools with `@tool` +3. **[03_multi_turn.py](./01-get-started/03_multi_turn.py)** β€” Multi-turn conversations with `AgentThread` +4. **[04_memory.py](./01-get-started/04_memory.py)** β€” Agent memory with `ContextProvider` +5. **[05_first_workflow.py](./01-get-started/05_first_workflow.py)** β€” Build a workflow with executors and edges +6. **[06_host_your_agent.py](./01-get-started/06_host_your_agent.py)** β€” Host your agent via A2A -## Observability +## Prerequisites -| File | Description | -|------|-------------| -| [`getting_started/observability/advanced_manual_setup_console_output.py`](./getting_started/observability/advanced_manual_setup_console_output.py) | Advanced manual observability setup with console output | -| [`getting_started/observability/advanced_zero_code.py`](./getting_started/observability/advanced_zero_code.py) | Zero-code observability setup example | -| [`getting_started/observability/agent_observability.py`](./getting_started/observability/agent_observability.py) | Agent observability example | -| [`getting_started/observability/agent_with_foundry_tracing.py`](./getting_started/observability/agent_with_foundry_tracing.py) | Any chat client setup with Azure Foundry Observability | -| [`getting_started/observability/azure_ai_agent_observability.py`](./getting_started/observability/azure_ai_agent_observability.py) | Azure AI agent observability example | -| [`getting_started/observability/configure_otel_providers_with_env_var.py`](./getting_started/observability/configure_otel_providers_with_env_var.py) | Setup observability using environment variables | -| [`getting_started/observability/configure_otel_providers_with_parameters.py`](./getting_started/observability/configure_otel_providers_with_parameters.py) | Setup observability using parameters | -| [`getting_started/observability/workflow_observability.py`](./getting_started/observability/workflow_observability.py) | Workflow observability example | +```bash +pip install agent-framework --pre +``` -## Threads +Set the following environment variables for the getting-started samples: -| File | Description | -|------|-------------| -| [`getting_started/threads/custom_chat_message_store_thread.py`](./getting_started/threads/custom_chat_message_store_thread.py) | Implementation of custom chat message store state | -| [`getting_started/threads/redis_chat_message_store_thread.py`](./getting_started/threads/redis_chat_message_store_thread.py) | Basic example of using Redis chat message store | -| [`getting_started/threads/suspend_resume_thread.py`](./getting_started/threads/suspend_resume_thread.py) | Demonstrates how to suspend and resume a service-managed thread | +```bash +export AZURE_AI_PROJECT_ENDPOINT="your-foundry-project-endpoint" +export AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="gpt-4o" +``` -## Tools +For Azure authentication, run `az login` before running samples. -Note: Many tool samples set `approval_mode="never_require"` to keep the examples concise. For production scenarios, -keep `approval_mode="always_require"` unless you are confident in the tool behavior and approval flow. See -`getting_started/tools/function_tool_with_approval.py` and -`getting_started/tools/function_tool_with_approval_and_threads.py`, plus the workflow approval samples in -`getting_started/workflows/tool-approval/`, for end-to-end approval handling. +## Additional Resources -| File | Description | -|------|-------------| -| [`getting_started/tools/function_tool_declaration_only.py`](./getting_started/tools/function_tool_declaration_only.py) | Function declarations without implementations for testing agent reasoning | -| [`getting_started/tools/function_tool_from_dict_with_dependency_injection.py`](./getting_started/tools/function_tool_from_dict_with_dependency_injection.py) | Creating local tools from dictionary definitions using dependency injection | -| [`getting_started/tools/function_tool_recover_from_failures.py`](./getting_started/tools/function_tool_recover_from_failures.py) | Graceful error handling when tools raise exceptions | -| [`getting_started/tools/function_tool_with_approval.py`](./getting_started/tools/function_tool_with_approval.py) | User approval workflows for function calls without threads | -| [`getting_started/tools/function_tool_with_approval_and_threads.py`](./getting_started/tools/function_tool_with_approval_and_threads.py) | Tool approval workflows using threads for conversation history management | -| [`getting_started/tools/function_tool_with_max_exceptions.py`](./getting_started/tools/function_tool_with_max_exceptions.py) | Limiting tool failure exceptions using max_invocation_exceptions | -| [`getting_started/tools/function_tool_with_max_invocations.py`](./getting_started/tools/function_tool_with_max_invocations.py) | Limiting total tool invocations using max_invocations | -| [`getting_started/tools/tool_in_class.py`](./getting_started/tools/tool_in_class.py) | Using the tool decorator with class methods for stateful tools | +- [Agent Framework Documentation](https://learn.microsoft.com/agent-framework/) +- [AGENTS.md](./AGENTS.md) β€” Structure documentation for maintainers +- [SAMPLE_GUIDELINES.md](./SAMPLE_GUIDELINES.md) β€” Coding conventions for samples -## Workflows - -View the list of Workflows samples [here](./getting_started/workflows/README.md). - -## Sample Guidelines - -For information on creating new samples, see [SAMPLE_GUIDELINES.md](./SAMPLE_GUIDELINES.md). - -## More Information - -- [Python Package Documentation](../README.md) diff --git a/python/samples/autogen-migration/single_agent/02_assistant_agent_with_tool.py b/python/samples/autogen-migration/single_agent/02_assistant_agent_with_tool.py index cb027d636c..134eb6ef59 100644 --- a/python/samples/autogen-migration/single_agent/02_assistant_agent_with_tool.py +++ b/python/samples/autogen-migration/single_agent/02_assistant_agent_with_tool.py @@ -62,7 +62,7 @@ async def run_agent_framework() -> None: from agent_framework.openai import OpenAIChatClient # Define tool with @tool decorator (automatic schema inference) - # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. + # NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py. @tool(approval_mode="never_require") def get_weather(location: str) -> str: """Get the weather for a location. diff --git a/python/samples/concepts/README.md b/python/samples/concepts/README.md deleted file mode 100644 index 8e3c0282fa..0000000000 --- a/python/samples/concepts/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Concept Samples - -This folder contains samples that dive deep into specific Agent Framework concepts. - -## Samples - -| Sample | Description | -|--------|-------------| -| [response_stream.py](response_stream.py) | Deep dive into `ResponseStream` - the streaming abstraction for AI responses. Covers the four hook types (transform hooks, cleanup hooks, finalizer, result hooks), two consumption patterns (iteration vs direct finalization), and the `wrap()` API for layering streams without double-consumption. | -| [typed_options.py](typed_options.py) | Demonstrates TypedDict-based chat options for type-safe configuration with IDE autocomplete support. | diff --git a/python/samples/concepts/tools/README.md b/python/samples/concepts/tools/README.md deleted file mode 100644 index 2af617cf4c..0000000000 --- a/python/samples/concepts/tools/README.md +++ /dev/null @@ -1,499 +0,0 @@ -# Tools and Middleware: Request Flow Architecture - -This document describes the complete request flow when using an Agent with middleware and tools, from the initial `Agent.run()` call through middleware layers, function invocation, and back to the caller. - -## Overview - -The Agent Framework uses a layered architecture with three distinct middleware/processing layers: - -1. **Agent Middleware Layer** - Wraps the entire agent execution -2. **Chat Middleware Layer** - Wraps calls to the chat client -3. **Function Middleware Layer** - Wraps individual tool/function invocations - -Each layer provides interception points where you can modify inputs, inspect outputs, or alter behavior. - -## Flow Diagram - -```mermaid -sequenceDiagram - participant User - participant Agent as Agent.run() - participant AML as AgentMiddlewareLayer - participant AMP as AgentMiddlewarePipeline - participant RawAgent as RawAgent.run() - participant CML as ChatMiddlewareLayer - participant CMP as ChatMiddlewarePipeline - participant FIL as FunctionInvocationLayer - participant Client as BaseChatClient._inner_get_response() - participant LLM as LLM Service - participant FMP as FunctionMiddlewarePipeline - participant Tool as FunctionTool.invoke() - - User->>Agent: run(messages, thread, options, middleware) - - Note over Agent,AML: Agent Middleware Layer - Agent->>AML: run() with middleware param - AML->>AML: categorize_middleware() β†’ split by type - AML->>AMP: execute(AgentContext) - - loop Agent Middleware Chain - AMP->>AMP: middleware[i].process(context, call_next) - Note right of AMP: Can modify: messages, options, thread - end - - AMP->>RawAgent: run() via final_handler - - alt Non-Streaming (stream=False) - RawAgent->>RawAgent: _prepare_run_context() [async] - Note right of RawAgent: Builds: thread_messages, chat_options, tools - RawAgent->>CML: client.get_response(stream=False) - else Streaming (stream=True) - RawAgent->>RawAgent: ResponseStream.from_awaitable() - Note right of RawAgent: Defers async prep to stream consumption - RawAgent-->>User: Returns ResponseStream immediately - Note over RawAgent,CML: Async work happens on iteration - RawAgent->>RawAgent: _prepare_run_context() [deferred] - RawAgent->>CML: client.get_response(stream=True) - end - - Note over CML,CMP: Chat Middleware Layer - CML->>CMP: execute(ChatContext) - - loop Chat Middleware Chain - CMP->>CMP: middleware[i].process(context, call_next) - Note right of CMP: Can modify: messages, options - end - - CMP->>FIL: get_response() via final_handler - - Note over FIL,Tool: Function Invocation Loop - loop Max Iterations (default: 40) - FIL->>Client: _inner_get_response(messages, options) - Client->>LLM: API Call - LLM-->>Client: Response (may include tool_calls) - Client-->>FIL: ChatResponse - - alt Response has function_calls - FIL->>FIL: _extract_function_calls() - FIL->>FIL: _try_execute_function_calls() - - Note over FIL,Tool: Function Middleware Layer - loop For each function_call - FIL->>FMP: execute(FunctionInvocationContext) - loop Function Middleware Chain - FMP->>FMP: middleware[i].process(context, call_next) - Note right of FMP: Can modify: arguments - end - FMP->>Tool: invoke(arguments) - Tool-->>FMP: result - FMP-->>FIL: Content.from_function_result() - end - - FIL->>FIL: Append tool results to messages - - alt tool_choice == "required" - Note right of FIL: Return immediately with function call + result - FIL-->>CMP: ChatResponse - else tool_choice == "auto" or other - Note right of FIL: Continue loop for text response - end - else No function_calls - FIL-->>CMP: ChatResponse - end - end - - CMP-->>CML: ChatResponse - Note right of CMP: Can observe/modify result - - CML-->>RawAgent: ChatResponse / ResponseStream - - alt Non-Streaming - RawAgent->>RawAgent: _finalize_response_and_update_thread() - else Streaming - Note right of RawAgent: .map() transforms updates - Note right of RawAgent: .with_result_hook() runs post-processing - end - - RawAgent-->>AMP: AgentResponse / ResponseStream - Note right of AMP: Can observe/modify result - AMP-->>AML: AgentResponse - AML-->>Agent: AgentResponse - Agent-->>User: AgentResponse / ResponseStream -``` - -## Layer Details - -### 1. Agent Middleware Layer (`AgentMiddlewareLayer`) - -**Entry Point:** `Agent.run(messages, thread, options, middleware)` - -**Context Object:** `AgentContext` - -| Field | Type | Description | -|-------|------|-------------| -| `agent` | `SupportsAgentRun` | The agent being invoked | -| `messages` | `list[Message]` | Input messages (mutable) | -| `thread` | `AgentThread \| None` | Conversation thread | -| `options` | `Mapping[str, Any]` | Chat options dict | -| `stream` | `bool` | Whether streaming is enabled | -| `metadata` | `dict` | Shared data between middleware | -| `result` | `AgentResponse \| None` | Set after `call_next()` is called | -| `kwargs` | `Mapping[str, Any]` | Additional run arguments | - -**Key Operations:** -1. `categorize_middleware()` separates middleware by type (agent, chat, function) -2. Chat and function middleware are forwarded to `client` -3. `AgentMiddlewarePipeline.execute()` runs the agent middleware chain -4. Final handler calls `RawAgent.run()` - -**What Can Be Modified:** -- `context.messages` - Add, remove, or modify input messages -- `context.options` - Change model parameters, temperature, etc. -- `context.thread` - Replace or modify the thread -- `context.result` - Override the final response (after `call_next()`) - -### 2. Chat Middleware Layer (`ChatMiddlewareLayer`) - -**Entry Point:** `client.get_response(messages, options)` - -**Context Object:** `ChatContext` - -| Field | Type | Description | -|-------|------|-------------| -| `client` | `SupportsChatGetResponse` | The chat client | -| `messages` | `Sequence[Message]` | Messages to send | -| `options` | `Mapping[str, Any]` | Chat options | -| `stream` | `bool` | Whether streaming | -| `metadata` | `dict` | Shared data between middleware | -| `result` | `ChatResponse \| None` | Set after `call_next()` is called | -| `kwargs` | `Mapping[str, Any]` | Additional arguments | - -**Key Operations:** -1. `ChatMiddlewarePipeline.execute()` runs the chat middleware chain -2. Final handler calls `FunctionInvocationLayer.get_response()` -3. Stream hooks can be registered for streaming responses - -**What Can Be Modified:** -- `context.messages` - Inject system prompts, filter content -- `context.options` - Change model, temperature, tool_choice -- `context.result` - Override the response (after `call_next()`) - -### 3. Function Invocation Layer (`FunctionInvocationLayer`) - -**Entry Point:** `FunctionInvocationLayer.get_response()` - -This layer manages the tool execution loop: - -1. **Calls** `BaseChatClient._inner_get_response()` to get LLM response -2. **Extracts** function calls from the response -3. **Executes** functions through the Function Middleware Pipeline -4. **Appends** results to messages and loops back to step 1 - -**Configuration:** `FunctionInvocationConfiguration` - -| Setting | Default | Description | -|---------|---------|-------------| -| `enabled` | `True` | Enable auto-invocation | -| `max_iterations` | `40` | Maximum tool execution loops | -| `max_consecutive_errors_per_request` | `3` | Error threshold before stopping | -| `terminate_on_unknown_calls` | `False` | Raise error for unknown tools | -| `additional_tools` | `[]` | Extra tools to register | -| `include_detailed_errors` | `False` | Include exceptions in results | - -**`tool_choice` Behavior:** - -The `tool_choice` option controls how the model uses available tools: - -| Value | Behavior | -|-------|----------| -| `"auto"` | Model decides whether to call a tool or respond with text. After tool execution, the loop continues to get a text response. | -| `"none"` | Model is prevented from calling tools, will only respond with text. | -| `"required"` | Model **must** call a tool. After tool execution, returns immediately with the function call and resultβ€”**no additional model call** is made. | -| `{"mode": "required", "required_function_name": "fn"}` | Model must call the specified function. Same return behavior as `"required"`. | - -**Why `tool_choice="required"` returns immediately:** - -When you set `tool_choice="required"`, your intent is to force one or more tool calls (not all models supports multiple, either by name or when using `required` without a name). The framework respects this by: -1. Getting the model's function call(s) -2. Executing the tool(s) -3. Returning the response(s) with both the function call message(s) and the function result(s) - -This avoids an infinite loop (model forced to call tools β†’ executes β†’ model forced to call tools again) and gives you direct access to the tool result. - -```python -# With tool_choice="required", response contains function call + result only -response = await client.get_response( - "What's the weather?", - options={"tool_choice": "required", "tools": [get_weather]} -) - -# response.messages contains: -# [0] Assistant message with function_call content -# [1] Tool message with function_result content -# (No text response from model) - -# To get a text response after tool execution, use tool_choice="auto" -response = await client.get_response( - "What's the weather?", - options={"tool_choice": "auto", "tools": [get_weather]} -) -# response.text contains the model's interpretation of the weather data -``` - -### 4. Function Middleware Layer (`FunctionMiddlewarePipeline`) - -**Entry Point:** Called per function invocation within `_auto_invoke_function()` - -**Context Object:** `FunctionInvocationContext` - -| Field | Type | Description | -|-------|------|-------------| -| `function` | `FunctionTool` | The function being invoked | -| `arguments` | `BaseModel` | Validated Pydantic arguments | -| `metadata` | `dict` | Shared data between middleware | -| `result` | `Any` | Set after `call_next()` is called | -| `kwargs` | `Mapping[str, Any]` | Runtime kwargs | - -**What Can Be Modified:** -- `context.arguments` - Modify validated arguments before execution -- `context.result` - Override the function result (after `call_next()`) -- Raise `MiddlewareTermination` to skip execution and terminate the function invocation loop - -**Special Behavior:** When `MiddlewareTermination` is raised in function middleware, it signals that the function invocation loop should exit **without making another LLM call**. This is useful when middleware determines that no further processing is needed (e.g., a termination condition is met). - -```python -class TerminatingMiddleware(FunctionMiddleware): - async def process(self, context: FunctionInvocationContext, call_next): - if self.should_terminate(context): - context.result = "terminated by middleware" - raise MiddlewareTermination # Exit function invocation loop - await call_next() -``` - -## Arguments Added/Altered at Each Layer - -### Agent Layer β†’ Chat Layer - -```python -# RawAgent._prepare_run_context() builds: -{ - "thread": AgentThread, # Validated/created thread - "input_messages": [...], # Normalized input messages - "thread_messages": [...], # Messages from thread + context + input - "agent_name": "...", # Agent name for attribution - "chat_options": { - "model_id": "...", - "conversation_id": "...", # From thread.service_thread_id - "tools": [...], # Normalized tools + MCP tools - "temperature": ..., - "max_tokens": ..., - # ... other options - }, - "filtered_kwargs": {...}, # kwargs minus 'chat_options' - "finalize_kwargs": {...}, # kwargs with 'thread' added -} -``` - -### Chat Layer β†’ Function Layer - -```python -# Passed through to FunctionInvocationLayer: -{ - "messages": [...], # Prepared messages - "options": {...}, # Mutable copy of chat_options - "function_middleware": [...], # Function middleware from kwargs -} -``` - -### Function Layer β†’ Tool Invocation - -```python -# FunctionInvocationContext receives: -{ - "function": FunctionTool, # The tool to invoke - "arguments": BaseModel, # Validated from function_call.arguments - "kwargs": { - # Runtime kwargs (filtered, no conversation_id) - }, -} -``` - -### Tool Result β†’ Back Up - -```python -# Content.from_function_result() creates: -{ - "type": "function_result", - "call_id": "...", # From function_call.call_id - "result": ..., # Serialized tool output - "exception": "..." | None, # Error message if failed -} -``` - -## Middleware Control Flow - -There are three ways to exit a middleware's `process()` method: - -### 1. Return Normally (with or without calling `call_next`) - -Returns control to the upstream middleware, allowing its post-processing code to run. - -```python -class CachingMiddleware(FunctionMiddleware): - async def process(self, context: FunctionInvocationContext, call_next): - # Option A: Return early WITHOUT calling call_next (skip downstream) - if cached := self.cache.get(context.function.name): - context.result = cached - return # Upstream post-processing still runs - - # Option B: Call call_next, then return normally - await call_next() - self.cache[context.function.name] = context.result - return # Normal completion -``` - -### 2. Raise `MiddlewareTermination` - -Immediately exits the entire middleware chain. Upstream middleware's post-processing code is **skipped**. - -```python -class BlockedFunctionMiddleware(FunctionMiddleware): - async def process(self, context: FunctionInvocationContext, call_next): - if context.function.name in self.blocked_functions: - context.result = "Function blocked by policy" - raise MiddlewareTermination("Blocked") # Skips ALL post-processing - await call_next() -``` - -### 3. Raise Any Other Exception - -Bubbles up to the caller. The middleware chain is aborted and the exception propagates. - -```python -class ValidationMiddleware(FunctionMiddleware): - async def process(self, context: FunctionInvocationContext, call_next): - if not self.is_valid(context.arguments): - raise ValueError("Invalid arguments") # Bubbles up to user - await call_next() -``` - -## `return` vs `raise MiddlewareTermination` - -The key difference is what happens to **upstream middleware's post-processing**: - -```python -class MiddlewareA(AgentMiddleware): - async def process(self, context, call_next): - print("A: before") - await call_next() - print("A: after") # Does this run? - -class MiddlewareB(AgentMiddleware): - async def process(self, context, call_next): - print("B: before") - context.result = "early result" - # Choose one: - return # Option 1 - # raise MiddlewareTermination() # Option 2 -``` - -With middleware registered as `[MiddlewareA, MiddlewareB]`: - -| Exit Method | Output | -|-------------|--------| -| `return` | `A: before` β†’ `B: before` β†’ `A: after` | -| `raise MiddlewareTermination` | `A: before` β†’ `B: before` (no `A: after`) | - -**Use `return`** when you want upstream middleware to still process the result (e.g., logging, metrics). - -**Use `raise MiddlewareTermination`** when you want to completely bypass all remaining processing (e.g., blocking a request, returning cached response without any modification). - -## Calling `call_next()` or Not - -The decision to call `call_next()` determines whether downstream middleware and the actual operation execute: - -### Without calling `call_next()` - Skip downstream - -```python -async def process(self, context, call_next): - context.result = "replacement result" - return # Downstream middleware and actual execution are SKIPPED -``` - -- Downstream middleware: ❌ NOT executed -- Actual operation (LLM call, function invocation): ❌ NOT executed -- Upstream middleware post-processing: βœ… Still runs (unless `MiddlewareTermination` raised) -- Result: Whatever you set in `context.result` - -### With calling `call_next()` - Full execution - -```python -async def process(self, context, call_next): - # Pre-processing - await call_next() # Execute downstream + actual operation - # Post-processing (context.result now contains real result) - return -``` - -- Downstream middleware: βœ… Executed -- Actual operation: βœ… Executed -- Upstream middleware post-processing: βœ… Runs -- Result: The actual result (possibly modified in post-processing) - -### Summary Table - -| Exit Method | Call `call_next()`? | Downstream Executes? | Actual Op Executes? | Upstream Post-Processing? | -|-------------|----------------|---------------------|---------------------|--------------------------| -| `return` (or implicit) | Yes | βœ… | βœ… | βœ… Yes | -| `return` | No | ❌ | ❌ | βœ… Yes | -| `raise MiddlewareTermination` | No | ❌ | ❌ | ❌ No | -| `raise MiddlewareTermination` | Yes | βœ… | βœ… | ❌ No | -| `raise OtherException` | Either | Depends | Depends | ❌ No (exception propagates) | - -> **Note:** The first row (`return` after calling `call_next()`) is the default behavior. Python functions implicitly return `None` at the end, so simply calling `await call_next()` without an explicit `return` statement achieves this pattern. - -## Streaming vs Non-Streaming - -The `run()` method handles streaming and non-streaming differently: - -### Non-Streaming (`stream=False`) - -Returns `Awaitable[AgentResponse]`: - -```python -async def _run_non_streaming(): - ctx = await self._prepare_run_context(...) # Async preparation - response = await self.client.get_response(stream=False, ...) - await self._finalize_response_and_update_thread(...) - return AgentResponse(...) -``` - -### Streaming (`stream=True`) - -Returns `ResponseStream[AgentResponseUpdate, AgentResponse]` **synchronously**: - -```python -# Async preparation is deferred using ResponseStream.from_awaitable() -async def _get_stream(): - ctx = await self._prepare_run_context(...) # Deferred until iteration - return self.client.get_response(stream=True, ...) - -return ( - ResponseStream.from_awaitable(_get_stream()) - .map( - transform=map_chat_to_agent_update, # Transform each update - finalizer=self._finalize_response_updates, # Build final response - ) - .with_result_hook(_post_hook) # Post-processing after finalization -) -``` - -Key points: -- `ResponseStream.from_awaitable()` wraps an async function, deferring execution until the stream is consumed -- `.map()` transforms `ChatResponseUpdate` β†’ `AgentResponseUpdate` and provides the finalizer -- `.with_result_hook()` runs after finalization (e.g., notify thread of new messages) - -## See Also - -- [Middleware Samples](../../getting_started/middleware/) - Examples of custom middleware -- [Function Tool Samples](../../getting_started/tools/) - Creating and using tools diff --git a/python/samples/getting_started/agents/README.md b/python/samples/getting_started/agents/README.md deleted file mode 100644 index 6f1601cdc4..0000000000 --- a/python/samples/getting_started/agents/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# Agent Examples - -This folder contains examples demonstrating how to create and use agents with different chat clients from the Agent Framework. Each sub-folder focuses on a specific provider and client type, showing various capabilities like function tools, code interpreter, thread management, structured outputs, image processing, web search, Model Context Protocol (MCP) integration, and more. - -## Examples by Provider - -### Azure AI Foundry Examples - -| Folder | Description | -|--------|-------------| -| **[`azure_ai_agent/`](azure_ai_agent/)** | Create agents using Azure AI Agent Service (based on `azure-ai-agents` V1 package) including function tools, code interpreter, MCP integration, thread management, and more. | -| **[`azure_ai/`](azure_ai/)** | Create agents using Azure AI Agent Service (based on `azure-ai-projects` [V2](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/CHANGELOG.md#200b1-2025-11-11) package) including function tools, code interpreter, MCP integration, thread management, and more. | - -### Microsoft Copilot Studio Examples - -| Folder | Description | -|--------|-------------| -| **[`copilotstudio/`](copilotstudio/)** | Create agents using Microsoft Copilot Studio with streaming and non-streaming responses, authentication handling, and explicit configuration options | - -### Azure OpenAI Examples - -| Folder | Description | -|--------|-------------| -| **[`azure_openai/`](azure_openai/)** | Create agents using Azure OpenAI APIs with multiple client types (Assistants, Chat, and Responses clients) supporting function tools, code interpreter, thread management, and more | - -### OpenAI Examples - -| Folder | Description | -|--------|-------------| -| **[`openai/`](openai/)** | Create agents using OpenAI APIs with comprehensive examples including Assistants, Chat, and Responses clients featuring function tools, code interpreter, file search, web search, MCP integration, image analysis/generation, structured outputs, reasoning, and thread management | - -### Anthropic Examples - -| Folder | Description | -|--------|-------------| -| **[`anthropic/`](anthropic/)** | Create agents using Anthropic models through OpenAI Chat Client configuration, demonstrating tool calling capabilities | - -### Custom Implementation Examples - -| Folder | Description | -|--------|-------------| -| **[`custom/`](custom/)** | Create custom agents and chat clients by extending the base framework classes, showing complete control over agent behavior and backend integration | diff --git a/python/samples/getting_started/middleware/README.md b/python/samples/getting_started/middleware/README.md deleted file mode 100644 index 659e81647a..0000000000 --- a/python/samples/getting_started/middleware/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Middleware Examples - -This folder contains examples demonstrating various middleware patterns with the Agent Framework. Middleware allows you to intercept and modify behavior at different execution stages, including agent runs, function calls, and chat interactions. - -## Examples - -| File | Description | -|------|-------------| -| [`function_based_middleware.py`](function_based_middleware.py) | Demonstrates how to implement middleware using simple async functions instead of classes. Shows security validation, logging, and performance monitoring middleware. Function-based middleware is ideal for simple, stateless operations and provides a lightweight approach. | -| [`class_based_middleware.py`](class_based_middleware.py) | Shows how to implement middleware using class-based approach by inheriting from `AgentMiddleware` and `FunctionMiddleware` base classes. Includes security checks for sensitive information and detailed function execution logging with timing. | -| [`decorator_middleware.py`](decorator_middleware.py) | Demonstrates how to use `@agent_middleware` and `@function_middleware` decorators to explicitly mark middleware functions without requiring type annotations. Shows different middleware detection scenarios and explicit decorator usage. | -| [`middleware_termination.py`](middleware_termination.py) | Shows how middleware can terminate execution using the `context.terminate` flag. Includes examples of pre-termination (prevents agent processing) and post-termination (allows processing but stops further execution). Useful for security checks, rate limiting, or early exit conditions. | -| [`exception_handling_with_middleware.py`](exception_handling_with_middleware.py) | Demonstrates how to use middleware for centralized exception handling in function calls. Shows how to catch exceptions from functions, provide graceful error responses, and override function results when errors occur to provide user-friendly messages. | -| [`override_result_with_middleware.py`](override_result_with_middleware.py) | Shows how to use middleware to intercept and modify function results after execution, supporting both regular and streaming agent responses. Demonstrates result filtering, formatting, enhancement, and custom streaming response generation. | -| [`shared_state_middleware.py`](shared_state_middleware.py) | Demonstrates how to implement function-based middleware within a class to share state between multiple middleware functions. Shows how middleware can work together by sharing state, including call counting and result enhancement. | -| [`thread_behavior_middleware.py`](thread_behavior_middleware.py) | Demonstrates how middleware can access and track thread state across multiple agent runs. Shows how `AgentContext.thread` behaves differently before and after the `next()` call, how conversation history accumulates in threads, and timing of thread message updates. Essential for understanding conversation flow in middleware. | -| [`agent_and_run_level_middleware.py`](agent_and_run_level_middleware.py) | Explains the difference between agent-level middleware (applied to ALL runs of the agent) and run-level middleware (applied to specific runs only). Shows security validation, performance monitoring, and context-specific middleware patterns. | -| [`chat_middleware.py`](chat_middleware.py) | Demonstrates how to use chat middleware to observe and override inputs sent to AI models. Shows how to intercept chat requests, log and modify input messages, and override entire responses before they reach the underlying AI service. | - -## Key Concepts - -### Middleware Types - -- **Agent Middleware**: Intercepts agent run execution, allowing you to modify requests and responses -- **Function Middleware**: Intercepts function calls within agents, enabling logging, validation, and result modification -- **Chat Middleware**: Intercepts chat requests sent to AI models, allowing input/output transformation - -### Implementation Approaches - -- **Function-based**: Simple async functions for lightweight, stateless operations -- **Class-based**: Inherit from base middleware classes for complex, stateful operations -- **Decorator-based**: Use decorators for explicit middleware marking - -### Common Use Cases - -- **Security**: Validate requests, block sensitive information, implement access controls -- **Logging**: Track execution timing, log parameters and results, monitor performance -- **Error Handling**: Catch exceptions, provide graceful fallbacks, implement retry logic -- **Result Transformation**: Filter, format, or enhance function outputs -- **State Management**: Share data between middleware functions, maintain execution context - -### Execution Control - -- **Termination**: Use `context.terminate` to stop execution early -- **Result Override**: Modify or replace function/agent results -- **Streaming Support**: Handle both regular and streaming responses diff --git a/python/samples/getting_started/minimal_sample.py b/python/samples/getting_started/minimal_sample.py deleted file mode 100644 index a3315b4962..0000000000 --- a/python/samples/getting_started/minimal_sample.py +++ /dev/null @@ -1,24 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -import asyncio -from random import randint -from typing import Annotated - -from agent_framework import tool -from agent_framework.openai import OpenAIChatClient - - -# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py. -@tool(approval_mode="never_require") -def get_weather( - location: Annotated[str, "The location to get the weather for."], -) -> str: - """Get the weather for a given location.""" - conditions = ["sunny", "cloudy", "rainy", "stormy"] - return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}Β°C." - - -agent = OpenAIChatClient().as_agent( - name="WeatherAgent", instructions="You are a helpful weather agent.", tools=get_weather -) -print(asyncio.run(agent.run("What's the weather like in Seattle?"))) diff --git a/python/samples/getting_started/orchestrations/README.md b/python/samples/getting_started/orchestrations/README.md deleted file mode 100644 index 8ea5470038..0000000000 --- a/python/samples/getting_started/orchestrations/README.md +++ /dev/null @@ -1,102 +0,0 @@ -# Orchestration Getting Started Samples - -## Installation - -The orchestrations package is included when you install `agent-framework` (which pulls in all optional packages): - -```bash -pip install agent-framework -``` - -Or install the orchestrations package directly: - -```bash -pip install agent-framework-orchestrations -``` - -Orchestration builders are available via the `agent_framework.orchestrations` submodule: - -```python -from agent_framework.orchestrations import ( - SequentialBuilder, - ConcurrentBuilder, - HandoffBuilder, - GroupChatBuilder, - MagenticBuilder, -) -``` - -## Samples Overview (by directory) - -### concurrent - -| Sample | File | Concepts | -| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| Concurrent Orchestration (Default Aggregator) | [concurrent/concurrent_agents.py](./concurrent/concurrent_agents.py) | Fan-out to multiple agents; fan-in with default aggregator returning combined Messages | -| Concurrent Orchestration (Custom Aggregator) | [concurrent/concurrent_custom_aggregator.py](./concurrent/concurrent_custom_aggregator.py) | Override aggregator via callback; summarize results with an LLM | -| Concurrent Orchestration (Custom Agent Executors) | [concurrent/concurrent_custom_agent_executors.py](./concurrent/concurrent_custom_agent_executors.py) | Child executors own Agents; concurrent fan-out/fan-in via ConcurrentBuilder | -| Concurrent Orchestration as Agent | [concurrent/concurrent_workflow_as_agent.py](./concurrent/concurrent_workflow_as_agent.py) | Build a ConcurrentBuilder workflow and expose it as an agent via `workflow.as_agent(...)` | -| Tool Approval with ConcurrentBuilder | [concurrent/concurrent_builder_tool_approval.py](./concurrent/concurrent_builder_tool_approval.py) | Require human approval for sensitive tools across concurrent participants | -| ConcurrentBuilder Request Info | [concurrent/concurrent_request_info.py](./concurrent/concurrent_request_info.py) | Review concurrent agent outputs before aggregation using `.with_request_info()` | - -### sequential - -| Sample | File | Concepts | -| ------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -| Sequential Orchestration (Agents) | [sequential/sequential_agents.py](./sequential/sequential_agents.py) | Chain agents sequentially with shared conversation context | -| Sequential Orchestration (Custom Executor) | [sequential/sequential_custom_executors.py](./sequential/sequential_custom_executors.py) | Mix agents with a summarizer that appends a compact summary | -| Sequential Orchestration as Agent | [sequential/sequential_workflow_as_agent.py](./sequential/sequential_workflow_as_agent.py) | Build a SequentialBuilder workflow and expose it as an agent via `workflow.as_agent(...)` | -| Tool Approval with SequentialBuilder | [sequential/sequential_builder_tool_approval.py](./sequential/sequential_builder_tool_approval.py) | Require human approval for sensitive tools in SequentialBuilder workflows | -| SequentialBuilder Request Info | [sequential/sequential_request_info.py](./sequential/sequential_request_info.py) | Request info for agent responses mid-orchestration using `.with_request_info()` | - -### group-chat - -| Sample | File | Concepts | -| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | -| Group Chat with Agent Manager | [group-chat/group_chat_agent_manager.py](./group-chat/group_chat_agent_manager.py) | Agent-based manager using `with_orchestrator(agent=)` to select next speaker | -| Group Chat Philosophical Debate | [group-chat/group_chat_philosophical_debate.py](./group-chat/group_chat_philosophical_debate.py) | Agent manager moderates long-form, multi-round debate across diverse participants | -| Group Chat with Simple Selector | [group-chat/group_chat_simple_selector.py](./group-chat/group_chat_simple_selector.py) | Group chat with a simple function selector for next speaker | -| Group Chat Orchestration as Agent | [group-chat/group_chat_workflow_as_agent.py](./group-chat/group_chat_workflow_as_agent.py) | Build a GroupChatBuilder workflow and wrap it as an agent for composition | -| Tool Approval with GroupChatBuilder | [group-chat/group_chat_builder_tool_approval.py](./group-chat/group_chat_builder_tool_approval.py) | Require human approval for sensitive tools in group chat orchestration | -| GroupChatBuilder Request Info | [group-chat/group_chat_request_info.py](./group-chat/group_chat_request_info.py) | Steer group discussions with periodic guidance using `.with_request_info()` | - -### handoff - -| Sample | File | Concepts | -| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| Handoff (Simple) | [handoff/handoff_simple.py](./handoff/handoff_simple.py) | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response | -| Handoff (Autonomous) | [handoff/handoff_autonomous.py](./handoff/handoff_autonomous.py) | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_autonomous_mode()` | -| Handoff with Code Interpreter | [handoff/handoff_with_code_interpreter_file.py](./handoff/handoff_with_code_interpreter_file.py) | Retrieve file IDs from code interpreter output in handoff workflow | -| Handoff with Tool Approval + Checkpoint | [handoff/handoff_with_tool_approval_checkpoint_resume.py](./handoff/handoff_with_tool_approval_checkpoint_resume.py) | Capture tool-approval decisions in checkpoints and resume from persisted state | -| Handoff Orchestration as Agent | [handoff/handoff_workflow_as_agent.py](./handoff/handoff_workflow_as_agent.py) | Build a HandoffBuilder workflow and expose it as an agent, including HITL request/response flow | - -### magentic - -| Sample | File | Concepts | -| ---------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | -| Magentic Workflow | [magentic/magentic.py](./magentic/magentic.py) | Orchestrate multiple agents with a Magentic manager and streaming | -| Magentic + Human Plan Review | [magentic/magentic_human_plan_review.py](./magentic/magentic_human_plan_review.py) | Human reviews or updates the plan before execution | -| Magentic + Checkpoint Resume | [magentic/magentic_checkpoint.py](./magentic/magentic_checkpoint.py) | Resume Magentic orchestration from saved checkpoints | -| Magentic Orchestration as Agent | [magentic/magentic_workflow_as_agent.py](./magentic/magentic_workflow_as_agent.py) | Build a MagenticBuilder workflow and reuse it as an agent | - -## Tips - -**Magentic checkpointing tip**: Treat `MagenticBuilder.participants` keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast. - -**Handoff workflow tip**: Handoff workflows maintain the full conversation history including any `Message.additional_properties` emitted by your agents. This ensures routing metadata remains intact across all agent transitions. For specialist-to-specialist handoffs, use `.add_handoff(source, targets)` to configure which agents can route to which others with a fluent, type-safe API. - -**Sequential orchestration note**: Sequential orchestration uses a few small adapter nodes for plumbing: -- `input-conversation` normalizes input to `list[Message]` -- `to-conversation:` converts agent responses into the shared conversation -- `complete` publishes the final output event (type='output') - -These may appear in event streams (executor_invoked/executor_completed). They're analogous to concurrent's dispatcher and aggregator and can be ignored if you only care about agent activity. - -## Environment Variables - -Orchestration samples that use `AzureOpenAIResponsesClient` expect: - -- `AZURE_AI_PROJECT_ENDPOINT` (Azure AI Foundry Agent Service (V2) project endpoint) -- `AZURE_AI_MODEL_DEPLOYMENT_NAME` (model deployment name) - -These values are passed directly into the client constructor via `os.getenv()` in sample code. diff --git a/python/samples/getting_started/threads/README.md b/python/samples/getting_started/threads/README.md deleted file mode 100644 index 32c19d537f..0000000000 --- a/python/samples/getting_started/threads/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# Thread Management Examples - -This folder contains examples demonstrating different ways to manage conversation threads and chat message stores with the Agent Framework. - -## Examples - -| File | Description | -|------|-------------| -| [`custom_chat_message_store_thread.py`](custom_chat_message_store_thread.py) | Demonstrates how to implement a custom `ChatMessageStore` for persisting conversation history. Shows how to create a custom store with serialization/deserialization capabilities and integrate it with agents for thread management across multiple sessions. | -| [`redis_chat_message_store_thread.py`](redis_chat_message_store_thread.py) | Comprehensive examples of using the Redis-backed `RedisChatMessageStore` for persistent conversation storage. Covers basic usage, user session management, conversation persistence across app restarts, thread serialization, and automatic message trimming. Requires Redis server and demonstrates production-ready patterns for scalable chat applications. | -| [`suspend_resume_thread.py`](suspend_resume_thread.py) | Shows how to suspend and resume conversation threads, comparing service-managed threads (Azure AI) with in-memory threads (OpenAI). Demonstrates saving conversation state and continuing it later, useful for long-running conversations or persisting state across application restarts. | - -## Environment Variables - -Make sure to set the following environment variables before running the examples: - -- `OPENAI_API_KEY`: Your OpenAI API key (required for all samples) -- `OPENAI_CHAT_MODEL_ID`: The OpenAI model to use (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`) (required for all samples) -- `AZURE_AI_PROJECT_ENDPOINT`: Azure AI Project endpoint URL (required for service-managed thread examples) -- `AZURE_AI_MODEL_DEPLOYMENT_NAME`: The name of your model deployment (required for service-managed thread examples) diff --git a/python/samples/getting_started/tools/README.md b/python/samples/getting_started/tools/README.md deleted file mode 100644 index 3f5445bfb8..0000000000 --- a/python/samples/getting_started/tools/README.md +++ /dev/null @@ -1,144 +0,0 @@ -# Tools Examples - -This folder contains examples demonstrating how to use local tools with the Agent Framework. Local tools allow agents to interact with external systems, perform computations, and execute custom logic. - -Note: Several examples set `approval_mode="never_require"` to keep the samples concise. For production scenarios, -keep `approval_mode="always_require"` unless you are confident in the tool behavior and approval flow. See -`function_tool_with_approval.py` and `function_tool_with_approval_and_threads.py` for end-to-end approval handling. - -## Examples - -| File | Description | -|------|-------------| -| [`function_tool_declaration_only.py`](function_tool_declaration_only.py) | Demonstrates how to create function declarations without implementations. Useful for testing agent reasoning about tool usage or when tools are defined elsewhere. Shows how agents request tool calls even when the tool won't be executed. | -| [`function_tool_from_dict_with_dependency_injection.py`](function_tool_from_dict_with_dependency_injection.py) | Shows how to create local tools from dictionary definitions using dependency injection. The function implementation is injected at runtime during deserialization, enabling dynamic tool creation and configuration. Note: This serialization/deserialization feature is in active development. | -| [`function_tool_recover_from_failures.py`](function_tool_recover_from_failures.py) | Demonstrates graceful error handling when tools raise exceptions. Shows how agents receive error information and can recover from failures, deciding whether to retry or respond differently based on the exception. | -| [`function_tool_with_approval.py`](function_tool_with_approval.py) | Shows how to implement user approval workflows for function calls without using threads. Demonstrates both streaming and non-streaming approval patterns where users can approve or reject function executions before they run. | -| [`function_tool_with_approval_and_threads.py`](function_tool_with_approval_and_threads.py) | Demonstrates tool approval workflows using threads for automatic conversation history management. Shows how threads simplify approval workflows by automatically storing and retrieving conversation context. Includes both approval and rejection examples. | -| [`function_tool_with_kwargs.py`](function_tool_with_kwargs.py) | Demonstrates how to inject custom arguments (context) into a local tool from the agent's run method. Useful for passing runtime information like access tokens or user IDs that the tool needs but the model shouldn't see. | -| [`function_tool_with_thread_injection.py`](function_tool_with_thread_injection.py) | Shows how to access the current `thread` object inside a local tool via `**kwargs`. | -| [`function_tool_with_max_exceptions.py`](function_tool_with_max_exceptions.py) | Shows how to limit the number of times a tool can fail with exceptions using `max_invocation_exceptions`. Useful for preventing expensive tools from being called repeatedly when they keep failing. | -| [`function_tool_with_max_invocations.py`](function_tool_with_max_invocations.py) | Demonstrates limiting the total number of times a tool can be invoked using `max_invocations`. Useful for rate-limiting expensive operations or ensuring tools are only called a specific number of times per conversation. | -| [`function_tool_with_explicit_schema.py`](function_tool_with_explicit_schema.py) | Demonstrates how to provide an explicit Pydantic model or JSON schema dictionary to the `@tool` decorator via the `schema` parameter, bypassing automatic inference from the function signature. | -| [`tool_in_class.py`](tool_in_class.py) | Shows how to use the `tool` decorator with class methods to create stateful tools. Demonstrates how class state can control tool behavior dynamically, allowing you to adjust tool functionality at runtime by modifying class properties. | - -## Key Concepts - -### Local Tool Features - -- **Function Declarations**: Define tool schemas without implementations for testing or external tools -- **Explicit Schema**: Provide a Pydantic model or JSON schema dict to control the tool's parameter schema directly -- **Dependency Injection**: Create tools from configurations with runtime-injected implementations -- **Error Handling**: Gracefully handle and recover from tool execution failures -- **Approval Workflows**: Require user approval before executing sensitive or important operations -- **Invocation Limits**: Control how many times tools can be called or fail -- **Stateful Tools**: Use class methods as tools to maintain state and dynamically control behavior - -### Common Patterns - -#### Basic Tool Definition - -```python -from agent_framework import tool -from typing import Annotated - -@tool(approval_mode="never_require") -def my_tool(param: Annotated[str, "Description"]) -> str: - """Tool description for the AI.""" - return f"Result: {param}" -``` - -#### Tool with Approval - -```python -@tool(approval_mode="always_require") -def sensitive_operation(data: Annotated[str, "Data to process"]) -> str: - """This requires user approval before execution.""" - return f"Processed: {data}" -``` - -#### Tool with Explicit Schema - -```python -from pydantic import BaseModel, Field -from agent_framework import tool -from typing import Annotated - -class WeatherInput(BaseModel): - location: Annotated[str, Field(description="City name")] - unit: str = "celsius" - -@tool(schema=WeatherInput) -def get_weather(location: str, unit: str = "celsius") -> str: - """Get the weather for a location.""" - return f"Weather in {location}: 22 {unit}" -``` - -#### Tool with Invocation Limits - -```python -@tool(max_invocations=3) -def limited_tool() -> str: - """Can only be called 3 times total.""" - return "Result" - -@tool(max_invocation_exceptions=2) -def fragile_tool() -> str: - """Can only fail 2 times before being disabled.""" - return "Result" -``` - -#### Stateful Tools with Classes - -```python -class MyTools: - def __init__(self, mode: str = "normal"): - self.mode = mode - - def process(self, data: Annotated[str, "Data to process"]) -> str: - """Process data based on current mode.""" - if self.mode == "safe": - return f"Safely processed: {data}" - return f"Processed: {data}" - -# Create instance and use methods as tools -tools = MyTools(mode="safe") -agent = client.as_agent(tools=tools.process) - -# Change behavior dynamically -tools.mode = "normal" -``` - -### Error Handling - -When tools raise exceptions: -1. The exception is captured and sent to the agent as a function result -2. The agent receives the error message and can reason about what went wrong -3. The agent can retry with different parameters, use alternative tools, or explain the issue to the user -4. With invocation limits, tools can be disabled after repeated failures - -### Approval Workflows - -Two approaches for handling approvals: - -1. **Without Threads**: Manually manage conversation context, including the query, approval request, and response in each iteration -2. **With Threads**: Thread automatically manages conversation history, simplifying the approval workflow - -## Usage Tips - -- Use **declaration-only** functions when you want to test agent reasoning without execution -- Use **dependency injection** for dynamic tool configuration and plugin architectures -- Implement **approval workflows** for operations that modify data, spend money, or require human oversight -- Set **invocation limits** to prevent runaway costs or infinite loops with expensive tools -- Handle **exceptions gracefully** to create robust agents that can recover from failures -- Use **class-based tools** when you need to maintain state or dynamically adjust tool behavior at runtime - -## Running the Examples - -Each example is a standalone Python script that can be run directly: - -```bash -uv run python function_tool_with_approval.py -``` - -Make sure you have the necessary environment variables configured (like `OPENAI_API_KEY` or Azure credentials) before running the examples. diff --git a/python/samples/getting_started/agents/resources/countries.json b/python/samples/shared/resources/countries.json similarity index 100% rename from python/samples/getting_started/agents/resources/countries.json rename to python/samples/shared/resources/countries.json diff --git a/python/samples/getting_started/agents/resources/employees.pdf b/python/samples/shared/resources/employees.pdf similarity index 100% rename from python/samples/getting_started/agents/resources/employees.pdf rename to python/samples/shared/resources/employees.pdf diff --git a/python/samples/getting_started/agents/resources/weather.json b/python/samples/shared/resources/weather.json similarity index 100% rename from python/samples/getting_started/agents/resources/weather.json rename to python/samples/shared/resources/weather.json diff --git a/python/samples/getting_started/sample_assets/sample.pdf b/python/samples/shared/sample_assets/sample.pdf similarity index 100% rename from python/samples/getting_started/sample_assets/sample.pdf rename to python/samples/shared/sample_assets/sample.pdf