langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/graph/factory.py

@@ -0,0 +1,1409 @@
+"""
+LangChain AgentX Agent Factory
+
+与 LangChain create_agent 接口完全兼容，但使用 LangChain AgentX 的退出逻辑。
+
+核心差异：
+1. 退出条件：finish_reason not in ["tool-calls", "unknown"]（主动）
+2. 退出位置：只在 model 节点退出
+3. 不支持 return_direct（会被忽略）
+
+参考设计文档：.claude/design/create-opencode-style-agent-design.md
+
+LangChain AgentX Agent 状态图（文字版，含 loop_controller）：
+
+    START
+      ↓
+    hook_loop_start
+      ↓
+    model 节点（同步/异步，带 OpenCode 退出判断）
+      ↓
+    hook_stop
+      ↓
+    loop_controller（集中处理 should_end / terminal_reason / 工具调用）
+      ├─ should_end=True  → END
+      ├─ 有工具调用       → tools → (task_event_*/prune_and_compress) → model
+      └─ 无工具调用       → END
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import SystemMessage
+from langchain_core.runnables import RunnableConfig
+from langgraph._internal._runnable import RunnableCallable
+from langgraph.constants import END, START
+from langgraph.graph.state import StateGraph
+from langgraph.prebuilt.tool_node import ToolNode
+import asyncio
+import logging
+import threading
+import uuid
+from types import MethodType
+
+from ..exit.exit_logic import (
+    CONTINUE_FINISH_REASONS,
+    LoopAgentStateFields,
+)
+from .graph_edges import _make_model_to_model_edge, _make_tools_to_model_edge, _make_loop_controller_edge
+from ..model.schema_and_format import (
+    STRUCTURED_OUTPUT_ERROR_TEMPLATE,
+    FALLBACK_MODELS_WITH_STRUCTURED_OUTPUT,
+    _resolve_schema,
+)
+from ..model.model_node import ModelNode
+from ..model.model_nodes import make_model_nodes
+from ..context import default_loop_context_compaction
+from ..context.settings import CompactionSettings
+from ..injection.dedup import filter_attachment_dicts_by_task_command_id
+from ..model.tool_call_degradation_corrector import (
+    ToolCallDegradationCorrector,
+    _build_allowed_tool_names_for_degradation_correction,
+)
+from ..hook import HookEngine, HooksConfigSnapshot, WorkspaceTrustChecker
+from ..hook.graph_wiring import HookGraphWiring
+from ..hook.registry import HookRegistry
+from ...task_runtime.integrations.loop_adapter import LoopInjectionBatch, LoopTaskInjectionAdapter
+from ...task_runtime.integrations.loop_integration import (
+    QueuedCommandProvider,
+    decode_provider_batch_id,
+    encode_provider_batch_id,
+)
+from ...task_runtime.core.types import QueuePriority, TaskScope
+from ...task_runtime.skill_prefetch import SkillPrefetchProvider
+from ...observability.trace import TraceCollector, SqliteTraceStore
+from ...observability.trace.trace_callback import TraceCallbackHandler
+from ...observability.trace.trace_lifecycle_collector import TraceLifecycleCollector
+from ...observability.trace.event_emitter import emit_task_event
+from ...observability.logging import ObservabilityLoggerAdapter, build_log_context
+from ...memory.instruction.runtime import (
+    CallbackActiveFilesProvider,
+    InstructionMemoryBootstrap,
+)
+from ...memory.memdir.agent_memory import (
+    AgentMemoryPromptBootstrap,
+    get_default_agent_memory_extraction_coordinator,
+)
+from ...memory.memdir.runtime import MemoryPromptBootstrap
+from ...memory.memdir.extractor import MemoryExtractionCoordinator
+from ...memory.session import (
+    SessionMemoryCompactBridge,
+    SessionMemoryManager,
+    make_session_memory_section,
+)
+from ..prompt import SystemPromptSection, build_effective_system_prompt
+from ...tools.agent.prompt import build_explore_plan_guidance
+from ..config import AgentLoopConfig, ModelContextResolver
+from ..config.runtime_settings import compute_recursion_limit
+from ...provider.model_profile import ModelProfileRegistry
+from ...workspace import resolve_agent_workspace_config
+
+logger = logging.getLogger(__name__)
+SKILL_TOOL_NAME = "skill"
+DYNAMIC_TOOL_ERROR_TEMPLATE = (
+    "Model returned tool calls that are not registered in this agent runtime. "
+    "Ensure tools are registered via ToolRuntimeLoader and passed via loader=..."
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# LangChain 兼容性导入（支持新旧版本）
+# ═══════════════════════════════════════════════════════════════════════════════
+from langchain.agents.middleware.types import AgentState, ContextT, OmitFromSchema, ResponseT, _InputAgentState, _OutputAgentState
+
+from langchain.agents.structured_output import (
+    AutoStrategy,
+    MultipleStructuredOutputsError,
+    OutputToolBinding,
+    ProviderStrategy,
+    ProviderStrategyBinding,
+    ResponseFormat,
+    StructuredOutputError,
+    StructuredOutputValidationError,
+    ToolStrategy,
+)
+from langchain.chat_models import init_chat_model
+from ..model.retrier import ModelCallRetrier, ModelRetryConfig
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Sequence
+
+    from langchain_core.runnables import Runnable, RunnableConfig
+    from langgraph.graph.state import CompiledStateGraph
+    from langgraph.runtime import Runtime
+    from ...task_runtime.core.interfaces import TaskRuntime
+    from ...tool_runtime import AgentSessionStore, ToolRuntimeLoader
+
+class LoopGraphBuilder:
+    """create_loop_agent 内部图构建器，不对外暴露。
+
+    职责：将 create_loop_agent 的图构建逻辑按职责分层，
+          compile() 返回 CompiledStateGraph。
+    CC 对照：无直接对应，属于本工程 LangGraph 适配层的内部拆分。
+    """
+
+    def __init__(
+        self,
+        model: str | BaseChatModel,
+        *,
+        system_prompt: str | SystemMessage | None = None,
+        override_system_prompt: str | None = None,
+        append_system_prompt: str | None = None,
+        dynamic_sections: Sequence[SystemPromptSection] = (),
+        response_format: ResponseFormat[ResponseT] | type[ResponseT] | dict[str, Any] | None = None,
+        fallback_model: BaseChatModel | None = None,
+        enable_tool_call_degradation_fix: bool = True,
+        session_id: str | None = None,
+        session_store: "AgentSessionStore | None" = None,
+        loader: "ToolRuntimeLoader | None" = None,
+        permission_resolver: Any | None = None,
+        state_schema: type[AgentState[ResponseT]] | None = None,
+        context_schema: type[ContextT] | None = None,
+        debug: bool = False,
+        name: str | None = None,
+        max_steps: int | None = None,
+        max_turns: int | None = None,
+        is_subagent: bool = False,
+        subagent_type: str | None = None,
+        container_type: str | None = None,
+        enable_trace: bool = True,
+        trace_collector: TraceCollector | None = None,
+        parent_run_id: str | None = None,
+        parent_tool_call_id: str | None = None,
+        parent_conversation_session_id: str | None = None,
+        trace_visibility: str | None = None,
+        task_runtime: TaskRuntime | None = None,
+        task_notification_max_priority: QueuePriority = QueuePriority.NEXT,
+        queued_command_providers: Sequence[QueuedCommandProvider] = (),
+        managed_rules: str | None = None,
+        active_files_getter: "Callable[[], list[str]] | None" = None,
+        workspace_root: str | Path | None = None,
+        agent_home: str = ".langchain_agentx",
+        workspace_trust_accepted: bool | None = None,
+        raw_hooks: "HookRegistry | None" = None,
+        enable_session_memory: bool = False,
+    ) -> None:
+        self._raw_model = model
+        self._raw_system_prompt = system_prompt
+        self._raw_override_system_prompt = override_system_prompt
+        self._raw_append_system_prompt = append_system_prompt
+        self._raw_dynamic_sections = list(dynamic_sections)
+        self._raw_response_format = response_format
+        self._raw_fallback_model = fallback_model
+        self._raw_enable_tool_call_degradation_fix = enable_tool_call_degradation_fix
+        self._raw_session_id = session_id
+        self._raw_session_store = session_store
+        self._raw_loader = loader
+        self._raw_permission_resolver = permission_resolver
+        self._raw_state_schema = state_schema
+        self._raw_context_schema = context_schema
+        self._raw_debug = debug
+        self._raw_name = name
+        self._raw_max_steps = max_steps
+        self._raw_max_turns = max_turns
+        self._raw_is_subagent = is_subagent
+        self._raw_subagent_type = subagent_type
+        self._raw_container_type = container_type
+        self._raw_enable_trace = enable_trace
+        self._raw_trace_collector = trace_collector
+        self._raw_parent_run_id = parent_run_id
+        self._raw_parent_tool_call_id = parent_tool_call_id
+        self._raw_parent_conversation_session_id = parent_conversation_session_id
+        self._raw_trace_visibility = trace_visibility
+        self._raw_task_runtime = task_runtime
+        self._raw_task_notification_max_priority = task_notification_max_priority
+        self._raw_queued_command_providers = list(queued_command_providers)
+        self._raw_managed_rules = managed_rules
+        self._raw_active_files_getter = active_files_getter
+        self._raw_workspace_root = workspace_root
+        self._raw_agent_home = agent_home
+        self._raw_workspace_trust_accepted = workspace_trust_accepted
+        self._raw_hooks = raw_hooks
+        self._raw_enable_session_memory = enable_session_memory
+
+        self._prepared = False
+
+    def _prepare_compile_context(self) -> None:
+        if self._prepared:
+            return
+        model, session_id, log = self._resolve_model_session_and_logger()
+        log.info(
+            "create_loop_agent start model=%s loader=%s max_steps=%s",
+            getattr(model, "model_name", type(model).__name__),
+            repr(self._raw_loader),
+            self._raw_max_steps,
+        )
+        session_store = self._resolve_session_store(session_id)
+        base_prompt = self._resolve_base_prompt()
+        self._dynamic_sections: list[SystemPromptSection] = list(self._raw_dynamic_sections)
+        append_system_prompt = self._raw_append_system_prompt
+        self._setup_loader_tools()
+        self._resolve_workspace_config()
+        self._model_profile_registry = ModelProfileRegistry.from_files(
+            agent_home_dir=self._workspace_cfg.agent_home_dir
+        )
+        self._model_context_resolver = ModelContextResolver()
+        self._session_memory_manager: SessionMemoryManager | None = None
+        self._session_memory_compact_bridge: SessionMemoryCompactBridge | None = None
+        if self._raw_enable_session_memory:
+            session_memory_path = self._workspace_cfg.session_memory_path(session_id)
+            self._session_memory_manager = SessionMemoryManager(
+                session_memory_path=session_memory_path,
+                llm=model,
+                is_subagent=self._raw_is_subagent,
+            )
+            self._session_memory_compact_bridge = SessionMemoryCompactBridge(
+                session_memory_path=session_memory_path,
+                extraction_state=self._session_memory_manager.extraction_state,
+            )
+            self._dynamic_sections.append(make_session_memory_section(session_memory_path))
+        self._dynamic_sections.extend(
+            InstructionMemoryBootstrap(
+                workspace_root=Path(self._workspace_root),
+                agent_home=self._agent_home,
+                managed_rules=self._raw_managed_rules,
+                active_files_provider=(
+                    CallbackActiveFilesProvider(self._raw_active_files_getter)
+                    if self._raw_active_files_getter is not None
+                    else None
+                ),
+            ).build_sections()
+        )
+        self._dynamic_sections.extend(
+            MemoryPromptBootstrap(
+                workspace_root=Path(self._workspace_root),
+                agent_home=self._agent_home,
+            ).build_sections()
+        )
+        self._dynamic_sections.extend(
+            AgentMemoryPromptBootstrap(
+                workspace_cfg=self._workspace_cfg,
+                is_subagent=self._raw_is_subagent,
+                subagent_type=self._raw_subagent_type,
+            ).build_sections()
+        )
+        system_message = self._build_system_message(
+            base_prompt=base_prompt,
+            append_system_prompt=append_system_prompt,
+        )
+        collector = self._resolve_trace_collector()
+        (
+            initial_response_format,
+            tool_strategy_for_setup,
+            structured_output_tools,
+        ) = self._resolve_response_format_setup()
+        self._built_in_tools = []
+        self._available_tools = list(self._loader_tools)
+
+        if not self._raw_is_subagent:
+            append_system_prompt, system_message = self._apply_explore_guidance(
+                append_system_prompt=append_system_prompt,
+                base_prompt=base_prompt,
+            )
+
+        self._loop_config = AgentLoopConfig(
+            model=self._loop_config_model,
+            fallback_model=self._raw_fallback_model,
+            max_steps=self._raw_max_steps,
+            max_turns=self._raw_max_turns,
+            available_tools=self._available_tools,
+            managed_rules=self._raw_managed_rules,
+            permission_resolver=self._raw_permission_resolver,
+            session_id=session_id or "",
+            conversation_session_id=(
+                self._raw_parent_conversation_session_id
+                if self._raw_is_subagent and self._raw_parent_conversation_session_id
+                else (session_id or "")
+            ),
+            workspace_root=self._workspace_root,
+            agent_home=self._agent_home,
+            cwd=self._workspace_root,
+            subagent_type=self._raw_subagent_type,
+            trace_enabled=self._raw_enable_trace,
+            model_profile_registry=self._model_profile_registry,
+        )
+        self._compaction_settings = self._build_compaction_settings()
+        self._loop_context_compaction = default_loop_context_compaction().with_default_pipeline(
+            settings=self._compaction_settings
+        )
+        self._model = model
+        self._session_id = session_id
+        self._log = log
+        self._session_store = session_store
+        self._base_prompt = base_prompt
+        self._system_message = system_message
+        self._trace_collector = collector
+        self._initial_response_format = initial_response_format
+        self._tool_strategy_for_setup = tool_strategy_for_setup
+        self._structured_output_tools = structured_output_tools
+        self._fallback_model = self._raw_fallback_model
+        self._max_turns = self._raw_max_turns
+        self._name = self._raw_name
+        self._state_schema = self._raw_state_schema
+        self._context_schema = self._raw_context_schema
+        self._is_subagent = self._raw_is_subagent
+        self._task_runtime = self._raw_task_runtime
+        self._task_notification_max_priority = self._raw_task_notification_max_priority
+        self._queued_command_providers = list(self._raw_queued_command_providers)
+        self._enable_tool_call_degradation_fix = self._raw_enable_tool_call_degradation_fix
+        self._override_system_prompt = self._raw_override_system_prompt
+        self._append_system_prompt = append_system_prompt
+        self._max_steps_param = self._raw_max_steps
+        self._debug = self._raw_debug
+        if self._raw_loader is not None:
+            self._raw_loader.set_permission_resolver(self._raw_permission_resolver)
+        self._hook_snapshot = (
+            self._raw_hooks.build_snapshot()
+            if self._raw_hooks is not None
+            else HooksConfigSnapshot()
+        )
+        self._trace_callback_handler: TraceCallbackHandler | None = None
+        self._trace_tool_callback_handler: TraceCallbackHandler | None = None
+        hook_event_emitter = None
+        trace_lifecycle_collector = (
+            TraceLifecycleCollector(
+                collector,
+                graph_name="subagent" if self._raw_is_subagent else "agent",
+                default_run_id=session_id or None,
+                unit_type="subagent" if self._raw_is_subagent else "main_loop",
+                container_type=self._raw_container_type or "agent_session",
+                origin="tool" if self._raw_is_subagent else "user",
+                visibility=self._raw_trace_visibility or "default",
+                parent_run_id=self._raw_parent_run_id if self._raw_is_subagent else None,
+                parent_tool_call_id=self._raw_parent_tool_call_id if self._raw_is_subagent else None,
+                conversation_session_id=(
+                    self._raw_parent_conversation_session_id
+                    if self._raw_is_subagent
+                    else None
+                ),
+            )
+            if self._raw_enable_trace
+            else None
+        )
+        if collector is not None:
+            from ...observability.trace.hook_event_emitter import HookEventEmitter
+
+            hook_event_emitter = HookEventEmitter(collector=collector)
+        is_headless_trust_context = bool(
+            self._raw_container_type in {"background", "batch", "worker", "sdk"}
+        )
+        trust_accepted = (
+            self._raw_workspace_trust_accepted
+            if self._raw_workspace_trust_accepted is not None
+            else self._workspace_cfg.workspace_trust_accepted
+        )
+        trust_checker = WorkspaceTrustChecker(
+            headless=is_headless_trust_context,
+            workspace_trust_accepted=trust_accepted,
+        )
+        hook_engine = HookEngine(
+            self._hook_snapshot,
+            event_emitter=hook_event_emitter,
+            trust_checker=trust_checker,
+        )
+        container_type = self._raw_container_type or "agent_session"
+        self._hook_graph_wiring = HookGraphWiring(
+            hook_engine,
+            trace_lifecycle_collector=trace_lifecycle_collector,
+            session_memory=self._session_memory_manager,
+            memory_extractor=MemoryExtractionCoordinator(),
+            agent_memory_extractor=get_default_agent_memory_extraction_coordinator(),
+            workspace_cfg=self._workspace_cfg,
+            session_id=session_id or "",
+            container_type=container_type,
+            subagent_type=self._raw_subagent_type,
+        )
+        if self._raw_enable_trace:
+            self._trace_callback_handler = TraceCallbackHandler(
+                collector=collector,
+                session_id=session_id or "",
+                capture_llm=True,
+                capture_tool=False,
+            )
+            self._trace_tool_callback_handler = TraceCallbackHandler(
+                collector=collector,
+                session_id=session_id or "",
+                capture_llm=False,
+                capture_tool=True,
+            )
+        self._prepared = True
+
+    def _resolve_model_session_and_logger(
+        self,
+    ) -> tuple[BaseChatModel, str, ObservabilityLoggerAdapter]:
+        model: str | BaseChatModel = self._raw_model
+        self._loop_config_model = model
+        if isinstance(model, str):
+            model = init_chat_model(model)
+        session_id = self._raw_session_id
+        if not session_id:
+            session_id = f"session-{uuid.uuid4().hex}"
+            logger.warning(
+                "session_id missing, generated ephemeral session_id=%s; "
+                "pass explicit session_id for multi-turn continuity",
+                session_id,
+            )
+        log = ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(session_id=session_id).as_extra(),
+        )
+        return model, session_id, log
+
+    def _resolve_session_store(self, session_id: str) -> Any:
+        session_store = self._raw_session_store
+        if session_store is None and self._raw_loader is not None:
+            return self._raw_loader.create_session(session_id=session_id)
+        return session_store
+
+    def _resolve_base_prompt(self) -> str | None:
+        if self._raw_system_prompt is None:
+            return None
+        if isinstance(self._raw_system_prompt, SystemMessage):
+            return (
+                self._raw_system_prompt.content
+                if isinstance(self._raw_system_prompt.content, str)
+                else None
+            )
+        return self._raw_system_prompt
+
+    def _setup_loader_tools(self) -> None:
+        self._loader_tools = []
+        self._skill_runtime_tool = None
+        if self._raw_loader is not None:
+            self._loader_tools = self._raw_loader._registry.to_langchain_tools()
+            for rt in self._raw_loader._registry.list():
+                if self._skill_runtime_tool is None and rt.__class__.__name__ == "SkillRuntimeTool":
+                    self._skill_runtime_tool = rt
+
+    def _resolve_workspace_config(self) -> None:
+        raw_workspace_root = self._raw_workspace_root
+        if raw_workspace_root is None:
+            workspace_root = Path.cwd()
+        else:
+            workspace_root = Path(raw_workspace_root)
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=workspace_root,
+            agent_home=self._raw_agent_home,
+        )
+        self._workspace_cfg = workspace_cfg
+        self._workspace_root = str(workspace_cfg.workspace_root)
+        self._agent_home = workspace_cfg.agent_home
+
+    @staticmethod
+    def _run_coro_sync(coro: Any) -> Any:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(coro)
+
+        result: dict[str, Any] = {}
+        error: dict[str, Exception] = {}
+
+        def _runner() -> None:
+            try:
+                result["value"] = asyncio.run(coro)
+            except Exception as exc:  # pragma: no cover
+                error["value"] = exc
+
+        thread = threading.Thread(target=_runner, daemon=True)
+        thread.start()
+        thread.join()
+        if "value" in error:
+            raise error["value"]
+        return result.get("value")
+
+    def _build_system_message(
+        self,
+        *,
+        base_prompt: str | None,
+        append_system_prompt: str | None,
+    ) -> SystemMessage | None:
+        has_dynamic = bool(
+            self._dynamic_sections or self._raw_override_system_prompt or append_system_prompt
+        )
+        self._has_dynamic_prompt = has_dynamic
+        if not has_dynamic:
+            return SystemMessage(content=base_prompt) if base_prompt is not None else None
+        section_cache: dict[str, str | None] = {}
+        effective = build_effective_system_prompt(
+            system_prompt=base_prompt,
+            override_system_prompt=self._raw_override_system_prompt,
+            append_system_prompt=append_system_prompt,
+            dynamic_sections=self._dynamic_sections,
+            section_cache=section_cache,
+        )
+        return SystemMessage(content=effective) if effective is not None else None
+
+    def _resolve_trace_collector(self) -> TraceCollector | None:
+        if not self._raw_enable_trace:
+            return None
+        return self._raw_trace_collector or TraceCollector(SqliteTraceStore.from_env())
+
+    def _resolve_response_format_setup(
+        self,
+    ) -> tuple[
+        ToolStrategy[Any] | ProviderStrategy[Any] | AutoStrategy[Any] | None,
+        ToolStrategy[Any] | None,
+        dict[str, OutputToolBinding[Any]],
+    ]:
+        initial_response_format: ToolStrategy[Any] | ProviderStrategy[Any] | AutoStrategy[Any] | None
+        if self._raw_response_format is None:
+            initial_response_format = None
+        elif isinstance(self._raw_response_format, (ToolStrategy, ProviderStrategy, AutoStrategy)):
+            initial_response_format = self._raw_response_format
+        else:
+            initial_response_format = AutoStrategy(schema=self._raw_response_format)
+
+        tool_strategy_for_setup: ToolStrategy[Any] | None = None
+        if isinstance(initial_response_format, AutoStrategy):
+            tool_strategy_for_setup = ToolStrategy(schema=initial_response_format.schema)
+        elif isinstance(initial_response_format, ToolStrategy):
+            tool_strategy_for_setup = initial_response_format
+
+        structured_output_tools: dict[str, OutputToolBinding[Any]] = {}
+        if tool_strategy_for_setup:
+            for response_schema in tool_strategy_for_setup.schema_specs:
+                structured_tool_info = OutputToolBinding.from_schema_spec(response_schema)
+                structured_output_tools[structured_tool_info.tool.name] = structured_tool_info
+        return initial_response_format, tool_strategy_for_setup, structured_output_tools
+
+    def _apply_explore_guidance(
+        self,
+        *,
+        append_system_prompt: str | None,
+        base_prompt: str | None,
+    ) -> tuple[str | None, SystemMessage | None]:
+        explore_guidance = build_explore_plan_guidance(self._available_tools)
+        if not explore_guidance:
+            return append_system_prompt, self._build_system_message(
+                base_prompt=base_prompt,
+                append_system_prompt=append_system_prompt,
+            )
+        updated_append_prompt = (
+            f"{append_system_prompt}\n\n{explore_guidance}"
+            if append_system_prompt
+            else explore_guidance
+        )
+        return updated_append_prompt, self._build_system_message(
+            base_prompt=base_prompt,
+            append_system_prompt=updated_append_prompt,
+        )
+
+    def _build_tool_node(self) -> Any:
+        self._prepare_compile_context()
+        need_tool_node = bool(self._available_tools)
+        tool_node: ToolNode | None = None
+        if need_tool_node:
+            tool_node = ToolNode(tools=self._available_tools)
+            if self._trace_tool_callback_handler is not None:
+                tool_node = tool_node.with_config({"callbacks": [self._trace_tool_callback_handler]})
+        return tool_node
+
+    def _prepare_for_model_nodes(self, tool_node: Any) -> None:
+        """在 make_model_nodes 之前设置 default_tools、模型包装与图节点所需字段。"""
+        if tool_node:
+            default_tools = list(tool_node.tools_by_name.values()) + self._built_in_tools
+        else:
+            default_tools = list(self._built_in_tools)
+        model = self._model
+        if self._enable_tool_call_degradation_fix and not isinstance(model, ToolCallDegradationCorrector):
+            allowed_tool_names = _build_allowed_tool_names_for_degradation_correction(
+                tool_node=tool_node,
+                built_in_tools=self._built_in_tools,
+                structured_output_tools=self._structured_output_tools,
+            )
+            model = ToolCallDegradationCorrector(
+                llm=model,
+                allowed_tool_names=allowed_tool_names,
+            )
+        self._default_tools = default_tools
+        self._model = model
+        _retrier = ModelCallRetrier(ModelRetryConfig())
+
+        self._model_retrier = _retrier
+
+    def _build_model_nodes(self, tool_node: Any) -> ModelNode:
+        """构建 model 节点，返回 ModelNode(Runnable) 实例，供 LangGraph 直接注册。"""
+        self._prepare_compile_context()
+        self._prepare_for_model_nodes(tool_node)
+        return ModelNode(
+            model=self._model,
+            default_tools=self._default_tools,
+            compaction_settings=self._compaction_settings,
+            max_output_tokens_cap=self._model_context_resolver.resolve_max_output_tokens(
+                self._loop_config
+            ),
+            system_message=self._system_message,
+            initial_response_format=self._initial_response_format,
+            max_steps=self._raw_max_steps,
+            max_turns=self._max_turns,
+            max_withhold_retries=self._loop_config.max_withhold_retries,
+            name=self._name,
+            structured_output_tools=self._structured_output_tools,
+            tool_strategy_for_setup=self._tool_strategy_for_setup,
+            retrier=self._model_retrier,
+            tool_node=tool_node,
+            dynamic_tool_error_template=DYNAMIC_TOOL_ERROR_TEMPLATE,
+            fallback_model=self._fallback_model,
+            llm_callback_handler=self._trace_callback_handler,
+            dynamic_sections=self._dynamic_sections if self._has_dynamic_prompt else None,
+            base_prompt=self._base_prompt,
+            override_prompt=self._override_system_prompt,
+            append_prompt=self._append_system_prompt,
+        )
+
+    def _build_compaction_settings(self) -> CompactionSettings:
+        base = CompactionSettings()
+        return CompactionSettings(
+            num_chars_per_token=base.num_chars_per_token,
+            prune_protect_tokens=base.prune_protect_tokens,
+            prune_minimum_tokens=base.prune_minimum_tokens,
+            prune_protected_tools=base.prune_protected_tools,
+            default_max_context_tokens=self._model_context_resolver.resolve_context_window(
+                self._loop_config
+            ),
+            default_compress_trigger_fraction=base.default_compress_trigger_fraction,
+            default_compress_keep_recent_messages=base.default_compress_keep_recent_messages,
+            autocompact_llm_prompt_kind=base.autocompact_llm_prompt_kind,
+            compact_custom_instructions=base.compact_custom_instructions,
+            autocompact_llm_instructions_override=base.autocompact_llm_instructions_override,
+            compaction_system_prompt=base.compaction_system_prompt,
+            tool_result_max_chars_per_message=base.tool_result_max_chars_per_message,
+            tool_result_budget_suffix=base.tool_result_budget_suffix,
+            snip_preserve_tail_messages=base.snip_preserve_tail_messages,
+            snip_max_tool_content_chars=base.snip_max_tool_content_chars,
+            snip_suffix=base.snip_suffix,
+            microcompact_skip_query_sources=base.microcompact_skip_query_sources,
+            collapse_dedupe_consecutive_same_tool_call_id=base.collapse_dedupe_consecutive_same_tool_call_id,
+            autocompact_skip_query_sources=base.autocompact_skip_query_sources,
+            autocompact_use_llm_when_available=base.autocompact_use_llm_when_available,
+            autocompact_llm_excerpt_chars_per_message=base.autocompact_llm_excerpt_chars_per_message,
+            autocompact_snip_carry_threshold_slack=base.autocompact_snip_carry_threshold_slack,
+            compaction_token_warn_fraction=base.compaction_token_warn_fraction,
+            compaction_block_compact_llm_fraction=base.compaction_block_compact_llm_fraction,
+            compaction_block_main_model_fraction=base.compaction_block_main_model_fraction,
+            enable_main_model_context_token_block=base.enable_main_model_context_token_block,
+            enable_tool_transcript_repair_before_llm=base.enable_tool_transcript_repair_before_llm,
+            emit_compaction_pipeline_meta=base.emit_compaction_pipeline_meta,
+        )
+
+    def _build_graph(
+        self,
+        model_node: ModelNode,
+        tool_node: Any,
+        resolved_state_schema: Any,
+    ) -> Any:
+        """构建 StateGraph，注册节点与边，返回未编译的 graph。"""
+        self._prepare_compile_context()
+        graph_inner = self._create_graph_skeleton(
+            model_node=model_node,
+            tool_node=tool_node,
+            resolved_state_schema=resolved_state_schema,
+        )
+        routing = self._wire_task_and_hook_nodes(graph_inner=graph_inner, tool_node=tool_node)
+        self._wire_main_edges(graph_inner=graph_inner, tool_node=tool_node, routing=routing)
+        return graph_inner
+
+    def _create_graph_skeleton(
+        self,
+        *,
+        model_node: ModelNode,
+        tool_node: Any,
+        resolved_state_schema: Any,
+    ) -> Any:
+        state_schemas: set[type] = set()
+        base_state = self._state_schema if self._state_schema is not None else AgentState
+        state_schemas.add(base_state)
+        state_schemas.add(LoopAgentStateFields)
+        input_schema = _resolve_schema(state_schemas, "InputSchema", "input")
+        output_schema = _resolve_schema(state_schemas, "OutputSchema", "output")
+        graph_inner: StateGraph[
+            AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]
+        ] = StateGraph(
+            state_schema=resolved_state_schema,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            context_schema=self._context_schema,
+        )
+        graph_inner.add_node("model", model_node)
+        if tool_node is not None:
+            graph_inner.add_node("tools", tool_node)
+
+            def _prune_and_compress_node(state, runtime):
+                return self._run_prune_and_compress_with_trace(state)
+
+            graph_inner.add_node(
+                "prune_and_compress",
+                RunnableCallable(_prune_and_compress_node, None, trace=False),
+            )
+        return graph_inner
+
+    def _run_prune_and_compress_with_trace(self, state: dict[str, Any]) -> dict[str, Any]:
+        """执行 compaction，并在当前 session 内记录 compaction span。"""
+        collector = state.get("_trace_collector")
+        run_id = state.get("_run_id")
+        span_id: str | None = None
+        if (
+            collector is not None
+            and isinstance(run_id, str)
+            and run_id
+            and hasattr(collector, "has_session")
+            and collector.has_session(run_id)
+        ):
+            span_id = collector.span_start(
+                span_type="compaction",
+                name="prune_and_compress",
+                session_id=run_id,
+                metadata={"visibility": "summary_only"},
+            )
+        try:
+            if self._session_memory_compact_bridge is not None:
+                self._run_coro_sync(self._session_memory_compact_bridge.wait_for_extraction())
+                compacted_messages = self._session_memory_compact_bridge.try_compact(
+                    list(state.get("messages") or [])
+                )
+                if compacted_messages is not None:
+                    return {
+                        "messages": compacted_messages,
+                        "collapse_retry_available": True,
+                        "compaction_pipeline_meta": {
+                            "autocompact_mode": "session_memory",
+                            "session_memory_compaction": "applied",
+                        },
+                    }
+            patch = self._loop_context_compaction.run(state, model=self._model)
+            compaction_meta = patch.get("compaction_pipeline_meta")
+            if isinstance(compaction_meta, dict):
+                patch["collapse_retry_available"] = bool(compaction_meta.get("tokens_freed_sum", 0))
+        except Exception as exc:
+            if span_id is not None:
+                collector.span_end(
+                    span_id=span_id,
+                    session_id=run_id,
+                    error=str(exc),
+                    metadata={"visibility": "summary_only"},
+                )
+            raise
+        if span_id is not None:
+            metadata: dict[str, Any] = {"visibility": "summary_only"}
+            compaction_meta = patch.get("compaction_pipeline_meta")
+            if isinstance(compaction_meta, dict):
+                metadata["compaction_pipeline_meta"] = compaction_meta
+            collector.span_end(
+                span_id=span_id,
+                session_id=run_id,
+                metadata=metadata,
+            )
+        return patch
+
+    def _wire_task_and_hook_nodes(self, *, graph_inner: Any, tool_node: Any) -> dict[str, Any]:
+        entry_node = "hook_before_model"
+        loop_entry_node = "hook_before_model"
+        raw_loop_entry_node = "hook_before_model"
+        provider_chain, has_skill_tool = self._build_provider_chain(tool_node)
+        if provider_chain:
+            loop_entry_node = self._wire_task_event_nodes(
+                graph_inner=graph_inner,
+                provider_chain=provider_chain,
+                tool_node=tool_node,
+                raw_loop_entry_node=raw_loop_entry_node,
+            )
+        skill_prefetch_provider = self._find_skill_prefetch_provider(
+            provider_chain=provider_chain,
+            has_skill_tool=has_skill_tool,
+        )
+        self._wire_hook_nodes(graph_inner)
+        self._wire_skill_entry(
+            graph_inner=graph_inner,
+            skill_prefetch_provider=skill_prefetch_provider,
+            entry_node=entry_node,
+        )
+        graph_inner.add_edge("hook_before_model", "model")
+        graph_inner.add_node("loop_controller", lambda state: state)
+        return {
+            "entry_node": entry_node,
+            "loop_entry_node": loop_entry_node,
+            "raw_loop_entry_node": raw_loop_entry_node,
+            "loop_exit_node": "model",
+            "exit_node": "hook_loop_end",
+            "provider_chain": provider_chain,
+        }
+
+    def _build_provider_chain(self, tool_node: Any) -> tuple[list[QueuedCommandProvider], bool]:
+        provider_chain: list[QueuedCommandProvider] = list(self._queued_command_providers)
+        has_skill_tool = bool(tool_node and SKILL_TOOL_NAME in tool_node.tools_by_name)
+        has_skill_prefetch_provider = any(
+            isinstance(item, SkillPrefetchProvider) for item in provider_chain
+        )
+        if has_skill_tool and not has_skill_prefetch_provider:
+            rt_skill = self._skill_runtime_tool
+            if rt_skill is not None:
+                wr_skill = getattr(rt_skill, "_workspace_root", None) or self._workspace_root
+                ah_skill = getattr(rt_skill, "_agent_home", None) or self._workspace_cfg.agent_home
+            else:
+                wr_skill = self._workspace_root
+                ah_skill = self._workspace_cfg.agent_home
+            if wr_skill is None:
+                wr_skill = Path.cwd()
+            provider_chain.insert(
+                0,
+                SkillPrefetchProvider(workspace_root=wr_skill, agent_home=str(ah_skill)),
+            )
+        if self._task_runtime is not None:
+            provider_chain.append(LoopTaskInjectionAdapter(self._task_runtime))
+        return provider_chain, has_skill_tool
+
+    def _wire_task_event_nodes(
+        self,
+        *,
+        graph_inner: Any,
+        provider_chain: list[QueuedCommandProvider],
+        tool_node: Any,
+        raw_loop_entry_node: str,
+    ) -> str:
+        def _task_event_commit_ack_node(state, runtime):
+            pending_batch_id = state.get("pending_task_batch_id")
+            pending_command_ids = state.get("pending_task_command_ids")
+            task_events: list[dict[str, Any]] = []
+            if isinstance(pending_batch_id, str) and pending_batch_id:
+                emit_task_event(
+                    state=state,
+                    event_type="task.ack",
+                    batch_id=pending_batch_id,
+                    command_ids=list(pending_command_ids or []),
+                )
+                decoded = decode_provider_batch_id(pending_batch_id)
+                if decoded is not None:
+                    provider_index, raw_batch_id = decoded
+                    if 0 <= provider_index < len(provider_chain):
+                        provider_chain[provider_index].ack_batch(
+                            LoopInjectionBatch(
+                                batch_id=raw_batch_id,
+                                command_ids=list(pending_command_ids or []),
+                                attachment_messages=[],
+                            )
+                        )
+                task_events.append(
+                    {
+                        "event_type": "task-notification-consumed",
+                        "batch_id": pending_batch_id,
+                        "command_ids": list(pending_command_ids or []),
+                        "agent_id": state.get("agent_id"),
+                    }
+                )
+            return {
+                "pending_task_batch_id": None,
+                "pending_task_command_ids": [],
+                "task_events": task_events,
+            }
+
+        def _task_event_reserve_node(state, runtime):
+            agent_id = state.get("agent_id")
+            scope = TaskScope(agent_id=agent_id if isinstance(agent_id, str) else None)
+            task_events: list[dict[str, Any]] = []
+
+            provider_index = -1
+            batch = None
+            try:
+                # Let providers optionally ingest current loop messages before reserve.
+                # This enables auto-bridge scenarios like tool_use_summary without external pump.
+                state_messages = list(state.get("messages") or [])
+                for provider in provider_chain:
+                    ingest = getattr(provider, "ingest_from_messages", None)
+                    if callable(ingest):
+                        try:
+                            ingest(scope=scope, messages=state_messages)
+                        except Exception:
+                            logger.debug(
+                                "provider ingest_from_messages failed; skip provider=%s",
+                                provider.__class__.__name__,
+                                exc_info=True,
+                            )
+                for idx, provider in enumerate(provider_chain):
+                    candidate = provider.build_batch(
+                        scope=scope,
+                        max_priority=self._task_notification_max_priority,
+                        limit=8,
+                    )
+                    if candidate.batch_id:
+                        provider_index = idx
+                        batch = candidate
+                        break
+                if batch is None or not batch.batch_id:
+                    if self._task_runtime is not None:
+                        runtime_events = self._task_runtime.drain_events()
+                        for event in runtime_events:
+                            if str(event.event_type.value) == "terminal":
+                                task_events.append(
+                                    {
+                                        "event_type": "task-terminated",
+                                        "task_id": event.task_id,
+                                        "task_type": event.task_type.value,
+                                        "status": event.status.value,
+                                        "summary": event.summary,
+                                        "agent_id": event.scope.agent_id,
+                                        "terminal_reason": event.terminal_reason,
+                                        "loop_terminal_reason": state.get("terminal_reason"),
+                                    }
+                                )
+                    return {
+                        "pending_task_batch_id": None,
+                        "pending_task_command_ids": [],
+                        "task_events": task_events,
+                    }
+                messages = list(state.get("messages") or [])
+                # 冻结契约：task 通知附件仅经本节点注入；按 command_id 与已有 messages 去重
+                # （见 docs/design-docs/loop/agent-loop/post-tools-injection-contract.md）
+                to_attach = filter_attachment_dicts_by_task_command_id(
+                    messages, list(batch.attachment_messages)
+                )
+                messages.extend(to_attach)
+                emit_task_event(
+                    state=state,
+                    event_type="task.reserve",
+                    batch_id=encode_provider_batch_id(provider_index, batch.batch_id),
+                    command_ids=list(batch.command_ids),
+                    attachment_count=len(to_attach),
+                )
+                task_events.append(
+                    {
+                        "event_type": "task-notification-enqueued",
+                        "batch_id": encode_provider_batch_id(provider_index, batch.batch_id),
+                        "command_ids": list(batch.command_ids),
+                        "agent_id": scope.agent_id,
+                    }
+                )
+                if self._task_runtime is not None:
+                    runtime_events = self._task_runtime.drain_events()
+                    for event in runtime_events:
+                        if str(event.event_type.value) == "terminal":
+                            task_events.append(
+                                {
+                                    "event_type": "task-terminated",
+                                    "task_id": event.task_id,
+                                    "task_type": event.task_type.value,
+                                    "status": event.status.value,
+                                    "summary": event.summary,
+                                    "agent_id": event.scope.agent_id,
+                                    "terminal_reason": event.terminal_reason,
+                                    "loop_terminal_reason": state.get("terminal_reason"),
+                                }
+                            )
+                return {
+                    "messages": messages,
+                    "pending_task_batch_id": encode_provider_batch_id(
+                        provider_index, batch.batch_id
+                    ),
+                    "pending_task_command_ids": list(batch.command_ids),
+                    "task_events": task_events,
+                }
+            except Exception:
+                if batch is not None and batch.batch_id:
+                    if 0 <= provider_index < len(provider_chain):
+                        provider_chain[provider_index].nack_batch(batch, requeue=True)
+                raise
+
+        graph_inner.add_node(
+            "task_event_commit_ack",
+            RunnableCallable(_task_event_commit_ack_node, None, trace=False),
+        )
+        graph_inner.add_node(
+            "task_event_reserve",
+            RunnableCallable(_task_event_reserve_node, None, trace=False),
+        )
+        graph_inner.add_edge("task_event_commit_ack", "task_event_reserve")
+        # Phase 5A：压缩收束到「每轮进入 model 之前」唯一入口；有 task 链时在注入附件之后再压缩。
+        if tool_node is not None:
+            graph_inner.add_edge("task_event_reserve", "prune_and_compress")
+            graph_inner.add_edge("prune_and_compress", raw_loop_entry_node)
+        else:
+            graph_inner.add_edge("task_event_reserve", raw_loop_entry_node)
+        return "task_event_commit_ack"
+
+    def _find_skill_prefetch_provider(
+        self,
+        *,
+        provider_chain: list[QueuedCommandProvider],
+        has_skill_tool: bool,
+    ) -> SkillPrefetchProvider | None:
+        if not has_skill_tool:
+            return None
+        return next(
+            (p for p in provider_chain if isinstance(p, SkillPrefetchProvider)),
+            None,
+        )
+
+    def _wire_hook_nodes(self, graph_inner: Any) -> None:
+        graph_inner.add_node(
+            "hook_loop_start",
+            RunnableCallable(self._hook_graph_wiring.loop_start_node, None, trace=False),
+        )
+        graph_inner.add_node(
+            "hook_before_model",
+            RunnableCallable(self._hook_graph_wiring.before_model_node, None, trace=False),
+        )
+        graph_inner.add_node(
+            "hook_after_model",
+            RunnableCallable(self._hook_graph_wiring.after_model_node, None, trace=False),
+        )
+        graph_inner.add_node(
+            "hook_stop",
+            RunnableCallable(self._hook_graph_wiring.stop_hooks_node, None, trace=False),
+        )
+        graph_inner.add_node(
+            "hook_loop_end",
+            RunnableCallable(self._hook_graph_wiring.loop_end_node, None, trace=False),
+        )
+        graph_inner.add_edge("hook_loop_end", END)
+
+    def _wire_skill_entry(
+        self,
+        *,
+        graph_inner: Any,
+        skill_prefetch_provider: SkillPrefetchProvider | None,
+        entry_node: str,
+    ) -> None:
+        if skill_prefetch_provider is not None:
+            skill_init_scope = TaskScope(agent_id=None)
+
+            def _skill_init_node(state, runtime):
+                messages = list(state.get("messages") or [])
+                # 已有 skill_listing 则幂等跳过（任何类型消息含 [skill_listing] 前缀）
+                for msg in messages:
+                    content = getattr(msg, "content", "")
+                    if isinstance(content, str) and "[skill_listing]" in content:
+                        return {}
+                hint = skill_prefetch_provider._build_listing_hint(scope=skill_init_scope)
+                if hint is None:
+                    return {}
+                return {"messages": [SystemMessage(content=f"[skill_listing] {hint.summary}")]}
+
+            graph_inner.add_node(
+                "skill_init",
+                RunnableCallable(_skill_init_node, None, trace=False),
+            )
+            graph_inner.add_edge(START, "skill_init")
+            graph_inner.add_edge("skill_init", "hook_loop_start")
+            graph_inner.add_edge("hook_loop_start", entry_node)
+            return
+        graph_inner.add_edge(START, "hook_loop_start")
+        graph_inner.add_edge("hook_loop_start", entry_node)
+
+    def _wire_main_edges(self, *, graph_inner: Any, tool_node: Any, routing: dict[str, Any]) -> None:
+        loop_entry_node = routing["loop_entry_node"]
+        loop_exit_node = routing["loop_exit_node"]
+        exit_node = routing["exit_node"]
+        provider_chain = routing["provider_chain"]
+        if tool_node is not None:
+            self._wire_main_edges_with_tools(
+                graph_inner=graph_inner,
+                tool_node=tool_node,
+                loop_entry_node=loop_entry_node,
+                loop_exit_node=loop_exit_node,
+                exit_node=exit_node,
+                provider_chain=provider_chain,
+            )
+            return
+        if len(self._structured_output_tools) > 0:
+            self._wire_main_edges_with_structured_output(
+                graph_inner=graph_inner,
+                loop_entry_node=loop_entry_node,
+                loop_exit_node=loop_exit_node,
+            )
+            return
+        self._wire_main_edges_without_tools(
+            graph_inner=graph_inner,
+            loop_exit_node=loop_exit_node,
+        )
+
+    def _wire_main_edges_with_tools(
+        self,
+        *,
+        graph_inner: Any,
+        tool_node: Any,
+        loop_entry_node: str,
+        loop_exit_node: str,
+        exit_node: str,
+        provider_chain: list[QueuedCommandProvider],
+    ) -> None:
+        if provider_chain:
+            tools_model_destination = loop_entry_node
+            tools_to_model_destinations = [loop_entry_node, exit_node]
+        else:
+            tools_model_destination = "prune_and_compress"
+            tools_to_model_destinations = ["prune_and_compress", exit_node]
+
+        graph_inner.add_conditional_edges(
+            "tools",
+            RunnableCallable(
+                _make_tools_to_model_edge(
+                    tool_node=tool_node,
+                    model_destination=tools_model_destination,
+                    structured_output_tools=self._structured_output_tools,
+                    end_destination=exit_node,
+                ),
+                trace=False,
+            ),
+            tools_to_model_destinations,
+        )
+        if not provider_chain:
+            graph_inner.add_edge("prune_and_compress", loop_entry_node)
+        graph_inner.add_edge(loop_exit_node, "hook_after_model")
+        graph_inner.add_edge("hook_after_model", "hook_stop")
+        graph_inner.add_edge("hook_stop", "loop_controller")
+
+        loop_controller_destinations = ["tools", loop_entry_node, exit_node]
+        if provider_chain and "task_event_commit_ack" not in loop_controller_destinations:
+            loop_controller_destinations.append("task_event_commit_ack")
+        graph_inner.add_conditional_edges(
+            "loop_controller",
+            RunnableCallable(
+                _make_loop_controller_edge(
+                    model_destination=loop_entry_node,
+                    tools_destination="tools",
+                    structured_output_tools=self._structured_output_tools,
+                    end_destination=exit_node,
+                    max_output_tokens_cap=self._model_context_resolver.resolve_max_output_tokens(
+                        self._loop_config
+                    ),
+                    token_budget_max_continuations=self._loop_config.token_budget_max_continuations,
+                    task_reconcile_destination=(
+                        "task_event_commit_ack" if provider_chain else None
+                    ),
+                    has_pending_task_notifications=self._build_pending_task_notifications_checker(
+                        provider_chain
+                    ),
+                ),
+                trace=False,
+            ),
+            loop_controller_destinations,
+        )
+
+    def _wire_main_edges_with_structured_output(
+        self,
+        *,
+        graph_inner: Any,
+        loop_entry_node: str,
+        loop_exit_node: str,
+    ) -> None:
+        graph_inner.add_edge(loop_exit_node, "hook_after_model")
+        graph_inner.add_conditional_edges(
+            "hook_after_model",
+            RunnableCallable(
+                _make_model_to_model_edge(
+                    model_destination=loop_entry_node,
+                    end_destination="hook_stop",
+                ),
+                trace=False,
+            ),
+            [loop_entry_node, "hook_stop"],
+        )
+        graph_inner.add_edge("hook_stop", "hook_loop_end")
+
+    def _wire_main_edges_without_tools(
+        self,
+        *,
+        graph_inner: Any,
+        loop_exit_node: str,
+    ) -> None:
+        graph_inner.add_edge(loop_exit_node, "hook_after_model")
+        graph_inner.add_edge("hook_after_model", "hook_stop")
+        graph_inner.add_edge("hook_stop", "hook_loop_end")
+
+    def _build_pending_task_notifications_checker(
+        self,
+        provider_chain: list[QueuedCommandProvider],
+    ) -> Callable[[dict[str, Any]], bool] | None:
+        if not provider_chain:
+            return None
+
+        def has_pending(state: dict[str, Any]) -> bool:
+            return any(
+                provider.has_pending(
+                    TaskScope(
+                        agent_id=state.get("agent_id")
+                        if isinstance(state.get("agent_id"), str)
+                        else None
+                    ),
+                    max_priority=self._task_notification_max_priority,
+                )
+                for provider in provider_chain
+            )
+
+        return has_pending
+
+    def build_compiled(self) -> Any:
+        """完整构建并编译 graph，等价于 create_loop_agent 内部流程。"""
+        self._prepare_compile_context()
+        tool_node = self._build_tool_node()
+        model_node = self._build_model_nodes(tool_node)
+        state_schemas: set[type] = set()
+        base_state = self._raw_state_schema if self._raw_state_schema is not None else AgentState
+        state_schemas.add(base_state)
+        state_schemas.add(LoopAgentStateFields)
+        resolved_state_schema = _resolve_schema(state_schemas, "StateSchema", None)
+        graph = self._build_graph(model_node, tool_node, resolved_state_schema)
+        return self.compile(graph)
+
+    def compile(self, graph: Any) -> Any:
+        """编译 graph，注入 configurable，返回 CompiledStateGraph。"""
+        self._prepare_compile_context()
+        config: RunnableConfig = {"recursion_limit": compute_recursion_limit(self._max_steps_param)}
+        if self._name:
+            config["metadata"] = {"lc_agent_name": self._name}
+        if self._session_store is not None:
+            if "configurable" not in config:
+                config["configurable"] = {}
+            config["configurable"]["session_store"] = self._session_store
+        if self._raw_loader is not None:
+            if "configurable" not in config:
+                config["configurable"] = {}
+            config["configurable"]["tool_loader"] = self._raw_loader
+            config["configurable"]["tool_registry"] = self._raw_loader.registry
+        compiled = graph.compile(
+            debug=self._debug,
+            name=self._name,
+        )
+        compiled = compiled.with_config(config)
+        compiled = compiled.with_config({"configurable": {"loop_config": self._loop_config}})
+        if self._trace_tool_callback_handler is not None:
+            compiled = compiled.with_config({"callbacks": [self._trace_tool_callback_handler]})
+        self._wrap_compiled_ainvoke_with_trace_failure_fallback(compiled)
+        self._log.info("create_loop_agent completed")
+        return compiled
+
+    def _wrap_compiled_ainvoke_with_trace_failure_fallback(self, compiled: Any) -> None:
+        """在 graph 异常路径上兜底 end_session，避免 loop_end_node 未执行导致会话悬挂。"""
+        collector = self._trace_collector
+        session_id = self._session_id
+        if collector is None or not session_id or not hasattr(compiled, "ainvoke"):
+            return
+
+        original_ainvoke = compiled.ainvoke
+
+        async def _ainvoke_with_trace_fallback(this: Any, *args: Any, **kwargs: Any) -> Any:
+            try:
+                return await original_ainvoke(*args, **kwargs)
+            except Exception as exc:
+                if collector.has_session(session_id):
+                    collector.end_session(
+                        session_id=session_id,
+                        status="failed",
+                        terminal_reason=str(exc),
+                    )
+                raise
+
+        compiled.ainvoke = MethodType(_ainvoke_with_trace_fallback, compiled)
+
+
+def create_loop_agent(
+    model: str | BaseChatModel,
+    *,
+    # Prompt 配置
+    system_prompt: str | SystemMessage | None = None,
+    override_system_prompt: str | None = None,
+    append_system_prompt: str | None = None,
+    dynamic_sections: Sequence[SystemPromptSection] = (),
+    # Model 配置
+    response_format: ResponseFormat[ResponseT] | type[ResponseT] | dict[str, Any] | None = None,
+    fallback_model: BaseChatModel | None = None,
+    enable_tool_call_degradation_fix: bool = True,
+    # Session / Runtime 配置
+    session_id: str | None = None,
+    session_store: "AgentSessionStore | None" = None,
+    loader: "ToolRuntimeLoader | None" = None,
+    permission_resolver: Any | None = None,
+    # Graph / Runtime 基础配置
+    state_schema: type[AgentState[ResponseT]] | None = None,
+    context_schema: type[ContextT] | None = None,
+    debug: bool = False,
+    name: str | None = None,
+    # LangChain AgentX 特有参数
+    max_steps: int | None = None,
+    max_turns: int | None = None,
+    is_subagent: bool = False,
+    subagent_type: str | None = None,
+    container_type: str | None = None,
+    # Observability
+    enable_trace: bool = True,
+    trace_collector: TraceCollector | None = None,
+    parent_run_id: str | None = None,
+    parent_tool_call_id: str | None = None,
+    parent_conversation_session_id: str | None = None,
+    trace_visibility: str | None = None,
+    # Task Runtime / Provider
+    task_runtime: TaskRuntime | None = None,
+    task_notification_max_priority: QueuePriority = QueuePriority.NEXT,
+    queued_command_providers: Sequence[QueuedCommandProvider] = (),
+    managed_rules: str | None = None,
+    active_files_getter: "Callable[[], list[str]] | None" = None,
+    workspace_root: str | Path | None = None,
+    agent_home: str = ".langchain_agentx",
+    workspace_trust_accepted: bool | None = None,
+    hooks: "HookRegistry | None" = None,
+    enable_session_memory: bool = False,
+) -> CompiledStateGraph[
+    AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]
+]:
+
+ 
+    builder = LoopGraphBuilder(
+        model,
+        system_prompt=system_prompt,
+        override_system_prompt=override_system_prompt,
+        append_system_prompt=append_system_prompt,
+        dynamic_sections=dynamic_sections,
+        response_format=response_format,
+        fallback_model=fallback_model,
+        enable_tool_call_degradation_fix=enable_tool_call_degradation_fix,
+        session_id=session_id,
+        session_store=session_store,
+        loader=loader,
+        permission_resolver=permission_resolver,
+        state_schema=state_schema,
+        context_schema=context_schema,
+        debug=debug,
+        name=name,
+        max_steps=max_steps,
+        max_turns=max_turns,
+        is_subagent=is_subagent,
+        subagent_type=subagent_type,
+        container_type=container_type,
+        enable_trace=enable_trace,
+        trace_collector=trace_collector,
+        parent_run_id=parent_run_id,
+        parent_tool_call_id=parent_tool_call_id,
+        parent_conversation_session_id=parent_conversation_session_id,
+        trace_visibility=trace_visibility,
+        task_runtime=task_runtime,
+        task_notification_max_priority=task_notification_max_priority,
+        queued_command_providers=queued_command_providers,
+        managed_rules=managed_rules,
+        active_files_getter=active_files_getter,
+        workspace_root=workspace_root,
+        agent_home=agent_home,
+        workspace_trust_accepted=workspace_trust_accepted,
+        raw_hooks=hooks,
+        enable_session_memory=enable_session_memory,
+    )
+    tool_node = builder._build_tool_node()
+    model_node = builder._build_model_nodes(tool_node)
+    state_schemas: set[type] = set()
+    base_state = state_schema if state_schema is not None else AgentState
+    state_schemas.add(base_state)
+    state_schemas.add(LoopAgentStateFields)
+    resolved_state_schema = _resolve_schema(state_schemas, "StateSchema", None)
+    graph = builder._build_graph(model_node, tool_node, resolved_state_schema)
+    return builder.compile(graph)
+
+
+__all__ = [
+    "create_loop_agent",
+]