Python: Enhanced documentation for dependency injection and serialization features (#1324)

* improvements in dep injection and sample

* fix for falsy default

* fix mypy

* update to use a nested dict instead of a string.

* clarify docs

* Update python/packages/core/agent_framework/_tools.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update python/packages/core/agent_framework/_tools.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update python/packages/core/agent_framework/_tools.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update python/packages/core/agent_framework/_serialization.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* format

---------

Co-authored-by: eavanvalkenburg <github@vanvalkenburg.eu>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

python/packages/core/tests/core/test_serializable_mixin.py

@@ -45,7 +45,7 @@ class TestSerializationMixin:
         with caplog.at_level(logging.DEBUG):
             obj = TestClass.from_dict(
                 {"type": "test_class", "value": "test"},
-                dependencies={"test_class.client": mock_client},
+                dependencies={"test_class": {"client": mock_client}},
             )
 
         assert obj.value == "test"
@@ -68,7 +68,7 @@ class TestSerializationMixin:
         with caplog.at_level(logging.DEBUG):
             obj = TestClass.from_dict(
                 {"type": "test_class", "value": "test"},
-                dependencies={"test_class.other": mock_other},
+                dependencies={"test_class": {"other": mock_other}},
             )
 
         assert obj.value == "test"
@@ -105,9 +105,11 @@ class TestSerializationMixin:
             obj = TestClass.from_dict(
                 {"type": "test_class", "value": "test"},
                 dependencies={
-                    "test_class.client": mock_client,
-                    "test_class.logger": mock_logger,
-                    "test_class.other": mock_other,
+                    "test_class": {
+                        "client": mock_client,
+                        "logger": mock_logger,
+                        "other": mock_other,
+                    }
                 },
             )
 
@@ -136,7 +138,7 @@ class TestSerializationMixin:
         with caplog.at_level(logging.DEBUG):
             obj = TestClass.from_dict(
                 {"type": "test_class", "value": "test"},
-                dependencies={"test_class.client": mock_client},
+                dependencies={"test_class": {"client": mock_client}},
             )
 
         assert obj.value == "test"
@@ -184,7 +186,7 @@ class TestSerializationMixin:
         assert "client" not in data  # Excluded from serialization
 
         # Deserialize with dependency injection
-        restored = TestClass.from_dict(data, dependencies={"test_class.client": mock_client})
+        restored = TestClass.from_dict(data, dependencies={"test_class": {"client": mock_client}})
         assert restored.value == "test"
         assert restored.number == 42
         assert restored.client == mock_client

python/packages/core/tests/core/test_tools.py

@@ -299,6 +299,48 @@ async def test_ai_function_invoke_invalid_pydantic_args():
         await invalid_args_test.invoke(arguments=wrong_args)
 
 
+def test_ai_function_serialization():
+    """Test AIFunction serialization and deserialization."""
+
+    def serialize_test(x: int, y: int) -> int:
+        """A function for testing serialization."""
+        return x - y
+
+    serialize_test_ai_function = ai_function(name="serialize_test", description="A test tool for serialization")(
+        serialize_test
+    )
+
+    # Serialize to dict
+    tool_dict = serialize_test_ai_function.to_dict()
+    assert tool_dict["type"] == "ai_function"
+    assert tool_dict["name"] == "serialize_test"
+    assert tool_dict["description"] == "A test tool for serialization"
+    assert tool_dict["input_model"] == {
+        "properties": {"x": {"title": "X", "type": "integer"}, "y": {"title": "Y", "type": "integer"}},
+        "required": ["x", "y"],
+        "title": "serialize_test_input",
+        "type": "object",
+    }
+
+    # Deserialize from dict
+    restored_tool = AIFunction.from_dict(tool_dict, dependencies={"ai_function": {"func": serialize_test}})
+    assert isinstance(restored_tool, AIFunction)
+    assert restored_tool.name == "serialize_test"
+    assert restored_tool.description == "A test tool for serialization"
+    assert restored_tool.parameters() == serialize_test_ai_function.parameters()
+    assert restored_tool(10, 4) == 6
+
+    # Deserialize from dict with instance name
+    restored_tool_2 = AIFunction.from_dict(
+        tool_dict, dependencies={"ai_function": {"name:serialize_test": {"func": serialize_test}}}
+    )
+    assert isinstance(restored_tool_2, AIFunction)
+    assert restored_tool_2.name == "serialize_test"
+    assert restored_tool_2.description == "A test tool for serialization"
+    assert restored_tool_2.parameters() == serialize_test_ai_function.parameters()
+    assert restored_tool_2(10, 4) == 6
+
+
 # region HostedCodeInterpreterTool and _parse_inputs