diff --git a/python/packages/core/agent_framework/_clients.py b/python/packages/core/agent_framework/_clients.py
index fb1d0ab3662..5e659dc6e22 100644
--- a/python/packages/core/agent_framework/_clients.py
+++ b/python/packages/core/agent_framework/_clients.py
@@ -581,9 +581,9 @@ def as_agent(
         tokenizer: TokenizerProtocol | None = None,
         additional_properties: Mapping[str, Any] | None = None,
     ) -> Agent[OptionsCoT]:
-        """Create a Agent with this client.
+        """Create an Agent with this client.
 
-        This is a convenience method that creates a Agent instance with this
+        This is a convenience method that creates an Agent instance with this
         chat client already configured.
 
         Keyword Args:
@@ -614,7 +614,7 @@ def as_agent(
             additional_properties: Additional properties stored on the created agent.
 
         Returns:
-            A Agent instance configured with this chat client.
+            An Agent instance configured with this chat client.
 
         Examples:
             .. code-block:: python
@@ -671,11 +671,11 @@ class SupportsCodeInterpreterTool(Protocol):
     Examples:
         .. code-block:: python
 
-            from agent_framework import SupportsCodeInterpreterTool
+            from agent_framework import Agent, SupportsCodeInterpreterTool
 
             if isinstance(client, SupportsCodeInterpreterTool):
                 tool = client.get_code_interpreter_tool()
-                agent = ChatAgent(client, tools=[tool])
+                agent = Agent(client, tools=[tool])
     """
 
     @staticmethod
@@ -686,7 +686,7 @@ def get_code_interpreter_tool(**kwargs: Any) -> Any:
             **kwargs: Provider-specific configuration options.
 
         Returns:
-            A tool configuration ready to pass to ChatAgent.
+            A tool configuration ready to pass to Agent.
         """
         ...
 
@@ -701,11 +701,11 @@ class SupportsWebSearchTool(Protocol):
     Examples:
         .. code-block:: python
 
-            from agent_framework import SupportsWebSearchTool
+            from agent_framework import Agent, SupportsWebSearchTool
 
             if isinstance(client, SupportsWebSearchTool):
                 tool = client.get_web_search_tool()
-                agent = ChatAgent(client, tools=[tool])
+                agent = Agent(client, tools=[tool])
     """
 
     @staticmethod
@@ -716,7 +716,7 @@ def get_web_search_tool(**kwargs: Any) -> Any:
             **kwargs: Provider-specific configuration options.
 
         Returns:
-            A tool configuration ready to pass to ChatAgent.
+            A tool configuration ready to pass to Agent.
         """
         ...
 
@@ -731,11 +731,11 @@ class SupportsImageGenerationTool(Protocol):
     Examples:
         .. code-block:: python
 
-            from agent_framework import SupportsImageGenerationTool
+            from agent_framework import Agent, SupportsImageGenerationTool
 
             if isinstance(client, SupportsImageGenerationTool):
                 tool = client.get_image_generation_tool()
-                agent = ChatAgent(client, tools=[tool])
+                agent = Agent(client, tools=[tool])
     """
 
     @staticmethod
@@ -746,7 +746,7 @@ def get_image_generation_tool(**kwargs: Any) -> Any:
             **kwargs: Provider-specific configuration options.
 
         Returns:
-            A tool configuration ready to pass to ChatAgent.
+            A tool configuration ready to pass to Agent.
         """
         ...
 
@@ -761,11 +761,11 @@ class SupportsMCPTool(Protocol):
     Examples:
         .. code-block:: python
 
-            from agent_framework import SupportsMCPTool
+            from agent_framework import Agent, SupportsMCPTool
 
             if isinstance(client, SupportsMCPTool):
                 tool = client.get_mcp_tool(name="my_mcp", url="https://...")
-                agent = ChatAgent(client, tools=[tool])
+                agent = Agent(client, tools=[tool])
     """
 
     @staticmethod
@@ -777,7 +777,7 @@ def get_mcp_tool(**kwargs: Any) -> Any:
                 name and url for the MCP server.
 
         Returns:
-            A tool configuration ready to pass to ChatAgent.
+            A tool configuration ready to pass to Agent.
         """
         ...
 
@@ -792,11 +792,11 @@ class SupportsFileSearchTool(Protocol):
     Examples:
         .. code-block:: python
 
-            from agent_framework import SupportsFileSearchTool
+            from agent_framework import Agent, SupportsFileSearchTool
 
             if isinstance(client, SupportsFileSearchTool):
                 tool = client.get_file_search_tool(vector_store_ids=["vs_123"])
-                agent = ChatAgent(client, tools=[tool])
+                agent = Agent(client, tools=[tool])
     """
 
     @staticmethod
@@ -807,7 +807,7 @@ def get_file_search_tool(**kwargs: Any) -> Any:
             **kwargs: Provider-specific configuration options.
 
         Returns:
-            A tool configuration ready to pass to ChatAgent.
+            A tool configuration ready to pass to Agent.
         """
         ...
 
@@ -822,11 +822,15 @@ class SupportsShellTool(Protocol):
     Examples:
         .. code-block:: python
 
-            from agent_framework import SupportsShellTool
+            from agent_framework import Agent, SupportsShellTool
+            from agent_framework_tools.shell import LocalShellTool
 
-            if isinstance(client, SupportsShellTool):
-                tool = client.get_shell_tool(func=shell.as_function())
-                agent = ChatAgent(client, tools=[tool])
+
+            async def build_agent(client):
+                if isinstance(client, SupportsShellTool):
+                    async with LocalShellTool() as shell:
+                        tool = client.get_shell_tool(func=shell.as_function())
+                        return Agent(client, tools=[tool])
     """
 
     @staticmethod
@@ -837,7 +841,7 @@ def get_shell_tool(**kwargs: Any) -> Any:
             **kwargs: Provider-specific configuration options.
 
         Returns:
-            A tool configuration ready to pass to ChatAgent.
+            A tool configuration ready to pass to Agent.
         """
         ...