chore: import upstream snapshot with attribution

python/README.md

@@ -0,0 +1,261 @@
+# Get Started with Microsoft Agent Framework for Python Developers
+
+## Quick Install
+
+We recommend two common installation paths depending on your use case.
+
+### 1. Development mode
+
+If you are exploring or developing locally, install the entire framework with all sub-packages:
+
+```bash
+pip install agent-framework
+```
+
+This installs the core and every integration package, making sure that all features are available without additional steps. This is the simplest way to get started.
+
+### 2. Selective install
+
+If you only need specific integrations, you can install at a more granular level. This keeps dependencies lighter and focuses on what you actually plan to use. Some examples:
+
+```bash
+# Core only
+# includes Azure OpenAI and OpenAI support by default
+# also includes workflows and orchestrations
+pip install agent-framework-core
+
+# Core + Azure AI Foundry integration
+pip install agent-framework-foundry
+
+# Core + Microsoft Copilot Studio integration (preview package)
+pip install agent-framework-copilotstudio --pre
+
+# Core + both Microsoft Copilot Studio and Azure AI Foundry integration
+pip install --pre agent-framework-copilotstudio agent-framework-foundry
+```
+
+This selective approach is useful when you know which integrations you need, and it is the recommended way to set up lightweight environments. Released packages such as `agent-framework`, `agent-framework-core`, and `agent-framework-foundry` no longer require `--pre`, while preview connectors such as `agent-framework-copilotstudio` still do.
+
+Supported Platforms:
+
+- Python: 3.10+
+- OS: Windows, macOS, Linux
+
+## 1. Setup API Keys
+
+Set as environment variables, or create a .env file at your project root:
+
+```bash
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=...
+...
+AZURE_OPENAI_API_KEY=...
+AZURE_OPENAI_ENDPOINT=...
+AZURE_OPENAI_MODEL=...
+...
+FOUNDRY_PROJECT_ENDPOINT=...
+FOUNDRY_MODEL=...
+```
+
+For the generic OpenAI clients (`OpenAIChatClient` and `OpenAIChatCompletionClient`), configuration
+resolves in this order:
+
+1. Explicit Azure inputs such as `credential` or `azure_endpoint`
+2. `OPENAI_API_KEY` / explicit OpenAI API-key parameters
+3. Azure environment fallback such as `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_API_KEY`
+
+This means mixed shells default to OpenAI when `OPENAI_API_KEY` is present. To force Azure routing,
+pass an explicit Azure input such as `credential=AzureCliCredential()`.
+
+You can also override environment variables by explicitly passing configuration parameters to the chat client constructor:
+
+```python
+from agent_framework.openai import OpenAIChatClient
+
+client = OpenAIChatClient(
+    api_key='',
+    azure_endpoint='',
+    model='',
+    api_version='',
+)
+```
+
+See the following [setup guide](samples/01-get-started) for more information.
+
+## 2. Create a Simple Agent
+
+Create agents and invoke them directly:
+
+```python
+import asyncio
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+
+async def main():
+    agent = Agent(
+        client=OpenAIChatClient(),
+        instructions="""
+        1) A robot may not injure a human being...
+        2) A robot must obey orders given it by human beings...
+        3) A robot must protect its own existence...
+
+        Give me the TLDR in exactly 5 words.
+        """
+    )
+
+    result = await agent.run("Summarize the Three Laws of Robotics")
+    print(result)
+
+asyncio.run(main())
+# Output: Protect humans, obey, self-preserve, prioritized.
+```
+
+## 3. Directly Use Chat Clients (No Agent Required)
+
+You can use the chat client classes directly for advanced workflows:
+
+```python
+import asyncio
+from agent_framework import Message
+from agent_framework.openai import OpenAIChatClient
+
+async def main():
+    client = OpenAIChatClient()
+
+    messages = [
+        Message("system", ["You are a helpful assistant."]),
+        Message("user", ["Write a haiku about Agent Framework."])
+    ]
+
+    response = await client.get_response(messages)
+    print(response.messages[0].text)
+
+    """
+    Output:
+
+    Agents work in sync,
+    Framework threads through each task—
+    Code sparks collaboration.
+    """
+
+asyncio.run(main())
+```
+
+## 4. Build an Agent with Tools and Functions
+
+Enhance your agent with custom tools and function calling:
+
+```python
+import asyncio
+from typing import Annotated
+from random import randint
+from pydantic import Field
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+
+
+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."
+
+
+def get_menu_specials() -> str:
+    """Get today's menu specials."""
+    return """
+    Special Soup: Clam Chowder
+    Special Salad: Cobb Salad
+    Special Drink: Chai Tea
+    """
+
+
+async def main():
+    agent = Agent(
+        client=OpenAIChatClient(),
+        instructions="You are a helpful assistant that can provide weather and restaurant information.",
+        tools=[get_weather, get_menu_specials]
+    )
+
+    response = await agent.run("What's the weather in Amsterdam and what are today's specials?")
+    print(response)
+
+    """
+    Output:
+    The weather in Amsterdam is sunny with a high of 22°C. Today's specials include
+    Clam Chowder soup, Cobb Salad, and Chai Tea as the special drink.
+    """
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+You can explore additional agent samples [here](samples/02-agents).
+
+## 5. Multi-Agent Orchestration
+
+Coordinate multiple agents to collaborate on complex tasks using orchestration patterns:
+
+```python
+import asyncio
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+
+
+async def main():
+    # Create specialized agents
+    writer = Agent(
+        client=OpenAIChatClient(),
+        name="Writer",
+        instructions="You are a creative content writer. Generate and refine slogans based on feedback."
+    )
+
+    reviewer = Agent(
+        client=OpenAIChatClient(),
+        name="Reviewer",
+        instructions="You are a critical reviewer. Provide detailed feedback on proposed slogans."
+    )
+
+    # Sequential workflow: Writer creates, Reviewer provides feedback
+    task = "Create a slogan for a new electric SUV that is affordable and fun to drive."
+
+    # Step 1: Writer creates initial slogan
+    initial_result = await writer.run(task)
+    print(f"Writer: {initial_result}")
+
+    # Step 2: Reviewer provides feedback
+    feedback_request = f"Please review this slogan: {initial_result}"
+    feedback = await reviewer.run(feedback_request)
+    print(f"Reviewer: {feedback}")
+
+    # Step 3: Writer refines based on feedback
+    refinement_request = f"Please refine this slogan based on the feedback: {initial_result}\nFeedback: {feedback}"
+    final_result = await writer.run(refinement_request)
+    print(f"Final Slogan: {final_result}")
+
+    # Example Output:
+    # Writer: "Charge Forward: Affordable Adventure Awaits!"
+    # Reviewer: "Good energy, but 'Charge Forward' is overused in EV marketing..."
+    # Final Slogan: "Power Up Your Adventure: Premium Feel, Smart Price!"
+
+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/03-workflows/orchestrations).
+
+## More Examples & Samples
+
+- [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
+- [Foundry Integration](https://github.com/microsoft/agent-framework/tree/main/python/packages/foundry): Microsoft Foundry integration
+- [Workflow Samples](samples/03-workflows): Advanced multi-agent patterns
+
+## Agent Framework Documentation
+
+- [Agent Framework Repository](https://github.com/microsoft/agent-framework)
+- [Python Package Documentation](https://github.com/microsoft/agent-framework/tree/main/python)
+- [.NET Package Documentation](https://github.com/microsoft/agent-framework/tree/main/dotnet)
+- [Design Documents](https://github.com/microsoft/agent-framework/tree/main/docs/design)
+- Learn docs are coming soon.