feat(docs): enhance AI chat API documentation with examples and details

- Improve POST /chat endpoint documentation with request/response examples
- Add session ID management flow explanation
- Enhance GET /sessions endpoint with query parameters and response example
- Update GET /sessions/{session_id}/history with detailed response structure
- Format parameters as tables for better readability
- Clarify session ID usage in streaming conversations

gns3server/agent/gns3_copilot/agent/gns3_copilot.py

@@ -47,6 +47,7 @@ Copilot Modes:
 # Standard library imports
 import logging
 import operator
+from datetime import datetime
 from typing import Annotated
 from typing import Literal
 
@@ -262,6 +263,17 @@ def llm_call(state: dict, config: RunnableConfig | None = None):
     # Invoke model with prepared messages
     response = model_with_tools.invoke(prepared_messages)
 
+    # Add metadata with created_at timestamp to AI response
+    if hasattr(response, "metadata"):
+        existing_metadata = response.metadata or {}
+        response.metadata = {**existing_metadata, "created_at": datetime.utcnow().isoformat()}
+    else:
+        # LangChain messages should have metadata attribute, but defensive fallback
+        try:
+            response.metadata = {"created_at": datetime.utcnow().isoformat()}
+        except Exception:
+            logger.warning("Could not add metadata to AI response")
+
     logger.info("LLM call completed: tool_calls=%d", len(response.tool_calls) if hasattr(response, "tool_calls") else 0)
 
     return {
@@ -371,7 +383,16 @@ def tool_node(state: dict, config: RunnableConfig | None = None):
         except Exception as e:
             logger.error("Tool %s failed: %s", tool_name, e, exc_info=True)
             observation = f"Error: {str(e)}"
-        result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"], name=tool_call["name"]))
+
+        # Create ToolMessage with metadata including created_at
+        tool_msg = ToolMessage(
+            content=observation,
+            tool_call_id=tool_call["id"],
+            name=tool_call["name"],
+            metadata={"created_at": datetime.utcnow().isoformat()}
+        )
+        result.append(tool_msg)
+
     return {"messages": result}
 
 

gns3server/agent/gns3_copilot/agent_service.py

@@ -276,7 +276,13 @@ class AgentService:
 
         # Build inputs
         inputs = {
-            "messages": [HumanMessage(content=message, id=str(uuid4()))],
+            "messages": [
+                HumanMessage(
+                    content=message,
+                    id=str(uuid4()),
+                    metadata={"created_at": datetime.utcnow().isoformat()},
+                )
+            ],
             "llm_calls": 0,
             "remaining_steps": 20,
             "mode": mode,

gns3server/agent/gns3_copilot/utils/message_converters.py

@@ -31,7 +31,6 @@ Converts between LangChain messages and OpenAI-compatible format.
 
 import json
 import uuid
-from datetime import datetime
 from typing import Any
 from typing import Dict
 
@@ -66,15 +65,13 @@ def convert_langchain_to_openai(lc_message) -> Dict[str, Any]:
     if msg_id is None:
         msg_id = str(uuid.uuid4())
 
-    # Get timestamp
-    timestamp = getattr(lc_message, "created_at", None)
-    if timestamp is None:
-        timestamp = datetime.utcnow().isoformat()
-    elif hasattr(timestamp, "isoformat"):
-        timestamp = timestamp.isoformat()
+    # Get metadata from message (including created_at)
+    metadata = getattr(lc_message, "metadata", None) or {}
+    if not isinstance(metadata, dict):
+        metadata = {}
 
-    # Base message structure
-    base_msg = {"id": msg_id, "created_at": timestamp, "metadata": {}}
+    # Base message structure (no top-level created_at, only metadata)
+    base_msg = {"id": msg_id, "metadata": metadata}
 
     # Convert based on message type
     if isinstance(lc_message, HumanMessage):

gns3server/schemas/controller/chat.py

@@ -75,8 +75,7 @@ class OpenAIMessage(BaseModel):
     name: Optional[str] = Field(None, description="Tool message name")
     tool_call_id: Optional[str] = Field(None, description="Associated tool call ID (for tool messages)")
     tool_calls: Optional[List[OpenAIToolCall]] = Field(None, description="Tool calls (for assistant messages)")
-    metadata: Dict[str, Any] = Field(default_factory=dict, description="Message metadata")
-    created_at: str = Field(..., description="Message timestamp (ISO 8601)")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Message metadata (includes created_at)")
 
 
 class ConversationHistory(BaseModel):