agentengine-sdk-python 0.6.9__py3-none-any.whl → 0.7.0__py3-none-any.whl

ksadk/conversations/message_projection.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import quote
+
+
+def project_session_messages(
+    events: Sequence[Mapping[str, Any]],
+    *,
+    include_reasoning: bool = False,
+    include_tool_events: bool = False,
+    include_attachments: bool = True,
+) -> list[dict[str, Any]]:
+    """Project persisted runtime events into the chat history contract."""
+
+    groups: dict[str, list[Mapping[str, Any]]] = {}
+    for event in sorted(events, key=lambda item: int(item.get("SeqId") or 0)):
+        invocation_id = str(event.get("InvocationId") or f"seq:{event.get('SeqId')}")
+        groups.setdefault(invocation_id, []).append(event)
+
+    messages: list[dict[str, Any]] = []
+    for group in groups.values():
+        messages.extend(
+            _project_event_group(
+                group,
+                include_reasoning=include_reasoning,
+                include_tool_events=include_tool_events,
+                include_attachments=include_attachments,
+            )
+        )
+    return sorted(messages, key=lambda item: int(item.get("SeqId") or 0))
+
+
+def _project_event_group(
+    events: Sequence[Mapping[str, Any]],
+    *,
+    include_reasoning: bool,
+    include_tool_events: bool,
+    include_attachments: bool,
+) -> list[dict[str, Any]]:
+    reasoning = [
+        {"text": _event_text(event), "SeqId": event.get("SeqId")}
+        for event in events
+        if event.get("EventType") == "reasoning" and _event_text(event)
+    ]
+    tool_events = _project_tool_events(events) if include_tool_events else []
+    projected: list[dict[str, Any]] = []
+    assistant_seen = False
+
+    for event in events:
+        event_type = str(event.get("EventType") or "")
+        if event_type == "user_message":
+            message = _base_message(event, "user")
+            if include_attachments:
+                attachments = _event_attachments(event)
+                if attachments:
+                    message["Attachments"] = attachments
+            projected.append(message)
+        elif event_type == "assistant_message":
+            message = _base_message(event, "assistant")
+            if include_reasoning and reasoning:
+                message["Reasoning"] = reasoning
+            if tool_events:
+                message["ToolEvents"] = tool_events
+            projected.append(message)
+            assistant_seen = True
+
+    if not assistant_seen and (reasoning or tool_events):
+        anchor = next(
+            (
+                event
+                for event in reversed(events)
+                if event.get("EventType")
+                in {"assistant_stream_snapshot", "approval_request", "tool_call", "reasoning"}
+            ),
+            events[-1],
+        )
+        message = _base_message(anchor, "assistant", content="")
+        if include_reasoning and reasoning:
+            message["Reasoning"] = reasoning
+        if tool_events:
+            message["ToolEvents"] = tool_events
+        projected.append(message)
+
+    return projected
+
+
+def _base_message(
+    event: Mapping[str, Any],
+    role: str,
+    *,
+    content: str | None = None,
+) -> dict[str, Any]:
+    metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+    message: dict[str, Any] = {
+        "MessageId": event.get("EventId"),
+        "Role": role,
+        "Content": {"text": _event_text(event) if content is None else content},
+        "Timestamp": event.get("Timestamp"),
+        "SeqId": event.get("SeqId"),
+        "InvocationId": event.get("InvocationId"),
+    }
+    for target, *sources in (
+        ("ResponseId", "response_id", "ResponseId"),
+        ("TraceId", "trace_id", "TraceId"),
+        ("RootSpanId", "root_span_id", "rootSpanId", "RootSpanId"),
+    ):
+        value = next((metadata.get(source) for source in sources if metadata.get(source)), None)
+        if value:
+            message[target] = str(value)
+    return message
+
+
+def _event_text(event: Mapping[str, Any]) -> str:
+    content = event.get("Content")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, Mapping):
+        return ""
+    if content.get("text") is not None:
+        return str(content.get("text") or "")
+    return "".join(
+        str(part.get("text") or "")
+        for part in content.get("parts") or []
+        if isinstance(part, Mapping)
+    )
+
+
+def _project_tool_events(events: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    projected: list[dict[str, Any]] = []
+    pending_calls: list[tuple[Mapping[str, Any], dict[str, Any]]] = []
+
+    for event in events:
+        event_type = str(event.get("EventType") or "")
+        metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+        if event_type == "tool_call":
+            entry = _tool_event_from_call(event, metadata)
+            projected.append(entry)
+            pending_calls.append((event, entry))
+            continue
+        if event_type != "tool_result":
+            continue
+
+        name = str(metadata.get("tool_name") or "tool")
+        match = next(
+            (
+                item
+                for item in reversed(pending_calls)
+                if item[1]["Name"] == name and item[1]["Status"] == "running"
+            ),
+            None,
+        )
+        if match is None:
+            entry = _tool_event_from_call(event, metadata)
+            projected.append(entry)
+        else:
+            entry = match[1]
+        output = metadata.get("tool_output", _event_text(event))
+        entry["Status"] = (
+            "failed" if isinstance(output, Mapping) and output.get("ok") is False else "completed"
+        )
+        entry["Result"] = output
+        entry["ResultSeqId"] = event.get("SeqId")
+
+    projected.extend(_project_approval_events(events))
+    return projected
+
+
+def _tool_event_from_call(
+    event: Mapping[str, Any], metadata: Mapping[str, Any]
+) -> dict[str, Any]:
+    tool_receipt = metadata.get("tool_receipt")
+    call_id = metadata.get("call_id") or metadata.get("run_id")
+    if not call_id and isinstance(tool_receipt, Mapping):
+        call_id = tool_receipt.get("tool_call_id")
+    return {
+        "SeqId": event.get("SeqId"),
+        "Type": "tool_call",
+        "Name": str(metadata.get("tool_name") or "tool"),
+        "Args": metadata.get("tool_args"),
+        "Status": "running",
+        "ToolCallId": call_id,
+    }
+
+
+def _project_approval_events(events: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    responses: dict[str, Mapping[str, Any]] = {}
+    for event in events:
+        if event.get("EventType") != "approval_response":
+            continue
+        metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+        resume_input = metadata.get("resume_input")
+        if not isinstance(resume_input, Mapping):
+            continue
+        request_id = str(
+            resume_input.get("approval_request_id")
+            or resume_input.get("interrupt_id")
+            or resume_input.get("id")
+            or ""
+        )
+        responses[request_id] = event
+
+    approvals: list[dict[str, Any]] = []
+    for request in events:
+        if request.get("EventType") != "approval_request":
+            continue
+        metadata = request.get("Metadata") if isinstance(request.get("Metadata"), Mapping) else {}
+        interrupt_info = metadata.get("interrupt_info")
+        if not isinstance(interrupt_info, Mapping):
+            interrupt_info = {}
+        request_id = str(
+            interrupt_info.get("approval_request_id") or interrupt_info.get("id") or ""
+        )
+        response = responses.get(request_id)
+        response_metadata = (
+            response.get("Metadata")
+            if response is not None and isinstance(response.get("Metadata"), Mapping)
+            else {}
+        )
+        resume_input = response_metadata.get("resume_input")
+        if not isinstance(resume_input, Mapping):
+            resume_input = {}
+        status = "paused" if response is None else (
+            "approved"
+            if resume_input.get("approve") or resume_input.get("approved")
+            else "denied"
+        )
+        entry: dict[str, Any] = {
+            "SeqId": request.get("SeqId"),
+            "Type": "approval",
+            "Name": str(interrupt_info.get("tool_name") or "approval"),
+            "Status": status,
+            "ApprovalRequestId": request_id or None,
+        }
+        arguments = (
+            interrupt_info.get("arguments")
+            or interrupt_info.get("tool_args")
+            or interrupt_info.get("args")
+        )
+        if arguments is not None:
+            entry["Args"] = arguments
+        approvals.append(entry)
+    return approvals
+
+
+def _event_attachments(event: Mapping[str, Any]) -> list[dict[str, Any]]:
+    metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+    attachments: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in metadata.get("attachments") or []:
+        if not isinstance(item, Mapping):
+            continue
+        file_uri = str(item.get("file_uri") or item.get("fileUri") or "")
+        if not file_uri or file_uri in seen:
+            continue
+        mime = str(item.get("mime_type") or item.get("mimeType") or "")
+        attachments.append(
+            {
+                "file_uri": file_uri,
+                "name": str(item.get("display_name") or item.get("displayName") or ""),
+                "mime": mime,
+                "size": int(item.get("size_bytes") or item.get("sizeBytes") or 0),
+                "is_image": mime.startswith("image/"),
+                "url": "/agentengine/api/v1/AttachmentContent?FileUri=" + quote(file_uri, safe=""),
+            }
+        )
+        seen.add(file_uri)
+    return attachments

ksadk/conversations/model_context.py

@@ -182,6 +182,16 @@ def estimate_text_tokens(text: str) -> int:
     return max(1, cjk_tokens + math.ceil(ascii_chars / 4))
 
 
+def get_context_window_tokens(model_metadata: Mapping[str, Any] | None = None) -> int:
+    limits = dict(DEFAULT_MODEL_LIMITS)
+    if isinstance(model_metadata, Mapping):
+        limits.update(dict(model_metadata.get("limits") or {}))
+        if model_metadata.get("context_window_tokens"):
+            limits["context_window_tokens"] = model_metadata["context_window_tokens"]
+
+    return _coerce_positive_int(limits.get("context_window_tokens")) or DEFAULT_CONTEXT_WINDOW_TOKENS
+
+
 def get_effective_context_window_tokens(model_metadata: Mapping[str, Any] | None = None) -> int:
     limits = dict(DEFAULT_MODEL_LIMITS)
     if isinstance(model_metadata, Mapping):
@@ -191,7 +201,7 @@ def get_effective_context_window_tokens(model_metadata: Mapping[str, Any] | None
         if model_metadata.get("max_output_tokens"):
             limits["max_output_tokens"] = model_metadata["max_output_tokens"]
 
-    context_window = _coerce_positive_int(limits.get("context_window_tokens")) or DEFAULT_CONTEXT_WINDOW_TOKENS
+    context_window = get_context_window_tokens(model_metadata)
     max_output_tokens = _coerce_positive_int(limits.get("max_output_tokens")) or DEFAULT_MAX_OUTPUT_TOKENS
     reserved_tokens = min(max_output_tokens, AUTOCOMPACT_SUMMARY_RESERVE_TOKENS)
     return max(1, context_window - reserved_tokens)

ksadk/conversations/runtime.py

@@ -534,6 +534,59 @@ def _set_conversation_output_attributes(span: Any | None, output_text: str | Non
         _set_span_attribute(span, key, text)
 
 
+def _set_conversation_usage_attributes(
+    span: Any | None,
+    usage: Mapping[str, Any] | None,
+) -> None:
+    normalized = _normalize_usage_payload(usage)
+    if not normalized:
+        return
+
+    def _usage_int(value: Any) -> int:
+        try:
+            return int(value or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    input_tokens = _usage_int(normalized.get("input_tokens"))
+    output_tokens = _usage_int(normalized.get("output_tokens"))
+    total_tokens = _usage_int(normalized.get("total_tokens") or (input_tokens + output_tokens))
+    input_details = normalized.get("input_token_details")
+    output_details = normalized.get("output_token_details")
+    cache_read_tokens = 0
+    reasoning_tokens = 0
+    if isinstance(input_details, Mapping):
+        cache_read_tokens = _usage_int(
+            input_details.get("cache_read")
+            or input_details.get("cached")
+            or input_details.get("cached_tokens")
+        )
+    if isinstance(output_details, Mapping):
+        reasoning_tokens = _usage_int(
+            output_details.get("reasoning")
+            or output_details.get("reasoning_tokens")
+        )
+
+    attributes = {
+        "gen_ai.usage.input_tokens": input_tokens,
+        "gen_ai.usage.output_tokens": output_tokens,
+        "gen_ai.usage.total_tokens": total_tokens,
+        "llm.usage.prompt_tokens": input_tokens,
+        "llm.usage.completion_tokens": output_tokens,
+        "llm.usage.total_tokens": total_tokens,
+    }
+    if cache_read_tokens:
+        attributes["gen_ai.usage.cache_read.input_tokens"] = cache_read_tokens
+        attributes["llm.usage.cache_read.input_tokens"] = cache_read_tokens
+    if reasoning_tokens:
+        attributes["gen_ai.usage.reasoning.output_tokens"] = reasoning_tokens
+        attributes["llm.usage.reasoning_tokens"] = reasoning_tokens
+
+    for key, value in attributes.items():
+        if value:
+            _set_span_attribute(span, key, value)
+
+
 def _set_conversation_span_attributes(
     span: Any,
     *,
@@ -3862,6 +3915,7 @@ async def invoke_conversation_once(
             (result.get("metadata") or {}).get("last_usage")
         ) or (result_usage if result_usage else {})
         _set_conversation_output_attributes(span, output_text)
+        _set_conversation_usage_attributes(span, result_usage)
         result_agentengine_metadata = _extract_agentengine_metadata(result)
         assistant_metadata: dict[str, Any] = {
             **trace_metadata,
@@ -4148,6 +4202,7 @@ async def _iter_conversation_turn_events(
         )
 
         accumulated_text = ""
+        accumulated_reasoning_parts: list[str] = []
         emitted_anything = False
         emitted_response_artifacts = False
         saw_final_chunk = False
@@ -4157,6 +4212,20 @@ async def _iter_conversation_turn_events(
         stream_usage: dict[str, Any] = {}
         stream_last_usage: dict[str, Any] = {}
         reasoning_disabled = _model_options_disable_reasoning(prepared.model_options)
+
+        async def _persist_accumulated_reasoning() -> None:
+            if not accumulated_reasoning_parts:
+                return
+            reasoning = "".join(accumulated_reasoning_parts)
+            accumulated_reasoning_parts.clear()
+            await append_reasoning_event(
+                session_id=prepared.session_id,
+                author=runner_name,
+                text=reasoning,
+                invocation_id=prepared.invocation_id,
+                session_service_provider=provider,
+            )
+
         for attempt in range(2):
             try:
                 runtime_context.history = list(prepared.history)
@@ -4237,12 +4306,8 @@ async def _iter_conversation_turn_events(
                                         responses_output
                                     ):
                                         if semantic_event.get("type") == "thinking":
-                                            await append_reasoning_event(
-                                                session_id=prepared.session_id,
-                                                author=runner_name,
-                                                text=str(semantic_event.get("delta") or ""),
-                                                invocation_id=prepared.invocation_id,
-                                                session_service_provider=provider,
+                                            accumulated_reasoning_parts.append(
+                                                str(semantic_event.get("delta") or "")
                                             )
                                         emitted_anything = True
                                         yield semantic_event
@@ -4252,13 +4317,7 @@ async def _iter_conversation_turn_events(
                                     continue
                                 delta = str(chunk.get("delta", ""))
                                 if delta:
-                                    await append_reasoning_event(
-                                        session_id=prepared.session_id,
-                                        author=runner_name,
-                                        text=delta,
-                                        invocation_id=prepared.invocation_id,
-                                        session_service_provider=provider,
-                                    )
+                                    accumulated_reasoning_parts.append(delta)
                                     emitted_anything = True
                                     emitted_response_artifacts = True
                                     yield {"type": "thinking", "delta": delta}
@@ -4295,6 +4354,7 @@ async def _iter_conversation_turn_events(
                                     session_service_provider=provider,
                                 )
                                 emitted_anything = True
+                                await _persist_accumulated_reasoning()
                                 yield {
                                     "type": "tool_call",
                                     "name": chunk.get("tool_name"),
@@ -4391,6 +4451,7 @@ async def _iter_conversation_turn_events(
                                         run_trigger=run_trigger,
                                     )
                                     emitted_anything = True
+                                    await _persist_accumulated_reasoning()
                                     yield {
                                         "type": "interrupt",
                                         "interrupt_info": approval_interrupt_info,
@@ -4448,6 +4509,7 @@ async def _iter_conversation_turn_events(
                                     governance, chunk.get("tool_output", "")
                                 )
                                 emitted_anything = True
+                                await _persist_accumulated_reasoning()
                                 yield {
                                     "type": "tool_result",
                                     "name": chunk.get("tool_name"),
@@ -4497,6 +4559,7 @@ async def _iter_conversation_turn_events(
                                     stream_last_usage = _normalize_usage_payload(chunk_last) or stream_usage
                 break
             except asyncio.CancelledError:
+                await _persist_accumulated_reasoning()
                 await append_run_status_event(
                     session_id=prepared.session_id,
                     author=runner_name,
@@ -4541,6 +4604,7 @@ async def _iter_conversation_turn_events(
                             run_mode=run_mode,
                             run_trigger=run_trigger,
                         )
+                        await _persist_accumulated_reasoning()
                         yield {"type": "error", "message": str(circuit_exc) or "Agent 运行失败"}
                         return
                     if checkpoint:
@@ -4594,6 +4658,7 @@ async def _iter_conversation_turn_events(
                     run_mode=run_mode,
                     run_trigger=run_trigger,
                 )
+                await _persist_accumulated_reasoning()
                 yield {"type": "error", "message": str(exc) or "Agent 运行失败"}
                 return
 
@@ -4628,6 +4693,7 @@ async def _iter_conversation_turn_events(
                 run_mode=run_mode,
                 run_trigger=run_trigger,
             )
+            await _persist_accumulated_reasoning()
             _finish_span()
             yield {
                 "type": "error",
@@ -4641,6 +4707,7 @@ async def _iter_conversation_turn_events(
             return
         _set_conversation_output_attributes(span, accumulated_text)
 
+        await _persist_accumulated_reasoning()
         await append_conversation_event(
             session_id=prepared.session_id,
             author=runner_name,
@@ -4674,6 +4741,7 @@ async def _iter_conversation_turn_events(
             run_mode=run_mode,
             run_trigger=run_trigger,
         )
+        _set_conversation_usage_attributes(span, assistant_metadata.get("usage"))
         _finish_span()
         yield {
             "type": "completed",

ksadk/deployment/base.py

@@ -41,7 +41,7 @@ class NetworkConfig(BaseModel):
     """网络配置"""
     access_type: str = "public"  # public | private
     enable_https: bool = True
-    enable_public_access: bool = False
+    enable_public_access: Optional[bool] = None
     enable_vpc_access: bool = False
     vpc_id: str = ""
     subnet_id: str = ""

ksadk/deployment/providers/serverless.py

@@ -261,22 +261,32 @@ class ServerlessProvider(BaseDeployProvider):
             json.dump(payload, f, indent=2, ensure_ascii=False)
 
     @staticmethod
-    def _serialize_network_config(target: DeployTarget) -> Optional[Dict[str, Any]]:
+    def _serialize_network_config(
+        target: DeployTarget, *, is_update: bool = False
+    ) -> Optional[Dict[str, Any]]:
         network = getattr(target, "network", None)
         if network is None:
             return None
 
-        payload: Dict[str, Any] = {
-            "enable_public_access": bool(getattr(network, "enable_public_access", False)),
-            "enable_vpc_access": bool(getattr(network, "enable_vpc_access", False)),
-        }
+        public_access = getattr(network, "enable_public_access", None)
+        # 三态：None=未指定。create 默认开公网；update 未指定则不发 network 字段（保留服务端现有配置）。
+        if public_access is None:
+            public_value: Optional[bool] = None if is_update else True
+        else:
+            public_value = bool(public_access)
+
+        payload: Dict[str, Any] = {}
+        if public_value is not None:
+            payload["enable_public_access"] = public_value
+        if bool(getattr(network, "enable_vpc_access", False)):
+            payload["enable_vpc_access"] = True
 
         for field in ("vpc_id", "subnet_id", "security_group_id", "availability_zone"):
             value = str(getattr(network, field, "") or "").strip()
             if value:
                 payload[field] = value
 
-        if not payload["enable_public_access"] and not payload["enable_vpc_access"] and len(payload) == 2:
+        if not payload:
             return None
         return payload
 
@@ -710,7 +720,7 @@ class ServerlessProvider(BaseDeployProvider):
                             else:
                                 click.echo(f"   📦 更新环境变量: {len(env_vars)} 项 from 全局配置")
 
-                        network_config = self._serialize_network_config(target)
+                        network_config = self._serialize_network_config(target, is_update=True)
                         if network_config:
                             update_data["network"] = network_config
 
@@ -829,7 +839,7 @@ class ServerlessProvider(BaseDeployProvider):
                     if env_vars:
                          request_data["env_vars"] = env_vars
 
-                    network_config = self._serialize_network_config(target)
+                    network_config = self._serialize_network_config(target, is_update=False)
                     if network_config:
                         request_data["network"] = network_config