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

ksadk/common/kop_client.py

@@ -19,6 +19,7 @@ from urllib.parse import urlsplit
 import requests
 
 from ksadk.common.auth import AWSV4Auth
+from ksadk.common.cloud_headers import build_cloud_headers
 
 logger = logging.getLogger(__name__)
 
@@ -152,7 +153,7 @@ class KOPClient:
             if action:
                 headers["X-Action"] = action
                 headers["X-Version"] = self.api_version
-        return headers
+        return build_cloud_headers(headers)
 
     def _build_url(self, action: str) -> str:
         if self._kop_mode:

ksadk/configs/__init__.py

@@ -13,7 +13,7 @@ AgentEngine 统一配置管理
 
 默认值:
     OPENAI_API_BASE: 自动检测内网/外网，使用金山云模型服务
-    MODEL_NAME: glm-5.2
+    MODEL_NAME: deepseek-v4.1-flash
 """
 
 from ksadk.configs.settings import (

ksadk/configs/env_registry.py

@@ -1,138 +1,83 @@
 from __future__ import annotations
 
+from ksadk.configs.env_registry_a2a import A2A_ENV_VAR_REGISTRY_ITEMS
 from ksadk.configs.env_registry_pcm import PCM_ENV_VAR_REGISTRY_ITEMS
+from ksadk.configs.env_registry_studio import STUDIO_ENV_VAR_REGISTRY_ITEMS
 from ksadk.configs.env_var_spec import EnvVarSpec
 
 _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
-        "KSADK_AGENT_EVAL",
-        "evaluation",
-        "Enable internal Agent evaluation integration.",
-        "0",
-        documented=False,
-    ),
-    EnvVarSpec("KSADK_ADK_RESUMABLE", "runners", "Enable ADK invocation resume support.", "false"),
-    EnvVarSpec("KSADK_ADK_SESSION_BACKEND", "sessions", "ADK-native session backend selector."),
-    EnvVarSpec("KSADK_ADK_SESSION_PATH", "sessions", "ADK-native SQLite session database path."),
-    EnvVarSpec(
-        "KSADK_ADK_SESSION_URL", "sessions", "ADK-native database session URL.", sensitive=True
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_AGENT_ID",
-        "a2a",
-        "Opaque registered A2A Agent id injected post-registration; "
-        "required to wire full inbound JSON-RPC in v2. v1 discovery-only card "
-        "does not depend on it.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_ACCOUNT_ID",
-        "a2a",
-        "Runtime owner account id injected by the deploy layer (ar-* agent's account).",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_RUNTIME_ID",
-        "a2a",
-        "Hosted Agent runtime resource id (ar-*) injected by the deploy layer; "
-        "the v1 discovery-only card mounts whenever this is non-empty.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_AGENT_NAME",
-        "a2a",
-        "AgentCard display name injected by the deploy layer; falls back to "
-        "AGENTENGINE_MANAGED_RUNTIME_NAME then to the agent id.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_AGENT_VERSION",
-        "a2a",
-        "AgentCard business version injected by the deploy layer; defaults to 0.1.0.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_CONTROL_PLANE_URL",
-        "a2a",
-        "AgentEngine A2A runtime control-plane base URL injected by the deploy layer.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_ENABLE_PUBLIC_EGRESS",
-        "a2a",
-        "Allow calling external (public-egress) agents in the A2A Space.",
-        "false when the deploy layer does not inject a value",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_EVENT_OUTBOX_PATH",
-        "a2a",
-        "SQLite path for durable A2A task-event delivery batches.",
-        ".agentengine/a2a_event_outbox.sqlite3",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_INTERNAL_BASE_URL",
-        "a2a",
-        "Internal HTTP(S) origin used as AgentCard base_url before the gateway rewrites it; "
-        "must be an absolute origin with no path/query/fragment.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_SPACE_ID",
-        "a2a",
-        "Primary A2A Space id configured for this Runtime Agent.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_SPACE_IDS",
-        "a2a",
-        "Compatibility JSON array of A2A Space ids configured for this Runtime Agent.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_TENANT_ID",
-        "a2a",
-        "Runtime tenant id injected by the deploy layer; falls back to account id.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_TOKEN_DIR",
-        "a2a",
-        "Directory containing audience-specific projected A2A workload JWT files.",
-        "/var/run/secrets/agentengine/a2a",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_SERVICE_URL",
-        "a2a",
-        "A2A control plane service URL (KOP public API); auto-detected if unset.",
+        "KSADK_TRAFFIC_SOURCE",
+        "cloud",
+        "Cloud resource request X-Traffic-Source header.",
+        "agentkit",
+    ),
+    *STUDIO_ENV_VAR_REGISTRY_ITEMS,
+    EnvVarSpec("KSADK_DB_CONNECT_SECONDS", "sessions", "Database connect budget in seconds.", ".5"),
+    EnvVarSpec("KSADK_DB_READ_ACQUIRE_SECONDS", "sessions", "Database read acquire budget in seconds.", ".3"),
+    EnvVarSpec("KSADK_DB_READ_SQL_SECONDS", "sessions", "Database read sql budget in seconds.", "1"),
+    EnvVarSpec("KSADK_DB_WRITE_ACQUIRE_SECONDS", "sessions", "Database write acquire budget in seconds.", ".5"),
+    EnvVarSpec("KSADK_DB_WRITE_SQL_SECONDS", "sessions", "Database write sql budget in seconds.", "3"),
+    EnvVarSpec("KSADK_DB_WRITE_OPERATION_SECONDS", "sessions", "Database write operation budget in seconds.", "5"),
+    EnvVarSpec("KSADK_DB_LOCK_SECONDS", "sessions", "Database lock budget in seconds.", ".5"),
+    EnvVarSpec("KSADK_DB_CLEANUP_SECONDS", "sessions", "Database cleanup budget in seconds.", "1"),
+    EnvVarSpec("KSADK_DB_REPLAY_OPERATION_SECONDS", "sessions", "Database replay operation budget in seconds.", "30"),
+    EnvVarSpec("KSADK_DB_REPLAY_SQL_SECONDS", "sessions", "Database replay sql budget in seconds.", "3"),
+    EnvVarSpec("KSADK_HISTORY_INITIAL_EVENTS", "sessions", "Initial history projection window (32–256 events).", "256"),
+    EnvVarSpec("KSADK_HISTORY_READ_CONCURRENCY", "sessions", "Concurrent PostgreSQL history transfers per process (1–32).", "4"),
+    EnvVarSpec(
+        "AGENTENGINE_CHANNEL_URL",
+        "studio",
+        "Channel service HTTPS base URL used by Studio and Channel Connector defaults.",
     ),
     EnvVarSpec(
-        "KSADK_A2A_SERVICE_TOKEN",
-        "a2a",
-        "Bearer token for A2A control plane service authentication.",
+        "KSADK_MEMORY_POSTGRES_DSN",
+        "memory",
+        "Harness memory PostgreSQL DSN.",
         sensitive=True,
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_A2A_SERVICE_ENDPOINT",
-        "a2a",
-        "A2A service endpoint hostname (used for auto-detection with scheme).",
+        "KSADK_OTEL_ENDPOINT",
+        "harness",
+        "Optional Harness trace export endpoint.",
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_A2A_SERVICE_SCHEME",
-        "a2a",
-        "A2A service URL scheme (http/https) for auto-detection.",
+        "KSADK_OTEL_SERVICE_NAME",
+        "harness",
+        "Harness trace service name.",
+        "ksadk-harness",
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_A2A_SERVICE_REGION",
-        "a2a",
-        "A2A service region for KOP signing.",
+        "KSADK_SANDBOX_API_KEY",
+        "sandbox",
+        "Legacy Skill MCP forwarded sandbox credential.",
+        sensitive=True,
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_A2A_ACCESS_KEY",
-        "a2a",
-        "A2A KOP access key for signing; falls back to KSYUN_ACCESS_KEY.",
-        sensitive=True,
+        "KSADK_SKILL_MANIFEST_TTL",
+        "skills",
+        "Skill manifest cache TTL in seconds.",
+        "60",
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_A2A_SECRET_KEY",
-        "a2a",
-        "A2A KOP secret key for signing; falls back to KSYUN_SECRET_KEY.",
-        sensitive=True,
+        "KSADK_AGENT_EVAL",
+        "evaluation",
+        "Enable internal Agent evaluation integration.",
+        "0",
+        documented=False,
     ),
+    EnvVarSpec("KSADK_ADK_RESUMABLE", "runners", "Enable ADK invocation resume support.", "false"),
+    EnvVarSpec("KSADK_ADK_SESSION_BACKEND", "sessions", "ADK-native session backend selector."),
+    EnvVarSpec("KSADK_ADK_SESSION_PATH", "sessions", "ADK-native SQLite session database path."),
     EnvVarSpec(
-        "KSADK_A2A_SERVICE",
-        "a2a",
-        "A2A KOP signing service name (default: aicp).",
+        "KSADK_ADK_SESSION_URL", "sessions", "ADK-native database session URL.", sensitive=True
     ),
+    *A2A_ENV_VAR_REGISTRY_ITEMS,
     EnvVarSpec(
         "KSADK_EVAL_JUDGE_API_KEY",
         "eval",
@@ -244,41 +189,16 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_DSH_HOME",
         "plugins",
         (
-            "Directory containing the isolated DSH Profile; defaults to .agentkit/dsh-home "
-            "in the workspace."
+            "Directory containing isolated DSH Profiles; defaults to "
+            ".agentkit/dsh-homes/<pinned DSH version> in the workspace. "
+            "An existing explicit home requires a compatible version receipt before Core starts."
         ),
     ),
     EnvVarSpec(
         "KSADK_DSH_PROFILE",
         "plugins",
-        "DSH Profile name used by Studio and the plugin bridge.",
-        "studio",
-    ),
-    EnvVarSpec(
-        "KSADK_STUDIO_NO_SECURITY",
-        "studio",
-        "Disable Studio loopback session and CSRF checks for controlled tests only.",
-        "0",
-    ),
-    EnvVarSpec(
-        "KSADK_STUDIO_AUTHORIZER",
-        "studio",
-        "Internal authoring backend selector; bounded chat is the default and the "
-        "filesystem-capable Codex authorizer requires an explicit opt-in.",
-        "chat",
-        documented=False,
-    ),
-    EnvVarSpec(
-        "KSADK_STUDIO_SESSION_TOKEN",
-        "studio",
-        "Explicit local Studio browser session token; generated randomly when unset.",
-        sensitive=True,
-    ),
-    EnvVarSpec(
-        "KSADK_STUDIO_TRACE_CONTENT",
-        "studio",
-        "Persist Studio trace event content; set to 0 to retain metadata only.",
-        "1",
+        "DSH Profile name used by Studio and the plugin bridge; defaults to the web profile.",
+        "web",
     ),
     EnvVarSpec(
         "KSADK_COMMAND_", "sandbox", "Internal prefix for command policy environment controls."
@@ -390,14 +310,101 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         ),
         "false",
     ),
+    EnvVarSpec(
+        "KSADK_HARNESS_STATE_DIR",
+        "harness",
+        "Runtime server durable state directory (checkpoints and receipts).",
+    ),
     EnvVarSpec(
         "KSADK_LANGGRAPH_POSTGRES_REQUIREMENTS",
         "builders",
         "Internal bundled LangGraph PostgreSQL checkpointer requirement constant.",
     ),
+    EnvVarSpec(
+        "KSADK_LANGGRAPH_RECURSION_LIMIT",
+        "sessions",
+        (
+            "Fallback LangGraph recursion limit carried by the hosted runner when the "
+            "graph's own with_config does not set one. Must be explicit: astream_events "
+            "otherwise fills LangChain's default 25, which overrides the graph-level "
+            "setting on the streaming path."
+        ),
+        "50",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_ADDRESS_SPACE_BYTES",
+        "skills",
+        "Local-process RLIMIT_AS address-space bytes.",
+        "1073741824",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_CONTROLS",
+        "skills",
+        "Internal marker injected by the local Skill runtime backend.",
+        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_CPU_SECONDS",
+        "skills",
+        "Local-process RLIMIT_CPU seconds.",
+        "120",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_ENV_ALLOWLIST",
+        "skills",
+        "Additional environment names allowed into local Skill commands.",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_MAX_FILE_BYTES",
+        "skills",
+        "Local-process RLIMIT_FSIZE bytes per file.",
+        "67108864",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_MAX_OPEN_FILES",
+        "skills",
+        "Local-process RLIMIT_NOFILE descriptor count.",
+        "256",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_MAX_OUTPUT_BYTES",
+        "skills",
+        "Maximum captured bytes for each local-process output stream.",
+        "1048576",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_MAX_PROCESSES",
+        "skills",
+        "Local-process RLIMIT_NPROC per-UID process count.",
+        "64",
+    ),
+    EnvVarSpec(
+        "KSADK_LOCAL_PROCESS_WALL_SECONDS",
+        "skills",
+        "Local-process hard wall-clock command limit.",
+        "900",
+    ),
     EnvVarSpec(
         "KSADK_LOCAL_SKILLS_DIR", "skills", "Local directory containing extracted Skill packages."
     ),
+    EnvVarSpec(
+        "KSADK_SKILL_SANDBOX_PROTOCOL",
+        "skills",
+        "Sandbox Skill delivery protocol. Only pinned_v1 is supported.",
+        "pinned_v1",
+    ),
+    EnvVarSpec(
+        "KSADK_SKILL_EVENT_FILE",
+        "skills",
+        "Internal per-run sandbox Skill event file.",
+        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_SKILL_OUTPUT_TEXT_MAX_BYTES",
+        "skills",
+        "Maximum text artifact bytes returned by the Skill runtime agent.",
+        "65536",
+    ),
     EnvVarSpec("KSADK_LTM", "memory", "AICP long-term-memory connection prefix."),
     EnvVarSpec(
         "KSADK_LTM_ACCESS_KEY", "memory", "Long-term-memory API access key.", sensitive=True
@@ -451,6 +458,61 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec("KSADK_MEMORY_PREFIX", "memory", "Generic memory key prefix.", "ksadk:memory:"),
     EnvVarSpec("KSADK_MEMORY_TTL", "memory", "Generic memory default TTL seconds."),
     EnvVarSpec("KSADK_MEMORY_URL", "memory", "Generic memory backend URL.", sensitive=True),
+    EnvVarSpec(
+        "KSADK_MODEL_PROFILE_MAP",
+        "models",
+        "JSON object mapping model profile refs to provider model ids.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_STREAMING",
+        "models",
+        "Enable streaming model responses when supported (unset = auto).",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_CAPABILITY_FILE",
+        "models",
+        "Provider capability declaration file produced by the model matrix.",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_GATEWAY_METADATA_FILE",
+        "models",
+        "Platform-provided model metadata consumed before measured capability probes.",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_WIRE_API",
+        "models",
+        "Direct SDK model wire protocol: chat or responses.",
+        "chat",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_COMPAT_RULE",
+        "models",
+        "Explicit model endpoint compatibility profile override.",
+    ),
+    EnvVarSpec(
+        "KSADK_DELEGATION_DECISION_MAX_OUTPUT_TOKENS",
+        "harness",
+        "Maximum output-token budget for a delegation decision turn.",
+    ),
+    EnvVarSpec(
+        "KSADK_RUN_STALL_WARN_SECONDS",
+        "studio",
+        "Seconds without run progress before Studio emits a stall warning; <=0 disables it.",
+        "60",
+    ),
+    EnvVarSpec(
+        "KSADK_RUN_STALL_DUMP_SECONDS",
+        "studio",
+        "Seconds without run progress before Studio captures a diagnostic dump.",
+        "120",
+    ),
+    EnvVarSpec(
+        "KSADK_RUN_STALL_MAX_DUMPS",
+        "studio",
+        "Maximum diagnostic dumps retained for one continuously stalled run.",
+        "5",
+    ),
     EnvVarSpec(
         "KSADK_MODEL_PROXY_AGENTS",
         "model_proxy",
@@ -866,7 +928,7 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_WEB_VERSION",
         "web",
         "Published KsADK Web npm version used for a reproducible wheel build.",
-        "0.3.7",
+        "0.3.13",
     ),
     EnvVarSpec(
         "KSADK_WORKING_SET_MAX_FILES",
@@ -974,6 +1036,17 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "Maximum spans exported per OTLP batch to avoid oversized collector requests.",
         "64",
     ),
+    EnvVarSpec(
+        "KSADK_HARNESS_SPEC",
+        "harness",
+        "Path to the HarnessSpec JSON consumed by `python -m ksadk.harness.rpc`.",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_REQUEST_IDLE_TIMEOUT_SECONDS",
+        "studio",
+        "Idle timeout in seconds for a single managed model request before failover.",
+        "60",
+    ),
 )
 
 ENV_VAR_REGISTRY: tuple[EnvVarSpec, ...] = tuple(

ksadk/configs/env_registry_a2a.py

@@ -0,0 +1,173 @@
+"""A2A environment variable contracts consumed by the canonical registry."""
+
+from __future__ import annotations
+
+from ksadk.configs.env_var_spec import EnvVarSpec
+
+A2A_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec(
+        "KSADK_A2A_API_KEY",
+        "a2a",
+        "Product API Key used only by product_key_http_client when api_key is omitted; "
+        "never inherits unrelated service credentials.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_ID",
+        "a2a",
+        "Managed Runtime target Agent id (ar-*); required for the fail-closed "
+        "A2A data-plane composition.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_ACCOUNT_ID",
+        "a2a",
+        "Runtime owner account id injected by the deploy layer (ar-* agent's account).",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_RUNTIME_ID",
+        "a2a",
+        "Hosted Agent runtime resource id injected before registration for discovery.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED",
+        "a2a",
+        "Platform-owned marker enabling the complete managed A2A composition.",
+        "false",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_NAME",
+        "a2a",
+        "AgentCard display name injected by the deploy layer; falls back to "
+        "AGENTENGINE_MANAGED_RUNTIME_NAME then to the agent id.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_VERSION",
+        "a2a",
+        "AgentCard business version injected by the deploy layer; defaults to 0.1.0.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_CONTROL_PLANE_URL",
+        "a2a",
+        "AgentEngine A2A runtime control-plane base URL injected by the deploy layer.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_CONTROL_PLANE_CA_FILE",
+        "a2a",
+        "Platform-projected CA bundle used only for managed A2A control-plane HTTPS.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_GATEWAY_CA_FILE",
+        "a2a",
+        "Optional Gateway CA file added to public trust roots for managed A2A HTTPS.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_ENABLE_PUBLIC_EGRESS",
+        "a2a",
+        "Allow calling external (public-egress) agents in the A2A Space.",
+        "false when the deploy layer does not inject a value",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_EVENT_OUTBOX_PATH",
+        "a2a",
+        "SQLite path for local-only A2A task-event delivery batches; forbidden in managed Runtime.",
+        ".agentengine/a2a_event_outbox.sqlite3",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_INBOUND_ENABLED",
+        "a2a",
+        "Enable managed inbound A2A serving; false configures a caller-only Runtime.",
+        "true",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_PUBLIC_TOOL_POLICY_FILE",
+        "a2a",
+        "Projected JSON file containing the public tool activity disclosure policy.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_DATABASE_DSN",
+        "a2a",
+        "PostgreSQL DSN projected from the AgentKernel store SecretKeyRef.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_GATEWAY_PUBLIC_KEY_FILE",
+        "a2a",
+        "Projected file locator containing the Gateway forward-assertion public key.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_REGISTRATION_ID",
+        "a2a",
+        "Opaque registered a2a-agent-* target identity injected by the deploy layer.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_INTERNAL_BASE_URL",
+        "a2a",
+        "Internal HTTP(S) origin used as AgentCard base_url before the gateway rewrites it; "
+        "must be an absolute origin with no path/query/fragment.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SPACE_ID",
+        "a2a",
+        "Primary A2A Space id configured for this Runtime Agent.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SPACE_IDS",
+        "a2a",
+        "Compatibility JSON array of A2A Space ids configured for this Runtime Agent.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_TENANT_ID",
+        "a2a",
+        "Runtime tenant id injected by the deploy layer; falls back to account id.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_TOKEN_DIR",
+        "a2a",
+        "Directory containing audience-specific projected A2A workload JWT files.",
+        "/var/run/secrets/agentengine/a2a",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_URL",
+        "a2a",
+        "A2A control plane service URL (KOP public API); auto-detected if unset.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_TOKEN",
+        "a2a",
+        "Bearer token for A2A control plane service authentication.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_ENDPOINT",
+        "a2a",
+        "A2A service endpoint hostname (used for auto-detection with scheme).",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_SCHEME",
+        "a2a",
+        "A2A service URL scheme (http/https) for auto-detection.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_REGION",
+        "a2a",
+        "A2A service region for KOP signing.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_ACCESS_KEY",
+        "a2a",
+        "A2A KOP access key for signing; falls back to KSYUN_ACCESS_KEY.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SECRET_KEY",
+        "a2a",
+        "A2A KOP secret key for signing; falls back to KSYUN_SECRET_KEY.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE",
+        "a2a",
+        "A2A KOP signing service name (default: aicp).",
+    ),
+)