Python: small fixes in foundry (#297)

* small fixes in foundry

* other samples updated

* make it optional

* added instructions and response format to create agent

* mypy fix

* shortened main readme and improved python readme

Author: eavanvalkenburg

README.md

@@ -9,7 +9,9 @@ Highlights
 - Multimodal: Text, vision, and function calling
 - Cross-Platform: .NET and Python implementations
 
-## Quick Install
+Below are the basics for each language implementation. For more details on python see [here](./python/README.md) and for .NET see [here](./dotnet/README.md).
+
+## Python - Quick Install
 
 ```bash
 pip install agent-framework
@@ -25,13 +27,14 @@ Supported Platforms:
 - Python: 3.10+
 - OS: Windows, macOS, Linux
 
-## 1. Setup API Keys
+## Python - 1. Setup API Keys
 
 Set as environment variables, or create a .env file at your project root:
 
 ```bash
 OPENAI_API_KEY=sk-...
 OPENAI_CHAT_MODEL_ID=...
+OPENAI_RESPONSES_MODEL_ID=...
 ...
 AZURE_OPENAI_API_KEY=...
 AZURE_OPENAI_ENDPOINT=...
@@ -56,66 +59,38 @@ chat_client = AzureChatClient(
 
 See the following [setup guide](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started) for more information.
 
-## 2. Create a Simple Agent
+## Python - 2. Create a Simple Agent
 
 Create agents and invoke them directly:
 
 ```python
 import asyncio
 from agent_framework import ChatClientAgent
-from agent_framework.openai import OpenAIChatClient
+from agent_framework.foundry import FoundryChatClient
 
 async def main():
-    agent = ChatClientAgent(
-        chat_client=OpenAIChatClient(),
-        instructions="""
+    async with ChatClientAgent(
+        chat_client=FoundryChatClient(),
+        instructions="""These are the Three Laws of Robotics:
         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.
+        Respond concisely to the user's request.
+        """
+    ):
+        result = await agent.run("Summarize the Three Laws of Robotics")
+        print(result.text)
+        """
+        Output:
+        Protect humans, obey, self-preserve, prioritized.
         """
-    )
-
-    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.openai import OpenAIChatClient
-from agent_framework import ChatMessage, ChatRole
-
-async def main():
-    client = OpenAIChatClient()
-
-    messages = [
-        ChatMessage(role=ChatRole.SYSTEM, text="You are a helpful assistant."),
-        ChatMessage(role=ChatRole.USER, text="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())
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
-## 4. Build an Agent with Tools and Functions
+## Python - 3. Build an Agent with Tools
 
 Enhance your agent with custom tools and function calling:
 
@@ -125,7 +100,7 @@ from typing import Annotated
 from random import randint
 from pydantic import Field
 from agent_framework import ChatClientAgent
-from agent_framework.openai import OpenAIChatClient
+from agent_framework.openai import OpenAIResponsesClient
 
 
 def get_weather(
@@ -147,13 +122,13 @@ def get_menu_specials() -> str:
 
 async def main():
     agent = ChatClientAgent(
-        chat_client=OpenAIChatClient(),
+        chat_client=OpenAIResponsesClient(),
         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)
+    print(response.text)
 
     """
     Output:
@@ -167,56 +142,6 @@ if __name__ == "__main__":
 
 You can explore additional agent samples [here](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents).
 
-## 5. Multi-Agent Orchestration
-
-Coordinate multiple agents to collaborate on complex tasks using orchestration patterns:
-
-```python
-import asyncio
-from agent_framework import ChatClientAgent
-from agent_framework.openai import OpenAIChatClient
-
-
-async def main():
-    # Create specialized agents
-    writer = ChatClientAgent(
-        chat_client=OpenAIChatClient(),
-        name="Writer",
-        instructions="You are a creative content writer. Generate and refine slogans based on feedback."
-    )
-
-    reviewer = ChatClientAgent(
-        chat_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())
-```
-
 **Note**: Advanced orchestration patterns like GroupChat, Sequential, and Concurrent orchestrations are coming soon.
 
 ## More Examples & Samples

python/DEV_SETUP.md

@@ -6,6 +6,8 @@ want to run the tests included.
 
 ## System setup
 
+We are using a tool called [poethepoet](https://github.com/nat-n/poethepoet) for task management and [uv](https://github.com/astral-sh/uv) for dependency management. At the [end of this document](#available-poe-tasks), you will find the available Poe tasks.
+
 ## If you're on WSL
 
 Check that you've cloned the repository to `~/workspace` or a similar folder.
@@ -461,3 +463,163 @@ or:
 This is assuming the upstream branch refers to the main repository. If you have a different name for the upstream branch, you can replace `upstream` with the name of your upstream branch.
 
 After running the rebase command, you may need to resolve any conflicts that arise. If you are unsure how to resolve a conflict, please refer to the [GitHub's documentation on resolving conflicts](https://docs.github.com/en/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase), or for [VSCode](https://code.visualstudio.com/docs/sourcecontrol/overview#_merge-conflicts).
+
+# Task automation
+
+## Available Poe Tasks
+This project uses [poethepoet](https://github.com/nat-n/poethepoet) for task management and [uv](https://github.com/astral-sh/uv) for dependency management.
+
+### Setup and Installation
+
+Once uv is installed, and you do not yet have a virtual environment setup:
+
+```bash
+uv venv
+```
+
+and then you can run the following tasks:
+```bash
+uv sync --all-extras --dev
+```
+
+After this initial setup, you can use the following tasks to manage your development environment, it is adviced to use the following setup command since that also installs the pre-commit hooks.
+
+#### `setup`
+Set up the development environment with a virtual environment, install dependencies and pre-commit hooks:
+```bash
+uv run poe setup
+# or with specific Python version
+uv run poe setup --python 3.12
+```
+
+#### `install`
+Install all dependencies including extras and dev dependencies, including updates:
+```bash
+uv run poe install
+```
+
+#### `venv`
+Create a virtual environment with specified Python version or switch python version:
+```bash
+uv run poe venv
+# or with specific Python version
+uv run poe venv --python 3.12
+```
+
+#### `pre-commit-install`
+Install pre-commit hooks:
+```bash
+uv run poe pre-commit-install
+```
+
+### Code Quality and Formatting
+
+Each of the following tasks are designed to run against both the main `agent-framework` package and the extension packages, ensuring consistent code quality across the project.
+
+#### `fmt` (format)
+Format code using ruff:
+```bash
+uv run poe fmt
+```
+
+#### `lint`
+Run linting checks and fix issues:
+```bash
+uv run poe lint
+```
+
+#### `pyright`
+Run Pyright type checking:
+```bash
+uv run poe pyright
+```
+
+#### `mypy`
+Run MyPy type checking:
+```bash
+uv run poe mypy
+```
+
+### Testing
+
+#### `test`
+Run unit tests with coverage:
+```bash
+uv run poe test
+```
+
+### Documentation
+
+#### `docs-clean`
+Remove the docs build directory:
+```bash
+uv run poe docs-clean
+```
+
+#### `docs-build`
+Build the documentation:
+```bash
+uv run poe docs-build
+```
+
+#### `docs-serve`
+Serve documentation locally with auto-reload:
+```bash
+uv run poe docs-serve
+```
+
+#### `docs-check`
+Build documentation and fail on warnings:
+```bash
+uv run poe docs-check
+```
+
+#### `docs-check-examples`
+Check documentation examples for code correctness:
+```bash
+uv run poe docs-check-examples
+```
+
+### Code Validation
+
+#### `markdown-code-lint`
+Lint markdown code blocks:
+```bash
+uv run poe markdown-code-lint
+```
+
+#### `samples-code-check`
+Run type checking on samples:
+```bash
+uv run poe samples-code-check
+```
+
+### Comprehensive Checks
+
+#### `check`
+Run all quality checks (format, lint, pyright, mypy, test, markdown lint, samples check):
+```bash
+uv run poe check
+```
+
+#### `pre-commit-check`
+Run pre-commit specific checks (all of the above, excluding `mypy`):
+```bash
+uv run poe pre-commit-check
+```
+
+### Building
+
+#### `build`
+Build the package:
+```bash
+uv run poe build
+```
+
+## Pre-commit Hooks
+
+You can also run all checks using pre-commit directly:
+
+```bash
+uv run pre-commit run -a
+```