agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/conversations/runtime_stream_events.py

@@ -10,6 +10,7 @@ from ksadk.conversations.run_kinds import (
     trigger_from_resume_input,
     validate_run_mode,
 )
+from ksadk.conversations.runtime_baseline import record_baseline_turn
 from ksadk.conversations.runtime_compaction import preview_auto_compaction
 from ksadk.conversations.runtime_constants import (
     ASSISTANT_STREAM_SNAPSHOT_INTERVAL_SECONDS,
@@ -46,6 +47,7 @@ from ksadk.conversations.runtime_observability import (
     _set_conversation_usage_attributes,
     _set_prompt_cache_attributes,
     _set_prompt_source_attributes,
+    _set_skill_eval_result_attributes,
     _set_span_attribute,
     _span_current_context,
     _span_feedback_metadata,
@@ -57,6 +59,7 @@ from ksadk.conversations.runtime_persistence import (
     append_reasoning_event,
     append_run_checkpoint_event,
     append_run_status_event,
+    prepare_stream_identity_session,
 )
 from ksadk.conversations.runtime_preparation import _refresh_history, build_run_input
 from ksadk.conversations.runtime_resume import (
@@ -72,6 +75,7 @@ from ksadk.conversations.runtime_resume import (
     _tool_receipt_metadata,
 )
 from ksadk.model_policy import fallback_model_for_exception, model_policy_options_for_model
+from ksadk.runtime.skill_eval_result import skill_eval_response_fields
 from ksadk.runtime_context import (
     PlatformInvocationContext,
     platform_invocation_scope,
@@ -83,35 +87,6 @@ from ksadk.tools.gateway import (
 )
 
 
-def _record_baseline_turn(
-    *,
-    prepared: Any,
-    model: str | None,
-    usage: Any,
-    ptl: bool,
-    attempts: int,
-    turn_start_monotonic: float | None,
-) -> None:
-    """env-gated 旁路采集：未启用时 no-op，启用时记录一条 turn 基线。不进决策路径。"""
-    from ksadk.context_engine.baseline import record_baseline_turn
-
-    latency_ms = None
-    if turn_start_monotonic is not None:
-        latency_ms = int((time.monotonic() - turn_start_monotonic) * 1000)
-    record_baseline_turn(
-        getattr(prepared, "shadow_context_plan", None),
-        session_id=getattr(prepared, "session_id", ""),
-        invocation_id=getattr(prepared, "invocation_id", ""),
-        model=str(model or ""),
-        usage=usage if isinstance(usage, Mapping) else None,
-        compaction_triggered=bool(getattr(prepared, "compaction_triggered", False)),
-        compaction_trigger=str(getattr(prepared, "compaction_trigger", "") or ""),
-        prompt_too_long=ptl,
-        retry_attempts=attempts,
-        turn_latency_ms=latency_ms,
-    )
-
-
 async def _iter_conversation_turn_events(
     *,
     runner: Any,
@@ -145,6 +120,18 @@ async def _iter_conversation_turn_events(
     _governance_record_turn_start(governance)
     entry_run_mode = validate_run_mode(run_mode)
     entry_run_trigger = trigger_from_resume_input(resume_input)
+    (
+        user_id,
+        session_id,
+        invocation_identity,
+        public_request_metadata,
+    ) = await prepare_stream_identity_session(
+        agent_id=agent_id,
+        user_id=user_id,
+        session_id=session_id,
+        request_metadata=request_metadata,
+        session_service_provider=provider,
+    )
     if resume_input is None:
         compaction_preview = await preview_auto_compaction(
             agent_id=agent_id,
@@ -220,9 +207,10 @@ async def _iter_conversation_turn_events(
         yield {"type": "error", "message": str(exc) or "Agent 运行失败"}
         return
     _inject_runner_deferred_tools_for_request(runner, prepared)
+    effective_user_id = prepared.user_id or user_id
     ambient_contexts = _build_runner_ambient_contexts(
         runner=runner,
-        user_id=user_id,
+        user_id=effective_user_id,
         user_input=prepared.user_input,
     )
     prepared.memory_recall_events = ambient_contexts.get("memory_recall_events", [])
@@ -231,7 +219,7 @@ async def _iter_conversation_turn_events(
     runtime_context = PlatformInvocationContext(
         session=SessionContext.from_payload(prepared.session_context),
         agent_id=agent_id,
-        user_id=user_id,
+        user_id=effective_user_id,
         account_id=str(account_id or ""),
         session_id=prepared.session_id,
         history=list(prepared.history),
@@ -250,6 +238,7 @@ async def _iter_conversation_turn_events(
         kb_context=ambient_contexts.get("kb_context"),
         memory_context=ambient_contexts.get("memory_context"),
         tool_approval_mode=str(prepared.request_metadata.get("tool_approval_mode") or ""),
+        identity=invocation_identity,
     )
     if prepared.compaction_triggered:
         yield {
@@ -293,7 +282,7 @@ async def _iter_conversation_turn_events(
         _set_conversation_span_attributes(
             span,
             agent_id=agent_id,
-            user_id=user_id,
+            user_id=effective_user_id,
             session_id=prepared.session_id,
             invocation_id=prepared.invocation_id,
             runner_name=runner_name,
@@ -309,7 +298,7 @@ async def _iter_conversation_turn_events(
         yield {
             "type": "started",
             "session_id": prepared.session_id,
-            "metadata": {**trace_metadata, **dict(request_metadata or {})},
+            "metadata": {**trace_metadata, **public_request_metadata},
         }
         await append_run_status_event(
             session_id=prepared.session_id,
@@ -329,6 +318,7 @@ async def _iter_conversation_turn_events(
         emitted_anything = False
         emitted_response_artifacts = False
         saw_final_chunk = False
+        result_fields: dict[str, Any] = {}
         responses_output: list[Any] = []
         responses_response_id: str | None = response_id
         runner_agentengine_metadata: dict[str, Any] = {}
@@ -756,6 +746,9 @@ async def _iter_conversation_turn_events(
                                 return
                             if chunk_type == "final":
                                 saw_final_chunk = True
+                                result_fields = skill_eval_response_fields(chunk)
+                                if result_fields:
+                                    _set_skill_eval_result_attributes(span, result_fields["skill_eval_result"])
                                 final_text = str(chunk.get("output", ""))
                                 if final_text:
                                     accumulated_text = final_text
@@ -946,7 +939,7 @@ async def _iter_conversation_turn_events(
         )
         await _auto_save_ltm_turn(
             agent_id=agent_id,
-            user_id=user_id,
+            user_id=effective_user_id,
             prepared=prepared,
             output_text=accumulated_text,
             runner_type=runtime_context.runner_type,
@@ -969,7 +962,7 @@ async def _iter_conversation_turn_events(
             usage=assistant_metadata.get("usage"),
         )
         _set_prompt_source_attributes(span, getattr(prepared, "compiled_prompt", None))
-        _record_baseline_turn(
+        record_baseline_turn(
             prepared=prepared,
             model=model,
             usage=assistant_metadata.get("usage"),
@@ -980,6 +973,7 @@ async def _iter_conversation_turn_events(
         _finish_span()
         yield {
             "type": "completed",
+            **result_fields,
             "output_text": accumulated_text,
             "model": model,
             "session_id": prepared.session_id,

ksadk/conversations/runtime_streaming.py

@@ -205,6 +205,8 @@ async def _stream_conversation_semantic_events(
                     event.get("metadata") if isinstance(event.get("metadata"), Mapping) else None
                 ),
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
             )
             yield _response_sse("response.completed", final_payload)
 
@@ -626,6 +628,8 @@ async def _stream_responses_semantic_events(
                 status="failed",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
                 error={"message": event.get("message") or "Agent 运行失败"},
             )
             yield _response_sse("response.failed", failed_payload)
@@ -641,6 +645,8 @@ async def _stream_responses_semantic_events(
                 status="cancelled",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
             )
             yield _response_sse("response.cancelled", cancelled_payload)
             return
@@ -704,6 +710,8 @@ async def _stream_responses_semantic_events(
                 status="completed",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
                 output_items=(
                     event.get("responses_output")
                     if isinstance(event.get("responses_output"), Sequence)

ksadk/conversations/tool_receipt_resume.py

@@ -0,0 +1,387 @@
+"""Durable receipt helpers used by approval resume orchestration."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import replace
+from typing import Any
+
+from ksadk.conversations.runtime_persistence import append_conversation_event
+from ksadk.sessions import SessionEvent, ToolReceiptClaim
+
+
+class ToolReceiptUncertainError(ValueError):
+    """A durable receipt exists without a safely replayable terminal result."""
+
+    def __init__(self, idempotency_key: str | None = None) -> None:
+        self.idempotency_key = str(idempotency_key or "")
+        detail = "tool receipt execution is uncertain; reconciliation required"
+        if self.idempotency_key:
+            detail += f"; idempotency_key={self.idempotency_key}"
+        super().__init__(detail)
+
+
+async def claim_receipt_for_execution(
+    *,
+    service: Any,
+    session_id: str,
+    receipt: Mapping[str, Any],
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    invocation_id: str,
+    preclaimed_receipt: tuple[dict[str, Any], ToolReceiptClaim] | None,
+) -> ToolReceiptClaim:
+    claim = (
+        preclaimed_receipt[1]
+        if preclaimed_receipt is not None
+        else await service.claim_tool_receipt(
+            session_id,
+            idempotency_key=str(receipt["idempotency_key"]),
+            tool_name=tool_name,
+            arguments_digest=_tool_receipt_arguments_digest(call_args),
+            claim_id=f"{invocation_id}:{uuid.uuid4().hex}",
+        )
+    )
+    return _validate_tool_receipt_claim(claim)
+
+
+async def replay_existing_tool_receipt_event(
+    *,
+    existing_event: SessionEvent,
+    receipt: Mapping[str, Any],
+    session_id: str,
+    invocation_id: str,
+    run_id: str,
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+) -> dict[str, Any]:
+    from ksadk.conversations.runtime_resume import _validate_tool_receipt_event
+
+    existing_metadata = existing_event.metadata or {}
+    _validate_tool_receipt_event(existing_event)
+    output = existing_metadata["tool_output"]
+    if isinstance(output, Mapping):
+        output = {**dict(output), "replayed": True}
+    replayed_receipt = {
+        **dict((existing_metadata.get("tool_receipt") or receipt)),
+        "replayed": True,
+        "replayed_from_event_id": existing_event.id,
+    }
+    await append_conversation_event(
+        session_id=session_id,
+        author="tool",
+        role="user",
+        text=str(output),
+        invocation_id=invocation_id,
+        event_type="tool_result",
+        session_service_provider=session_service_provider,
+        metadata={
+            "tool_name": tool_name,
+            "tool_args": dict(call_args),
+            "tool_output": output,
+            "run_id": run_id,
+            "approval_request_id": resume_input.get("approval_request_id")
+            or resume_input.get("interrupt_id"),
+            "tool_receipt": replayed_receipt,
+            "replayed": True,
+        },
+    )
+    return {"type": "function_call_output", "call_id": run_id, "output": output}
+
+
+def _validate_tool_receipt_claim_state(state: str, idempotency_key: str = "") -> str:
+    normalized = str(state or "").strip().lower()
+    if normalized not in {"unknown", "completed", "failed"}:
+        raise ToolReceiptUncertainError(idempotency_key)
+    return normalized
+
+
+def _validate_tool_receipt_claim(claim: ToolReceiptClaim) -> ToolReceiptClaim:
+    state = _validate_tool_receipt_claim_state(claim.state, claim.idempotency_key)
+    if isinstance(claim.output, Mapping) and state in {"completed", "failed"}:
+        expected = (
+            "completed"
+            if claim.output.get("status") == "accepted_not_extracted"
+            else ("failed" if claim.output.get("ok") is False else "completed")
+        )
+        if state != expected:
+            raise ToolReceiptUncertainError(claim.idempotency_key)
+    return claim
+
+
+def _tool_receipt_arguments_digest(tool_args: Mapping[str, Any]) -> str:
+    try:
+        encoded = json.dumps(tool_args, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    except TypeError:
+        encoded = json.dumps(str(tool_args), ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+def _pending_approval_events(events: Sequence[SessionEvent]) -> list[SessionEvent]:
+    from ksadk.conversations.runtime_resume import (
+        _approval_lifecycle_event_type,
+        _approval_request_id_from_event,
+    )
+
+    pending: list[SessionEvent] = []
+    for event in events:
+        event_type = _approval_lifecycle_event_type(event)
+        if event_type == "approval_request":
+            pending.append(event)
+            continue
+        if event_type != "approval_response" or not pending:
+            continue
+        resume_input = (event.metadata or {}).get("resume_input")
+        response_id = ""
+        if isinstance(resume_input, Mapping):
+            response_id = str(
+                resume_input.get("approval_request_id")
+                or resume_input.get("interrupt_id") or resume_input.get("id") or ""
+            )
+        content = event.content or {}
+        payload = content.get("runtime_event") or content.get("payload")
+        if not response_id and isinstance(payload, Mapping):
+            response_id = str(
+                payload.get("interaction_id") or payload.get("approval_id")
+                or payload.get("call_id") or ""
+            )
+        if response_id:
+            remaining = []
+            for item in pending:
+                request_ids = {_approval_request_id_from_event(item)}
+                request_payload = (item.content or {}).get("runtime_event")
+                if isinstance(request_payload, Mapping):
+                    request_ids.add(str(request_payload.get("interaction_id") or ""))
+                    request = request_payload.get("request")
+                    if isinstance(request, Mapping):
+                        request_ids.add(str(request.get("call_id") or ""))
+                if response_id not in request_ids:
+                    remaining.append(item)
+            pending = remaining
+        else:
+            pending.pop()
+    return pending
+
+
+def _has_pending_approval_for_resume(
+    events: Sequence[SessionEvent], resume_input: Mapping[str, Any]
+) -> bool:
+    from ksadk.conversations.runtime_resume import (
+        _approval_request_id_from_event,
+    )
+
+    decision = resume_input.get("approval")
+    decision = decision if isinstance(decision, Mapping) else {}
+    request_id = str(
+        resume_input.get("approval_request_id") or resume_input.get("interrupt_id")
+        or decision.get("approval_request_id") or ""
+    )
+    pending = _pending_approval_events(events)
+    if not request_id:
+        return bool(pending)
+    return any(_approval_request_id_from_event(event) == request_id for event in pending)
+
+
+async def _claim_approved_builtin_tool_resume(
+    *,
+    session_id: str,
+    invocation_id: str,
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+    existing_events: Sequence[SessionEvent],
+    require_existing: bool = False,
+) -> tuple[dict[str, Any] | None, ToolReceiptClaim | None]:
+    """Reserve an approved builtin before consuming its approval response."""
+
+    from ksadk.conversations.runtime_resume import (
+        LegacyToolReceiptCheckpointAmbiguityError,
+        _builtin_tool_callable,
+        _find_legacy_tool_receipt_event_for_resume,
+        _find_tool_receipt_event_by_key,
+        _latest_checkpoint_metadata_for_run,
+        _tool_receipt_metadata,
+        _tool_resume_run_id,
+        _validate_tool_receipt_event,
+    )
+
+    approval = resume_input.get("approval")
+    if not isinstance(approval, Mapping) or not bool(approval.get("approved")):
+        return None, None
+    tool_name = str(resume_input.get("tool_name") or "").strip()
+    tool_args = resume_input.get("tool_args")
+    if not tool_name or not isinstance(tool_args, Mapping):
+        return None, None
+    call_args = dict(tool_args)
+    run_id = _tool_resume_run_id(resume_input)
+    if not run_id:
+        return None, None
+    checkpoint_metadata = _latest_checkpoint_metadata_for_run(existing_events, run_id)
+    requested_checkpoint_id = str(resume_input.get("checkpoint_id") or "").strip()
+    if requested_checkpoint_id:
+        checkpoint_metadata = {**checkpoint_metadata, "checkpoint_id": requested_checkpoint_id}
+    receipt = _tool_receipt_metadata(
+        session_id=session_id,
+        run_id=run_id,
+        tool_call_id=run_id,
+        tool_name=tool_name,
+        tool_args=call_args,
+        checkpoint_id=checkpoint_metadata.get("checkpoint_id"),
+        framework=checkpoint_metadata.get("framework"),
+        framework_ref=checkpoint_metadata.get("framework_ref"),
+    )
+    existing_event = _find_tool_receipt_event_by_key(
+        existing_events,
+        receipt["idempotency_key"],
+        expected_receipt=receipt,
+        expected_tool_args=call_args,
+    )
+    if existing_event is not None:
+        _validate_tool_receipt_event(existing_event)
+        return receipt, None
+    if requested_checkpoint_id:
+        legacy_event = _find_legacy_tool_receipt_event_for_resume(
+            session_id=session_id,
+            resume_input=resume_input,
+            events=existing_events,
+        )
+        if legacy_event is not None:
+            raise LegacyToolReceiptCheckpointAmbiguityError()
+    if _builtin_tool_callable(tool_name) is None:
+        return None, None
+    if require_existing:
+        # No approval is pending. A crash retry may only inspect/replay the
+        # previous claim; it must not acquire a new right to perform effects.
+        claim = await session_service_provider().get_tool_receipt_claim(
+            session_id, idempotency_key=str(receipt["idempotency_key"])
+        )
+        if claim is None:
+            raise ValueError("Responses resume input requires a pending approval_request")
+        if (claim.tool_name != tool_name
+                or claim.arguments_digest != _tool_receipt_arguments_digest(call_args)):
+            raise ValueError("tool receipt idempotency key conflict")
+        return receipt, _validate_tool_receipt_claim(replace(claim, acquired=False))
+    claim = await session_service_provider().claim_tool_receipt(
+        session_id,
+        idempotency_key=str(receipt["idempotency_key"]),
+        tool_name=tool_name,
+        arguments_digest=_tool_receipt_arguments_digest(call_args),
+        claim_id=f"{invocation_id}:{uuid.uuid4().hex}",
+    )
+    _validate_tool_receipt_claim(claim)
+    return receipt, claim
+
+
+
+async def replay_claimed_tool_receipt(
+    *,
+    claim: ToolReceiptClaim,
+    receipt: Mapping[str, Any],
+    session_id: str,
+    invocation_id: str,
+    run_id: str,
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+) -> dict[str, Any]:
+    _validate_tool_receipt_claim(claim)
+    if claim.state == "unknown":
+        raise ToolReceiptUncertainError(claim.idempotency_key)
+    output = claim.output
+    if isinstance(output, Mapping):
+        output = {**dict(output), "replayed": True}
+    replayed_receipt = {
+        **dict(receipt),
+        "status": claim.state,
+        "replayed": True,
+        "replayed_from_claim": True,
+    }
+    await append_conversation_event(
+        session_id=session_id,
+        author="tool",
+        role="user",
+        text=str(output),
+        invocation_id=invocation_id,
+        event_type="tool_result",
+        session_service_provider=session_service_provider,
+        metadata={
+            "tool_name": tool_name,
+            "tool_args": dict(call_args),
+            "tool_output": output,
+            "run_id": run_id,
+            "approval_request_id": resume_input.get("approval_request_id")
+            or resume_input.get("interrupt_id"),
+            "tool_receipt": replayed_receipt,
+            "replayed": True,
+        },
+    )
+    return {"type": "function_call_output", "call_id": run_id, "output": output}
+
+
+async def claim_or_replay_tool_receipt(
+    *,
+    service: Any,
+    session_id: str,
+    receipt: dict[str, Any],
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    invocation_id: str,
+    run_id: str,
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+    preclaimed_receipt: tuple[dict[str, Any], ToolReceiptClaim] | None,
+) -> tuple[ToolReceiptClaim, dict[str, Any] | None]:
+    claim = await claim_receipt_for_execution(
+        service=service,
+        session_id=session_id,
+        receipt=receipt,
+        tool_name=tool_name,
+        call_args=call_args,
+        invocation_id=invocation_id,
+        preclaimed_receipt=preclaimed_receipt,
+    )
+    if claim.acquired:
+        return claim, None
+    return claim, await replay_claimed_tool_receipt(
+        claim=claim,
+        receipt=receipt,
+        session_id=session_id,
+        invocation_id=invocation_id,
+        run_id=run_id,
+        tool_name=tool_name,
+        call_args=call_args,
+        resume_input=resume_input,
+        session_service_provider=session_service_provider,
+    )
+
+
+async def settle_claimed_tool_receipt(
+    *,
+    service: Any,
+    claim: ToolReceiptClaim,
+    receipt: dict[str, Any],
+    session_id: str,
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    output: Any,
+) -> None:
+    from ksadk.conversations.runtime_resume import _tool_receipt_status_from_output
+
+    status = _tool_receipt_status_from_output(output)
+    settled = await service.settle_tool_receipt(
+        session_id,
+        idempotency_key=str(receipt["idempotency_key"]),
+        tool_name=tool_name,
+        arguments_digest=_tool_receipt_arguments_digest(call_args),
+        claim_id=claim.claim_id,
+        state="failed" if status == "failed" else "completed",
+        output=output,
+    )
+    if settled.claim_id != claim.claim_id or settled.state == "unknown":
+        raise ToolReceiptUncertainError(claim.idempotency_key)
+    receipt["status"] = status

ksadk/conversations/tool_receipts.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Mapping
+
+from ksadk.sessions import SessionEvent
+
+_KNOWN_TOOL_RECEIPT_STATUSES = frozenset({"completed", "failed", "succeeded"})
+
+
+def _validate_tool_receipt_event(event: SessionEvent) -> str:
+    """Reject malformed persisted output/status pairs before replay."""
+
+    metadata = event.metadata or {}
+    if "tool_output" not in metadata:
+        raise ValueError("tool receipt is missing tool_output")
+    receipt = metadata.get("tool_receipt")
+    if not isinstance(receipt, Mapping):
+        raise ValueError("tool receipt is missing receipt metadata")
+    status = str(receipt.get("status") or "").strip().lower()
+    if status not in _KNOWN_TOOL_RECEIPT_STATUSES:
+        raise ValueError(f"tool receipt has unknown status {status!r}")
+    output = metadata["tool_output"]
+    if isinstance(output, Mapping):
+        expected = (
+            "completed"
+            if output.get("status") == "accepted_not_extracted"
+            else ("failed" if output.get("ok") is False else "completed")
+        )
+        normalized_status = "completed" if status == "succeeded" else status
+        if normalized_status != expected:
+            raise ValueError("tool receipt status does not match mapping tool_output ok value")
+    return status

ksadk/deployment/env_forward.py

@@ -45,6 +45,11 @@ DEPLOY_PROCESS_ENV_DENYLIST = frozenset(
         "KSADK_GLOBAL_CONFIG_ENV_KEYS",
         "KSADK_UPDATED_AT",
         "KSADK_VERSION",
+        # Local Studio host selection must not change a hosted Runtime policy.
+        "KSADK_STUDIO_NATIVE_DEFAULT",
+        "KSADK_STUDIO_NATIVE_AGENT_IDS",
+        "KSADK_STUDIO_NATIVE_DURABLE",
+        "KSADK_STUDIO_AGENT_ID",
     }
 )
 

ksadk/deployment/manager.py

@@ -244,19 +244,28 @@ runtime_context = RuntimeLaunchContext(
     detection=detection_result,
     config=dict(getattr(detection_result, "raw_config", None) or {{}}),
 )
-# managed A2A discovery-only card:KSADK_A2A_RUNTIME_ID 非空时挂
-# /.well-known/agent-card.json;注册前即可被 server 探测(a2a-runtime-inbound-wiring)。
-_managed_a2a_card = None
+# Runtime identity is available before registration for discovery.  Operator
+# enables the complete composition only after every Secret projection exists.
+_managed_a2a_bootstrap = None
+_a2a_adapter = None
 if os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip():
-    from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
+    if os.environ.get("KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED", "").strip().lower() == "true":
+        from ksadk.a2a.platform import build_managed_a2a_bootstrap_from_env
+        from ksadk.runtime.factory import create_runtime_adapter
 
-    _managed_a2a_card = build_managed_a2a_card_if_configured()
+        _managed_a2a_bootstrap = build_managed_a2a_bootstrap_from_env()
+        _a2a_adapter = create_runtime_adapter(runtime_context)
+    else:
+        from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
+
+        _managed_a2a_bootstrap = build_managed_a2a_card_if_configured()
 app = create_runtime_app(
     RuntimeAppConfig(
         runtime_type=detection_result.type.value,
         runtime_executor=RuntimeExecutor(build_default_runtime_registry()),
         launch_context=runtime_context,
-        a2a=_managed_a2a_card,
+        a2a=_managed_a2a_bootstrap,
+        a2a_runtime_adapter=_a2a_adapter,
     ),
     configure_runtime_app,
 )