Python: Fix tool normalization and provider sample consolidation

python/CODING_STANDARD.md

@@ -10,6 +10,21 @@ We use [ruff](https://github.com/astral-sh/ruff) for both linting and formatting
 - **Target Python version**: 3.10+
 - **Google-style docstrings**: All public functions, classes, and modules should have docstrings following Google conventions
 
+### Module Docstrings
+
+Public modules must include a module-level docstring, including `__init__.py` files.
+
+- Namespace-style `__init__.py` modules (for example under `agent_framework/<provider>/`) should use a structured
+  docstring that includes:
+  - A one-line summary of the namespace
+  - A short "This module lazily re-exports objects from:" section that lists only pip install package names
+    (for example `agent-framework-a2a`)
+  - A short "Supported classes:" (or "Supported classes and functions:") section
+- The main `agent_framework/__init__.py` should include a concise background-oriented docstring rather than a long
+  per-symbol list.
+- Core modules with broad surface area, including `agent_framework/exceptions.py` and
+  `agent_framework/observability.py`, should always have explicit module docstrings.
+
 ## Type Annotations
 
 ### Future Annotations

python/packages/anthropic/agent_framework_anthropic/_chat_client.py

@@ -720,6 +720,8 @@ def _prepare_tools_for_anthropic(self, options: Mapping[str, Any]) -> dict[str,
         if options.get("tool_choice") is None:
             return result or None
         tool_mode = validate_tool_mode(options.get("tool_choice"))
+        if tool_mode is None:
+            return result or None
         allow_multiple = options.get("allow_multiple_tool_calls")
         match tool_mode.get("mode"):
             case "auto":

python/packages/azure-ai/agent_framework_azure_ai/_agent_provider.py

@@ -16,6 +16,7 @@
 )
 from agent_framework._mcp import MCPTool
 from agent_framework._settings import load_settings
+from agent_framework._tools import ToolTypes
 from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.agents.aio import AgentsClient
 from azure.ai.agents.models import Agent as AzureAgent
@@ -169,11 +170,7 @@ async def create_agent(
         model: str | None = None,
         instructions: str | None = None,
         description: str | None = None,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -242,7 +239,12 @@ async def create_agent(
         normalized_tools = normalize_tools(tools)
         if normalized_tools:
             # Only convert non-MCP tools to Azure AI format
-            non_mcp_tools = [t for t in normalized_tools if not isinstance(t, MCPTool)]
+            non_mcp_tools: list[FunctionTool | MutableMapping[str, Any]] = []
+            for normalized_tool in normalized_tools:
+                if isinstance(normalized_tool, MCPTool):
+                    continue
+                if isinstance(normalized_tool, (FunctionTool, MutableMapping)):
+                    non_mcp_tools.append(normalized_tool)
             if non_mcp_tools:
                 # Pass run_options to capture tool_resources (e.g., for file search vector stores)
                 run_options: dict[str, Any] = {}
@@ -266,11 +268,7 @@ async def get_agent(
         self,
         id: str,
         *,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -322,11 +320,7 @@ async def get_agent(
     def as_agent(
         self,
         agent: AzureAgent,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -379,7 +373,7 @@ def as_agent(
     def _to_chat_agent_from_agent(
         self,
         agent: AzureAgent,
-        provided_tools: Sequence[FunctionTool | MutableMapping[str, Any]] | None = None,
+        provided_tools: Sequence[ToolTypes] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -422,8 +416,8 @@ def _to_chat_agent_from_agent(
     def _merge_tools(
         self,
         agent_tools: Sequence[Any] | None,
-        provided_tools: Sequence[FunctionTool | MutableMapping[str, Any]] | None,
-    ) -> list[FunctionTool | dict[str, Any]]:
+        provided_tools: Sequence[ToolTypes] | None,
+    ) -> list[ToolTypes]:
         """Merge hosted tools from agent with user-provided function tools.
 
         Args:
@@ -433,7 +427,7 @@ def _merge_tools(
         Returns:
             Combined list of tools for the Agent.
         """
-        merged: list[FunctionTool | dict[str, Any]] = []
+        merged: list[ToolTypes] = []
 
         # Convert hosted tools from agent definition
         hosted_tools = from_azure_ai_agent_tools(agent_tools)
@@ -459,7 +453,7 @@ def _merge_tools(
     def _validate_function_tools(
         self,
         agent_tools: Sequence[Any] | None,
-        provided_tools: Sequence[FunctionTool | MutableMapping[str, Any]] | None,
+        provided_tools: Sequence[ToolTypes] | None,
     ) -> None:
         """Validate that required function tools are provided.
 

python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py

@@ -34,6 +34,7 @@
     UsageDetails,
 )
 from agent_framework._settings import load_settings
+from agent_framework._tools import ToolTypes
 from agent_framework.exceptions import ServiceInitializationError, ServiceInvalidRequestError, ServiceResponseException
 from agent_framework.observability import ChatTelemetryLayer
 from azure.ai.agents.aio import AgentsClient
@@ -1428,11 +1429,7 @@ def as_agent(
         name: str | None = None,
         description: str | None = None,
         instructions: str | None = None,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: AzureAIAgentOptionsT | Mapping[str, Any] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,

python/packages/azure-ai/agent_framework_azure_ai/_client.py

@@ -5,7 +5,7 @@
 import json
 import logging
 import sys
-from collections.abc import Callable, Mapping, MutableMapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from contextlib import suppress
 from typing import Any, ClassVar, Generic, Literal, TypedDict, TypeVar, cast
 
@@ -22,6 +22,7 @@
     MiddlewareTypes,
 )
 from agent_framework._settings import load_settings
+from agent_framework._tools import ToolTypes
 from agent_framework.exceptions import ServiceInitializationError
 from agent_framework.observability import ChatTelemetryLayer
 from agent_framework.openai import OpenAIResponsesOptions
@@ -880,11 +881,7 @@ def as_agent(
         name: str | None = None,
         description: str | None = None,
         instructions: str | None = None,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: AzureAIClientOptionsT | Mapping[str, Any] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,

python/packages/azure-ai/agent_framework_azure_ai/_project_provider.py

@@ -17,6 +17,7 @@
 )
 from agent_framework._mcp import MCPTool
 from agent_framework._settings import load_settings
+from agent_framework._tools import ToolTypes
 from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.projects.aio import AIProjectClient
 from azure.ai.projects.models import (
@@ -161,11 +162,7 @@ async def create_agent(
         model: str | None = None,
         instructions: str | None = None,
         description: str | None = None,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -226,7 +223,7 @@ async def create_agent(
             for tool in normalized_tools:
                 if isinstance(tool, MCPTool):
                     mcp_tools.append(tool)
-                else:
+                elif isinstance(tool, (FunctionTool, MutableMapping)):
                     non_mcp_tools.append(tool)
 
         # Connect MCP tools and discover their functions BEFORE creating the agent
@@ -263,11 +260,7 @@ async def get_agent(
         *,
         name: str | None = None,
         reference: AgentReference | None = None,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -323,11 +316,7 @@ async def get_agent(
     def as_agent(
         self,
         details: AgentVersionDetails,
-        tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None = None,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -367,7 +356,7 @@ def as_agent(
     def _to_chat_agent_from_details(
         self,
         details: AgentVersionDetails,
-        provided_tools: Sequence[FunctionTool | MutableMapping[str, Any]] | None = None,
+        provided_tools: Sequence[ToolTypes] | None = None,
         default_options: OptionsCoT | None = None,
         middleware: Sequence[MiddlewareTypes] | None = None,
         context_providers: Sequence[BaseContextProvider] | None = None,
@@ -415,8 +404,8 @@ def _to_chat_agent_from_details(
     def _merge_tools(
         self,
         definition_tools: Sequence[Any] | None,
-        provided_tools: Sequence[FunctionTool | MutableMapping[str, Any]] | None,
-    ) -> list[FunctionTool | dict[str, Any]]:
+        provided_tools: Sequence[ToolTypes] | None,
+    ) -> list[ToolTypes]:
         """Merge hosted tools from definition with user-provided function tools.
 
         Args:
@@ -426,7 +415,7 @@ def _merge_tools(
         Returns:
             Combined list of tools for the Agent.
         """
-        merged: list[FunctionTool | dict[str, Any]] = []
+        merged: list[ToolTypes] = []
 
         # Convert hosted tools from definition (MCP, code interpreter, file search, web search)
         # Function tools from the definition are skipped - we use user-provided implementations instead
@@ -450,11 +439,7 @@ def _merge_tools(
     def _validate_function_tools(
         self,
         agent_tools: Sequence[Any] | None,
-        provided_tools: FunctionTool
-        | Callable[..., Any]
-        | MutableMapping[str, Any]
-        | Sequence[FunctionTool | Callable[..., Any] | MutableMapping[str, Any]]
-        | None,
+        provided_tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None,
     ) -> None:
         """Validate that required function tools are provided."""
         # Normalize and validate function tools

python/packages/bedrock/AGENTS.md

@@ -12,7 +12,7 @@ Integration with AWS Bedrock for LLM inference.
 ## Usage
 
 ```python
-from agent_framework_bedrock import BedrockChatClient
+from agent_framework.amazon import BedrockChatClient
 
 client = BedrockChatClient(model_id="anthropic.claude-3-sonnet-20240229-v1:0")
 response = await client.get_response("Hello")
@@ -21,5 +21,5 @@ response = await client.get_response("Hello")
 ## Import Path
 
 ```python
-from agent_framework_bedrock import BedrockChatClient
+from agent_framework.amazon import BedrockChatClient
 ```

python/packages/bedrock/README.md

@@ -12,7 +12,7 @@ The Bedrock integration enables Microsoft Agent Framework applications to call A
 
 ### Basic Usage Example
 
-See the [Bedrock sample script](samples/bedrock_sample.py) for a runnable end-to-end script that:
+See the [Bedrock sample](../../samples/02-agents/providers/amazon/bedrock_chat_client.py) for a runnable end-to-end script that:
 
 - Loads credentials from the `BEDROCK_*` environment variables
 - Instantiates `BedrockChatClient`

python/packages/bedrock/agent_framework_bedrock/_chat_client.py

@@ -260,7 +260,7 @@ def __init__(
         Examples:
             .. code-block:: python
 
-                from agent_framework.bedrock import BedrockChatClient
+                from agent_framework.amazon import BedrockChatClient
 
                 # Basic usage with default credentials
                 client = BedrockChatClient(model_id="<model name>")