simplai-sdk 0.1.0__py3-none-any.whl

core/agents/execution/client.py

@@ -0,0 +1,1139 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+import httpx
+
+from ..models import AgentExecutionError, AgentMessage, AgentResult, AgentStatus, AgentStreamChunk
+from constants import (
+    AGENT_CONVERSATION_FETCH_DETAILS_PATH,
+    AGENT_CONVERSATION_FETCH_PATH,
+    AGENT_CONVERSATION_PATH,
+    AGENT_STREAM_PATH,
+    DEFAULT_BASE_URL,
+)
+
+
+class AgentClient:
+    """Low-level HTTP client for the Simplai agent API.
+
+    This class is reusable and manages underlying HTTP clients for efficiency.
+
+    Args:
+        api_key: PIM-SID key used for authenticating with the Simplai edge service.
+        base_url: Base URL of the Simplai edge service.
+        timeout: Default request timeout in seconds.
+        max_retries: Number of retries for transient HTTP errors.
+        backoff_factor: Base factor (in seconds) used for exponential backoff.
+        user_id: Optional user ID for agent conversations.
+        tenant_id: Optional tenant ID (defaults to "1").
+        project_id: Optional project ID.
+    """
+
+    # Fallback: when fetchDetails returns no response text, get it via GET /conversation/fetch (SSE)
+    _CONVERSATION_FETCH_INITIAL_DELAY = 2.0
+    _CONVERSATION_FETCH_MAX_RETRIES = 15
+    _CONVERSATION_FETCH_RETRY_DELAY = 2.0
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+        user_id: Optional[str] = None,
+        tenant_id: str = "1",
+        project_id: Optional[int] = None,
+        seller_id: Optional[str] = None,
+        client_id: Optional[str] = None,
+        seller_profile_id: Optional[str] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
+        self.user_id = user_id
+        self.tenant_id = tenant_id
+        self.project_id = project_id
+        self.seller_id = seller_id
+        self.client_id = client_id
+        self.seller_profile_id = seller_profile_id
+
+        self._sync_client: Optional[httpx.Client] = None
+        self._async_client: Optional[httpx.AsyncClient] = None
+
+    # ------------------------------------------------------------------
+    # Internal HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _get_sync_client(self) -> httpx.Client:
+        if self._sync_client is None:
+            self._sync_client = httpx.Client(timeout=self.timeout)
+        return self._sync_client
+
+    def _get_async_client(self) -> httpx.AsyncClient:
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(timeout=self.timeout)
+        return self._async_client
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {
+            "PIM-SID": self.api_key,  # Uppercase as shown in curl
+            "Content-Type": "application/json",
+        }
+        
+        # Required headers - X-USER-ID is mandatory for validation
+        # The backend uses X-USER-ID for userId, sellerId, and sellerProfileId
+        if self.user_id:
+            headers["X-USER-ID"] = self.user_id
+        else:
+            # Use seller_id as fallback, or default to "sdk-user"
+            headers["X-USER-ID"] = self.seller_id if self.seller_id else "sdk-user"
+        
+        # X-TENANT-ID is required (defaults to "1" in __init__)
+        if self.tenant_id:
+            headers["X-TENANT-ID"] = self.tenant_id
+        
+        # Optional headers
+        if self.project_id:
+            headers["X-PROJECT-ID"] = str(self.project_id)
+        if self.seller_id:
+            headers["X-SELLER-ID"] = self.seller_id
+        if self.client_id:
+            headers["X-CLIENT-ID"] = self.client_id
+        if self.seller_profile_id:
+            headers["X-SELLER-PROFILE-ID"] = self.seller_profile_id
+        
+        return headers
+
+    # ------------------------------------------------------------------
+    # Public HTTP methods (sync)
+    # ------------------------------------------------------------------
+
+    def chat_once(
+        self,
+        agent_id: str,
+        message: str,
+        chat_history: Optional[List[AgentMessage]] = None,
+        conversation_id: Optional[str] = None,
+        version_id: Optional[str] = None,
+        state_override: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Send a single agent chat request and return the response."""
+        url = self.base_url + AGENT_CONVERSATION_PATH
+        # Use snake_case to match the actual API structure from curl
+        payload: Dict[str, Any] = {
+            # In the SimplAI app, "model" is a logical model name (e.g., "sync mode"),
+            # while app_id/model_id carry the actual agent identifier.
+            "model": "sync mode",
+            "app_id": agent_id,
+            "model_id": agent_id,
+            "action": "START_SCREEN",
+            "query": {
+                "message": message,
+                "message_type": "text",  # snake_case
+                "message_category": "",  # snake_case
+            },
+            "language_code": "EN",  # snake_case
+            "source": "APP",  # Must be one of: APP, MOBILE_WEB, WEB, SLACK, API, EMBED
+        }
+
+        if conversation_id:
+            payload["conversation_id"] = conversation_id  # snake_case
+        if version_id:
+            payload["version_id"] = version_id  # snake_case
+        else:
+            payload["version_id"] = "latest"  # Default as shown in curl
+        
+        if state_override:
+            payload["state_override"] = state_override
+        else:
+            # Add default state_override if not provided
+            payload["state_override"] = {
+                "sys": {
+                    "user_timezone": "UTC",
+                    "language_code": "en-US"
+                }
+            }
+        
+        if chat_history:
+            # Include chat_history in payload if explicitly provided
+            # Note: If conversation_id is provided but chat_history is None,
+            # the backend will automatically fetch history from the database
+            payload["chat_history"] = [
+                {"role": msg.role, "content": msg.content} for msg in chat_history
+            ]
+
+        resp_json = self._request_with_retries_sync("POST", url, json=payload)
+        return resp_json
+
+    def fetch_message_once(
+        self,
+        conversation_id: str,
+        message_id: str,
+    ) -> tuple[Dict[str, Any], Optional[str], Optional[str]]:
+        """Fetch the status/result for a single message.
+        
+        Uses the /conversation/fetchDetails endpoint which may return JSON or plain string.
+        
+        Returns:
+            Tuple of (response_dict, trace_id, node_id)
+        """
+        url = self.base_url + AGENT_CONVERSATION_FETCH_DETAILS_PATH
+        params = {"cId": conversation_id, "mId": message_id}
+        client = self._get_sync_client()
+        
+        response = client.get(url, headers=self._headers(), params=params)
+        response.raise_for_status()
+        
+        # Extract trace_id and node_id from response headers
+        trace_id = response.headers.get("trace_id") or response.headers.get("trace-id")
+        node_id = response.headers.get("node_id") or response.headers.get("node-id")
+        
+        # Get message_status from headers (0/1=processing, 2=completed)
+        message_status = response.headers.get("message_status")
+        if message_status:
+            try:
+                message_status = int(message_status)
+            except (ValueError, TypeError):
+                message_status = None
+        
+        # Try to parse as JSON first
+        try:
+            resp_json = response.json()
+            # The response structure is: BaseRestResponse<Map<String, Object>>
+            # { "result": { messageId: Messages object } }
+            result = resp_json.get("result", {})
+            if isinstance(result, dict) and message_id in result:
+                message_data = result[message_id]
+                if isinstance(message_data, dict):
+                    # The message_data is the Messages object with fields like:
+                    # queryResult, messageStatus, id, etc.
+                    query_result = message_data.get("queryResult") or message_data.get("query_result") or ""
+                    msg_status = message_data.get("messageStatus") or message_data.get("message_status") or message_status
+                    
+                    return ({
+                        "result": {
+                            "response": [{
+                                "id": message_data.get("id") or message_id,
+                                "queryResult": query_result,
+                                "messageStatus": msg_status,
+                            }]
+                        }
+                    }, trace_id, node_id)
+            # Fallback: return the raw JSON structure
+            return (resp_json, trace_id, node_id)
+        except (json.JSONDecodeError, ValueError):
+            # If not JSON, it might be a plain string (queryResult directly)
+            query_result = response.text.strip()
+            
+            return ({
+                "result": {
+                    "response": [{
+                        "id": message_id,
+                        "queryResult": query_result,
+                        "messageStatus": message_status,
+                    }]
+                }
+            }, trace_id, node_id)
+
+    # ------------------------------------------------------------------
+    # Public HTTP methods (async)
+    # ------------------------------------------------------------------
+
+    async def achat_once(
+        self,
+        agent_id: str,
+        message: str,
+        chat_history: Optional[List[AgentMessage]] = None,
+        conversation_id: Optional[str] = None,
+        version_id: Optional[str] = None,
+        state_override: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Async variant of chat_once."""
+        url = self.base_url + AGENT_CONVERSATION_PATH
+        # Use snake_case to match the actual API structure from curl
+        payload: Dict[str, Any] = {
+            # Match the same semantics as in chat_once()
+            "model": "sync mode",
+            "app_id": agent_id,
+            "model_id": agent_id,
+            "action": "START_SCREEN",
+            "query": {
+                "message": message,
+                "message_type": "text",  # snake_case
+                "message_category": "",  # snake_case
+            },
+            "language_code": "EN",  # snake_case
+            "source": "APP",  # Must be one of: APP, MOBILE_WEB, WEB, SLACK, API, EMBED
+        }
+
+        if conversation_id:
+            payload["conversation_id"] = conversation_id  # snake_case
+        if version_id:
+            payload["version_id"] = version_id  # snake_case
+        else:
+            payload["version_id"] = "latest"  # Default as shown in curl
+        
+        if state_override:
+            payload["state_override"] = state_override
+        else:
+            # Add default state_override if not provided
+            payload["state_override"] = {
+                "sys": {
+                    "user_timezone": "UTC",
+                    "language_code": "en-US"
+                }
+            }
+        
+        if chat_history:
+            # Include chat_history in payload if explicitly provided
+            # Note: If conversation_id is provided but chat_history is None,
+            # the backend will automatically fetch history from the database
+            payload["chat_history"] = [
+                {"role": msg.role, "content": msg.content} for msg in chat_history
+            ]
+
+        resp_json = await self._request_with_retries_async("POST", url, json=payload)
+        return resp_json
+
+    async def afetch_message_once(
+        self,
+        conversation_id: str,
+        message_id: str,
+    ) -> tuple[Dict[str, Any], Optional[str], Optional[str]]:
+        """Async variant of fetch_message_once.
+        
+        Uses the /conversation/fetchDetails endpoint which returns JSON format
+        instead of SSE, making it better for non-streaming polling.
+        
+        Returns:
+            Tuple of (response_dict, trace_id, node_id)
+        """
+        url = self.base_url + AGENT_CONVERSATION_FETCH_DETAILS_PATH
+        params = {"cId": conversation_id, "mId": message_id}
+        client = self._get_async_client()
+        
+        response = await client.get(url, headers=self._headers(), params=params)
+        response.raise_for_status()
+        
+        # Extract trace_id and node_id from response headers
+        trace_id = response.headers.get("trace_id") or response.headers.get("trace-id")
+        node_id = response.headers.get("node_id") or response.headers.get("node-id")
+        
+        # Get message_status from headers (0/1=processing, 2=completed)
+        message_status = response.headers.get("message_status")
+        if message_status:
+            try:
+                message_status = int(message_status)
+            except (ValueError, TypeError):
+                message_status = None
+        
+        # Try to parse as JSON first
+        try:
+            resp_json = response.json()
+            
+            # Check if trace_id and node_id are in the response body
+            if not trace_id:
+                trace_id = resp_json.get("trace_id") or resp_json.get("traceId")
+            if not node_id:
+                node_id = resp_json.get("node_id") or resp_json.get("nodeId") or resp_json.get("job_id") or resp_json.get("jobId")
+            
+            # Also check in nested result structure
+            result = resp_json.get("result", {})
+            if isinstance(result, dict):
+                if not trace_id:
+                    trace_id = result.get("trace_id") or result.get("traceId")
+                if not node_id:
+                    node_id = result.get("node_id") or result.get("nodeId") or result.get("job_id") or result.get("jobId")
+                
+                if message_id in result:
+                    message_data = result[message_id]
+                    if isinstance(message_data, dict):
+                        # Check in message_data as well
+                        if not trace_id:
+                            trace_id = message_data.get("trace_id") or message_data.get("traceId")
+                        if not node_id:
+                            # Try node_id, nodeId, job_id, jobId
+                            node_id = message_data.get("node_id") or message_data.get("nodeId") or message_data.get("job_id") or message_data.get("jobId")
+                        
+                        # The message_data is the Messages object with fields like:
+                        # queryResult, messageStatus, id, etc.
+                        query_result = message_data.get("queryResult") or message_data.get("query_result") or ""
+                        msg_status = message_data.get("messageStatus") or message_data.get("message_status") or message_status
+                        
+                        return ({
+                            "result": {
+                                "response": [{
+                                    "id": message_data.get("id") or message_id,
+                                    "queryResult": query_result,
+                                    "messageStatus": msg_status,
+                                }]
+                            }
+                        }, trace_id, node_id)
+            # Fallback: return the raw JSON structure
+            return (resp_json, trace_id, node_id)
+        except (json.JSONDecodeError, ValueError):
+            # If not JSON, it might be a plain string (queryResult directly)
+            query_result = response.text.strip()
+            
+            return ({
+                "result": {
+                    "response": [{
+                        "id": message_id,
+                        "queryResult": query_result,
+                        "messageStatus": message_status,
+                    }]
+                }
+            }, trace_id, node_id)
+
+    @staticmethod
+    def _normalize_conversation_fetch_response(raw: str) -> str:
+        """Treat backend placeholder 'processing' as empty."""
+        if not raw or raw.strip() == "processing":
+            return ""
+        return raw
+
+    def _fetch_response_via_conversation_fetch(
+        self, conversation_id: str, message_id: str
+    ) -> str:
+        """Sync: get agent response via GET /conversation/fetch (SSE) when fetchDetails returns no text."""
+        time.sleep(self._CONVERSATION_FETCH_INITIAL_DELAY)
+        url = self.base_url + AGENT_CONVERSATION_FETCH_PATH
+        params = {"cId": conversation_id, "mId": message_id}
+        client = self._get_sync_client()
+        for attempt in range(self._CONVERSATION_FETCH_MAX_RETRIES):
+            accumulated = ""
+            try:
+                with client.stream("GET", url, headers=self._headers(), params=params) as response:
+                    response.raise_for_status()
+                    for line in response.iter_lines():
+                        content = self._parse_sse_line(line)
+                        if content is not None and "endstream" not in content.lower():
+                            accumulated += content
+            except Exception:
+                pass
+            result = self._normalize_conversation_fetch_response(accumulated)
+            if result:
+                return result
+            if attempt < self._CONVERSATION_FETCH_MAX_RETRIES - 1:
+                time.sleep(self._CONVERSATION_FETCH_RETRY_DELAY)
+        return ""
+
+    async def _afetch_response_via_conversation_fetch(
+        self, conversation_id: str, message_id: str
+    ) -> str:
+        """Get agent response via GET /conversation/fetch (SSE) when fetchDetails returns no text."""
+        await asyncio.sleep(self._CONVERSATION_FETCH_INITIAL_DELAY)
+        url = self.base_url + AGENT_CONVERSATION_FETCH_PATH
+        params = {"cId": conversation_id, "mId": message_id}
+        client = self._get_async_client()
+        for attempt in range(self._CONVERSATION_FETCH_MAX_RETRIES):
+            accumulated = ""
+            try:
+                async with client.stream("GET", url, headers=self._headers(), params=params) as response:
+                    response.raise_for_status()
+                    async for line in response.aiter_lines():
+                        content = self._parse_sse_line(line)
+                        if content is not None and "endstream" not in content.lower():
+                            accumulated += content
+            except Exception:
+                pass
+            result = self._normalize_conversation_fetch_response(accumulated)
+            if result:
+                return result
+            if attempt < self._CONVERSATION_FETCH_MAX_RETRIES - 1:
+                await asyncio.sleep(self._CONVERSATION_FETCH_RETRY_DELAY)
+        return ""
+
+    # ------------------------------------------------------------------
+    # High-level polling (sync)
+    # ------------------------------------------------------------------
+
+    def chat_and_wait(
+        self,
+        agent_id: str,
+        message: str,
+        chat_history: Optional[List[AgentMessage]] = None,
+        conversation_id: Optional[str] = None,
+        version_id: Optional[str] = None,
+        state_override: Optional[Dict[str, Any]] = None,
+        *,
+        poll_interval: float = 2.0,
+        timeout: Optional[float] = None,
+    ) -> AgentResult:
+        """Send agent chat request and block until response is ready."""
+        # Create conversation
+        response = self.chat_once(
+            agent_id, message, chat_history, conversation_id, version_id, state_override
+        )
+
+        # Extract conversation_id and message_id from response
+        conv_id, msg_id = self._extract_ids(response)
+        start = time.monotonic()
+
+        # Poll for completion
+        while True:
+            if timeout is not None:
+                elapsed = time.monotonic() - start
+                if elapsed >= timeout:
+                    raise AgentExecutionError(
+                        f"Agent conversation {conv_id} timed out after {elapsed:.1f}s"
+                    )
+
+            status_payload, trace_id, node_id = self.fetch_message_once(conv_id, msg_id)
+            status, response_text = self._parse_message_response(status_payload)
+
+            if status in {AgentStatus.COMPLETED, AgentStatus.FAILED, AgentStatus.TIMEOUT}:
+                if status != AgentStatus.COMPLETED:
+                    raise AgentExecutionError(
+                        f"Agent conversation {conv_id} finished with status {status.value}"
+                    )
+                if not response_text:
+                    response_text = self._fetch_response_via_conversation_fetch(conv_id, msg_id)
+                    # Re-fetch details so payload/trace_id/node_id reflect latest (backend may set trace_id after COMPLETED)
+                    status_payload, trace_id, node_id = self.fetch_message_once(conv_id, msg_id)
+                return AgentResult(
+                    conversation_id=conv_id,
+                    message_id=msg_id,
+                    status=status,
+                    response=response_text,
+                    payload=status_payload,
+                    trace_id=trace_id,
+                    node_id=node_id,
+                )
+
+            # Still processing; sleep and poll again
+            time.sleep(poll_interval)
+
+    # ------------------------------------------------------------------
+    # High-level polling (async)
+    # ------------------------------------------------------------------
+
+    async def achat_and_wait(
+        self,
+        agent_id: str,
+        message: str,
+        chat_history: Optional[List[AgentMessage]] = None,
+        conversation_id: Optional[str] = None,
+        version_id: Optional[str] = None,
+        state_override: Optional[Dict[str, Any]] = None,
+        *,
+        poll_interval: float = 2.0,
+        timeout: Optional[float] = None,
+    ) -> AgentResult:
+        """Async variant of chat_and_wait."""
+        # Create conversation
+        response = await self.achat_once(
+            agent_id, message, chat_history, conversation_id, version_id, state_override
+        )
+
+        # Extract conversation_id and message_id from response
+        conv_id, msg_id = self._extract_ids(response)
+        start = time.monotonic()
+
+        # Poll for completion
+        while True:
+            if timeout is not None:
+                elapsed = time.monotonic() - start
+                if elapsed >= timeout:
+                    raise AgentExecutionError(
+                        f"Agent conversation {conv_id} timed out after {elapsed:.1f}s"
+                    )
+
+            status_payload, trace_id, node_id = await self.afetch_message_once(conv_id, msg_id)
+            status, response_text = self._parse_message_response(status_payload)
+
+            if status in {AgentStatus.COMPLETED, AgentStatus.FAILED, AgentStatus.TIMEOUT}:
+                if status != AgentStatus.COMPLETED:
+                    raise AgentExecutionError(
+                        f"Agent conversation {conv_id} finished with status {status.value}"
+                    )
+                if not response_text:
+                    response_text = await self._afetch_response_via_conversation_fetch(
+                        conv_id, msg_id
+                    )
+                    # Re-fetch details so payload/trace_id/node_id reflect latest (backend may set trace_id after COMPLETED)
+                    status_payload, trace_id, node_id = await self.afetch_message_once(
+                        conv_id, msg_id
+                    )
+                return AgentResult(
+                    conversation_id=conv_id,
+                    message_id=msg_id,
+                    status=status,
+                    response=response_text,
+                    payload=status_payload,
+                    trace_id=trace_id,
+                    node_id=node_id,
+                )
+
+            # Still processing; sleep and poll again
+            await asyncio.sleep(poll_interval)
+
+    # ------------------------------------------------------------------
+    # Streaming support
+    # ------------------------------------------------------------------
+
+    def stream_chat(
+        self,
+        agent_id: str,
+        message: str,
+        chat_history: Optional[List[AgentMessage]] = None,
+        conversation_id: Optional[str] = None,
+        version_id: Optional[str] = None,
+        state_override: Optional[Dict[str, Any]] = None,
+        *,
+        on_chunk: Optional[Callable[[AgentStreamChunk], None]] = None,
+    ) -> AgentResult:
+        """Stream agent chat response and call on_chunk callback for each chunk."""
+        # Create conversation
+        response = self.chat_once(
+            agent_id, message, chat_history, conversation_id, version_id, state_override
+        )
+
+        conv_id, msg_id = self._extract_ids(response)
+
+        # Use messageId directly as the streaming key (Redis channel: chat:{messageId})
+        stream_url = self.base_url + AGENT_STREAM_PATH.format(key=msg_id)
+        client = self._get_sync_client()
+
+        try:
+            with client.stream("GET", stream_url, headers=self._headers()) as response:
+                accumulated_content = ""
+                trace_id: Optional[str] = None
+                node_id: Optional[str] = None
+                tree_id: Optional[str] = None
+                first_chunk_processed = False
+                
+                # Extract trace_id, node_id, and tree_id from response headers (if available)
+                trace_id = response.headers.get("trace_id") or response.headers.get("trace-id")
+                node_id = response.headers.get("node_id") or response.headers.get("node-id")
+                tree_id = response.headers.get("tree_id") or response.headers.get("tree-id")
+                
+                for line in response.iter_lines():
+                    # Parse SSE format (handles both SSE and plain text for backward compatibility)
+                    content = self._parse_sse_line(line)
+                    
+                    # Skip empty lines, comments, and event types
+                    if content is None:
+                        continue
+                    
+                    # Check for endstream marker (case-insensitive)
+                    if "endstream" in content.lower():
+                        # Stream ended
+                        break
+                    
+                    # Try to extract trace_id, node_id, and tree_id from first chunk if not in headers
+                    if not first_chunk_processed:
+                        first_chunk_processed = True
+                        # Try parsing first chunk as JSON to extract trace info
+                        if not trace_id or not node_id:
+                            try:
+                                import json
+                                # First chunk might be JSON with trace info
+                                chunk_data = json.loads(content)
+                                if isinstance(chunk_data, dict):
+                                    trace_id = trace_id or chunk_data.get("trace_id") or chunk_data.get("traceId")
+                                    node_id = node_id or chunk_data.get("node_id") or chunk_data.get("nodeId")
+                                    tree_id = tree_id or chunk_data.get("tree_id") or chunk_data.get("treeId")
+                                    # If it's a JSON object, extract content separately
+                                    content = chunk_data.get("content", content)
+                            except (json.JSONDecodeError, ValueError):
+                                # Not JSON, use as-is
+                                pass
+                    
+                    chunk = AgentStreamChunk(
+                        content=content,
+                        conversation_id=conv_id,
+                        message_id=msg_id,
+                        is_complete=False,
+                        trace_id=trace_id,
+                        node_id=node_id,
+                        tree_id=tree_id,
+                    )
+                    accumulated_content += content
+                    if on_chunk:
+                        on_chunk(chunk)
+
+            # Final result
+            final_response, final_trace_id, final_node_id = self.fetch_message_once(conv_id, msg_id)
+            status, response_text = self._parse_message_response(final_response)
+            
+            # Use trace_id and node_id from stream if available, otherwise from final response
+            result_trace_id = trace_id or final_trace_id
+            result_node_id = node_id or final_node_id
+
+            return AgentResult(
+                conversation_id=conv_id,
+                message_id=msg_id,
+                status=status,
+                response=response_text or accumulated_content,
+                payload=final_response,
+                trace_id=result_trace_id,
+                node_id=result_node_id,
+            )
+        except Exception as e:
+            raise AgentExecutionError(f"Streaming failed: {str(e)}") from e
+
+    async def astream_chat(
+        self,
+        agent_id: str,
+        message: str,
+        chat_history: Optional[List[AgentMessage]] = None,
+        conversation_id: Optional[str] = None,
+        version_id: Optional[str] = None,
+        state_override: Optional[Dict[str, Any]] = None,
+        *,
+        on_chunk: Optional[Callable[[AgentStreamChunk], None]] = None,
+    ) -> AgentResult:
+        """Async variant of stream_chat."""
+        # Create conversation
+        response = await self.achat_once(
+            agent_id, message, chat_history, conversation_id, version_id, state_override
+        )
+
+        conv_id, msg_id = self._extract_ids(response)
+
+        # Use messageId directly as the streaming key (Redis channel: chat:{messageId})
+        stream_url = self.base_url + AGENT_STREAM_PATH.format(key=msg_id)
+        client = self._get_async_client()
+
+        try:
+            accumulated_content = ""
+            trace_id: Optional[str] = None
+            node_id: Optional[str] = None
+            first_chunk_processed = False
+            
+            async with client.stream("GET", stream_url, headers=self._headers()) as response:
+                # Extract trace_id, node_id, and tree_id from response headers (if available)
+                trace_id = response.headers.get("trace_id") or response.headers.get("trace-id")
+                node_id = response.headers.get("node_id") or response.headers.get("node-id")
+                tree_id = response.headers.get("tree_id") or response.headers.get("tree-id")
+                
+                async for line in response.aiter_lines():
+                    # Parse SSE format (handles both SSE and plain text for backward compatibility)
+                    content = self._parse_sse_line(line)
+                    
+                    # Skip empty lines, comments, and event types
+                    if content is None:
+                        continue
+                    
+                    # Check for endstream marker (case-insensitive)
+                    if "endstream" in content.lower():
+                        # Stream ended
+                        break
+                    
+                    # Try to extract trace_id, node_id, and tree_id from first chunk if not in headers
+                    if not first_chunk_processed:
+                        first_chunk_processed = True
+                        # Try parsing first chunk as JSON to extract trace info
+                        if not trace_id or not node_id:
+                            try:
+                                import json
+                                # First chunk might be JSON with trace info
+                                chunk_data = json.loads(content)
+                                if isinstance(chunk_data, dict):
+                                    trace_id = trace_id or chunk_data.get("trace_id") or chunk_data.get("traceId")
+                                    node_id = node_id or chunk_data.get("node_id") or chunk_data.get("nodeId")
+                                    tree_id = tree_id or chunk_data.get("tree_id") or chunk_data.get("treeId")
+                                    # If it's a JSON object, extract content separately
+                                    content = chunk_data.get("content", content)
+                            except (json.JSONDecodeError, ValueError):
+                                # Not JSON, use as-is
+                                pass
+                    
+                    chunk = AgentStreamChunk(
+                        content=content,
+                        conversation_id=conv_id,
+                        message_id=msg_id,
+                        is_complete=False,
+                        trace_id=trace_id,
+                        node_id=node_id,
+                        tree_id=tree_id,
+                    )
+                    accumulated_content += content
+                    if on_chunk:
+                        on_chunk(chunk)
+
+            # Final result
+            final_response, final_trace_id, final_node_id = await self.afetch_message_once(conv_id, msg_id)
+            status, response_text = self._parse_message_response(final_response)
+            
+            # Use trace_id and node_id from stream if available, otherwise from final response
+            result_trace_id = trace_id or final_trace_id
+            result_node_id = node_id or final_node_id
+
+            return AgentResult(
+                conversation_id=conv_id,
+                message_id=msg_id,
+                status=status,
+                response=response_text or accumulated_content,
+                payload=final_response,
+                trace_id=result_trace_id,
+                node_id=result_node_id,
+            )
+        except Exception as e:
+            raise AgentExecutionError(f"Streaming failed: {str(e)}") from e
+
+    # ------------------------------------------------------------------
+    # Internal utilities
+    # ------------------------------------------------------------------
+
+    def _request_with_retries_sync(
+        self,
+        method: str,
+        url: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        client = self._get_sync_client()
+        last_exc: Optional[BaseException] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = client.request(
+                    method,
+                    url,
+                    headers=self._headers(),
+                    json=json,
+                    params=params,
+                )
+                # Check for 511 before raise_for_status (it's treated as server error but is actually auth error)
+                if response.status_code == 511:
+                    body_preview = response.text[:500] if response.text else ""
+                    headers_sent = {k: "***" if k.lower() == "pim-sid" else v for k, v in self._headers().items()}
+                    raise AgentExecutionError(
+                        f"Network Authentication Required (511)\n"
+                        f"This usually means the API key is invalid or missing required headers.\n"
+                        f"URL: {url}\n"
+                        f"Response: {body_preview}\n"
+                        f"Headers sent: {headers_sent}\n"
+                        f"Please verify your API_KEY in .env file is correct."
+                    )
+                response.raise_for_status()
+                return self._parse_json(response)
+            except (httpx.HTTPStatusError, httpx.TransportError) as exc:
+                last_exc = exc
+                status = (
+                    getattr(exc.response, "status_code", None)
+                    if isinstance(exc, httpx.HTTPStatusError)
+                    else None
+                )
+
+                # For client errors (4xx, 511), surface a clear SDK error immediately.
+                if isinstance(exc, httpx.HTTPStatusError) and status is not None:
+                    # Get full response body for better debugging
+                    body_text = exc.response.text if exc.response.text else ""
+                    try:
+                        # Try to parse as JSON to get structured error message
+                        body_json = exc.response.json() if body_text else {}
+                        import json as json_module
+                        # Show full JSON response for debugging
+                        error_detail = json_module.dumps(body_json, indent=2) if body_json else body_text[:1000]
+                        # Also try to extract message field if present
+                        if isinstance(body_json, dict):
+                            error_msg_text = body_json.get("message") or body_json.get("error") or ""
+                            if error_msg_text:
+                                error_detail = f"{error_msg_text}\n\nFull response:\n{error_detail}"
+                    except:
+                        error_detail = body_text[:1000]
+                    
+                    # Include more details for debugging
+                    headers_sent = {k: "***" if k.lower() == "pim-sid" else v for k, v in self._headers().items()}
+                    payload_sent = json if json else {}
+                    # Add helpful suggestions for 400 errors
+                    suggestions = ""
+                    if status == 400:
+                        suggestions = (
+                            "\n\nTroubleshooting tips for 400 Bad Request:\n"
+                            "1. Verify the agent_id exists and is published in your environment\n"
+                            "2. Check if X-PROJECT-ID header is required (set PROJECT_ID in .env)\n"
+                            "3. Ensure USER_ID, SELLER_ID, SELLER_PROFILE_ID match the agent's configuration\n"
+                            "4. Check backend logs using requestId to see the specific validation error\n"
+                        )
+                    error_msg = (
+                        f"Request to {url} failed with {status} {exc.response.reason_phrase}\n"
+                        f"Response body: {error_detail}\n"
+                        f"Headers sent: {headers_sent}\n"
+                        f"Payload sent: {json_module.dumps(payload_sent, indent=2)[:1000]}"
+                        f"{suggestions}"
+                    )
+                    if 400 <= status < 500 or status == 511:
+                        raise AgentExecutionError(error_msg) from exc
+
+                should_retry = status is None or (500 <= status < 600 and status != 511)
+                if not should_retry or attempt >= self.max_retries:
+                    raise
+
+                backoff = self.backoff_factor * (2**attempt)
+                time.sleep(backoff)
+
+        assert last_exc is not None
+        raise last_exc
+
+    async def _request_with_retries_async(
+        self,
+        method: str,
+        url: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        client = self._get_async_client()
+        last_exc: Optional[BaseException] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await client.request(
+                    method,
+                    url,
+                    headers=self._headers(),
+                    json=json,
+                    params=params,
+                )
+                # Check for 511 before raise_for_status (it's treated as server error but is actually auth error)
+                if response.status_code == 511:
+                    body_preview = response.text[:500] if response.text else ""
+                    headers_sent = {k: "***" if k.lower() == "pim-sid" else v for k, v in self._headers().items()}
+                    raise AgentExecutionError(
+                        f"Network Authentication Required (511)\n"
+                        f"This usually means the API key is invalid or missing required headers.\n"
+                        f"URL: {url}\n"
+                        f"Response: {body_preview}\n"
+                        f"Headers sent: {headers_sent}\n"
+                        f"Please verify your API_KEY in .env file is correct."
+                    )
+                response.raise_for_status()
+                return self._parse_json(response)
+            except (httpx.HTTPStatusError, httpx.TransportError) as exc:
+                last_exc = exc
+                status = (
+                    getattr(exc.response, "status_code", None)
+                    if isinstance(exc, httpx.HTTPStatusError)
+                    else None
+                )
+
+                # For client errors (4xx, 511), surface a clear SDK error immediately.
+                if isinstance(exc, httpx.HTTPStatusError) and status is not None:
+                    # Get full response body for better debugging
+                    body_text = exc.response.text if exc.response.text else ""
+                    try:
+                        # Try to parse as JSON to get structured error message
+                        body_json = exc.response.json() if body_text else {}
+                        import json as json_module
+                        # Show full JSON response for debugging
+                        error_detail = json_module.dumps(body_json, indent=2) if body_json else body_text[:1000]
+                        # Also try to extract message field if present
+                        if isinstance(body_json, dict):
+                            error_msg_text = body_json.get("message") or body_json.get("error") or ""
+                            if error_msg_text:
+                                error_detail = f"{error_msg_text}\n\nFull response:\n{error_detail}"
+                    except:
+                        error_detail = body_text[:1000]
+                    
+                    # Include more details for debugging
+                    headers_sent = {k: "***" if k.lower() == "pim-sid" else v for k, v in self._headers().items()}
+                    payload_sent = json if json else {}
+                    # Add helpful suggestions for 400 errors
+                    suggestions = ""
+                    if status == 400:
+                        suggestions = (
+                            "\n\nTroubleshooting tips for 400 Bad Request:\n"
+                            "1. Verify the agent_id exists and is published in your environment\n"
+                            "2. Check if X-PROJECT-ID header is required (set PROJECT_ID in .env)\n"
+                            "3. Ensure USER_ID, SELLER_ID, SELLER_PROFILE_ID match the agent's configuration\n"
+                            "4. Check backend logs using requestId to see the specific validation error\n"
+                        )
+                    error_msg = (
+                        f"Request to {url} failed with {status} {exc.response.reason_phrase}\n"
+                        f"Response body: {error_detail}\n"
+                        f"Headers sent: {headers_sent}\n"
+                        f"Payload sent: {json_module.dumps(payload_sent, indent=2)[:1000]}"
+                        f"{suggestions}"
+                    )
+                    if 400 <= status < 500 or status == 511:
+                        raise AgentExecutionError(error_msg) from exc
+
+                should_retry = status is None or (500 <= status < 600 and status != 511)
+                if not should_retry or attempt >= self.max_retries:
+                    raise
+
+                backoff = self.backoff_factor * (2**attempt)
+                await asyncio.sleep(backoff)
+
+        assert last_exc is not None
+        raise last_exc
+
+    @staticmethod
+    def _parse_json(response: httpx.Response) -> Dict[str, Any]:
+        try:
+            data = response.json()
+        except json.JSONDecodeError:
+            raise AgentExecutionError(
+                f"Invalid JSON response from {response.url!s}: {response.text[:200]}"
+            )
+        if not isinstance(data, dict):
+            raise AgentExecutionError(
+                f"Expected JSON object from {response.url!s}, got: {type(data).__name__}"
+            )
+        return data
+
+    @staticmethod
+    def _extract_ids(payload: Dict[str, Any]) -> tuple[str, str]:
+        """Extract conversation_id and message_id from API response.
+        
+        Response structure: BaseRestResponse<ChatResponse>
+        {
+          "result": {
+            "conversationId": "...",
+            "messageId": "...",
+            "response": [Messages...]
+          }
+        }
+        """
+        # Extract from BaseRestResponse<ChatResponse> structure
+        result = payload.get("result", {})
+        if isinstance(result, dict):
+            # ChatResponse has conversationId and messageId at top level
+            conv_id = result.get("conversationId") or result.get("conversation_id")
+            msg_id = result.get("messageId") or result.get("message_id")
+            
+            # If not at top level, try from first message in response array
+            if not (conv_id and msg_id):
+                response_list = result.get("response", [])
+                if response_list and isinstance(response_list, list) and len(response_list) > 0:
+                    message = response_list[0]
+                    if isinstance(message, dict):
+                        # Try to get from message object
+                        if not conv_id:
+                            conv_id = message.get("cId") or message.get("conversationId") or message.get("conversation_id")
+                        if not msg_id:
+                            msg_id = message.get("id") or message.get("messageId") or message.get("message_id")
+            
+            if conv_id and msg_id:
+                return str(conv_id), str(msg_id)
+
+        # Fallback: try direct keys in payload
+        conv_id = payload.get("conversationId") or payload.get("conversation_id")
+        msg_id = payload.get("messageId") or payload.get("message_id") or payload.get("id")
+
+        if conv_id and msg_id:
+            return str(conv_id), str(msg_id)
+
+        raise AgentExecutionError(
+            f"Could not find conversation_id and message_id in response: {json.dumps(payload)[:200]}"
+        )
+
+    @staticmethod
+    def _parse_sse_line(line: str) -> Optional[str]:
+        """Parse a Server-Sent Events (SSE) format line.
+        
+        SSE format rules:
+        - Lines starting with "data:" contain the actual content
+        - Lines starting with "event:" are event types (ignored)
+        - Lines starting with ":" are comments (ignored)
+        - Empty lines separate events (ignored)
+        - If line doesn't match SSE format, return as-is (backward compatibility)
+        
+        Args:
+            line: Raw line from the stream
+            
+        Returns:
+            Content string if it's a data line or plain text, None if it should be ignored
+        """
+        if not line:
+            return None  # Empty lines are event separators in SSE
+        
+        line = line.strip()
+        if not line:
+            return None
+        
+        # SSE format: "data: <content>"
+        if line.startswith("data:"):
+            # Extract content after "data:" (may have leading space)
+            content = line[5:].lstrip()
+            return content
+        
+        # SSE format: "event: <event_type>" - ignore
+        if line.startswith("event:"):
+            return None
+        
+        # SSE format: ": <comment>" - ignore
+        if line.startswith(":"):
+            return None
+        
+        # Not SSE format - return as-is for backward compatibility
+        # (handles plain text streams from Redis)
+        return line
+
+    # Keys in result that are metadata, not message_id (External API puts message_id as key)
+    _RESULT_METADATA_KEYS = frozenset({
+        "trace_id", "traceId", "node_id", "nodeId", "job_id", "jobId",
+    })
+
+    @staticmethod
+    def _parse_message_response(payload: Dict[str, Any]) -> tuple[AgentStatus, str]:
+        """Parse message response and extract status and text.
+
+        Supports:
+        1) Standard shape: result.response[0].queryResult / messageStatus
+        2) External API shape: result[message_id] = message object (or null), result.trace_id
+        """
+        # Extract from BaseRestResponse<ChatResponse> structure
+        result = payload.get("result", {})
+        if isinstance(result, dict):
+            # Standard: result.response = [ { queryResult, messageStatus } ]
+            response_list = result.get("response", [])
+            if response_list and isinstance(response_list, list) and len(response_list) > 0:
+                message = response_list[0]
+                if isinstance(message, dict):
+                    status_raw = message.get("messageStatus") or message.get("message_status")
+                    response_text = message.get("queryResult") or message.get("query_result") or ""
+                    if status_raw is not None:
+                        status = AgentStatus.from_raw(status_raw)
+                    else:
+                        status = AgentStatus.COMPLETED if response_text else AgentStatus.PROCESSING
+                    return status, str(response_text) if response_text else ""
+
+            # External API shape: result = { message_id: message_data_or_null, trace_id: ... }
+            # message_id is the key that's not in _RESULT_METADATA_KEYS
+            for key, value in result.items():
+                if key in AgentClient._RESULT_METADATA_KEYS:
+                    continue
+                # This key is the message_id; value is message data or None
+                if isinstance(value, dict):
+                    response_text = value.get("queryResult") or value.get("query_result") or ""
+                    status_raw = value.get("messageStatus") or value.get("message_status")
+                    status = AgentStatus.from_raw(status_raw) if status_raw is not None else (
+                        AgentStatus.COMPLETED if response_text else AgentStatus.PROCESSING
+                    )
+                    return status, str(response_text) if response_text else ""
+                # value is None (backend sent getResult() which is null) -> return empty response
+                return AgentStatus.COMPLETED, ""
+
+        # Fallback: direct keys; never use result dict as response text
+        status_raw = payload.get("messageStatus") or payload.get("status")
+        raw_result = payload.get("result")
+        raw_response = payload.get("response")
+        response_text = (
+            payload.get("queryResult")
+            or payload.get("query_result")
+            or (raw_result if isinstance(raw_result, str) else "")
+            or (raw_response if isinstance(raw_response, str) else "")
+            or ""
+        )
+
+        if status_raw is not None:
+            status = AgentStatus.from_raw(status_raw)
+        else:
+            status = AgentStatus.COMPLETED if response_text else AgentStatus.PROCESSING
+
+        return status, str(response_text) if response_text else ""
+