agstack 1.18.0__tar.gz → 1.19.0__tar.gz

{agstack-1.18.0 → agstack-1.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.18.0
+Version: 1.19.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.18.0 → agstack-1.19.0}/agstack/llm/flow/__init__.py

@@ -23,6 +23,7 @@ from .records import Record, Status
 from .registry import registry
 from .state import FlowState
 from .tool import Tool, ToolResult
+from .trace import EdgeTrace, FlowTrace, NodeTrace
 
 
 register_node_handler = registry.register_node_handler
@@ -35,6 +36,10 @@ __all__ = [
     "Flow",
     "FlowContext",
     "Usage",
+    # 结构化执行轨迹
+    "FlowTrace",
+    "NodeTrace",
+    "EdgeTrace",
     # 节点处理器
     "NodeHandler",
     "register_node_handler",

{agstack-1.18.0 → agstack-1.19.0}/agstack/llm/flow/agent.py

@@ -264,17 +264,30 @@ class Agent:
                 # 执行工具（传入 LLM 解析的参数作为 inputs）
                 result = await tool.execute_async(context, tool_args)
 
-                # 保存工具结果
-                result_content = json.dumps(result.result) if result.success else json.dumps({"error": result.error})
+                # 使用 result.content 作为 LLM 上下文（Tool 已计算好）
+                result_content = result.content or (
+                    json.dumps(result.result) if result.success else json.dumps({"error": result.error})
+                )
                 context.add_message(self.name, "tool", content=result_content, tool_call_id=tool_call["id"])
 
                 # AG-UI: TOOL_CALL_RESULT
                 yield event.tool_call_result(tool_call_id=tool_call["id"], content=result_content)
 
-                # 可观测性：yield tool 执行记录
-                for record in context.pop_execution_records():
-                    record["tool_call_id"] = tool_call["id"]
-                    yield event.custom(name="tool_execution", value=record)
+                # 实时用户进度 — 有 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
 
             # 更新消息列表，继续下一轮
             messages = [self.get_system_message()] + context.history + context.get_messages(self.name)

{agstack-1.18.0 → agstack-1.19.0}/agstack/llm/flow/context.py

@@ -5,10 +5,14 @@
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
 
+if TYPE_CHECKING:
+    from .trace import FlowTrace
+
+
 @dataclass
 class Usage:
     """Token 使用统计"""
@@ -56,6 +60,18 @@ class FlowContext:
     # 执行记录（可选）
     execution_records: list[dict[str, Any]] = field(default_factory=list)
 
+    # 结构化执行轨迹
+    trace: "FlowTrace" = field(default=None, repr=False)  # type: ignore[assignment]
+
+    # 业务自定义事件缓冲（tool 内部通过 context 注入，agent 循环中 flush）
+    pending_custom_events: list[dict[str, Any]] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.trace is None:
+            from .trace import FlowTrace
+
+            self.trace = FlowTrace()
+
     def get_variable(self, key: str, default: Any = None) -> Any:
         """获取变量值"""
         return self.variables.get(key, default)
@@ -157,3 +173,9 @@ class FlowContext:
         records = self.execution_records
         self.execution_records = []
         return records
+
+    def pop_pending_custom_events(self) -> list[dict[str, Any]]:
+        """取出并清空待发射的业务自定义事件"""
+        events = self.pending_custom_events
+        self.pending_custom_events = []
+        return events

{agstack-1.18.0 → agstack-1.19.0}/agstack/llm/flow/flow.py

@@ -3,6 +3,7 @@
 """Flow 定义和执行"""
 
 import asyncio
+import time
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
@@ -127,8 +128,27 @@ class Flow:
             cond = edge.get("condition")
             if cond is None:
                 fallback_target = edge.get("target")
-            elif not force_fallback and self._eval_condition(cond, context):
-                return edge.get("target")
+            elif not force_fallback:
+                satisfied = self._eval_condition(cond, context)
+                context.trace.record_edge(
+                    current_id,
+                    edge.get("target"),
+                    condition=cond,
+                    condition_value=satisfied,
+                    satisfied=satisfied,
+                )
+                if satisfied:
+                    return edge.get("target")
+
+        # 记录最终选中的 fallback 边
+        if fallback_target is not None:
+            context.trace.record_edge(
+                current_id,
+                fallback_target,
+                condition=None,
+                condition_value=None,
+                satisfied=True,
+            )
         return fallback_target
 
     # ── message 节点 ──
@@ -349,16 +369,22 @@ class Flow:
 
     async def stream(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
         """流式执行 Flow（输出 AG-UI 标准事件）"""
+        context.trace.started_at = time.time()
         yield event.step_started(step_name=f"flow:{self.name}")
 
-        if not self.edges:
-            # 向后兼容：无 edges 时按 nodes 列表顺序执行（原有逻辑）
-            async for evt in self._stream_sequential(context):
-                yield evt
-        else:
-            # edge 驱动执行
-            async for evt in self._stream_edge_driven(context):
-                yield evt
+        try:
+            if not self.edges:
+                async for evt in self._stream_sequential(context):
+                    yield evt
+            else:
+                async for evt in self._stream_edge_driven(context):
+                    yield evt
+        except Exception as e:
+            context.trace.error = str(e)
+            raise
+        finally:
+            context.trace.finished_at = time.time()
+            context.trace.total_usage = context.usage
 
         yield event.step_finished(step_name=f"flow:{self.name}")
 
@@ -408,32 +434,73 @@ class Flow:
 
             if node_type == "message":
                 msg_config = node.get("config", {})
+                context.trace.record_node_start(current_node_id, "message", inputs=msg_config)
+
+                # message 节点增加 STEP 事件
+                step_evt = event.step_started(step_name=f"message:{current_node_id}")
+                step_evt["_node_id"] = current_node_id
+                step_evt["_label"] = msg_config.get("label")
+                step_evt["_echo"] = msg_config.get("echo", True)
+                yield step_evt
+
                 async for evt in self._emit_message(node, context):
                     evt["_node_id"] = current_node_id
                     evt["_label"] = msg_config.get("label")
                     evt["_echo"] = msg_config.get("echo", True)
                     yield evt
+
+                # 存储 message 输出
+                template = msg_config.get("content", "")
+                text = template.format_map(_SafeFormatDict(context.variables))
+                context.set_output(current_node_id, {"result": text})
+
+                fin_evt = event.step_finished(step_name=f"message:{current_node_id}")
+                fin_evt["_node_id"] = current_node_id
+                fin_evt["_label"] = msg_config.get("label")
+                fin_evt["_echo"] = msg_config.get("echo", True)
+                yield fin_evt
+
+                context.trace.record_node_end(current_node_id, outputs={"result": text})
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type == "parallel":
                 config = node.get("config", {})
                 branches = config.get("branches", [])
+
+                context.trace.record_node_start(current_node_id, "parallel", inputs=config)
+
                 step_evt = event.step_started(step_name=f"parallel:{current_node_id}")
                 step_evt["_node_id"] = current_node_id
                 step_evt["_label"] = None
                 step_evt["_echo"] = False
                 yield step_evt
 
-                async def _exec_branch(branch_id: str) -> None:
+                parallel_qid = context.trace._qualify_id(current_node_id)
+
+                async def _exec_branch(branch_id: str, _parent_qid: str = parallel_qid) -> None:
                     branch_node = self.get_node_config(branch_id)
                     if not branch_node:
                         return
-                    context.current_node = branch_id
                     branch_type = branch_node.get("type", "")
+                    branch_config = branch_node.get("config", {})
                     branch_handler = self._node_handlers.get(branch_type)
-                    if branch_handler:
+                    if not branch_handler:
+                        return
+
+                    context.trace.record_node_start(
+                        branch_id,
+                        branch_type,
+                        inputs=branch_config.get("inputs", {}),
+                        parent_id=_parent_qid,
+                    )
+                    context.current_node = branch_id
+                    try:
                         result = await branch_handler.execute(branch_node, context)
                         context.set_output(branch_id, result)
+                        context.trace.record_node_end(branch_id, outputs=result)
+                    except Exception as e:
+                        context.trace.record_node_end(branch_id, error=str(e))
+                        raise
 
                 await asyncio.gather(*[_exec_branch(bid) for bid in branches])
                 merged: dict[str, Any] = {}
@@ -442,11 +509,14 @@ class Flow:
                     if isinstance(branch_result, dict):
                         merged.update(branch_result)
                 context.set_output(current_node_id, merged)
+
                 fin_evt = event.step_finished(step_name=f"parallel:{current_node_id}")
                 fin_evt["_node_id"] = current_node_id
                 fin_evt["_label"] = None
                 fin_evt["_echo"] = False
                 yield fin_evt
+
+                context.trace.record_node_end(current_node_id, outputs=merged)
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type == "iteration":
@@ -461,11 +531,14 @@ class Flow:
                 body_nodes: list[str] = config.get("body", [])
                 results: list[Any] = []
 
+                context.trace.record_node_start(current_node_id, "iteration", inputs=config)
+
                 step_evt = event.step_started(step_name=f"iteration:{current_node_id}")
                 step_evt["_node_id"] = current_node_id
                 step_evt["_label"] = None
                 step_evt["_echo"] = False
                 yield step_evt
+
                 for idx, item in enumerate(items):
                     context.set_variable(item_var, item)
                     context.set_variable(index_var, idx)
@@ -474,24 +547,77 @@ class Flow:
                         if not body_node:
                             continue
                         body_type = body_node.get("type", "")
+                        body_config = body_node.get("config", {})
                         body_handler = self._node_handlers.get(body_type)
-                        if body_handler:
-                            body_result = await body_handler.execute(body_node, context)
-                            context.set_output(body_node_id, body_result)
+                        if not body_handler:
+                            continue
+
+                        context.trace.record_node_start(
+                            body_node_id,
+                            body_type,
+                            inputs=body_config.get("inputs", {}),
+                            parent_id=context.trace._qualify_id(current_node_id),
+                            iteration_index=idx,
+                        )
+                        body_result = await body_handler.execute(body_node, context)
+                        context.set_output(body_node_id, body_result)
+                        # 收集 body 节点产生的 execution_records
+                        body_tool_calls = context.pop_execution_records()
+                        context.trace.record_node_end(
+                            body_node_id,
+                            outputs=body_result,
+                            tool_calls=body_tool_calls if body_tool_calls else None,
+                        )
                     if body_nodes:
                         results.append(context.outputs.get(body_nodes[-1]))
 
-                context.set_output(current_node_id, {"results": results})
+                iteration_output = {"results": results}
+                context.set_output(current_node_id, iteration_output)
+
                 fin_evt = event.step_finished(step_name=f"iteration:{current_node_id}")
                 fin_evt["_node_id"] = current_node_id
                 fin_evt["_label"] = None
                 fin_evt["_echo"] = False
                 yield fin_evt
+
+                context.trace.record_node_end(current_node_id, outputs=iteration_output)
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type in self._node_handlers:
+                # 获取 resolved inputs 用于 trace
+                config = node.get("config", {})
+                handler = self._node_handlers[node_type]
+                resolved_inputs = handler.resolve_inputs(config, context)
+
+                context.trace.record_node_start(
+                    current_node_id,
+                    node_type,
+                    inputs=resolved_inputs,
+                    label=config.get("label"),
+                )
+
                 async for evt in self._execute_node_with_retry(node, context, current_node_id):
                     yield evt
+
+                # 收集 agent 节点存放的 tool_calls 或通用 execution_records
+                tool_calls = context.get_variable("_last_node_tool_calls")
+                if tool_calls is None:
+                    tool_calls = context.pop_execution_records() or None
+                else:
+                    context.set_variable("_last_node_tool_calls", None)
+
+                # 获取可选的 messages（agent 节点）
+                messages = None
+                if node_type == "agent" and context.get_variable("_capture_messages"):
+                    agent_name = config.get("agent_name", "")
+                    messages = context.get_messages(agent_name) if agent_name else None
+
+                context.trace.record_node_end(
+                    current_node_id,
+                    outputs=context.outputs.get(current_node_id),
+                    tool_calls=tool_calls if tool_calls else None,
+                    messages=messages,
+                )
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             else:

{agstack-1.18.0 → agstack-1.19.0}/agstack/llm/flow/nodes/agent_node.py

@@ -58,4 +58,9 @@ class AgentNodeHandler(NodeHandler):
         else:
             result = context.get_last_output(ag.name) or ""
             context.set_output(node_id, {"result": result})
+
+        # 一次性收集累积的 tool 执行记录，供 flow 引擎存入 NodeTrace
+        tool_calls = context.pop_execution_records()
+        context.set_variable("_last_node_tool_calls", tool_calls)
+
         yield event.step_finished(step_name=step_name)

{agstack-1.18.0 → agstack-1.19.0}/agstack/llm/flow/nodes/base.py

@@ -48,9 +48,4 @@ class NodeHandler:
         yield event.step_started(step_name=step_name)
         result = await self.execute(node, context)
         context.set_output(node_id, result)
-
-        # 可观测性：drain tool 执行记录
-        for record in context.pop_execution_records():
-            yield event.custom(name="tool_execution", value=record)
-
         yield event.step_finished(step_name=step_name)

{agstack-1.18.0 → agstack-1.19.0}/agstack/llm/flow/nodes/subflow_node.py

@@ -67,8 +67,12 @@ class SubflowNodeHandler(NodeHandler):
         self._resolve_and_apply_inputs(config, context)
         sub_flow = self._load_subflow(config)
 
-        async for evt in sub_flow.stream(context):
-            yield evt
+        context.trace.push_namespace(node_id)
+        try:
+            async for evt in sub_flow.stream(context):
+                yield evt
+        finally:
+            context.trace.pop_namespace()
 
         result = self._get_last_node_output(sub_flow, context)
         context.set_output(node_id, result)

{agstack-1.18.0 → agstack-1.19.0}/agstack/llm/flow/tool.py

@@ -24,6 +24,8 @@ class ToolResult:
     result: dict[str, Any]
     success: bool
     error: str | None = None
+    content: str | None = None
+    summary: str | None = None
 
 
 class Tool:
@@ -38,6 +40,9 @@ class Tool:
         *,
         label: str | None = None,
         echo: bool = False,
+        category: str | None = None,
+        summary_fn: Callable[["ToolResult"], str | None] | None = None,
+        result_formatter: Callable[["ToolResult"], str] | None = None,
     ):
         """初始化工具
 
@@ -47,6 +52,9 @@ class Tool:
         :param parameters: JSON Schema 参数定义（用于 LLM 调用）
         :param label: 面向用户的展示名称（控制 STEP/TOOL_CALL 进度事件可见性）
         :param echo: 是否转发 TEXT_MESSAGE 给用户
+        :param category: 工具分类（retrieval / analysis / action / utility）
+        :param summary_fn: 生成面向用户摘要的函数 (ToolResult) -> str | None
+        :param result_formatter: 自定义 LLM 内容格式化函数 (ToolResult) -> str
         """
         self.name = name
         self.description = description
@@ -54,24 +62,45 @@ class Tool:
         self.parameters = parameters or {"type": "object", "properties": {}, "required": []}
         self.label = label
         self.echo = echo
+        self.category = category
+        self.summary_fn = summary_fn
+        self.result_formatter = result_formatter
 
     async def execute_async(self, context: "FlowContext", inputs: dict[str, Any] | None = None) -> ToolResult:
-        """异步执行工具（包含计时和可观测性记录）"""
+        """异步执行工具（包含计时、摘要生成、结果格式化、可观测性记录）"""
         args = inputs or {}
         _t0 = time.perf_counter()
         result = await self._execute(context, args)
         _duration_ms = int((time.perf_counter() - _t0) * 1000)
 
-        result_content = json.dumps(result.result) if result.success else json.dumps({"error": result.error})
-        context.execution_records.append({
-            "agent_call_id": context.get_variable("_agent_call_id"),
-            "tool_name": self.name,
-            "tool_args": args,
-            "success": result.success,
-            "result": result_content,
-            "error": result.error,
-            "duration_ms": _duration_ms,
-        })
+        # 计算 LLM 消费内容
+        if self.result_formatter:
+            try:
+                result.content = self.result_formatter(result)
+            except Exception:
+                result.content = json.dumps(result.result) if result.success else json.dumps({"error": result.error})
+        else:
+            result.content = json.dumps(result.result) if result.success else json.dumps({"error": result.error})
+
+        # 生成面向用户的摘要
+        if self.summary_fn:
+            try:
+                result.summary = self.summary_fn(result)
+            except Exception:
+                result.summary = None
+
+        context.execution_records.append(
+            {
+                "agent_call_id": context.get_variable("_agent_call_id"),
+                "tool_name": self.name,
+                "tool_args": args,
+                "success": result.success,
+                "result": result.content,
+                "error": result.error,
+                "duration_ms": _duration_ms,
+                "summary": result.summary,
+            }
+        )
 
         return result
 

agstack-1.19.0/agstack/llm/flow/trace.py

@@ -0,0 +1,142 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""结构化执行轨迹 — 与事件流独立，flow 执行完成后一次性可用"""
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from .context import Usage
+
+
+@dataclass
+class NodeTrace:
+    """单次节点执行记录"""
+
+    node_id: str
+    node_type: str
+    label: str | None = None
+
+    inputs: dict[str, Any] = field(default_factory=dict)
+    outputs: Any = None
+    error: str | None = None
+
+    started_at: float = field(default_factory=time.time)
+    finished_at: float | None = None
+    duration_ms: int | None = None
+
+    usage: Usage | None = None
+
+    parent_id: str | None = None
+    iteration_index: int | None = None
+    execution_index: int = 0
+
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    messages: list[dict[str, Any]] | None = None
+
+
+@dataclass
+class EdgeTrace:
+    """实际遍历的边"""
+
+    source: str
+    target: str | None = None
+    condition: str | None = None
+    condition_value: Any = None
+    satisfied: bool = True
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class FlowTrace:
+    """完整执行轨迹"""
+
+    nodes: list[NodeTrace] = field(default_factory=list)
+    edges: list[EdgeTrace] = field(default_factory=list)
+    total_usage: Usage = field(default_factory=Usage)
+    started_at: float | None = None
+    finished_at: float | None = None
+    error: str | None = None
+
+    _namespace_stack: list[str] = field(default_factory=list, repr=False)
+    _active_nodes: dict[str, NodeTrace] = field(default_factory=dict, repr=False)
+    _execution_counter: int = field(default=0, repr=False)
+
+    def push_namespace(self, parent_id: str) -> None:
+        self._namespace_stack.append(parent_id)
+
+    def pop_namespace(self) -> str:
+        return self._namespace_stack.pop()
+
+    def _qualify_id(self, node_id: str) -> str:
+        if self._namespace_stack:
+            return "::".join(self._namespace_stack) + "::" + node_id
+        return node_id
+
+    def record_node_start(
+        self,
+        node_id: str,
+        node_type: str,
+        inputs: dict[str, Any] | None = None,
+        *,
+        label: str | None = None,
+        parent_id: str | None = None,
+        iteration_index: int | None = None,
+    ) -> NodeTrace:
+        qid = self._qualify_id(node_id)
+        self._execution_counter += 1
+        trace = NodeTrace(
+            node_id=qid,
+            node_type=node_type,
+            label=label,
+            inputs=inputs or {},
+            parent_id=parent_id or (self._namespace_stack[-1] if self._namespace_stack else None),
+            iteration_index=iteration_index,
+            execution_index=self._execution_counter,
+        )
+        self.nodes.append(trace)
+        self._active_nodes[qid] = trace
+        return trace
+
+    def record_node_end(
+        self,
+        node_id: str,
+        outputs: Any = None,
+        *,
+        error: str | None = None,
+        usage: Usage | None = None,
+        tool_calls: list[dict[str, Any]] | None = None,
+        messages: list[dict[str, Any]] | None = None,
+    ) -> None:
+        qid = self._qualify_id(node_id)
+        trace = self._active_nodes.pop(qid, None)
+        if trace is None:
+            return
+        trace.outputs = outputs
+        trace.error = error
+        trace.finished_at = time.time()
+        trace.duration_ms = int((trace.finished_at - trace.started_at) * 1000)
+        trace.usage = usage
+        if tool_calls:
+            trace.tool_calls = tool_calls
+        if messages is not None:
+            trace.messages = messages
+
+    def record_edge(
+        self,
+        source: str,
+        target: str | None,
+        *,
+        condition: str | None = None,
+        condition_value: Any = None,
+        satisfied: bool = True,
+    ) -> None:
+        self.edges.append(
+            EdgeTrace(
+                source=self._qualify_id(source),
+                target=self._qualify_id(target) if target else None,
+                condition=condition,
+                condition_value=condition_value,
+                satisfied=satisfied,
+            )
+        )

{agstack-1.18.0 → agstack-1.19.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.18.0
+Version: 1.19.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.18.0 → agstack-1.19.0}/agstack.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ agstack/llm/flow/registry.py
 agstack/llm/flow/sandbox.py
 agstack/llm/flow/state.py
 agstack/llm/flow/tool.py
+agstack/llm/flow/trace.py
 agstack/llm/flow/nodes/__init__.py
 agstack/llm/flow/nodes/agent_node.py
 agstack/llm/flow/nodes/base.py

{agstack-1.18.0 → agstack-1.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agstack"
-version = "1.18.0"
+version = "1.19.0"
 description = "Production-ready toolkit for building FastAPI and LLM applications"
 readme = "README.md"
 license = "MIT"