agstack 1.25.1__tar.gz → 2.1.0__tar.gz

{agstack-1.25.1 → agstack-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.25.1
+Version: 2.1.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.25.1 → agstack-2.1.0}/agstack/llm/flow/__init__.py

@@ -22,7 +22,7 @@ from .nodes import NodeHandler
 from .records import Record, Status
 from .registry import registry
 from .state import FlowState
-from .tool import Tool, ToolResult
+from .tool import Deny, Tool, ToolHook, ToolResult
 from .trace import EdgeTrace, FlowTrace, NodeTrace
 
 
@@ -32,6 +32,8 @@ __all__ = [
     # 核心抽象
     "Tool",
     "ToolResult",
+    "ToolHook",
+    "Deny",
     "Agent",
     "Flow",
     "FlowContext",

{agstack-1.25.1 → agstack-2.1.0}/agstack/llm/flow/agent.py

@@ -2,6 +2,7 @@
 
 """Agent 定义和执行"""
 
+import asyncio
 import json
 from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
@@ -10,7 +11,7 @@ from ..client import get_llm_client
 from . import event
 from .context import Usage
 from .event import EventType
-from .exceptions import FlowError
+from .exceptions import AgentError, FlowError
 
 
 if TYPE_CHECKING:
@@ -32,6 +33,7 @@ class Agent:
         max_turns: int = 10,
         *,
         tool_choice: str = "auto",
+        on_max_turns: str = "finalize",
         label: str | None = None,
         echo: bool = False,
     ):
@@ -44,6 +46,7 @@ class Agent:
         :param temperature: 温度参数
         :param max_tokens: 最大 token 数
         :param max_turns: 最大轮次
+        :param on_max_turns: max_turns 耗尽时的行为，"finalize"（降级输出并标记 truncated）或 "error"（抛出异常）
         :param label: 面向用户的展示名称（控制 STEP 进度事件可见性）
         :param echo: 是否转发 TEXT_MESSAGE 给用户
         """
@@ -55,6 +58,7 @@ class Agent:
         self.max_tokens = max_tokens
         self.max_turns = max_turns
         self.tool_choice = tool_choice
+        self.on_max_turns = on_max_turns
         self.label = label
         self.echo = echo
 
@@ -73,6 +77,149 @@ class Agent:
                 return tool
         return None
 
+    def _group_tool_calls(self, tool_calls: list[dict[str, Any]]) -> list[list[dict[str, Any]]]:
+        """按声明分组：连续的 concurrency_safe 调用聚为一组并发执行，其余单独成组串行
+
+        未注册/未声明的工具一律按不安全处理（fail closed），
+        默认全 False 时每组恰好一个调用，行为与串行完全一致。
+        """
+        groups: list[list[dict[str, Any]]] = []
+        prev_safe = False
+        for tc in tool_calls:
+            tool = self.get_tool_by_name(tc["name"])
+            safe = bool(tool and tool.concurrency_safe)
+            if safe and prev_safe:
+                groups[-1].append(tc)
+            else:
+                groups.append([tc])
+            prev_safe = safe
+        return groups
+
+    async def _stream_tool_call(
+        self,
+        context: "FlowContext",
+        tool_call: dict[str, Any],
+        message_sink: list[dict[str, Any]] | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """执行单个 tool_call，yield 其 AG-UI 事件
+
+        tool 消息默认即时写回 context；并发分组执行时传入 message_sink 收集，
+        由调用方在组完成后按 tool_call 原始顺序统一写回
+        （OpenAI 协议要求 tool 消息与 assistant.tool_calls 顺序对应）。
+        """
+
+        def _emit_message(**kwargs: Any) -> None:
+            if message_sink is None:
+                context.add_message(self.name, "tool", **kwargs)
+            else:
+                message_sink.append(kwargs)
+
+        tool = self.get_tool_by_name(tool_call["name"])
+        if not tool:
+            error_content = json.dumps({"error": f"Tool not found: {tool_call['name']}"}, ensure_ascii=False)
+            _emit_message(content=error_content, tool_call_id=tool_call["id"])
+            # AG-UI: TOOL_CALL_RESULT (错误)
+            yield event.tool_call_result(tool_call_id=tool_call["id"], content=error_content)
+            return
+
+        # 解析 LLM 返回的工具参数；解析失败作为该次调用的失败反馈给模型，由模型自行重试
+        try:
+            tool_args = json.loads(tool_call["arguments"]) if tool_call["arguments"] else {}
+        except json.JSONDecodeError as e:
+            error_content = json.dumps(
+                {
+                    "error": f"Invalid tool arguments (JSON parse failed): {e}",
+                    "raw_arguments": tool_call["arguments"][:500],
+                },
+                ensure_ascii=False,
+            )
+            _emit_message(content=error_content, tool_call_id=tool_call["id"])
+            # AG-UI: TOOL_CALL_RESULT (错误)
+            yield event.tool_call_result(tool_call_id=tool_call["id"], content=error_content)
+            return
+
+        # 执行前进度事件
+        progress_label = tool.get_progress_label(tool_args)
+        if progress_label:
+            yield event.custom(
+                name="skill_progress",
+                value={
+                    "progressId": tool_call["id"],
+                    "description": progress_label,
+                    "status": "running",
+                },
+            )
+
+        # 执行工具（传入 LLM 解析的参数作为 inputs）
+        result = await tool.execute_async(context, tool_args)
+
+        # 执行后进度事件
+        if progress_label:
+            yield event.custom(
+                name="skill_progress",
+                value={
+                    "progressId": tool_call["id"],
+                    "status": "completed" if result.success else "failed",
+                },
+            )
+
+        # 使用 result.content 作为 LLM 上下文（Tool 已计算好）
+        result_content = result.content or (
+            json.dumps(result.result, ensure_ascii=False)
+            if result.success
+            else json.dumps({"error": result.error}, ensure_ascii=False)
+        )
+        _emit_message(content=result_content, tool_call_id=tool_call["id"], summary=result.summary)
+
+        # AG-UI: TOOL_CALL_RESULT
+        yield event.tool_call_result(tool_call_id=tool_call["id"], content=result_content)
+
+        # 实时用户进度 — 有 summary 时告知前端
+        if result.summary:
+            yield event.custom(
+                name="tool_progress",
+                value={
+                    "tool_call_id": tool_call["id"],
+                    "tool_name": result.name,
+                    "success": result.success,
+                    "summary": result.summary,
+                },
+            )
+
+        # 业务自定义事件 — flush pending
+        for pending_evt in context.pop_pending_custom_events():
+            yield pending_evt
+
+    async def _gather_tool_calls(
+        self, context: "FlowContext", group: list[dict[str, Any]]
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        """并发执行一组 concurrency_safe 的 tool_calls
+
+        返回 (按完成顺序展平的事件列表, 按原始顺序展平的 tool 消息 kwargs 列表)。
+        组内事件先缓冲、gather 结束后统一交调用方 yield，保证单 generator 语义；
+        单个调用的意外异常兜底转失败结果，不影响组内其它调用。
+        注意：并发期间 execution_records / pending_custom_events 的追加顺序不再确定。
+        """
+        event_buffers: list[list[dict[str, Any]]] = [[] for _ in group]
+        message_buffers: list[list[dict[str, Any]]] = [[] for _ in group]
+        finish_order: list[int] = []
+
+        async def _run_one(i: int, tc: dict[str, Any]) -> None:
+            try:
+                async for evt in self._stream_tool_call(context, tc, message_sink=message_buffers[i]):
+                    event_buffers[i].append(evt)
+            except Exception as e:
+                error_content = json.dumps({"error": str(e)}, ensure_ascii=False)
+                message_buffers[i].append({"content": error_content, "tool_call_id": tc["id"]})
+                event_buffers[i].append(event.tool_call_result(tool_call_id=tc["id"], content=error_content))
+            finally:
+                finish_order.append(i)
+
+        await asyncio.gather(*[_run_one(i, tc) for i, tc in enumerate(group)])
+        events = [evt for i in finish_order for evt in event_buffers[i]]
+        messages = [msg for msgs in message_buffers for msg in msgs]
+        return events, messages
+
     async def run(self, context: "FlowContext", inputs: dict[str, Any] | None = None) -> dict[str, Any]:
         """执行 Agent 逻辑"""
         content_parts = []
@@ -117,7 +264,15 @@ class Agent:
         client = get_llm_client()
 
         # Agent 循环
+        assistant_content = ""
         for _ in range(self.max_turns):
+            # 协作式取消检查点：不再开始新的 LLM 轮次
+            if context.is_cancelled:
+                if not context.get_variable("_cancel_emitted"):
+                    context.set_variable("_cancel_emitted", True)
+                    yield event.run_error(message="FLOW_CANCELLED", code="CANCELLED")
+                return
+
             context.increment_turn()
 
             # 调用模型
@@ -239,87 +394,41 @@ class Agent:
                 context.set_variable("_agent_call_id", None)
                 return
 
-            # 执行工具调用
-            for tool_call in tool_calls:
-                tool = self.get_tool_by_name(tool_call["name"])
-                if not tool:
-                    error_msg = f"Tool not found: {tool_call['name']}"
-                    context.add_message(
-                        self.name,
-                        "tool",
-                        content=json.dumps({"error": error_msg}, ensure_ascii=False),
-                        tool_call_id=tool_call["id"],
-                    )
-                    # AG-UI: TOOL_CALL_RESULT (错误)
-                    yield event.tool_call_result(
-                        tool_call_id=tool_call["id"],
-                        content=json.dumps({"error": error_msg}, ensure_ascii=False),
-                    )
-                    continue
-
-                # 解析 LLM 返回的工具参数
-                try:
-                    tool_args = json.loads(tool_call["arguments"]) if tool_call["arguments"] else {}
-                except json.JSONDecodeError:
-                    tool_args = {}
-
-                # 执行前进度事件
-                progress_label = tool.get_progress_label(tool_args)
-                if progress_label:
-                    yield event.custom(
-                        name="skill_progress",
-                        value={
-                            "progressId": tool_call["id"],
-                            "description": progress_label,
-                            "status": "running",
-                        },
-                    )
-
-                # 执行工具（传入 LLM 解析的参数作为 inputs）
-                result = await tool.execute_async(context, tool_args)
-
-                # 执行后进度事件
-                if progress_label:
-                    yield event.custom(
-                        name="skill_progress",
-                        value={
-                            "progressId": tool_call["id"],
-                            "status": "completed" if result.success else "failed",
-                        },
-                    )
-
-                # 使用 result.content 作为 LLM 上下文（Tool 已计算好）
-                result_content = result.content or (
-                    json.dumps(result.result, ensure_ascii=False)
-                    if result.success
-                    else json.dumps({"error": result.error}, ensure_ascii=False)
-                )
-                context.add_message(
-                    self.name,
-                    "tool",
-                    content=result_content,
-                    tool_call_id=tool_call["id"],
-                    summary=result.summary,
-                )
-
-                # AG-UI: TOOL_CALL_RESULT
-                yield event.tool_call_result(tool_call_id=tool_call["id"], content=result_content)
-
-                # 实时用户进度 — 有 summary 时告知前端
-                if result.summary:
-                    yield event.custom(
-                        name="tool_progress",
-                        value={
-                            "tool_call_id": tool_call["id"],
-                            "tool_name": result.name,
-                            "success": result.success,
-                            "summary": result.summary,
-                        },
-                    )
-
-                # 业务自定义事件 — flush pending
-                for pending_evt in context.pop_pending_custom_events():
-                    yield pending_evt
+            # 执行工具调用：连续的 concurrency_safe 调用聚组并发，其余保持串行（默认全串行）
+            for group in self._group_tool_calls(tool_calls):
+                # 协作式取消检查点：不再开始新的工具执行（不中断在途工具）
+                if context.is_cancelled:
+                    if not context.get_variable("_cancel_emitted"):
+                        context.set_variable("_cancel_emitted", True)
+                        yield event.run_error(message="FLOW_CANCELLED", code="CANCELLED")
+                    return
+
+                if len(group) == 1:
+                    # 串行路径：事件实时 yield，tool 消息即时写回
+                    async for evt in self._stream_tool_call(context, group[0]):
+                        yield evt
+                else:
+                    # 并发组：事件按完成顺序 yield，tool 消息按原始顺序写回
+                    group_events, group_messages = await self._gather_tool_calls(context, group)
+                    for evt in group_events:
+                        yield evt
+                    for msg in group_messages:
+                        context.add_message(self.name, "tool", **msg)
 
             # 更新消息列表，继续下一轮
             messages = [self.get_system_message()] + context.history + context.get_messages(self.name)
+
+        # max_turns 耗尽：必须显式收尾，禁止静默截断
+        if self.on_max_turns == "error":
+            error_msg = f"Agent {self.name} exceeded max_turns={self.max_turns}"
+            yield event.run_error(message=error_msg, code="AGENT_MAX_TURNS_EXCEEDED")
+            raise AgentError("AGENT_MAX_TURNS_EXCEEDED", 500, {"agent": self.name})
+
+        # finalize：最后一轮已生成的部分文本作为降级输出，带截断标记
+        yield event.custom(
+            name="agent_max_turns",
+            value={"agentName": self.name, "maxTurns": self.max_turns},
+        )
+        context.set_output(self.name, {"result": assistant_content, "truncated": True})
+        yield event.text_message_end(message_id=msg_id)
+        context.set_variable("_agent_call_id", None)

{agstack-1.25.1 → agstack-2.1.0}/agstack/llm/flow/context.py

@@ -2,6 +2,7 @@
 
 """统一的执行上下文"""
 
+import asyncio
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -66,6 +67,9 @@ class FlowContext:
     # 业务自定义事件缓冲（tool 内部通过 context 注入，agent 循环中 flush）
     pending_custom_events: list[dict[str, Any]] = field(default_factory=list)
 
+    # 协作式取消信号（不参与序列化，恢复即未取消）
+    _cancel_event: asyncio.Event = field(default_factory=asyncio.Event, repr=False)
+
     def __post_init__(self) -> None:
         if self.trace is None:
             from .trace import FlowTrace
@@ -80,6 +84,23 @@ class FlowContext:
         """设置变量值"""
         self.variables[key] = value
 
+    def pop_variable(self, key: str, default: Any = None) -> Any:
+        """取出并移除变量"""
+        return self.variables.pop(key, default)
+
+    def cancel(self) -> None:
+        """请求取消执行（幂等）
+
+        协作式取消：引擎在下一个检查点（节点执行前、agent 轮次开始、
+        tool_call 执行前）停止，不强杀在途的工具或 LLM 调用。
+        """
+        self._cancel_event.set()
+
+    @property
+    def is_cancelled(self) -> bool:
+        """是否已请求取消（长 I/O 工具可自查以提前返回）"""
+        return self._cancel_event.is_set()
+
     def update_variables(self, updates: dict[str, Any]) -> None:
         """批量更新变量"""
         self.variables.update(updates)