update example to make the devex better, added reference to env var to reduce grpc warning

Signed-off-by: Filinto Duran <[email protected]>

Author: filintod

docs/sessions/dapr_session.md

@@ -78,9 +78,6 @@ First, start the Dapr sidecar with a state store. The simplest way is using Redi
 ```bash
 # Start Redis (if not already running)
 docker run -d -p 6379:6379 redis:7-alpine
-
-# Start Dapr sidecar with Redis state store
-dapr run --app-id myapp --dapr-grpc-port 50001 --components-path ./components
 ```
 
 Create a component configuration file at `./components/statestore.yaml`:
@@ -100,43 +97,75 @@ spec:
     value: ""
 ```
 
-Now use DaprSession in your code:
+Create your Python application (save as `example.py`):
 
 ```python
+import asyncio
+import os
+
 from agents import Agent, Runner
 from agents.extensions.memory import DaprSession
 
-# Create agent
-agent = Agent(
-    name="Assistant",
-    instructions="Reply very concisely.",
-)
+grpc_port = os.environ.get("DAPR_GRPC_PORT", "50001")
 
-# Connect to Dapr sidecar (using default gRPC port 50001)
-session = DaprSession.from_address(
-    session_id="user-123",
-    state_store_name="statestore",
-    dapr_address="localhost:50001",  # Default Dapr gRPC port
-)
 
-# First turn
-result = await Runner.run(
-    agent,
-    "What city is the Golden Gate Bridge in?",
-    session=session
-)
-print(result.final_output)  # "San Francisco"
+async def main():
+    # Create agent
+    agent = Agent(
+        name="Assistant",
+        instructions="Reply very concisely.",
+    )
 
-# Second turn - agent remembers context
-result = await Runner.run(
-    agent,
-    "What state is it in?",
-    session=session
-)
-print(result.final_output)  # "California"
+    # Connect to Dapr sidecar (using default gRPC port 50001)
+    session = DaprSession.from_address(
+        session_id="user-123",
+        state_store_name="statestore",
+        dapr_address=f"localhost:{grpc_port}",
+    )
+
+    try:
+        # First turn
+        result = await Runner.run(
+            agent,
+            "What city is the Golden Gate Bridge in?",
+            session=session
+        )
+        print(f"Agent: {result.final_output}")  # "San Francisco"
+
+        # Second turn - agent remembers context
+        result = await Runner.run(
+            agent,
+            "What state is it in?",
+            session=session
+        )
+        print(f"Agent: {result.final_output}")  # "California"
+
+    finally:
+        # Always clean up
+        await session.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Now run your application **with the Dapr sidecar**:
 
-# Clean up
-await session.close()
+**Option 1: Run with Dapr (recommended)**
+
+```bash
+# Dapr starts the sidecar AND runs your application
+dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 --resources-path ./components -- python example.py
+```
+
+**Option 2: Run separately (for development)**
+
+```bash
+# Terminal 1: Start Dapr sidecar
+dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 --resources-path ./components
+
+# Terminal 2: Run your application (in a separate terminal)
+python example.py
 ```
 
 **What's happening here?**
@@ -145,6 +174,12 @@ await session.close()
 3. The agent can retrieve previous messages across multiple turns
 4. When you scale to multiple instances, all instances share the same session state
 
+**Want a more complete example?** See [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/blob/main/examples/memory/dapr_session_example.py) which demonstrates:
+- Multi-turn conversations with context
+- Session isolation and multi-tenancy
+- TTL and consistency levels
+- All with detailed output and comments
+
 ## Usage patterns
 
 ### Dapr ports
@@ -155,17 +190,20 @@ The `DaprSession` communicates with the Dapr sidecar using network ports. Dapr e
 - **HTTP port: 3500** - For REST API and health checks
 - **Metrics port: 9090** - For Prometheus metrics (monitoring)
 
-When starting the Dapr sidecar, you can specify custom ports if needed:
+When starting the Dapr sidecar, explicitly specify both ports to avoid connection issues:
 
 ```bash
 # Using default ports (recommended)
-dapr run --app-id myapp --components-path ./components
+dapr run --app-id myapp \
+  --dapr-http-port 3500 \
+  --dapr-grpc-port 50001 \
+  --resources-path ./components
 
-# Using custom ports
+# Using custom ports (in case of conflicts with other services)
 dapr run --app-id myapp \
-  --dapr-grpc-port 50002 \
   --dapr-http-port 3501 \
-  --components-path ./components
+  --dapr-grpc-port 50002 \
+  --resources-path ./components
 ```
 
 If using custom ports, specify them in your session connection:
@@ -556,9 +594,27 @@ else:
 ```
 
 Common issues:
+
+**Health check connection refused (port 3500)**:
+- **Cause**: The `--dapr-http-port` was not specified, so Dapr used a random port
+- **Solution 1**: Always explicitly set `--dapr-http-port 3500` when starting Dapr (recommended)
+- **Solution 2**: Set the HTTP endpoint via environment variable before creating the session:
+  ```python
+  import os
+  # Option A: Set full endpoint
+  os.environ["DAPR_HTTP_ENDPOINT"] = "http://localhost:3500"
+  
+  # Option B: Set just the port (SDK will construct http://localhost:PORT)
+  os.environ["DAPR_HTTP_PORT"] = "3500"
+  
+  # Then create your session
+  session = DaprSession.from_address(...)
+  ```
+
+**Other issues**:
 - Check that `dapr run` is active (use `dapr list` to see running sidecars)
 - Verify the gRPC port matches (default: 50001)
-- Ensure no firewall blocking the port
+- Ensure no firewall blocking the ports
 - Check that the Dapr sidecar finished initializing (check logs with `dapr logs --app-id myapp`)
 
 ### Configuration error: State store not found
@@ -570,13 +626,38 @@ Common issues:
 **Solution**: Ensure your component YAML file is in the components directory specified when starting Dapr:
 
 ```bash
-dapr run --app-id myapp --dapr-grpc-port 50001 --components-path ./components
+dapr run --app-id myapp \
+  --dapr-http-port 3500 \
+  --dapr-grpc-port 50001 \
+  --resources-path ./components
 ```
 
 ### TTL not working
 
 Verify your state store [supports TTL](https://docs.dapr.io/reference/components-reference/supported-state-stores/) and is properly configured.
 
+### gRPC fork warnings on first API call
+
+**Symptom**: You see informational messages like `This process is fork-safe due to gRPC...` on the first OpenAI API call.
+
+**Cause**: When `DaprSession` initializes, it creates gRPC background threads. The first OpenAI API call then initializes HTTP worker threads, and gRPC detects this concurrent thread creation and logs safety information.
+
+**Impact**: These are informational messages, not errors. They only appear once and don't affect functionality.
+
+**Solution** (optional): If you want to suppress these messages, set the gRPC verbosity level before creating the session:
+
+```python
+import os
+
+# Suppress gRPC informational messages
+os.environ["GRPC_VERBOSITY"] = "ERROR"
+
+# Now create your session
+session = DaprSession.from_address(...)
+```
+
+**Note**: These warnings are expected when using gRPC-based libraries (like Dapr) alongside other async HTTP libraries. They indicate that gRPC's fork handlers are working correctly to ensure thread safety.
+
 ## API reference
 
 For detailed API documentation, see:

examples/memory/dapr_session_example.py

@@ -16,6 +16,11 @@
 """
 
 import asyncio
+import os
+
+os.environ["GRPC_VERBOSITY"] = (
+    "ERROR"  # Suppress gRPC warnings caused by the Dapr Python SDK gRPC connection.
+)
 
 from agents import Agent, Runner
 from agents.extensions.memory import (
@@ -24,6 +29,8 @@
     DaprSession,
 )
 
+grpc_port = os.environ.get("DAPR_GRPC_PORT", "50001")
+
 
 async def main():
     # Create an agent
@@ -35,7 +42,7 @@ async def main():
     print("=== Dapr Session Example ===")
     print("This example requires Dapr sidecar to be running")
     print(
-        "Start Dapr with: dapr run --app-id myapp --dapr-grpc-port 50001 --components-path ./components"
+        "Start Dapr with: dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 --resources-path ./components"
     )  # noqa: E501
     print()
 
@@ -45,15 +52,15 @@ async def main():
         session = DaprSession.from_address(
             session_id,
             state_store_name="statestore",
-            dapr_address="localhost:50001",
+            dapr_address=f"localhost:{grpc_port}",
         )
 
         # Test Dapr connectivity
         if not await session.ping():
             print("Dapr sidecar is not available!")
             print("Please start Dapr sidecar and try again.")
             print(
-                "Command: dapr run --app-id myapp --dapr-grpc-port 50001 --components-path ./components"
+                "Command: dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 --resources-path ./components"
             )  # noqa: E501
             return
 
@@ -118,7 +125,7 @@ async def main():
         new_session = DaprSession.from_address(
             "different_conversation_456",
             state_store_name="statestore",
-            dapr_address="localhost:50001",
+            dapr_address=f"localhost:{grpc_port}",
         )
 
         print("Creating a new session with different ID...")
@@ -146,7 +153,7 @@ async def main():
     except Exception as e:
         print(f"Error: {e}")
         print(
-            "Make sure Dapr sidecar is running with: dapr run --app-id myapp --dapr-grpc-port 50001 --components-path ./components"
+            "Make sure Dapr sidecar is running with: dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 --resources-path ./components"
         )  # noqa: E501
 
 
@@ -160,7 +167,7 @@ async def demonstrate_advanced_features():
         ttl_session = DaprSession.from_address(
             "ttl_demo_session",
             state_store_name="statestore",
-            dapr_address="localhost:50001",
+            dapr_address=f"localhost:{grpc_port}",
             ttl=3600,  # 1 hour TTL
         )
 
@@ -182,15 +189,15 @@ async def demonstrate_advanced_features():
         eventual_session = DaprSession.from_address(
             "eventual_session",
             state_store_name="statestore",
-            dapr_address="localhost:50001",
+            dapr_address=f"localhost:{grpc_port}",
             consistency=DAPR_CONSISTENCY_EVENTUAL,
         )
 
         # Strong consistency (guaranteed read-after-write)
         strong_session = DaprSession.from_address(
             "strong_session",
             state_store_name="statestore",
-            dapr_address="localhost:50001",
+            dapr_address=f"localhost:{grpc_port}",
             consistency=DAPR_CONSISTENCY_STRONG,
         )
 
@@ -213,7 +220,7 @@ def get_tenant_session(tenant_id: str, user_id: str) -> DaprSession:
             return DaprSession.from_address(
                 session_id,
                 state_store_name="statestore",
-                dapr_address="localhost:50001",
+                dapr_address=f"localhost:{grpc_port}",
             )
 
         tenant_a_session = get_tenant_session("tenant-a", "user-123")
@@ -254,7 +261,9 @@ async def setup_instructions():
     print("\n3. Start Redis:")
     print("   docker run -d -p 6379:6379 redis:7-alpine")
     print("\n4. Start Dapr sidecar:")
-    print("   dapr run --app-id myapp --dapr-grpc-port 50001 --components-path ./components")
+    print(
+        "   dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 --resources-path ./components"
+    )
     print("\n5. Run this example:")
     print("   python examples/memory/dapr_session_example.py")
     print("\nAlternatively, you can use other state stores supported by Dapr:")

src/agents/extensions/memory/dapr_session.py

@@ -104,6 +104,12 @@ def from_address(
 
         Returns:
             DaprSession: An instance of DaprSession connected to the specified Dapr sidecar.
+
+        Note:
+            The Dapr Python SDK performs health checks on the HTTP endpoint (default: http://localhost:3500).
+            Ensure the Dapr sidecar is started with --dapr-http-port 3500. Alternatively, set one of
+            these environment variables: DAPR_HTTP_ENDPOINT (e.g., "http://localhost:3500") or
+            DAPR_HTTP_PORT (e.g., "3500") to avoid connection errors.
         """
         dapr_client = DaprClient(address=dapr_address)
         session = cls(

test.py

@@ -0,0 +1,49 @@
+import asyncio
+import os
+os.environ["GRPC_VERBOSITY"] = (
+    "ERROR"  # Suppress gRPC warnings caused by the Dapr Python SDK gRPC connection.
+)
+from agents import Agent, Runner
+from agents.extensions.memory import DaprSession
+
+grpc_port = os.environ.get("DAPR_GRPC_PORT", "50001")
+
+
+async def main():
+    # Create agent
+    agent = Agent(
+        name="Assistant",
+        instructions="Reply very concisely.",
+    )
+
+    # Connect to Dapr sidecar (using default gRPC port 50001)
+    session = DaprSession.from_address(
+        session_id="user-123",
+        state_store_name="statestore",
+        dapr_address=f"localhost:{grpc_port}",
+    )
+
+    try:
+        # First turn
+        result = await Runner.run(
+            agent,
+            "What city is the Golden Gate Bridge in?",
+            session=session
+        )
+        print(f"Agent: {result.final_output}")  # "San Francisco"
+
+        # Second turn - agent remembers context
+        result = await Runner.run(
+            agent,
+            "What state is it in?",
+            session=session
+        )
+        print(f"Agent: {result.final_output}")  # "California"
+
+    finally:
+        # Always clean up
+        await session.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())