Update Python docs to align with current code (github#943)

brettcannon · Copilot · Copilot · web-flow · commit c9b998bdfd93 · 2026-03-26T18:59:21.000Z
* Update Python docs to align with current code

* Update docs/getting-started.md

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* Review comment fixes

* refactor: replace if-elif with match-case for event handling in README example

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs/auth/byok.md b/docs/auth/byok.md
@@ -23,7 +23,8 @@ Azure AI Foundry (formerly Azure OpenAI) is a common BYOK deployment target for
 ```python
 import asyncio
 import os
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient
+from copilot.session import PermissionHandler
 
 FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/"
 # Set FOUNDRY_API_KEY environment variable
diff --git a/docs/features/custom-agents.md b/docs/features/custom-agents.md
@@ -414,9 +414,7 @@ def handle_event(event):
 
 unsubscribe = session.on(handle_event)
 
-response = await session.send_and_wait({
-    "prompt": "Research how authentication works in this codebase"
-})
+response = await session.send_and_wait("Research how authentication works in this codebase")
 ```
 
 </details>
diff --git a/docs/features/image-input.md b/docs/features/image-input.md
@@ -258,15 +258,15 @@ await session.send({
 
 ```python
 from copilot import CopilotClient
-from copilot.types import PermissionRequestResult
+from copilot.session import PermissionRequestResult
 
 client = CopilotClient()
 await client.start()
 
-session = await client.create_session({
-    "model": "gpt-4.1",
-    "on_permission_request": lambda req, inv: PermissionRequestResult(kind="approved"),
-})
+session = await client.create_session(
+    on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"),
+    model="gpt-4.1",
+)
 
 base64_image_data = "..."  # your base64-encoded image
 await session.send(
diff --git a/docs/features/mcp.md b/docs/features/mcp.md
@@ -59,7 +59,8 @@ const session = await client.createSession({
 
 ```python
 import asyncio
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient
+from copilot.session import PermissionHandler
 
 async def main():
     client = CopilotClient()
@@ -85,9 +86,7 @@ async def main():
         },
     })
 
-    response = await session.send_and_wait({
-        "prompt": "List my recent GitHub notifications"
-    })
+    response = await session.send_and_wait("List my recent GitHub notifications")
     print(response.data.content)
 
     await client.stop()
diff --git a/docs/features/session-persistence.md b/docs/features/session-persistence.md
@@ -46,7 +46,8 @@ await session.sendAndWait({ prompt: "Analyze my codebase" });
 ### Python
 
 ```python
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient
+from copilot.session import PermissionHandler
 
 client = CopilotClient()
 await client.start()
@@ -55,7 +56,7 @@ await client.start()
 session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.2-codex", session_id="user-123-task-456")
 
 # Do some work...
-await session.send_and_wait({"prompt": "Analyze my codebase"})
+await session.send_and_wait("Analyze my codebase")
 
 # Session state is automatically persisted
 ```
@@ -160,7 +161,7 @@ await session.sendAndWait({ prompt: "What did we discuss earlier?" });
 session = await client.resume_session("user-123-task-456", on_permission_request=PermissionHandler.approve_all)
 
 # Continue where you left off
-await session.send_and_wait({"prompt": "What did we discuss earlier?"})
+await session.send_and_wait("What did we discuss earlier?")
 ```
 
 ### Go
@@ -413,7 +414,7 @@ Each SDK also provides idiomatic automatic cleanup patterns:
 | Language | Pattern | Example |
 |----------|---------|---------|
 | **TypeScript** | `Symbol.asyncDispose` | `await using session = await client.createSession(config);` |
-| **Python** | `async with` context manager | `async with await client.create_session(config) as session:` |
+| **Python** | `async with` context manager | `async with await client.create_session(on_permission_request=handler) as session:` |
 | **C#** | `IAsyncDisposable` | `await using var session = await client.CreateSessionAsync(config);` |
 | **Go** | `defer` | `defer session.Disconnect()` |
 
diff --git a/docs/features/skills.md b/docs/features/skills.md
@@ -59,7 +59,7 @@ async def main():
     )
 
     # Copilot now has access to skills in those directories
-    await session.send_and_wait({"prompt": "Review this code for security issues"})
+    await session.send_and_wait("Review this code for security issues")
 
     await client.stop()
 ```
@@ -160,7 +160,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import PermissionHandler
+from copilot.session import PermissionHandler
 
 session = await client.create_session(
     on_permission_request=PermissionHandler.approve_all,
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -137,9 +137,7 @@ async def main():
     await client.start()
 
     session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
-    response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
-
-    response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
+    response = await session.send_and_wait("What is 2 + 2?")
     print(response.data.content)
 
     await client.stop()
@@ -296,7 +294,7 @@ async def main():
 
     session.on(handle_event)
 
-    await session.send_and_wait({"prompt": "Tell me a short joke"})
+    await session.send_and_wait("Tell me a short joke")
 
     await client.stop()
 
@@ -430,10 +428,11 @@ unsubscribeIdle();
 ```python
 from copilot import CopilotClient
 from copilot.generated.session_events import SessionEvent, SessionEventType
+from copilot.session import PermissionRequestResult
 
 client = CopilotClient()
 
-session = client.create_session(on_permission_request=lambda req, inv: {"kind": "approved"})
+session = await client.create_session(on_permission_request=lambda req, inv: PermissionRequestResult(kind="approved"))
 
 # Subscribe to all events
 unsubscribe = session.on(lambda event: print(f"Event: {event.type}"))
@@ -688,9 +687,7 @@ async def main():
 
     session.on(handle_event)
 
-    await session.send_and_wait({
-        "prompt": "What's the weather like in Seattle and Tokyo?"
-    })
+    await session.send_and_wait("What's the weather like in Seattle and Tokyo?")
 
     await client.stop()
 
@@ -965,7 +962,7 @@ async def main():
             break
 
         sys.stdout.write("Assistant: ")
-        await session.send_and_wait({"prompt": user_input})
+        await session.send_and_wait(user_input)
         print("\n")
 
     await client.stop()
diff --git a/docs/hooks/error-handling.md b/docs/hooks/error-handling.md
@@ -146,7 +146,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import PermissionHandler
+from copilot.session import PermissionHandler
 
 async def on_error_occurred(input_data, invocation):
     print(f"[{invocation['session_id']}] Error: {input_data['error']}")
diff --git a/docs/hooks/index.md b/docs/hooks/index.md
@@ -53,7 +53,8 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient
+from copilot.session import PermissionHandler
 
 async def main():
     client = CopilotClient()
diff --git a/docs/hooks/post-tool-use.md b/docs/hooks/post-tool-use.md
@@ -145,7 +145,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import PermissionHandler
+from copilot.session import PermissionHandler
 
 async def on_post_tool_use(input_data, invocation):
     print(f"[{invocation['session_id']}] Tool: {input_data['toolName']}")
diff --git a/docs/hooks/pre-tool-use.md b/docs/hooks/pre-tool-use.md
@@ -153,7 +153,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import PermissionHandler
+from copilot.session import PermissionHandler
 
 async def on_pre_tool_use(input_data, invocation):
     print(f"[{invocation['session_id']}] Calling {input_data['toolName']}")
diff --git a/docs/hooks/session-lifecycle.md b/docs/hooks/session-lifecycle.md
@@ -152,7 +152,7 @@ Package manager: ${projectInfo.packageManager}
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import PermissionHandler
+from copilot.session import PermissionHandler
 
 async def on_session_start(input_data, invocation):
     print(f"Session {invocation['session_id']} started ({input_data['source']})")
@@ -371,7 +371,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import PermissionHandler
+from copilot.session import PermissionHandler
 
 session_start_times = {}
 
diff --git a/docs/hooks/user-prompt-submitted.md b/docs/hooks/user-prompt-submitted.md
@@ -141,7 +141,7 @@ const session = await client.createSession({
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import PermissionHandler
+from copilot.session import PermissionHandler
 
 async def on_user_prompt_submitted(input_data, invocation):
     print(f"[{invocation['session_id']}] User: {input_data['prompt']}")
diff --git a/docs/setup/azure-managed-identity.md b/docs/setup/azure-managed-identity.md
@@ -43,7 +43,7 @@ import os
 
 from azure.identity import DefaultAzureCredential
 from copilot import CopilotClient
-from copilot.session import ProviderConfig, SessionConfig
+from copilot.session import PermissionHandler, ProviderConfig
 
 COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"
 
@@ -59,18 +59,17 @@ async def main():
     await client.start()
 
     session = await client.create_session(
-        SessionConfig(
-            model="gpt-4.1",
-            provider=ProviderConfig(
-                type="openai",
-                base_url=f"{foundry_url.rstrip('/')}/openai/v1/",
-                bearer_token=token,  # Short-lived bearer token
-                wire_api="responses",
-            ),
-        )
+        on_permission_request=PermissionHandler.approve_all,
+        model="gpt-4.1",
+        provider=ProviderConfig(
+            type="openai",
+            base_url=f"{foundry_url.rstrip('/')}/openai/v1/",
+            bearer_token=token,  # Short-lived bearer token
+            wire_api="responses",
+        ),
     )
 
-    response = await session.send_and_wait({"prompt": "Hello from Managed Identity!"})
+    response = await session.send_and_wait("Hello from Managed Identity!")
     print(response.data.content)
 
     await client.stop()
@@ -86,7 +85,7 @@ Bearer tokens expire (typically after ~1 hour). For servers or long-running agen
 ```python
 from azure.identity import DefaultAzureCredential
 from copilot import CopilotClient
-from copilot.session import ProviderConfig, SessionConfig
+from copilot.session import PermissionHandler, ProviderConfig
 
 COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"
 
@@ -100,26 +99,26 @@ class ManagedIdentityCopilotAgent:
         self.credential = DefaultAzureCredential()
         self.client = CopilotClient()
 
-    def _get_session_config(self) -> SessionConfig:
-        """Build a SessionConfig with a fresh bearer token."""
+    def _get_provider_config(self) -> ProviderConfig:
+        """Build a ProviderConfig with a fresh bearer token."""
         token = self.credential.get_token(COGNITIVE_SERVICES_SCOPE).token
-        return SessionConfig(
-            model=self.model,
-            provider=ProviderConfig(
-                type="openai",
-                base_url=f"{self.foundry_url}/openai/v1/",
-                bearer_token=token,
-                wire_api="responses",
-            ),
+        return ProviderConfig(
+            type="openai",
+            base_url=f"{self.foundry_url}/openai/v1/",
+            bearer_token=token,
+            wire_api="responses",
         )
 
     async def chat(self, prompt: str) -> str:
         """Send a prompt and return the response text."""
         # Fresh token for each session
-        config = self._get_session_config()
-        session = await self.client.create_session(config)
+        session = await self.client.create_session(
+            on_permission_request=PermissionHandler.approve_all,
+            model=self.model,
+            provider=self._get_provider_config(),
+        )
 
-        response = await session.send_and_wait({"prompt": prompt})
+        response = await session.send_and_wait(prompt)
         await session.disconnect()
 
         return response.data.content if response else ""
diff --git a/docs/setup/backend-services.md b/docs/setup/backend-services.md
@@ -111,16 +111,15 @@ res.json({ content: response?.data.content });
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient, ExternalServerConfig
+from copilot.session import PermissionHandler
 
-client = CopilotClient({
-    "cli_url": "localhost:4321",
-})
+client = CopilotClient(ExternalServerConfig(url="localhost:4321"))
 await client.start()
 
 session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", session_id=f"user-{user_id}-{int(time.time())}")
 
-response = await session.send_and_wait({"prompt": message})
+response = await session.send_and_wait(message)
 ```
 
 </details>
diff --git a/docs/setup/bundled-cli.md b/docs/setup/bundled-cli.md
@@ -85,7 +85,8 @@ await client.stop();
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient
+from copilot.session import PermissionHandler
 from pathlib import Path
 
 client = CopilotClient({
@@ -94,7 +95,7 @@ client = CopilotClient({
 await client.start()
 
 session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
-response = await session.send_and_wait({"prompt": "Hello!"})
+response = await session.send_and_wait("Hello!")
 print(response.data.content)
 
 await client.stop()
diff --git a/docs/setup/github-oauth.md b/docs/setup/github-oauth.md
@@ -145,7 +145,8 @@ const response = await session.sendAndWait({ prompt: "Hello!" });
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient
+from copilot.session import PermissionHandler
 
 def create_client_for_user(user_token: str) -> CopilotClient:
     return CopilotClient({
@@ -159,7 +160,7 @@ await client.start()
 
 session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1", session_id=f"user-{user_id}-session")
 
-response = await session.send_and_wait({"prompt": "Hello!"})
+response = await session.send_and_wait("Hello!")
 ```
 
 </details>
diff --git a/docs/setup/local-cli.md b/docs/setup/local-cli.md
@@ -51,13 +51,14 @@ await client.stop();
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient, PermissionHandler
+from copilot import CopilotClient
+from copilot.session import PermissionHandler
 
 client = CopilotClient()
 await client.start()
 
 session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
-response = await session.send_and_wait({"prompt": "Hello!"})
+response = await session.send_and_wait("Hello!")
 print(response.data.content)
 
 await client.stop()
diff --git a/python/README.md b/python/README.md
diff --git a/python/copilot/client.py b/python/copilot/client.py
diff --git a/python/copilot/session.py b/python/copilot/session.py
