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

langchain_agentx/loop/subagent/runner.py

@@ -0,0 +1,504 @@
+"""
+loop/subagent/runner.py — 子 Agent 同步执行路径
+
+职责：run_subagent()，plain/fork 模式同步阻塞执行，astream_events 流式处理
+在整体链路中的位置：AgentRuntimeTool.invoke() → run_subagent() → SubagentResult
+CC 对照：runAgent.ts runAgent()；onProgress 回调逻辑
+当前裁剪范围：v1 plain/fork 同步路径；coordinate 异步路径见 async_runner.py
+
+执行流程（run_subagent）：
+  1. 校验：is_async=True 时抛 RuntimeError，model=None 时抛 ValueError
+  2. 构造 SubagentTranscriptManager（InMemoryTranscriptStore）
+  3. create_subagent_graph(ctx, tools, model) 创建子图
+  4. 将 ctx.initial_messages 转为 LangChain HumanMessage 列表作为图输入
+  5. astream_events 循环（单线收集，CC agentMessages 累积模式）：
+       on_tool_start      → on_progress(tool_use)
+       on_tool_end        → on_progress(tool_result) + transcript.append()
+       on_chat_model_end  → 累积 assistant 消息 + total_steps 计数 + on_progress(model_step)
+       on_chain_end(LangGraph) → 仅提取 terminal_reason（不再取 messages）
+  6. 从累积的 assistant 消息中提取最终内容（CC finalizeAgentTool 语义）
+  7. on_progress(completed)，返回 SubagentResult
+  try/finally：确保 transcript.cleanup() + cleanup_subagent_context() 必然执行
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from concurrent.futures import Future
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from langchain_core.messages import HumanMessage
+
+from langchain_agentx.loop.subagent.context import (
+    SubagentContext,
+    SubagentResult,
+    cleanup_subagent_context,
+)
+from langchain_agentx.loop.subagent.graph import create_subagent_graph
+from langchain_agentx.loop.subagent.progress import SubagentProgressEvent
+from langchain_agentx.loop.subagent.transcript import (
+    InMemoryTranscriptStore,
+    SubagentTranscriptManager,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _run_coroutine_sync(coro: Any) -> Any:
+    """在同步上下文运行协程；若当前已有事件循环则转到子线程执行。"""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+
+    fut: Future[Any] = Future()
+
+    def _runner() -> None:
+        try:
+            fut.set_result(asyncio.run(coro))
+        except Exception as exc:
+            fut.set_exception(exc)
+
+    thread = threading.Thread(target=_runner, daemon=True)
+    thread.start()
+    thread.join()
+    return fut.result()
+
+
+@dataclass
+class BackgroundLaunchedResult:
+    """异步路径立即返回的凭证（coordinate 模式）。"""
+    status: str  # always "async_launched"
+    agent_id: str
+    task_id: str
+
+
+@dataclass
+class _EventCollectionResult:
+    """子图事件收集结果。"""
+    collected_assistant_messages: list[Any]
+    terminal_reason: str
+    total_steps: int
+    error_message: str
+    last_tool_name: str
+    child_run_id: str | None
+    tool_step: int
+
+
+def _to_message_dict(msg: Any) -> dict[str, Any]:
+    """将 LangChain message 对象转为 dict，已是 dict 则直接返回。"""
+    if isinstance(msg, dict):
+        return msg
+    role = getattr(msg, "type", None) or getattr(msg, "role", "unknown")
+    # LangChain message type → role 映射
+    role_map = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}
+    role = role_map.get(role, role)
+    content = getattr(msg, "content", "")
+    return {"role": role, "content": content}
+
+
+def _extract_final_content(messages: list[Any], allowed_tool_names: set[str] | None = None) -> str:
+    """从累积的 assistant 消息中提取最终文本内容。
+
+    策略（对齐 CC finalizeAgentTool）：
+    1. 从后往前找第一条有文本且不是纯工具调度消息的 AIMessage。
+    2. 若所有 AIMessage 都是纯工具调度（有 tool_calls 无文本），返回空串，
+       由调用方附诊断信息。
+
+    "纯工具调度消息"定义：tool_calls 非空，或内容含退化格式工具调用文本。
+    on_chat_model_end 在 ToolCallDegradationCorrector 处理前触发，因此
+    collected_assistant_messages 里的退化消息尚未被纠偏，需在此处识别并跳过。
+    """
+    def _text_from_msg(msg: Any) -> str:
+        if isinstance(msg, dict):
+            if msg.get("role") in ("assistant", "ai"):
+                return str(msg.get("content", ""))
+        else:
+            if getattr(msg, "type", None) == "ai":
+                content = getattr(msg, "content", "")
+                if isinstance(content, str):
+                    return content
+                if isinstance(content, list):
+                    parts = [
+                        item.get("text", "")
+                        for item in content
+                        if isinstance(item, dict) and item.get("type") == "text"
+                    ]
+                    return "".join(parts)
+        return ""
+
+    def _has_tool_calls(msg: Any) -> bool:
+        # on_chat_model_end fires before ToolCallDegradationCorrector processes the message,
+        # so raw degraded messages have no tool_calls but contain degradation text patterns.
+        # Treat those as tool dispatch messages too, so they are skipped when extracting
+        # the final summary content.
+        if isinstance(msg, dict):
+            if bool(msg.get("tool_calls")):
+                return True
+            content = str(msg.get("content", ""))
+        else:
+            if bool(getattr(msg, "tool_calls", None)):
+                return True
+            content = getattr(msg, "content", "")
+            if not isinstance(content, str):
+                return False
+        # JSON-tag / prefix degradation formats
+        if "<tool_call>" in content or "CALL_TOOL:" in content or "TOOL_CALL:" in content:
+            return True
+        # XML child-element / self-closing formats: <ToolName>...</ToolName> or <ToolName ... />
+        # Only match tags whose names are in the known tool whitelist to avoid false positives
+        # on <env>, <tool_code>, or arbitrary HTML in model output.
+        if allowed_tool_names:
+            for name in allowed_tool_names:
+                if f"<{name}>" in content or f"<{name} " in content or f"<{name}/>" in content:
+                    return True
+        return False
+
+    for msg in reversed(messages):
+        text = _text_from_msg(msg)
+        if text and not _has_tool_calls(msg):
+            # 有文本且不是工具调度消息 — 这是真正的最终回复
+            return text
+
+    # 所有消息都是纯工具调度（或无文本），返回空串
+    return ""
+
+
+def _resolve_subagent_model(ctx: SubagentContext, model: Any | None) -> Any:
+    if ctx.is_async:
+        raise RuntimeError(
+            "异步路径请调用 run_async_agent_lifecycle()，不要通过 run_subagent() 执行"
+        )
+    resolved_model = model if model is not None else ctx.model
+    if resolved_model is None:
+        raise ValueError("model is required for run_subagent")
+    return resolved_model
+
+
+def _build_graph_input_messages(initial_messages: list[Any]) -> list[Any]:
+    return [
+        HumanMessage(content=m["content"])
+        if isinstance(m, dict) and m.get("role") == "user"
+        else m
+        for m in initial_messages
+    ]
+
+
+def _emit_progress(
+    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    event: SubagentProgressEvent,
+) -> None:
+    if on_progress:
+        on_progress(event)
+
+
+def _handle_tool_start_event(
+    *,
+    ctx: SubagentContext,
+    event: dict[str, Any],
+    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    current_step: int,
+) -> tuple[int, str]:
+    next_step = current_step + 1
+    tool_name = event.get("name", "")
+    _emit_progress(
+        on_progress,
+        SubagentProgressEvent(
+            type="tool_use",
+            subagent_type=ctx.subagent_type,
+            agent_id=ctx.agent_id,
+            step=next_step,
+            tool_name=tool_name,
+            summary=f"calling {tool_name}",
+        ),
+    )
+    return next_step, tool_name
+
+
+def _handle_tool_end_event(
+    *,
+    ctx: SubagentContext,
+    event: dict[str, Any],
+    data: dict[str, Any],
+    transcript: SubagentTranscriptManager,
+    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    step: int,
+) -> None:
+    tool_name = event.get("name", "")
+    output = data.get("output")
+    output_str = str(output)[:500] if output is not None else ""
+    msg_dict = {"role": "tool", "tool_name": tool_name, "content": output_str}
+    transcript.append(msg_dict)
+    _emit_progress(
+        on_progress,
+        SubagentProgressEvent(
+            type="tool_result",
+            subagent_type=ctx.subagent_type,
+            agent_id=ctx.agent_id,
+            step=step,
+            tool_name=tool_name,
+            summary=output_str[:200],
+        ),
+    )
+
+
+def _handle_chat_model_end_event(
+    *,
+    ctx: SubagentContext,
+    data: dict[str, Any],
+    on_progress: Callable[[SubagentProgressEvent], None] | None,
+    collected_assistant_messages: list[Any],
+    total_steps: int,
+) -> int:
+    output = data.get("output")
+    if output is not None:
+        collected_assistant_messages.append(output)
+    has_tool_calls = bool(output is not None and getattr(output, "tool_calls", None))
+    if not has_tool_calls:
+        total_steps += 1
+        _emit_progress(
+            on_progress,
+            SubagentProgressEvent(
+                type="model_step",
+                subagent_type=ctx.subagent_type,
+                agent_id=ctx.agent_id,
+                step=total_steps,
+                summary="model responded",
+            ),
+        )
+    return total_steps
+
+
+def _handle_langgraph_end_event(
+    *,
+    data: dict[str, Any],
+    terminal_reason: str,
+    child_run_id: str | None,
+) -> tuple[str, str | None]:
+    output = data.get("output") or {}
+    if not isinstance(output, dict):
+        return terminal_reason, child_run_id
+    tr = output.get("terminal_reason")
+    if tr:
+        terminal_reason = str(tr)
+    if child_run_id is None:
+        child_run_id = output.get("_run_id")
+    return terminal_reason, child_run_id
+
+
+async def _collect_subagent_events(
+    *,
+    ctx: SubagentContext,
+    graph: Any,
+    graph_input: dict[str, Any],
+    run_tags: list[str],
+    transcript: SubagentTranscriptManager,
+    on_progress: Callable[[SubagentProgressEvent], None] | None,
+) -> _EventCollectionResult:
+    collected_assistant_messages: list[Any] = []
+    terminal_reason = "completed"
+    total_steps = 0
+    error_message = ""
+    last_tool_name = ""
+    child_run_id: str | None = None
+    tool_step = 0
+    try:
+        async for event in graph.astream_events(
+            graph_input,
+            config={"tags": run_tags, "recursion_limit": 9999},
+            version="v2",
+        ):
+            event_name = event.get("event", "")
+            data = event.get("data") or {}
+            if event_name == "on_tool_start":
+                tool_step, last_tool_name = _handle_tool_start_event(
+                    ctx=ctx,
+                    event=event,
+                    on_progress=on_progress,
+                    current_step=tool_step,
+                )
+            elif event_name == "on_tool_end":
+                _handle_tool_end_event(
+                    ctx=ctx,
+                    event=event,
+                    data=data,
+                    transcript=transcript,
+                    on_progress=on_progress,
+                    step=tool_step,
+                )
+            elif event_name == "on_chat_model_end":
+                total_steps = _handle_chat_model_end_event(
+                    ctx=ctx,
+                    data=data,
+                    on_progress=on_progress,
+                    collected_assistant_messages=collected_assistant_messages,
+                    total_steps=total_steps,
+                )
+            elif event_name == "on_chain_end" and event.get("name") == "LangGraph":
+                terminal_reason, child_run_id = _handle_langgraph_end_event(
+                    data=data,
+                    terminal_reason=terminal_reason,
+                    child_run_id=child_run_id,
+                )
+    except Exception as exc:
+        logger.warning(
+            "subagent astream_events error agent_id=%s: %s",
+            ctx.agent_id,
+            exc,
+            exc_info=True,
+        )
+        error_message = str(exc)
+        terminal_reason = "error"
+    return _EventCollectionResult(
+        collected_assistant_messages=collected_assistant_messages,
+        terminal_reason=terminal_reason,
+        total_steps=total_steps,
+        error_message=error_message,
+        last_tool_name=last_tool_name,
+        child_run_id=child_run_id,
+        tool_step=tool_step,
+    )
+
+
+def _build_subagent_result(
+    *,
+    ctx: SubagentContext,
+    collected: _EventCollectionResult,
+    transcript: SubagentTranscriptManager,
+    allowed_tool_names: set[str] | None,
+    on_progress: Callable[[SubagentProgressEvent], None] | None,
+) -> SubagentResult:
+    content = _extract_final_content(collected.collected_assistant_messages, allowed_tool_names)
+    status = "error" if collected.terminal_reason == "error" else "completed"
+    transcript.flush([_to_message_dict(m) for m in collected.collected_assistant_messages])
+    if not content and status == "completed":
+        diag = f"total_steps={collected.total_steps}"
+        if collected.last_tool_name:
+            diag += f" last_tool={collected.last_tool_name}"
+        diag += f" terminal_reason={collected.terminal_reason}"
+        logger.warning(
+            "subagent completed with no content agent_id=%s %s",
+            ctx.agent_id, diag,
+        )
+    _emit_progress(
+        on_progress,
+        SubagentProgressEvent(
+            type="completed",
+            subagent_type=ctx.subagent_type,
+            agent_id=ctx.agent_id,
+            step=collected.total_steps,
+            summary=content[:200] if content else "done",
+        ),
+    )
+    return SubagentResult(
+        agent_id=ctx.agent_id,
+        content=content,
+        status=status,
+        terminal_reason=collected.terminal_reason,
+        total_steps=collected.total_steps,
+        error_message=collected.error_message,
+        child_run_id=collected.child_run_id,
+    )
+
+
+async def run_subagent(
+    ctx: SubagentContext,
+    loader: Any,
+    model: Any | None = None,
+    on_progress: Callable[[SubagentProgressEvent], None] | None = None,
+    allowed_tool_names: set[str] | None = None,
+) -> SubagentResult:
+    """运行子 Agent（plain/fork 同步路径）。
+
+    Args:
+        ctx: 子 Agent 执行上下文
+        loader: 子会话 ToolRuntimeLoader
+        model: 语言模型（str 或 BaseChatModel），None 时继承 ctx.model
+        on_progress: 进度回调（Channel B），每个工具调用步骤触发
+        allowed_tool_names: 工具白名单，用于识别 XML 退化格式（如 <Read>...</Read>）
+
+    Returns:
+        SubagentResult
+
+    Raises:
+        RuntimeError: ctx.is_async=True 时（异步路径请调用 run_async_agent_lifecycle）
+        ValueError: model 与 ctx.model 均为 None 时
+
+    不变量：无论成功/失败，try/finally 确保 transcript.cleanup() 和
+            cleanup_subagent_context() 被调用。
+    """
+    resolved_model = _resolve_subagent_model(ctx, model)
+
+    store = InMemoryTranscriptStore()
+    transcript = SubagentTranscriptManager(
+        store=store,
+        agent_id=ctx.agent_id,
+        parent_agent_id=ctx.parent_agent_id,
+    )
+
+    try:
+        graph = create_subagent_graph(ctx=ctx, loader=loader, model=resolved_model)
+        input_messages = _build_graph_input_messages(ctx.initial_messages)
+        graph_input = {"messages": input_messages}
+        run_tags = [f"subagent:{ctx.subagent_type}", f"agent_id:{ctx.agent_id}"]
+        collected = await _collect_subagent_events(
+            ctx=ctx,
+            graph=graph,
+            graph_input=graph_input,
+            run_tags=run_tags,
+            transcript=transcript,
+            on_progress=on_progress,
+        )
+        return _build_subagent_result(
+            ctx=ctx,
+            collected=collected,
+            transcript=transcript,
+            allowed_tool_names=allowed_tool_names,
+            on_progress=on_progress,
+        )
+
+    finally:
+        transcript.cleanup()
+        cleanup_subagent_context(ctx)
+
+
+async def run_subagent_with_background_signal(
+    ctx: SubagentContext,
+    loader: Any,
+    model: Any | None = None,
+    on_progress: Callable[[SubagentProgressEvent], None] | None = None,
+    background_signal: asyncio.Event | None = None,
+    on_background_request: Callable[[SubagentContext], str] | None = None,
+    allowed_tool_names: set[str] | None = None,
+) -> SubagentResult | BackgroundLaunchedResult:
+    """同步执行中监听后台化信号（CC Promise.race 语义）。"""
+    agent_task = asyncio.create_task(
+        run_subagent(ctx=ctx, loader=loader, model=model, on_progress=on_progress, allowed_tool_names=allowed_tool_names)
+    )
+    if background_signal is None:
+        return await agent_task
+
+    signal_task = asyncio.create_task(background_signal.wait())
+    done, pending = await asyncio.wait(
+        {agent_task, signal_task},
+        return_when=asyncio.FIRST_COMPLETED,
+    )
+
+    if signal_task in done and signal_task.result():
+        agent_task.cancel()
+        for task in pending:
+            task.cancel()
+        if on_background_request is None:
+            raise RuntimeError("background signal received but no handler configured")
+        task_id = on_background_request(ctx)
+        return BackgroundLaunchedResult(
+            status="async_launched",
+            agent_id=ctx.agent_id,
+            task_id=task_id,
+        )
+
+    signal_task.cancel()
+    return await agent_task

langchain_agentx/loop/subagent/transcript.py

@@ -0,0 +1,172 @@
+"""Subagent Transcript 存储与管理
+
+职责：管理单个子会话 transcript 生命周期
+在整体链路中的位置：runner.py 构造 SubagentTranscriptManager → append/flush/cleanup
+CC 对照：src/agent/subagent/transcript.ts TranscriptStore 接口
+当前裁剪范围：v1 Protocol + 内存实现 + JSONL 文件后端
+"""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SubagentTranscriptStore(Protocol):
+    """Transcript 存储后端契约（可换实现：replay/内存/日志）"""
+
+    def write_transcript(
+        self,
+        agent_id: str,
+        messages: list[dict[str, Any]],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """写入完整 transcript"""
+        ...
+
+    def append_message(self, agent_id: str, message: dict[str, Any]) -> None:
+        """追加单条消息"""
+        ...
+
+    def read_transcript(self, agent_id: str) -> list[dict[str, Any]]:
+        """读取 transcript"""
+        ...
+
+    def cleanup_transcript(self, agent_id: str) -> None:
+        """清理 transcript"""
+        ...
+
+
+@dataclass
+class SubagentTranscriptManager:
+    """管理单个子会话 transcript 生命周期
+
+    协作者：依赖 SubagentTranscriptStore（注入）
+    不变量：flush() 必须在 cleanup() 之前调用
+    """
+    store: SubagentTranscriptStore
+    agent_id: str
+    parent_agent_id: str | None = None
+    _buffer: list[dict[str, Any]] = field(default_factory=list)
+
+    def append(self, message: dict[str, Any]) -> None:
+        """追加消息到缓冲区并写入 store"""
+        self._buffer.append(message)
+        self.store.append_message(self.agent_id, message)
+
+    def flush(self, final_messages: list[dict[str, Any]]) -> None:
+        """写入完整 transcript（含元数据）"""
+        metadata = {"parent_agent_id": self.parent_agent_id} if self.parent_agent_id else {}
+        self.store.write_transcript(self.agent_id, final_messages, metadata)
+
+    def cleanup(self) -> None:
+        """清理缓冲区与 store"""
+        self._buffer.clear()
+        self.store.cleanup_transcript(self.agent_id)
+
+
+class InMemoryTranscriptStore:
+    """内存实现（供单测与 stub 使用）"""
+
+    def __init__(self) -> None:
+        self._storage: dict[str, list[dict[str, Any]]] = {}
+
+    def write_transcript(
+        self,
+        agent_id: str,
+        messages: list[dict[str, Any]],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self._storage[agent_id] = messages.copy()
+
+    def append_message(self, agent_id: str, message: dict[str, Any]) -> None:
+        if agent_id not in self._storage:
+            self._storage[agent_id] = []
+        self._storage[agent_id].append(message)
+
+    def read_transcript(self, agent_id: str) -> list[dict[str, Any]]:
+        return self._storage.get(agent_id, [])
+
+    def cleanup_transcript(self, agent_id: str) -> None:
+        self._storage.pop(agent_id, None)
+
+
+class JsonlTranscriptStore:
+    """JSONL 文件实现（按 session/agent 隔离 transcript）。"""
+
+    def __init__(self, transcripts_dir: str | Path, session_id: str) -> None:
+        self._transcripts_dir = Path(transcripts_dir)
+        self._session_id = session_id
+
+    def write_transcript(
+        self,
+        agent_id: str,
+        messages: list[dict[str, Any]],
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        path = self._resolve_path(agent_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("w", encoding="utf-8") as handle:
+            for message in messages:
+                handle.write(self._encode_line(message))
+            if metadata:
+                handle.write(self._encode_line({"type": "metadata", **metadata}))
+
+    def append_message(self, agent_id: str, message: dict[str, Any]) -> None:
+        path = self._resolve_path(agent_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(self._encode_line(message))
+
+    def read_transcript(self, agent_id: str) -> list[dict[str, Any]]:
+        path = self._resolve_path(agent_id)
+        if not path.exists():
+            return []
+        messages: list[dict[str, Any]] = []
+        with path.open("r", encoding="utf-8") as handle:
+            for raw_line in handle:
+                decoded = self._decode_line(raw_line)
+                if decoded is None:
+                    continue
+                if decoded.get("type") == "metadata":
+                    continue
+                messages.append(decoded)
+        return messages
+
+    def read_transcript_after_last_boundary(self, agent_id: str) -> list[dict[str, Any]]:
+        """读取最后一个 compact_boundary 之后的消息（边界本身不返回）。"""
+        messages = self.read_transcript(agent_id)
+        last_boundary_index = -1
+        for idx, item in enumerate(messages):
+            if item.get("type") == "compact_boundary":
+                last_boundary_index = idx
+        if last_boundary_index < 0:
+            return messages
+        return messages[last_boundary_index + 1 :]
+
+    def cleanup_transcript(self, agent_id: str) -> None:
+        path = self._resolve_path(agent_id)
+        if path.exists():
+            path.unlink()
+        session_dir = path.parent
+        if session_dir.exists() and not any(session_dir.iterdir()):
+            session_dir.rmdir()
+
+    def _resolve_path(self, agent_id: str) -> Path:
+        return self._transcripts_dir / self._session_id / f"{agent_id}.jsonl"
+
+    def _encode_line(self, payload: dict[str, Any]) -> str:
+        return json.dumps(payload, ensure_ascii=False) + "\n"
+
+    def _decode_line(self, line: str) -> dict[str, Any] | None:
+        stripped = line.strip()
+        if stripped == "":
+            return None
+        try:
+            decoded = json.loads(stripped)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(decoded, dict):
+            return None
+        return decoded

langchain_agentx/memory/__init__.py

@@ -0,0 +1,2 @@
+"""memory — Agent 记忆能力包入口。"""
+

langchain_agentx/memory/instruction/__init__.py

@@ -0,0 +1,12 @@
+"""instruction memory — Layer 1 规则加载与提示词注入。"""
+
+from .types import ConditionalRule, InstructionMemoryConfig, LoadedRuleSet, RuleFile, RuleLayer
+
+__all__ = [
+    "RuleLayer",
+    "RuleFile",
+    "ConditionalRule",
+    "LoadedRuleSet",
+    "InstructionMemoryConfig",
+]
+