Python: restructure: Python samples into progressive 01-05 layout (#3862)

* restructure: Python samples into progressive 01-05 layout - 01-get-started/: 6 numbered steps (hello agent → hosting) - 02-agents/: all agent concept samples (tools, middleware, providers, etc.) - 03-workflows/: ALL existing workflow samples preserved as-is - 04-hosting/: azure-functions, durabletask, a2a - 05-end-to-end/: demos, evaluation, hosted agents - Old files moved to _to_delete/ for review - Added AGENTS.md with structure documentation - autogen-migration/ and semantic-kernel-migration/ preserved at root * fix: switch to AzureOpenAI Foundry, fix CI failures - Switch all 01-get-started samples to AzureOpenAIResponsesClient with Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential) - Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes - Fix test paths in packages/ that referenced old getting_started/ dirs: durabletask conftest + streaming test, azurefunctions conftest, devui conftest + capture_messages + openai_sdk_integration - Fix workflow_as_agent_human_in_the_loop.py import (sibling import) - Update hosting READMEs and tool comment paths - Replace root README.md with new structure overview - Update AGENTS.md to document Azure OpenAI Foundry as default provider * cleanup: remove _to_delete folder, copy resource files to active dirs All files in _to_delete/ were either: - Exact duplicates of files in the new structure (240 files) - Same file with only comment path updates (100 files) - One import-fix diff (workflow_as_agent_human_in_the_loop.py) - One superseded minimal_sample.py Resource files (sample.pdf, countries.json, employees.pdf, weather.json) copied to 02-agents/sample_assets/ and 02-agents/resources/ since active samples reference them. * fix: address PR review comments, centralize resources, remove root duplicates - Fix type annotation in 04_memory.py (string union -> proper types) - Fix old sample paths in observability files - Fix grammar/spelling in observability samples - Move sample_assets/ and resources/ to shared/ folder - Remove 8 duplicate observability files from 02-agents root - Update resource path references in multimodal_input and provider samples * fix: update broken links from old getting_started paths to new structure - Update relative paths in READMEs: getting_started/ → 01-get-started/, 02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/ - Fix absolute GitHub URLs in package READMEs - Fix broken link in ollama package README * fix: convert absolute GitHub URLs to relative paths for link checker Absolute URLs to python/samples/ on main branch 404 until PR merges. Converted to relative paths that linkspector can verify locally. * fix: update link for handoff sample moved to orchestrations/ * fix: update chatkit-integration README path from demos/ to 05-end-to-end/ * fix: update broken links in orchestrations README to match flat directory structure
2026-06-16 21:04:09 +08:00 · 2026-02-12 18:36:36 +01:00
parent 69dcfe31ee
commit a2856d3b92
536 changed files with 3816 additions and 1632 deletions
@@ -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:
+    # <create_agent>
+    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.",
+    )
+    # </create_agent>
+
+    # <run_agent>
+    # Non-streaming: get the complete response at once
+    result = await agent.run("What is the capital of France?")
+    print(f"Agent: {result}")
+    # </run_agent>
+
+    # <run_agent_streaming>
+    # 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()
+    # </run_agent_streaming>
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -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)
+"""
+
+
+# <define_tool>
+# 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."
+# </define_tool>
+
+
+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,
+    )
+
+    # <create_agent_with_tools>
+    agent = client.as_agent(
+        name="WeatherAgent",
+        instructions="You are a helpful weather agent. Use the get_weather tool to answer questions.",
+        tools=get_weather,
+    )
+    # </create_agent_with_tools>
+
+    # <run_agent>
+    result = await agent.run("What's the weather like in Seattle?")
+    print(f"Agent: {result}")
+    # </run_agent>
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -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:
+    # <create_agent>
+    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_agent>
+
+    # <multi_turn>
+    # 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}")
+    # </multi_turn>
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -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)
+"""
+
+
+# <context_provider>
+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()
+# </context_provider>
+
+
+async def main() -> None:
+    # <create_agent>
+    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,
+    )
+    # </create_agent>
+
+    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())
@@ -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.
+"""
+
+
+# <create_workflow>
+# 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()
+    )
+# </create_workflow>
+
+
+async def main() -> None:
+    # <run_workflow>
+    workflow = create_workflow()
+
+    events = await workflow.run("hello world")
+    print(f"Output: {events.get_outputs()}")
+    print(f"Final state: {events.get_final_state()}")
+    # </run_workflow>
+
+    """
+    Expected output:
+      Output: ['DLROW OLLEH']
+      Final state: WorkflowRunState.IDLE
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -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:
+    # <create_agent>
+    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.",
+    )
+    # </create_agent>
+
+    # <host_agent>
+    # 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}")
+    # </host_agent>
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -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
+```