Address PR review comments and refine chatbot architecture

- Simplify basic/worker.py to use asyncio.run(main()) pattern
- Basic activity now returns str instead of Response (drops pydantic dep)
- Remove pydantic_data_converter from basic worker/starter
- Replace chatbot signal+poll with update handler (message_from_user)
- Wrap update handler body in @Traceable for input/output capture
- Inline RetryPolicy in chatbot workflow (no separate RETRY constant)
- Add comment about alternative traceable() function-call style
- Make PROJECT_NAME a shared constant in starters, pass to client-side
  @Traceable so traces go to the right LangSmith project
- Update READMEs with correct trace hierarchies based on real output
- Fix wrap_openai span name (ChatOpenAI, not openai.responses.create)
- Simplify tests (mocks match new str return type, use execute_update)
- Remove poll_last_response helper

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: xumaple

langsmith_tracing/README.md

@@ -5,7 +5,7 @@ This sample demonstrates [LangSmith](https://smith.langchain.com/) tracing integ
 Two examples are included:
 
 - **[basic/](basic/)** — A one-shot LLM workflow that sends a prompt to OpenAI and returns the response.
-- **[chatbot/](chatbot/)** — A long-running conversational workflow with tool calls (save/read notes), signals, and queries.
+- **[chatbot/](chatbot/)** — A long-running conversational workflow with tool calls (save/read notes) and update handlers.
 
 ## Prerequisites
 

langsmith_tracing/basic/README.md

@@ -18,13 +18,13 @@ uv run --group langsmith-tracing python -m langsmith_tracing.basic.starter
 
 ### `add_temporal_runs=False` (default)
 
-Only `@traceable` and `wrap_openai` spans appear. The client-side `@traceable` is the root, and all workflow/activity traces nest under it via context propagation:
+Only `@traceable` and `wrap_openai` spans appear. The client-side `@traceable` is the root, and workflow/activity traces nest under it via context propagation.
 
 ```
 Basic LLM Request                    (@traceable, client-side)
 └── Ask: What is Temporal?           (@traceable, workflow)
     └── Call OpenAI                   (@traceable, activity)
-        └── openai.responses.create   (automatic via wrap_openai)
+        └── ChatOpenAI                (automatic via wrap_openai)
 ```
 
 ### `add_temporal_runs=True`
@@ -36,7 +36,7 @@ uv run --group langsmith-tracing python -m langsmith_tracing.basic.worker --add-
 uv run --group langsmith-tracing python -m langsmith_tracing.basic.starter --add-temporal-runs
 ```
 
-Temporal operation spans are added. `StartWorkflow` and `RunWorkflow` are siblings under the client root; `StartActivity` and `RunActivity` are siblings under the workflow:
+Temporal operation spans are added. `StartWorkflow`/`RunWorkflow` and `StartActivity`/`RunActivity` appear as sibling pairs:
 
 ```
 Basic LLM Request                       (@traceable, client-side)
@@ -46,5 +46,5 @@ Basic LLM Request                       (@traceable, client-side)
         ├── StartActivity:call_openai   (automatic, Temporal plugin)
         └── RunActivity:call_openai     (automatic, Temporal plugin)
             └── Call OpenAI             (@traceable, activity)
-                └── openai.responses.create  (automatic via wrap_openai)
+                └── ChatOpenAI          (automatic via wrap_openai)
 ```

langsmith_tracing/basic/activities.py

@@ -5,7 +5,6 @@
 from langsmith import traceable
 from langsmith.wrappers import wrap_openai
 from openai import AsyncOpenAI
-from openai.types.responses import Response
 from temporalio import activity
 
 
@@ -18,14 +17,15 @@ class OpenAIRequest:
 
 @traceable(name="Call OpenAI", run_type="llm")
 @activity.defn
-async def call_openai(request: OpenAIRequest) -> Response:
+async def call_openai(request: OpenAIRequest) -> str:
     """Call OpenAI Responses API. Retries handled by Temporal, not the OpenAI client."""
     # wrap_openai patches the client so each API call (e.g. responses.create)
     # creates its own child span with model parameters and token usage.
     client = wrap_openai(AsyncOpenAI(max_retries=0))
-    return await client.responses.create(
+    response = await client.responses.create(
         model=request.model,
         instructions=request.instructions,
         input=request.input,
         timeout=30,
     )
+    return response.output_text

langsmith_tracing/basic/starter.py

@@ -6,7 +6,6 @@
 from langsmith import traceable
 from temporalio.client import Client
 from temporalio.contrib.langsmith import LangSmithPlugin
-from temporalio.contrib.pydantic import pydantic_data_converter
 from temporalio.envconfig import ClientConfig
 
 from langsmith_tracing.basic.workflows import BasicLLMWorkflow
@@ -27,7 +26,6 @@ async def main():
 
     client = await Client.connect(
         **config,
-        data_converter=pydantic_data_converter,
         plugins=[plugin],
     )
 

langsmith_tracing/basic/worker.py

@@ -6,15 +6,12 @@
 
 from temporalio.client import Client
 from temporalio.contrib.langsmith import LangSmithPlugin
-from temporalio.contrib.pydantic import pydantic_data_converter
 from temporalio.envconfig import ClientConfig
 from temporalio.worker import Worker
 
 from langsmith_tracing.basic.activities import call_openai
 from langsmith_tracing.basic.workflows import BasicLLMWorkflow
 
-interrupt_event = asyncio.Event()
-
 
 async def main():
     logging.basicConfig(level=logging.INFO)
@@ -33,26 +30,20 @@ async def main():
 
     client = await Client.connect(
         **config,
-        data_converter=pydantic_data_converter,
         plugins=[plugin],
     )
 
-    async with Worker(
+    worker = Worker(
         client,
         task_queue="langsmith-basic-task-queue",
         workflows=[BasicLLMWorkflow],
         activities=[call_openai],
-    ):
-        label = "with" if add_temporal_runs else "without"
-        print(f"Worker started ({label} Temporal runs in traces), ctrl+c to exit")
-        await interrupt_event.wait()
-        print("Shutting down")
+    )
+
+    label = "with" if add_temporal_runs else "without"
+    print(f"Worker started ({label} Temporal runs in traces), ctrl+c to exit")
+    await worker.run()
 
 
 if __name__ == "__main__":
-    loop = asyncio.new_event_loop()
-    try:
-        loop.run_until_complete(main())
-    except KeyboardInterrupt:
-        interrupt_event.set()
-        loop.run_until_complete(loop.shutdown_asyncgens())
+    asyncio.run(main())

langsmith_tracing/basic/workflows.py

@@ -24,11 +24,10 @@ async def run(self, prompt: str) -> str:
             tags=["basic-llm"],
         )
         async def _run() -> str:
-            response = await workflow.execute_activity(
+            return await workflow.execute_activity(
                 call_openai,
                 OpenAIRequest(model="gpt-4o-mini", input=prompt),
                 start_to_close_timeout=timedelta(seconds=60),
             )
-            return response.output_text
 
         return await _run()

langsmith_tracing/chatbot/README.md

@@ -1,6 +1,6 @@
 # Chatbot with Tool Calls
 
-A long-running conversational workflow with tool calls, signals, and queries. Demonstrates how LangSmith traces an agentic loop where the model calls tools across multiple turns.
+A long-running conversational workflow with tool calls and update handlers. Demonstrates how LangSmith traces an agentic loop where the model calls tools across multiple turns.
 
 See the [parent README](../README.md) for prerequisites.
 
@@ -25,58 +25,57 @@ The model has two tools, both implemented as `@traceable` methods on the workflo
 - **`save_note(name, content)`** — Stores a note in the workflow's in-memory dict. The note is durable because workflow state survives crashes and restarts via Temporal's event history.
 - **`read_note(name)`** — Reads a note from the workflow's in-memory dict.
 
+## Architecture
+
+The main `@workflow.run` method runs a loop that processes user messages (calls `_query_openai`, which handles the tool-call loop). The `message_from_user` update handler coordinates: it hands the message to the main loop via a shared `_pending_message` field, then waits for the response.
+
+This means:
+- Activity calls and the tool loop happen inside the main workflow run
+- The update handler's trace just shows the input/output of the coordination step
+
 ## Trace Structure
 
 ### `add_temporal_runs=False` (default)
 
-Only `@traceable` and `wrap_openai` spans appear. The client-side `@traceable` wraps `start_workflow`, so the workflow's traces nest under it via context propagation. Signals and queries produce no traces in this mode.
+Only `@traceable` and `wrap_openai` spans appear. The client-side `@traceable` wraps `start_workflow` and each `execute_update`, so both workflow and update traces nest under it via context propagation.
 
 ```
-Chatbot Session a1b2c3d4                      (@traceable, client-side)
-├── Turn: What's the capital of Fr..          (@traceable, client-side)
-├── Turn: Save that as a note call..          (@traceable, client-side)
-├── Turn: What did I save about pa..          (@traceable, client-side)
-└── Session Apr 17 10:30                      (@traceable, workflow)
-    ├── Request: What's the capital of France?    (@traceable, per-message)
-    │   └── Call OpenAI                           (@traceable, activity)
-    │       └── openai.responses.create           (automatic via wrap_openai)
-    ├── Request: Save that as a note called paris (@traceable, per-message)
-    │   ├── Call OpenAI                           (@traceable, activity)
-    │   │   └── openai.responses.create           → function_call: save_note
-    │   ├── Save Note                             (@traceable, workflow method)
-    │   └── Call OpenAI                           (@traceable, activity)
-    │       └── openai.responses.create           → text response
-    └── Request: What did I save about paris?     (@traceable, per-message)
-        ├── Call OpenAI                           (@traceable, activity)
-        │   └── openai.responses.create           → function_call: read_note
-        ├── Read Note                             (@traceable, workflow method)
-        └── Call OpenAI                           (@traceable, activity)
-            └── openai.responses.create           → text response
+Chatbot Session a1b2c3d4              (@traceable, client-side)
+├── Session Apr 17 10:30               (@traceable, workflow main loop)
+│   ├── Request: hello                 (@traceable, per-message in main loop)
+│   │   └── Call OpenAI                (@traceable, activity)
+│   │       └── ChatOpenAI             (automatic via wrap_openai)
+│   └── Request: save that as note 15  (@traceable, per-message in main loop)
+│       ├── Call OpenAI                → function_call: save_note
+│       ├── Save Note                  (@traceable, workflow method)
+│       └── Call OpenAI                → text response
+├── Update: hello                      (@traceable, update handler)
+└── Update: save that as note 15       (@traceable, update handler)
 ```
 
 ### `add_temporal_runs=True`
 
-With `--add-temporal-runs`, Temporal operation spans are added. `StartWorkflow` and `RunWorkflow` are siblings under the client root (context propagated via headers at `start_workflow` time). Signals and queries each get their own trace.
+With `--add-temporal-runs`, Temporal operation spans are added. `StartWorkflow`/`RunWorkflow` and `StartActivity`/`RunActivity` appear as sibling pairs.
 
 ```
 Chatbot Session a1b2c3d4                          (@traceable, client-side)
 ├── StartWorkflow:ChatbotWorkflow                 (automatic, Temporal plugin)
 ├── RunWorkflow:ChatbotWorkflow                   (automatic, Temporal plugin)
-│   └── Session Apr 17 10:30                      (@traceable, workflow)
-│       └── Request: Save that as a note called.. (@traceable, per-message)
+│   └── Session Apr 17 10:30                      (@traceable, workflow main loop)
+│       └── Request: save that as note 15         (@traceable, per-message)
 │           ├── StartActivity:call_openai         (automatic, Temporal plugin)
 │           ├── RunActivity:call_openai           (automatic, Temporal plugin)
 │           │   └── Call OpenAI                   (@traceable, activity)
-│           │       └── openai.responses.create   (automatic via wrap_openai)
+│           │       └── ChatOpenAI                (automatic via wrap_openai)
 │           ├── Save Note                         (@traceable, workflow method)
 │           ├── StartActivity:call_openai         (automatic, Temporal plugin)
 │           └── RunActivity:call_openai           (automatic, Temporal plugin)
 │               └── Call OpenAI                   (@traceable, activity)
-│                   └── openai.responses.create   (automatic via wrap_openai)
-├── Turn: Save that as a note call..              (@traceable, client-side)
-│   ├── SignalWorkflow:user_message               (automatic, Temporal plugin)
-│   │   └── HandleSignal:user_message             (automatic, Temporal plugin)
-│   └── QueryWorkflow:last_response               (automatic, Temporal plugin)
-│       └── HandleQuery:last_response             (automatic, Temporal plugin)
+│                   └── ChatOpenAI                (automatic via wrap_openai)
+├── StartWorkflowUpdate:message_from_user         (automatic, Temporal plugin)
+│   └── HandleUpdate:message_from_user            (automatic, Temporal plugin)
+│       └── Update: save that as note 15          (@traceable, update handler)
 └── ...
 ```
+
+Note that the `Request:` chain (with activity calls) lives under `RunWorkflow` (the main loop), while the `Update:` span lives under `HandleUpdate` (the update handler). They're connected by the shared workflow state but appear as separate subtrees.

langsmith_tracing/chatbot/starter.py

@@ -40,7 +40,7 @@ async def main():
         run_type="chain",
         # CRITICAL: Client-side @traceable runs outside the LangSmithPlugin's scope.
         # Make sure client-side traces use the same project_name as what is given to
-        # # the plugin.
+        # the plugin.
         project_name=PROJECT_NAME,
         tags=["client-side", "chatbot"],
     )
@@ -64,27 +64,10 @@ async def run_session():
                 print(f"\nWorkflow finished: {result}")
                 return
 
-            # Each turn gets its own trace span
-            @traceable(
-                name=f"Turn: {user_input[:40]}",
-                run_type="chain",
-                tags=["client-turn"],
+            response = await wf_handle.execute_update(
+                ChatbotWorkflow.message_from_user, user_input
             )
-            async def send_and_wait(msg: str):
-                prev_response = await wf_handle.query(ChatbotWorkflow.last_response)
-                await wf_handle.signal(ChatbotWorkflow.user_message, msg)
-                for _ in range(60):
-                    await asyncio.sleep(0.5)
-                    response = await wf_handle.query(ChatbotWorkflow.last_response)
-                    if response != prev_response:
-                        return response
-                return None
-
-            response = await send_and_wait(user_input)
-            if response:
-                print(f"Bot: {response}\n")
-            else:
-                print("(timed out waiting for response)")
+            print(f"Bot: {response}\n")
 
     await run_session()
 

langsmith_tracing/chatbot/workflows.py

@@ -11,8 +11,6 @@
 
     from langsmith_tracing.chatbot.activities import OpenAIRequest, call_openai
 
-RETRY = RetryPolicy(initial_interval=timedelta(seconds=2), maximum_attempts=3)
-
 TOOLS = [
     {
         "type": "function",
@@ -57,45 +55,58 @@ def __init__(self):
         self._notes: dict[str, str] = {}
         self._done = False
 
-    @workflow.signal
-    async def user_message(self, message: str) -> None:
-        self._pending_message = message
-
     @workflow.signal
     async def exit(self) -> None:
         self._done = True
 
-    @workflow.query
-    def last_response(self) -> str:
-        return self._last_response
-
     @workflow.query
     def notes(self) -> dict[str, str]:
         return dict(self._notes)
 
+    @workflow.update
+    async def message_from_user(self, message: str) -> str:
+        """Hand the message to the main loop and wait for its response."""
+
+        # Inner @traceable captures the message as input and response as output.
+        @traceable(name=f"Update: {message[:60]}", run_type="chain")
+        async def _traced(msg: str) -> str:
+            # Wait until any previous message has finished processing
+            await workflow.wait_condition(lambda: self._pending_message is None)
+            self._pending_message = msg
+            # Main loop sets _last_response, then clears _pending_message to signal done
+            await workflow.wait_condition(lambda: self._pending_message is None)
+            return self._last_response
+
+        return await _traced(message)
+
     # Do not decorate @workflow.run with @traceable — it would violate
     # replay safety and produce duplicate or orphaned traces. Instead,
-    # wrap an inner function.
+    # wrap an inner function, eg. self._run_inner() in this case.
     @workflow.run
     async def run(self) -> str:
+        # Alternative to @traceable decorator: call traceable() as a function
+        # for dynamic trace names that depend on runtime values.
         now = workflow.now().strftime("%b %d %H:%M")
         return await traceable(
             name=f"Session {now}",
             run_type="chain",
             metadata={"workflow_id": workflow.info().workflow_id},
             tags=["chatbot-session"],
-        )(self._session)()
+        )(self._run_inner)()
 
-    async def _session(self) -> str:
+    async def _run_inner(self) -> str:
         while not self._done:
             await workflow.wait_condition(
                 lambda: self._pending_message is not None or self._done
             )
             if self._done:
                 break
+            assert self._pending_message is not None
             message = self._pending_message
-            self._pending_message = None
             self._last_response = await self._query_openai(message)
+            # Clear pending_message AFTER setting the response so the update
+            # handler reads the correct response when its wait_condition fires.
+            self._pending_message = None
 
         return "Session ended."
 
@@ -111,14 +122,14 @@ def _save_note(self, name: str, content: str) -> str:
     def _read_note(self, name: str) -> str:
         return self._notes.get(name, "Note not found.")
 
-    async def _query_openai(self, message: str | None) -> str:
+    async def _query_openai(self, message: str) -> str:
         @traceable(
-            name=f"Request: {(message or '')[:60]}",
+            name=f"Request: {message[:60]}",
             run_type="chain",
             tags=["user-message"],
         )
         async def _traced():
-            input_for_next: str | list = message or ""
+            input_for_next: str | list = message
             while True:
                 response = await workflow.execute_activity(
                     call_openai,
@@ -129,7 +140,9 @@ async def _traced():
                         previous_response_id=self._previous_response_id,
                     ),
                     start_to_close_timeout=timedelta(seconds=60),
-                    retry_policy=RETRY,
+                    retry_policy=RetryPolicy(
+                        initial_interval=timedelta(seconds=2), maximum_attempts=3
+                    ),
                 )
                 self._previous_response_id = response.id