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

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
+```