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

langchain_agentx/loop/__init__.py

@@ -0,0 +1,47 @@
+"""
+LangChain AgentX Agent - 基于 LangGraph 实现的 LangChain AgentX 风格 Agent
+
+核心特性：
+1. 使用原生 finish_reason 判断退出（与 OpenCode 一致）
+2. 与 LangGraph 生态完全兼容
+3. 解决 create_agent 的"工具调用噩梦"
+
+使用方式：
+```python
+from langchain_agentx.loop import create_loop_agent
+from langchain_agentx.tool_runtime import ToolRuntimeLoader
+# from langchain_agentx.tools.read import ReadRuntimeTool
+
+loader = ToolRuntimeLoader()
+# loader.register(ReadRuntimeTool())
+
+agent = create_loop_agent(
+    model="anthropic:claude-sonnet-4-5-20250929",
+    loader=loader,
+    system_prompt="You are a helpful assistant",
+    max_steps=50,
+)
+
+for chunk in agent.stream({"messages": [{"role": "user", "content": "Hello"}]}):
+    print(chunk)
+```
+
+参考设计文档：
+- .claude/design/lowest-layer-opencode-style-agent-design.md（原理和问题）
+- .claude/design/create-opencode-style-agent-design.md（实现方案）
+"""
+
+# 主要导出
+from .graph.factory import (
+    create_loop_agent,
+)
+from .loop_abort import LoopAbortSignal
+from .config import build_agent_config
+
+__all__ = [
+    # 主要接口
+    "create_loop_agent",
+    "LoopAbortSignal",
+    # 配置助手
+    "build_agent_config",
+]

langchain_agentx/loop/config/__init__.py

@@ -0,0 +1,20 @@
+from .agent_config import build_agent_config
+from .agent_loop_config import AgentLoopConfig
+from .model_context_resolver import ModelContextResolver
+from .token_estimator import TokenEstimator
+from .runtime_settings import (
+    compute_recursion_limit,
+    materialize_max_steps,
+    resolve_max_steps,
+)
+
+__all__ = [
+    "AgentLoopConfig",
+    "ModelContextResolver",
+    "TokenEstimator",
+    "build_agent_config",
+    "compute_recursion_limit",
+    "materialize_max_steps",
+    "resolve_max_steps",
+]
+

langchain_agentx/loop/config/agent_config.py

@@ -0,0 +1,66 @@
+"""agent_config.py — Agent config 构建助手
+
+职责：
+    构建 `agent.invoke/ainvoke/astream*` 所需的 config 字典。
+    只负责 LangGraph 配置参数（如 recursion_limit）。
+
+Note:
+    - run_id 由 HookGraphWiring/TraceLifecycleCollector 注入，不需要手动配置
+    - session_id 在 create_loop_agent 时配置，不在此处
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_agent_config(
+    *,
+    recursion_limit: int = 9_999,
+    **kwargs: Any,
+) -> dict[str, Any]:
+    """构建 Agent 运行配置（LangGraph 配置参数）。
+
+    Args:
+        recursion_limit: 运行递归上限（默认 9999）。
+        **kwargs: 其他 LangGraph config 参数（如 metadata, configurable 等）。
+
+    Returns:
+        可直接传给 `agent.invoke(..., config=...)` 的配置字典。
+
+    Example:
+        >>> # 使用默认配置
+        >>> config = build_agent_config()
+        >>> result = agent.invoke({"messages": [...]}, config=config)
+
+        >>> # 自定义 recursion_limit
+        >>> config = build_agent_config(recursion_limit=5000)
+        >>> result = agent.invoke({"messages": [...]}, config=config)
+
+        >>> # 添加其他 LangGraph 配置
+        >>> config = build_agent_config(
+        ...     recursion_limit=5000,
+        ...     metadata={"user_id": "123"},
+        ... )
+        >>> result = agent.invoke({"messages": [...]}, config=config)
+
+    Note:
+        - run_id 由 HookGraphWiring/TraceLifecycleCollector 在每次调用时自动注入
+        - session_id 已在 create_loop_agent 时配置
+        - 如果不需要自定义配置，可以直接调用 agent.invoke() 不传 config
+    """
+    config: dict[str, Any] = {
+        "recursion_limit": recursion_limit,
+    }
+
+    # 合并其他参数
+    if kwargs:
+        config.update(kwargs)
+
+    return config
+
+
+__all__ = ["build_agent_config"]
+
+
+

langchain_agentx/loop/config/agent_loop_config.py

@@ -0,0 +1,72 @@
+"""agent_loop_config.py — Agent Loop 不变配置（构建时确定）
+
+职责：
+    以强类型 dataclass 承载与 LangGraph 迭代轮次无关的不变配置；目标态下写入
+    `config["configurable"]["loop_config"]`，不进入 LangGraph state。
+
+在整体链路中的位置：
+    create_loop_agent（及子代理派生）组装本对象并注入 configurable；工具层
+   （如 adapter → ToolExecutionContext）从 configurable 读取模型与权限等控制面，
+    替代从 state 猜测 `__loop_model__` 等临时字段。
+
+CC 对照：
+    语义上对齐 CC 的 QueryParams（不变入参）与 toolUseContext.options（控制面）
+    的组合：控制面不进 queryLoop State，而通过独立上下文传递。
+
+当前裁剪范围：
+    仅提供 `AgentLoopConfig` 数据结构；与 `LoopRuntimeContext` 合并、工厂派生、
+    factory/adapter 接线在后续步骤完成。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from langchain_agentx.provider.model_profile import ModelProfile, ModelProfileRegistry
+
+
+@dataclass
+class AgentLoopConfig:
+    """Agent Loop 构建时确定的不变配置。
+
+    父子代理共用同一类型：RuntimeContextFactory.derive() 返回子代理的 AgentLoopConfig。
+    CC 对照：QueryParams（不变入参）+ toolUseContext.options（控制面）。
+    """
+
+    # 模型控制面
+    model: Any  # BaseChatModel 或 provider-qualified 字符串
+    fallback_model: Any | None = None
+
+    # 执行限制
+    max_steps: int | None = None
+    max_turns: int | None = None
+    max_withhold_retries: int = 1
+    token_budget_max_continuations: int = 3
+    managed_rules: str | None = None
+
+    # 工具与权限
+    available_tools: list[Any] = field(default_factory=list)
+    permission_mode: str = "default"
+    permission_resolver: Any | None = None
+    workspace_root: str | None = None  # 工具层 workspace 根路径，权限检查边界
+    agent_home: str = ".langchain_agentx"  # Agent 家目录（skills/worktrees/tasks 派生根）
+    cwd: str | None = None  # 当前工作目录，路径展开基准，可被子代理覆盖（CC 对照：getCwd()）
+
+    # 会话标识
+    session_id: str = ""
+    conversation_session_id: str = ""
+    agent_id: str | None = None
+    parent_agent_id: str | None = None
+    agent_depth: int = 0
+    subagent_type: str | None = None
+    # 观测控制面：主 Agent 打开则子 Agent 默认继承打开
+    trace_enabled: bool = True
+    # 模型能力配置：显式 profile > registry 匹配 > model metadata > 代码兜底
+    model_profile: ModelProfile | None = None
+    model_profile_registry: ModelProfileRegistry | None = None
+    compact_buffer_tokens: int = 13_000
+    max_output_tokens_reserved: int = 20_000
+
+
+__all__ = ["AgentLoopConfig"]

langchain_agentx/loop/config/model_context_resolver.py

@@ -0,0 +1,105 @@
+"""loop/config/model_context_resolver.py — 模型上下文能力解析器。
+
+职责：
+    - 解析当前 loop 使用模型的 context_window。
+    - 解析当前 loop 使用模型的 max_output_tokens。
+
+链路位置：
+    - loop/graph/factory.py：构建期生成动态 CompactionSettings。
+    - 后续 P2b：exit/model 消费侧读取 max_output_tokens 上限。
+
+当前裁剪范围：
+    - 仅负责模型能力解析，不做 token 估算，不做 compaction 判定。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from langchain_agentx.provider.model_profile import ModelProfileRegistry
+
+from .agent_loop_config import AgentLoopConfig
+
+
+class ModelContextResolver:
+    """按约定优先级链解析模型上下文能力。"""
+
+    def resolve_context_window(self, loop_config: AgentLoopConfig) -> int:
+        env_override = self._parse_positive_int(os.getenv("AGENTX_MAX_CONTEXT_TOKENS"))
+        if env_override is not None:
+            return env_override
+
+        if loop_config.model_profile is not None:
+            return int(loop_config.model_profile.context_window)
+
+        registry = loop_config.model_profile_registry
+        model_id = self._extract_model_id(loop_config.model)
+        if registry is not None and model_id:
+            profile = registry.get(model_id)
+            if profile.model_id_prefix != "__default__":
+                return int(profile.context_window)
+            if registry.defaults is not None:
+                return int(registry.defaults.context_window)
+
+        metadata_context_window = self._resolve_model_metadata_context_window(loop_config.model)
+        if metadata_context_window is not None:
+            return metadata_context_window
+
+        return 32_000
+
+    def resolve_max_output_tokens(self, loop_config: AgentLoopConfig) -> int:
+        if loop_config.model_profile is not None:
+            return int(loop_config.model_profile.max_output_tokens)
+
+        registry = loop_config.model_profile_registry
+        model_id = self._extract_model_id(loop_config.model)
+        if registry is not None and model_id:
+            profile = registry.get(model_id)
+            if profile.model_id_prefix != "__default__":
+                return int(profile.max_output_tokens)
+            if registry.defaults is not None:
+                return int(registry.defaults.max_output_tokens)
+
+        metadata_max_output = self._resolve_model_metadata_max_output_tokens(loop_config.model)
+        if metadata_max_output is not None:
+            return metadata_max_output
+
+        return 8_192
+
+    @staticmethod
+    def _extract_model_id(model: Any) -> str | None:
+        if isinstance(model, str):
+            return model.split(":")[-1] if ":" in model else model
+        return getattr(model, "model_name", None) or getattr(model, "model", None)
+
+    @staticmethod
+    def _resolve_model_metadata_context_window(model: Any) -> int | None:
+        metadata = getattr(model, "metadata", None) or {}
+        if not isinstance(metadata, dict):
+            return None
+        return ModelContextResolver._parse_positive_int(metadata.get("context_window"))
+
+    @staticmethod
+    def _resolve_model_metadata_max_output_tokens(model: Any) -> int | None:
+        metadata = getattr(model, "metadata", None) or {}
+        if not isinstance(metadata, dict):
+            return None
+        for key in ("max_output_tokens", "max_tokens"):
+            parsed = ModelContextResolver._parse_positive_int(metadata.get(key))
+            if parsed is not None:
+                return parsed
+        return None
+
+    @staticmethod
+    def _parse_positive_int(value: Any) -> int | None:
+        if value is None:
+            return None
+        try:
+            parsed = int(str(value).strip())
+        except (TypeError, ValueError):
+            return None
+        return parsed if parsed > 0 else None
+
+
+__all__ = ["ModelContextResolver"]

langchain_agentx/loop/config/runtime_settings.py

@@ -0,0 +1,50 @@
+"""runtime_settings.py — Loop 运行时全局策略设置。
+
+职责：
+    提供 max_steps 的透明解析函数。
+    接口语义与实现语义一致：None = 不限制，int = 确切上限。
+
+设计变更（2026-05-01）：
+    移除 get_global_max_steps_default() — 不再通过环境变量隐藏默认值 120。
+    接口设置 max_steps=None 就是真正的不限制，没有静默兜底。
+    环境变量支持由调用方（create_loop_agent 入口）自行处理，不做隐式注入。
+"""
+
+from __future__ import annotations
+
+UNBOUNDED_MAX_STEPS = 1_000_000
+
+
+def resolve_max_steps(value: int | None) -> int | None:
+    """透明解析：None → None（不限），int → int（确切上限）。
+
+    与接口语义保持一致，不做隐式默认值注入。
+    """
+    return value
+
+
+def materialize_max_steps(value: int | None) -> int:
+    """将可选 max_steps 物化为 Loop 内部可执行上限。
+
+    None（不限步）→ UNBOUNDED_MAX_STEPS（1_000_000），
+    int → 原值。
+    """
+    return UNBOUNDED_MAX_STEPS if value is None else value
+
+
+def compute_recursion_limit(value: int | None) -> int:
+    """按 OpenCode 公式计算 recursion_limit。
+
+    recursion_limit 是 LangGraph 图层面的安全阀，
+    与 max_steps 的退出逻辑是两层不同的守卫机制。
+    """
+    effective_steps = materialize_max_steps(value)
+    return 2 * effective_steps + 100
+
+
+__all__ = [
+    "UNBOUNDED_MAX_STEPS",
+    "resolve_max_steps",
+    "materialize_max_steps",
+    "compute_recursion_limit",
+]

langchain_agentx/loop/config/token_estimator.py

@@ -0,0 +1,133 @@
+"""loop/config/token_estimator.py — token 估算协作者。
+
+职责：
+    - 优先使用消息中的真实 usage 元数据估算 token。
+    - 无真实 usage 时回退到字符近似估算。
+
+链路位置：
+    - memory/session/session_memory.py：决定是否触发 session memory 提取。
+    - 后续 P2b：可被更多 loop 消费侧复用。
+
+当前裁剪范围：
+    - 仅实现消息级 token 估算；不负责 context window 判定。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+class TokenEstimator:
+    """真实 usage 优先，字符近似兜底。"""
+
+    def __init__(self, *, num_chars_per_token: int = 4) -> None:
+        self._num_chars_per_token = num_chars_per_token
+
+    def estimate_messages_tokens(self, messages: list[Any]) -> int:
+        baseline_tokens: int | None = None
+        baseline_index = -1
+
+        for index in range(len(messages) - 1, -1, -1):
+            usage_tokens = self.extract_usage_tokens(messages[index])
+            if usage_tokens is not None:
+                baseline_tokens = usage_tokens
+                baseline_index = index
+                break
+
+        if baseline_tokens is None:
+            return self._estimate_chars_tokens(messages)
+
+        return baseline_tokens + self._estimate_chars_tokens(messages[baseline_index + 1 :])
+
+    def extract_usage_tokens(self, message: Any) -> int | None:
+        usage = self._extract_usage_payload(message)
+        if not usage:
+            return None
+
+        if "input_tokens" in usage:
+            return (
+                self._as_int(usage.get("input_tokens"))
+                + self._as_int(usage.get("cache_creation_input_tokens"))
+                + self._as_int(usage.get("cache_read_input_tokens"))
+                + self._as_int(usage.get("output_tokens"))
+            )
+
+        if "prompt_tokens" in usage or "completion_tokens" in usage:
+            return self._as_int(usage.get("prompt_tokens")) + self._as_int(
+                usage.get("completion_tokens")
+            )
+
+        if "total_tokens" in usage:
+            total_tokens = self._as_int(usage.get("total_tokens"))
+            return total_tokens if total_tokens > 0 else None
+
+        return None
+
+    def _estimate_chars_tokens(self, messages: list[Any]) -> int:
+        total_chars = 0
+        for message in messages:
+            total_chars += len(self._stringify_content(self._extract_content(message)))
+        return self._estimate_tokens_from_chars(total_chars)
+
+    @staticmethod
+    def _extract_usage_payload(message: Any) -> Mapping[str, Any] | None:
+        if isinstance(message, Mapping):
+            response_metadata = message.get("response_metadata")
+            if isinstance(response_metadata, Mapping):
+                usage = response_metadata.get("usage") or response_metadata.get("token_usage")
+                return usage if isinstance(usage, Mapping) else None
+            usage = message.get("usage") or message.get("token_usage")
+            return usage if isinstance(usage, Mapping) else None
+
+        response_metadata = getattr(message, "response_metadata", None)
+        if isinstance(response_metadata, Mapping):
+            usage = response_metadata.get("usage") or response_metadata.get("token_usage")
+            if isinstance(usage, Mapping):
+                return usage
+
+        usage_metadata = getattr(message, "usage_metadata", None)
+        if isinstance(usage_metadata, Mapping):
+            return usage_metadata
+        return None
+
+    @staticmethod
+    def _extract_content(message: Any) -> Any:
+        if isinstance(message, Mapping):
+            return message.get("content", "")
+        return getattr(message, "content", "")
+
+    def _estimate_tokens_from_chars(self, n_chars: int) -> int:
+        if self._num_chars_per_token <= 0:
+            return n_chars
+        return (max(0, n_chars) + self._num_chars_per_token - 1) // self._num_chars_per_token
+
+    @staticmethod
+    def _stringify_content(content: Any) -> str:
+        if content is None:
+            return ""
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts: list[str] = []
+            for block in content:
+                if isinstance(block, str):
+                    parts.append(block)
+                elif isinstance(block, dict):
+                    if block.get("type") == "text":
+                        parts.append(str(block.get("text", "")))
+                    else:
+                        parts.append(str(block))
+                else:
+                    parts.append(str(block))
+            return "".join(parts)
+        return str(content)
+
+    @staticmethod
+    def _as_int(value: Any) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return 0
+
+
+__all__ = ["TokenEstimator"]

langchain_agentx/loop/context/__init__.py

@@ -0,0 +1,66 @@
+"""主循环上下文治理（OOP 门面 + CC 五段 `stages/`）。"""
+
+from __future__ import annotations
+
+from .blocking_guard import CompactionBlockingGuard, default_compaction_blocking_guard
+from .compaction_service import LoopContextCompaction, default_loop_context_compaction
+from .pipeline import ContextPipeline, DefaultCompactionStages
+from .settings import (
+    AutocompactLlmPromptKind,
+    CompactionSettings,
+    active_compaction_settings,
+    get_active_compaction_settings,
+    set_active_compaction_settings,
+)
+from .stages import (
+    AutocompactStage,
+    ContextCollapseStage,
+    MicrocompactStage,
+    SnipCompactStage,
+    ToolResultBudgetStage,
+)
+from .types import (
+    CompactionConfig,
+    ContextCompactionContext,
+    StageResult,
+    TokenWarningLevel,
+    TokenWarningState,
+)
+
+# 压缩提示词函数从 loop.prompt.compact 导入（向后兼容）
+from ..prompt.compact import (
+    build_autocompact_llm_instruction_prompt,
+    format_compact_summary,
+    get_compact_prompt,
+    get_compact_user_summary_message,
+    get_partial_compact_prompt,
+)
+
+__all__ = [
+    "active_compaction_settings",
+    "AutocompactLlmPromptKind",
+    "AutocompactStage",
+    "CompactionBlockingGuard",
+    "CompactionConfig",
+    "CompactionSettings",
+    "ContextCollapseStage",
+    "ContextCompactionContext",
+    "ContextPipeline",
+    "DefaultCompactionStages",
+    "default_compaction_blocking_guard",
+    "default_loop_context_compaction",
+    "build_autocompact_llm_instruction_prompt",
+    "format_compact_summary",
+    "get_active_compaction_settings",
+    "get_compact_prompt",
+    "get_compact_user_summary_message",
+    "get_partial_compact_prompt",
+    "LoopContextCompaction",
+    "MicrocompactStage",
+    "set_active_compaction_settings",
+    "SnipCompactStage",
+    "StageResult",
+    "TokenWarningLevel",
+    "TokenWarningState",
+    "ToolResultBudgetStage",
+]

langchain_agentx/loop/context/blocking_guard.py

@@ -0,0 +1,97 @@
+"""
+紧凑化路径上的 token 告警与「是否拦二次模型」守卫（阶段 C）。
+
+与 Claude Code 对齐：
+- `calculate_token_warning_state` 分档：`ok` / `warn` / `block_compact_llm` / `block_main_model`，
+  语义上贴近 CC `calculateTokenWarningState` 与 compact 前「过满则勿再调摘要模型」；
+- `should_block`：是否建议 **拦主循环 model**（估计已超过上下文硬顶），供 Graph / middleware 协作。
+
+设计要点：
+- 估计使用 `message_utils.total_estimated_tokens_for_messages`，与五段一致；
+- **不**插入默认五段列表；`AutocompactStage` 在调用 compact LLM 前查询 `should_block_compact_llm`。
+
+注意：
+- 不修改 LangGraph state；与 `CompactionStage.run` 正交。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..config.token_estimator import TokenEstimator
+from .settings import CompactionSettings, get_active_compaction_settings
+from .types import ContextCompactionContext, TokenWarningLevel, TokenWarningState
+
+
+class CompactionBlockingGuard:
+    """基于启发式 token 的告警与阻塞建议。"""
+
+    def __init__(self, settings: CompactionSettings | None = None) -> None:
+        self._settings_override = settings
+        self._token_estimator = TokenEstimator(
+            num_chars_per_token=(settings.num_chars_per_token if settings is not None else 4)
+        )
+
+    def _settings(self) -> CompactionSettings:
+        return self._settings_override or get_active_compaction_settings()
+
+    def estimate_messages_tokens(self, messages: list[Any]) -> int:
+        return self._token_estimator.estimate_messages_tokens(messages)
+
+    def calculate_token_warning_state(self, messages: list[Any]) -> TokenWarningState:
+        s = self._settings()
+        est = self.estimate_messages_tokens(messages)
+        max_ctx = max(1, s.default_max_context_tokens)
+        warn_line = int(max_ctx * s.compaction_token_warn_fraction)
+        block_llm_line = int(max_ctx * s.compaction_block_compact_llm_fraction)
+        block_main_line = int(max_ctx * s.compaction_block_main_model_fraction)
+        level: TokenWarningLevel
+        if est >= block_main_line:
+            level = "block_main_model"
+        elif est >= block_llm_line:
+            level = "block_compact_llm"
+        elif est >= warn_line:
+            level = "warn"
+        else:
+            level = "ok"
+        return TokenWarningState(
+            estimated_tokens=est,
+            warn_threshold_tokens=warn_line,
+            block_compact_llm_threshold_tokens=block_llm_line,
+            block_main_model_threshold_tokens=block_main_line,
+            level=level,
+        )
+
+    def should_block_compact_llm(self, messages: list[Any]) -> bool:
+        """估计已超过「compact 二次 LLM」安全线时返回 True（仅走 prune / 跳过摘要模型）。"""
+        st = self.calculate_token_warning_state(messages)
+        return st.level in ("block_compact_llm", "block_main_model")
+
+    def should_block(
+        self,
+        ctx: ContextCompactionContext,
+        *,
+        estimated_tokens: int = 0,
+    ) -> bool:
+        """是否建议阻塞 **主** model（由调用方传入已算好的 token 或自行先算 messages）。"""
+        _ = ctx
+        s = self._settings()
+        line = int(s.default_max_context_tokens * s.compaction_block_main_model_fraction)
+        return estimated_tokens >= line
+
+
+_default_guard: CompactionBlockingGuard | None = None
+
+
+def default_compaction_blocking_guard() -> CompactionBlockingGuard:
+    """进程内单例守卫。"""
+    global _default_guard
+    if _default_guard is None:
+        _default_guard = CompactionBlockingGuard()
+    return _default_guard
+
+
+__all__ = [
+    "CompactionBlockingGuard",
+    "default_compaction_blocking_guard",
+]