feat(tracing): Enhance trace parameters support in responder and generation models

- Add optional `trace_params` parameter to `respond_async` method
- Update `TraceParams` to use `dict[str, Any]` for metadata type
- Implement comprehensive trace parameter handling in `_create_tracing_contexts`
- Support additional tracing metadata fields like user_id, session_id, tags, version, and release
- Merge custom metadata from trace parameters with existing metadata
- Add example script demonstrating trace parameter usage
Improves observability and flexibility for tracing generation and response events with more granular configuration options.

Author: arthurbrenno

agentle/generations/models/generation/trace_params.py

@@ -53,7 +53,7 @@ class TraceParams(TypedDict, total=False):
     session_id: NotRequired[str]
     version: NotRequired[str]
     release: NotRequired[str]
-    metadata: NotRequired[Any]
+    metadata: NotRequired[dict[str, Any]]
     tags: NotRequired[Sequence[str]]
     public: NotRequired[bool]
     parent_trace_id: NotRequired[str]

agentle/responses/responder.py

@@ -13,6 +13,7 @@
 # from rsb.coroutines import fire_and_forget
 from rsb.models.field import Field
 
+from agentle.generations.models.generation.trace_params import TraceParams
 from agentle.generations.tracing.otel_client_type import OtelClientType
 from agentle.prompts.models.prompt import Prompt as AgentlePromptType
 from agentle.responses.async_stream import AsyncStream
@@ -279,6 +280,7 @@ async def respond_async[TextFormatT = None](
         stream_options: Optional[ResponseStreamOptions] = None,
         conversation: Optional[Union[str, ConversationParam]] = None,
         text_format: type[TextFormatT] | None = None,
+        trace_params: Optional[TraceParams] = None,
         # ResponseProperties parameters
         previous_response_id: Optional[str] = None,
         reasoning: Optional[Reasoning] = None,
@@ -324,6 +326,7 @@ async def respond_async[TextFormatT = None](
         stream_options: Optional[ResponseStreamOptions] = None,
         conversation: Optional[Union[str, ConversationParam]] = None,
         text_format: type[TextFormatT] | None = None,
+        trace_params: Optional[TraceParams] = None,
         # ResponseProperties parameters
         previous_response_id: Optional[str] = None,
         reasoning: Optional[Reasoning] = None,
@@ -369,6 +372,7 @@ async def respond_async[TextFormatT = None](
         stream_options: Optional[ResponseStreamOptions] = None,
         conversation: Optional[Union[str, ConversationParam]] = None,
         text_format: type[TextFormatT] | None = None,
+        trace_params: Optional[TraceParams] = None,
         # ResponseProperties parameters
         previous_response_id: Optional[str] = None,
         reasoning: Optional[Reasoning] = None,
@@ -413,6 +417,7 @@ async def respond_async[TextFormatT = None](
         stream_options: Optional[ResponseStreamOptions] = None,
         conversation: Optional[Union[str, ConversationParam]] = None,
         text_format: type[TextFormatT] | None = None,
+        trace_params: Optional[TraceParams] = None,
         # ResponseProperties parameters
         previous_response_id: Optional[str] = None,
         reasoning: Optional[Reasoning] = None,
@@ -508,12 +513,14 @@ async def respond_async[TextFormatT = None](
         return await self._respond_async(
             create_response,
             text_format=text_format,
+            trace_params=trace_params,
         )
 
     async def _respond_async[TextFormatT](
         self,
         create_response: CreateResponse,
         text_format: Type[TextFormatT] | None = None,
+        trace_params: Optional[TraceParams] = None,
     ) -> Response[TextFormatT] | AsyncStream[ResponseStreamEvent, TextFormatT]:
         _api_key = self.api_key
         if not _api_key:
@@ -557,6 +564,7 @@ async def _respond_async[TextFormatT](
                         model=model,
                         create_response=create_response,
                         custom_metadata=custom_metadata,
+                        trace_params=trace_params,
                     )
                 except Exception as e:
                     # Log error but don't fail the request
@@ -1136,6 +1144,7 @@ async def _create_tracing_contexts(
         model: str,
         create_response: CreateResponse,
         custom_metadata: dict[str, Any],
+        trace_params: Optional[TraceParams] = None,
     ) -> list[TracingContext]:
         """
         Create trace and generation contexts for all configured OtelClients.
@@ -1148,6 +1157,7 @@ async def _create_tracing_contexts(
             model: The model identifier
             create_response: The CreateResponse object
             custom_metadata: Custom metadata dictionary to include in traces
+            trace_params: Optional trace parameters for observability
 
         Returns:
             List of TracingContext objects containing client and context information
@@ -1164,35 +1174,67 @@ async def _create_tracing_contexts(
             f"Creating tracing contexts for {len(self.otel_clients)} OTel client(s) with model: {model}"
         )
 
+        # Initialize trace_params if not provided
+        if trace_params is None:
+            trace_params = TraceParams()
+
+        # Extract trace parameters
+        trace_name = trace_params.get("name", "responder_api_call")
+        user_id = trace_params.get("user_id")
+        session_id = trace_params.get("session_id")
+        tags = trace_params.get("tags")
+        trace_version = trace_params.get("version")
+        trace_release = trace_params.get("release")
+        trace_public = trace_params.get("public")
+        # parent_trace_id = trace_params.get("parent_trace_id")  # Reserved for future use
+
+        # Merge custom metadata from trace_params
+        merged_metadata = dict(custom_metadata)
+        if "metadata" in trace_params:
+            trace_metadata_val = trace_params["metadata"]
+            merged_metadata.update(trace_metadata_val)
+
         # Prepare input data and metadata for tracing
         input_data = self._prepare_trace_input_data(create_response)
         metadata = self._prepare_trace_metadata(
             model=model,
             base_url=self.base_url,
-            custom_metadata=custom_metadata,
+            custom_metadata=merged_metadata,
         )
 
+        # Add trace_params specific fields to metadata
+        if trace_version:
+            metadata.custom_metadata["version"] = trace_version
+        if trace_release:
+            metadata.custom_metadata["release"] = trace_release
+        if trace_public is not None:
+            metadata.custom_metadata["public"] = trace_public
+
         # Create contexts for each client
         for client in self.otel_clients:
             client_name = type(client).__name__
             try:
                 logger.debug(f"Creating trace context for client: {client_name}")
 
-                # Create trace context
+                # Create trace context with trace_params
                 trace_gen = client.trace_context(
-                    name="responder_api_call",
+                    name=trace_name,
                     input_data=input_data.model_dump(),
                     metadata=metadata.to_api_dict(),
+                    user_id=user_id,
+                    session_id=session_id,
+                    tags=tags,
                 )
                 trace_ctx = await trace_gen.__anext__()
 
                 logger.debug(f"Trace context created for client: {client_name}")
 
                 # Create generation context
                 logger.debug(f"Creating generation context for client: {client_name}")
+                generation_name = trace_params.get("name", "response_generation")
                 generation_gen = client.generation_context(
                     trace_context=trace_ctx,
-                    name="response_generation",
+                    name=generation_name,
                     model=model,
                     provider=metadata.provider,
                     input_data=input_data.model_dump(),

examples/responder_trace_params_example.py

@@ -0,0 +1,175 @@
+"""
+Example demonstrating TraceParams integration with Responder.
+
+This example shows how to use TraceParams to add metadata, tags, user_id,
+session_id, and other observability information to your API calls.
+"""
+
+import asyncio
+
+from dotenv import load_dotenv
+from rsb.models.base_model import BaseModel
+
+from agentle.generations.models.generation.trace_params import TraceParams
+from agentle.generations.tracing.langfuse_otel_client import LangfuseOtelClient
+from agentle.responses.responder import Responder
+
+load_dotenv(override=True)
+
+
+class Answer(BaseModel):
+    """Structured response format."""
+
+    answer: str
+    confidence: float
+
+
+async def basic_trace_params_example():
+    """Basic example with trace_params."""
+    print("\n=== Basic TraceParams Example ===")
+
+    responder = Responder.openrouter()
+    responder.append_otel_client(LangfuseOtelClient())
+
+    # Create trace params with basic information
+    trace_params = TraceParams(
+        name="customer_support_query",
+        user_id="user_123",
+        session_id="session_456",
+        tags=["support", "billing"],
+        metadata={
+            "department": "billing",
+            "priority": "high",
+            "source": "web_chat",
+        },
+    )
+
+    response = await responder.respond_async(
+        input="What is the capital of France?",
+        model="google/gemma-3-27b-it",
+        max_output_tokens=1000,
+        text_format=Answer,
+        trace_params=trace_params,
+    )
+
+    print(f"Response: {response.output_parsed}")
+    print(f"Trace name: {trace_params.get('name')}")
+    print(f"User ID: {trace_params.get('user_id')}")
+    print(f"Session ID: {trace_params.get('session_id')}")
+    print(f"Tags: {trace_params.get('tags')}")
+
+
+async def version_release_example():
+    """Example with version and release tracking."""
+    print("\n=== Version & Release Tracking Example ===")
+
+    responder = Responder.openrouter()
+    responder.append_otel_client(LangfuseOtelClient())
+
+    # Track version and release information
+    trace_params = TraceParams(
+        name="api_v2_query",
+        version="2.1.0",
+        release="production",
+        metadata={
+            "api_version": "v2",
+            "deployment": "us-east-1",
+        },
+    )
+
+    response = await responder.respond_async(
+        input="Explain quantum computing in simple terms",
+        model="google/gemma-3-27b-it",
+        max_output_tokens=1000,
+        trace_params=trace_params,
+    )
+
+    print(f"Response: {response.output_text}")
+    print(f"Version: {trace_params.get('version')}")
+    print(f"Release: {trace_params.get('release')}")
+
+
+async def multi_user_session_example():
+    """Example simulating multiple users and sessions."""
+    print("\n=== Multi-User Session Example ===")
+
+    responder = Responder.openrouter()
+    responder.append_otel_client(LangfuseOtelClient())
+
+    # Simulate different users asking questions
+    users = [
+        ("user_alice", "session_001", "What is machine learning?"),
+        ("user_bob", "session_002", "Explain neural networks"),
+        ("user_charlie", "session_003", "What is deep learning?"),
+    ]
+
+    for user_id, session_id, question in users:
+        trace_params = TraceParams(
+            name="educational_query",
+            user_id=user_id,
+            session_id=session_id,
+            tags=["education", "ai_concepts"],
+            metadata={
+                "category": "ai_education",
+                "difficulty": "beginner",
+            },
+        )
+
+        response = await responder.respond_async(
+            input=question,
+            model="google/gemma-3-27b-it",
+            max_output_tokens=500,
+            trace_params=trace_params,
+        )
+
+        print(f"\nUser: {user_id} | Session: {session_id}")
+        print(f"Question: {question}")
+        print(f"Answer: {response.output_text[:100]}...")
+
+
+async def streaming_with_trace_params():
+    """Example with streaming and trace_params."""
+    print("\n=== Streaming with TraceParams Example ===")
+
+    responder = Responder.openrouter()
+    responder.append_otel_client(LangfuseOtelClient())
+
+    trace_params = TraceParams(
+        name="streaming_query",
+        user_id="user_streaming",
+        session_id="stream_session_001",
+        tags=["streaming", "real_time"],
+        metadata={
+            "stream_type": "text",
+            "buffer_size": "default",
+        },
+    )
+
+    stream = await responder.respond_async(
+        input="Write a short poem about AI",
+        model="google/gemma-3-27b-it",
+        max_output_tokens=500,
+        stream=True,
+        trace_params=trace_params,
+    )
+
+    print("Streaming response:")
+    async for event in stream:
+        if event.type == "ResponseTextDeltaEvent":
+            print(event.delta, end="", flush=True)
+
+    print("\n")
+
+
+async def main():
+    """Run all examples."""
+    await basic_trace_params_example()
+    await version_release_example()
+    await multi_user_session_example()
+    await streaming_with_trace_params()
+
+    print("\n=== All Examples Complete ===")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())