agstack 1.22.0__tar.gz → 1.23.0__tar.gz

{agstack-1.22.0 → agstack-1.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.22.0
+Version: 1.23.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.22.0 → agstack-1.23.0}/agstack/llm/flow/event.py

@@ -97,12 +97,12 @@ def run_error(*, message: str, code: str | None = None) -> dict[str, Any]:
 # ── Step ──
 
 
-def step_started(*, step_name: str) -> dict[str, Any]:
-    return _ev(EventType.STEP_STARTED, step_name=step_name)
+def step_started(*, step_name: str, step_id: str | None = None) -> dict[str, Any]:
+    return _ev(EventType.STEP_STARTED, step_name=step_name, step_id=step_id or str(uuid4()))
 
 
-def step_finished(*, step_name: str) -> dict[str, Any]:
-    return _ev(EventType.STEP_FINISHED, step_name=step_name)
+def step_finished(*, step_name: str, step_id: str) -> dict[str, Any]:
+    return _ev(EventType.STEP_FINISHED, step_name=step_name, step_id=step_id)
 
 
 # ── State ──

{agstack-1.22.0 → agstack-1.23.0}/agstack/llm/flow/flow.py

@@ -358,8 +358,19 @@ class Flow:
 
                 elif node_type in self._node_handlers:
                     handler = self._node_handlers[node_type]
-                    result = await handler.execute(node, context)
+                    try:
+                        result = await handler.execute(node, context)
+                    except Exception as e:
+                        iter_target = self._find_iterator_fallback(current_node_id)
+                        if iter_target:
+                            context.set_variable(f"_iter_{iter_target}_error", str(e))
+                            context.set_output(current_node_id, {"error": str(e)})
+                            context.set_variable("_prev_node_id", current_node_id)
+                            current_node_id = iter_target
+                            continue
+                        raise
                     context.set_output(current_node_id, result)
+                    context.set_variable("_prev_node_id", current_node_id)
                     current_node_id = self._resolve_next_node(current_node_id, context)
 
                 else:
@@ -370,7 +381,8 @@ 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}")
+        flow_sid = str(uuid4())
+        yield event.step_started(step_name=f"flow:{self.name}", step_id=flow_sid)
 
         try:
             if not self.edges:
@@ -386,7 +398,7 @@ class Flow:
             context.trace.finished_at = time.time()
             context.trace.total_usage = context.usage
 
-        yield event.step_finished(step_name=f"flow:{self.name}")
+        yield event.step_finished(step_name=f"flow:{self.name}", step_id=flow_sid)
 
     async def _stream_sequential(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
         """顺序流式执行"""
@@ -408,6 +420,18 @@ class Flow:
                 )
                 raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
 
+    def _find_iterator_fallback(self, source_id: str) -> str | None:
+        """查找从 source_id 出发指向 iterator 节点的 edge target"""
+        for edge in self.edges:
+            if edge.get("source") == source_id:
+                target_id: str | None = edge.get("target")
+                if not target_id:
+                    continue
+                target_node = self.get_node_config(target_id)
+                if target_node and target_node.get("type") == "iterator":
+                    return target_id
+        return None
+
     async def _stream_edge_driven(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
         """边驱动流式执行"""
         current_node_id: str | None = self.nodes[0]["id"] if self.nodes else None
@@ -437,7 +461,8 @@ class Flow:
                 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}")
+                msg_sid = str(uuid4())
+                step_evt = event.step_started(step_name=f"message:{current_node_id}", step_id=msg_sid)
                 step_evt["_node_id"] = current_node_id
                 step_evt["_label"] = msg_config.get("label")
                 step_evt["_echo"] = msg_config.get("echo", True)
@@ -454,7 +479,7 @@ class Flow:
                 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 = event.step_finished(step_name=f"message:{current_node_id}", step_id=msg_sid)
                 fin_evt["_node_id"] = current_node_id
                 fin_evt["_label"] = msg_config.get("label")
                 fin_evt["_echo"] = msg_config.get("echo", True)
@@ -469,15 +494,16 @@ class Flow:
 
                 context.trace.record_node_start(current_node_id, "parallel", inputs=config)
 
-                step_evt = event.step_started(step_name=f"parallel:{current_node_id}")
+                parallel_sid = str(uuid4())
+                step_evt = event.step_started(step_name=f"parallel:{current_node_id}", step_id=parallel_sid)
                 step_evt["_node_id"] = current_node_id
                 step_evt["_label"] = None
                 step_evt["_echo"] = False
                 yield step_evt
 
-                parallel_qid = context.trace._qualify_id(current_node_id)
+                _pqid: str = context.trace._qualify_id(current_node_id)
 
-                async def _exec_branch(branch_id: str, _parent_qid: str = parallel_qid) -> None:
+                async def _exec_branch(branch_id: str, parent_qid: str) -> None:
                     branch_node = self.get_node_config(branch_id)
                     if not branch_node:
                         return
@@ -491,7 +517,7 @@ class Flow:
                         branch_id,
                         branch_type,
                         inputs=branch_config.get("inputs", {}),
-                        parent_id=_parent_qid,
+                        parent_id=parent_qid,
                     )
                     context.current_node = branch_id
                     try:
@@ -502,7 +528,7 @@ class Flow:
                         context.trace.record_node_end(branch_id, error=str(e))
                         raise
 
-                await asyncio.gather(*[_exec_branch(bid) for bid in branches])
+                await asyncio.gather(*[_exec_branch(bid, _pqid) for bid in branches])
                 merged: dict[str, Any] = {}
                 for bid in branches:
                     branch_result = context.outputs.get(bid, {})
@@ -510,7 +536,7 @@ class Flow:
                         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 = event.step_finished(step_name=f"parallel:{current_node_id}", step_id=parallel_sid)
                 fin_evt["_node_id"] = current_node_id
                 fin_evt["_label"] = None
                 fin_evt["_echo"] = False
@@ -533,7 +559,8 @@ class Flow:
 
                 context.trace.record_node_start(current_node_id, "iteration", inputs=config)
 
-                step_evt = event.step_started(step_name=f"iteration:{current_node_id}")
+                iter_sid = str(uuid4())
+                step_evt = event.step_started(step_name=f"iteration:{current_node_id}", step_id=iter_sid)
                 step_evt["_node_id"] = current_node_id
                 step_evt["_label"] = None
                 step_evt["_echo"] = False
@@ -574,7 +601,7 @@ class Flow:
                 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 = event.step_finished(step_name=f"iteration:{current_node_id}", step_id=iter_sid)
                 fin_evt["_node_id"] = current_node_id
                 fin_evt["_label"] = None
                 fin_evt["_echo"] = False
@@ -596,8 +623,20 @@ class Flow:
                     label=config.get("label"),
                 )
 
-                async for evt in self._execute_node_with_retry(node, context, current_node_id):
-                    yield evt
+                try:
+                    async for evt in self._execute_node_with_retry(node, context, current_node_id):
+                        yield evt
+                except (NodeExecutionError, Exception) as e:
+                    # 迭代体错误容忍：如果该节点有 edge 指向 iterator，路由回去而非中断 flow
+                    iter_target = self._find_iterator_fallback(current_node_id)
+                    if iter_target:
+                        context.set_variable(f"_iter_{iter_target}_error", str(e))
+                        context.set_output(current_node_id, {"error": str(e)})
+                        context.trace.record_node_end(current_node_id, error=str(e))
+                        context.set_variable("_prev_node_id", current_node_id)
+                        current_node_id = iter_target
+                        continue
+                    raise
 
                 # 收集 agent 节点存放的 tool_calls 或通用 execution_records
                 tool_calls = context.get_variable("_last_node_tool_calls")
@@ -618,6 +657,7 @@ class Flow:
                     tool_calls=tool_calls if tool_calls else None,
                     messages=messages,
                 )
+                context.set_variable("_prev_node_id", current_node_id)
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             else:

{agstack-1.22.0 → agstack-1.23.0}/agstack/llm/flow/nodes/__init__.py

@@ -6,6 +6,7 @@ from .agent_node import AgentNodeHandler
 from .base import NodeHandler
 from .detect_node import DetectNodeHandler
 from .echo_node import EchoNodeHandler
+from .iterator_node import IteratorNodeHandler
 from .llm_chat_node import LLMChatNodeHandler
 from .llm_embed_node import LLMEmbedNodeHandler
 from .llm_rerank_node import LLMRerankNodeHandler
@@ -27,6 +28,7 @@ builtin_handlers: list[NodeHandler] = [
     EchoNodeHandler(),
     SwitchNodeHandler(),
     SubflowNodeHandler(),
+    IteratorNodeHandler(),
 ]
 
 __all__ = [

{agstack-1.22.0 → agstack-1.23.0}/agstack/llm/flow/nodes/agent_node.py

@@ -3,6 +3,7 @@
 """Agent 节点处理器 — 从 flow.py 提取"""
 
 from typing import TYPE_CHECKING, Any, AsyncIterator
+from uuid import uuid4
 
 from .. import event
 from ..exceptions import FlowError
@@ -46,8 +47,9 @@ class AgentNodeHandler(NodeHandler):
     async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
         config = node.get("config", {})
         step_name = self.get_step_name(node, node_id)
+        sid = str(uuid4())
 
-        yield event.step_started(step_name=step_name)
+        yield event.step_started(step_name=step_name, step_id=sid)
         resolved = self.resolve_inputs(config, context)
         ag = self._create_agent(config, context)
         async for evt in ag.stream(context, inputs=resolved):
@@ -63,4 +65,4 @@ class AgentNodeHandler(NodeHandler):
         tool_calls = context.pop_execution_records()
         context.set_variable("_last_node_tool_calls", tool_calls)
 
-        yield event.step_finished(step_name=step_name)
+        yield event.step_finished(step_name=step_name, step_id=sid)

{agstack-1.22.0 → agstack-1.23.0}/agstack/llm/flow/nodes/base.py

@@ -3,6 +3,7 @@
 """NodeHandler 基类 — 所有执行类节点的公共接口"""
 
 from typing import TYPE_CHECKING, Any, AsyncIterator
+from uuid import uuid4
 
 from .. import event
 
@@ -45,7 +46,8 @@ class NodeHandler:
         需要流式输出的节点（如 agent, llm_chat）应覆盖此方法。
         """
         step_name = self.get_step_name(node, node_id)
-        yield event.step_started(step_name=step_name)
+        sid = str(uuid4())
+        yield event.step_started(step_name=step_name, step_id=sid)
         result = await self.execute(node, context)
         context.set_output(node_id, result)
-        yield event.step_finished(step_name=step_name)
+        yield event.step_finished(step_name=step_name, step_id=sid)

{agstack-1.22.0 → agstack-1.23.0}/agstack/llm/flow/nodes/echo_node.py

@@ -32,8 +32,9 @@ class EchoNodeHandler(NodeHandler):
     async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
         config = node.get("config", {})
         step_name = self.get_step_name(node, node_id)
+        sid = str(uuid4())
 
-        yield event.step_started(step_name=step_name)
+        yield event.step_started(step_name=step_name, step_id=sid)
 
         resolved = self.resolve_inputs(config, context)
         content = resolved.get("content", "")
@@ -51,4 +52,4 @@ class EchoNodeHandler(NodeHandler):
             yield event.text_message_end(message_id=msg_id)
 
         context.set_output(node_id, {"result": content})
-        yield event.step_finished(step_name=step_name)
+        yield event.step_finished(step_name=step_name, step_id=sid)

agstack-1.23.0/agstack/llm/flow/nodes/iterator_node.py

@@ -0,0 +1,172 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Iterator 节点处理器 — 通用迭代原语，管理遍历状态并通过 edge 组合实现路由"""
+
+from typing import TYPE_CHECKING, Any, AsyncIterator
+from uuid import uuid4
+
+from .. import event
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class IteratorNodeHandler(NodeHandler):
+    """Iterator 节点：管理数组遍历状态，暴露当前元素供下游引用，收集每轮结果。
+
+    通过 edge-driven 执行被多次访问：
+    - 首次访问：初始化迭代，暴露第一个元素，走迭代体 edge
+    - Cycle-back：收集上一轮结果，推进 index，继续或走 completion edge
+    """
+
+    node_type = "iterator"
+
+    def _resolve_items(self, config: dict, context: "FlowContext") -> list:
+        items_ref = config.get("items", "")
+        items = context.resolve_reference(items_ref) if isinstance(items_ref, str) else items_ref
+        if items is None:
+            return []
+        if not isinstance(items, list):
+            return [items]
+        return items
+
+    def _set_item_output(self, node_id: str, state: dict, config: dict, context: "FlowContext") -> None:
+        collect_to = config.get("collect_to", "results")
+        idx = state["index"]
+        context.set_output(
+            node_id,
+            {
+                "current_item": state["items"][idx],
+                "index": idx,
+                "count": len(state["items"]),
+                "done": False,
+                collect_to: list(state["collected"]),
+            },
+        )
+
+    def _set_done_output(self, node_id: str, state: dict, config: dict, context: "FlowContext") -> None:
+        collect_to = config.get("collect_to", "results")
+        context.set_output(
+            node_id,
+            {
+                "done": True,
+                "count": len(state["items"]),
+                collect_to: list(state["collected"]),
+            },
+        )
+
+    def _build_event(
+        self, config: dict, event_key: str, state: dict, *, error: str | None = None
+    ) -> dict[str, Any] | None:
+        events_config = config.get("events")
+        if not events_config:
+            return None
+        evt_cfg = events_config.get(event_key)
+        if not evt_cfg:
+            return None
+
+        name = evt_cfg.get("name", event_key)
+        value_template = evt_cfg.get("value", {})
+        value = self._interpolate_event_value(value_template, state, error=error)
+        return event.custom(name=name, value=value)
+
+    def _interpolate_event_value(self, template: Any, state: dict, *, error: str | None = None) -> Any:
+        if isinstance(template, str):
+            if template == "$index":
+                return state["index"]
+            if template == "$item":
+                return state["items"][state["index"]] if state["index"] < len(state["items"]) else None
+            if template == "$count":
+                return len(state["items"])
+            if template == "$error":
+                return error
+            return template
+        if isinstance(template, dict):
+            return {k: self._interpolate_event_value(v, state, error=error) for k, v in template.items()}
+        if isinstance(template, list):
+            return [self._interpolate_event_value(v, state, error=error) for v in template]
+        return template
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        items = self._resolve_items(config, context)
+        collect_to = config.get("collect_to", "results")
+        return {"done": True, "count": len(items), collect_to: [], "current_item": None, "index": 0}
+
+    async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
+        config = node.get("config", {})
+        state_key = f"_iter_{node_id}"
+        step_name = self.get_step_name(node, node_id)
+
+        state = context.get_variable(state_key)
+
+        if state is None:
+            # ═══ 首次访问：初始化 ═══
+            items = self._resolve_items(config, context)
+            state = {"items": items, "index": 0, "collected": []}
+            context.set_variable(state_key, state)
+
+            sid = str(uuid4())
+            yield event.step_started(step_name=step_name, step_id=sid)
+
+            evt = self._build_event(config, "on_start", state)
+            if evt:
+                yield evt
+
+            if not items:
+                self._set_done_output(node_id, state, config, context)
+                yield event.step_finished(step_name=step_name, step_id=sid)
+                return
+
+            self._set_item_output(node_id, state, config, context)
+            evt = self._build_event(config, "on_item_start", state)
+            if evt:
+                yield evt
+
+            yield event.step_finished(step_name=step_name, step_id=sid)
+
+        else:
+            # ═══ Cycle-back：收集 + 推进 ═══
+            sid = str(uuid4())
+            yield event.step_started(step_name=step_name, step_id=sid)
+
+            prev_node_id = context.get_variable("_prev_node_id")
+            error = context.get_variable(f"_iter_{node_id}_error")
+
+            if error:
+                state["collected"].append(
+                    {
+                        "error": error,
+                        "item": state["items"][state["index"]] if state["index"] < len(state["items"]) else None,
+                    }
+                )
+                evt = self._build_event(config, "on_item_error", state, error=error)
+                if evt:
+                    yield evt
+                context.set_variable(f"_iter_{node_id}_error", None)
+            else:
+                prev_output = context.outputs.get(prev_node_id) if prev_node_id else None
+                state["collected"].append(prev_output)
+                evt = self._build_event(config, "on_item_end", state)
+                if evt:
+                    yield evt
+
+            state["index"] += 1
+            max_iter = config.get("max_iterations")
+
+            if state["index"] >= len(state["items"]) or (max_iter and state["index"] >= max_iter):
+                self._set_done_output(node_id, state, config, context)
+                yield event.step_finished(step_name=step_name, step_id=sid)
+                return
+
+            self._set_item_output(node_id, state, config, context)
+            evt = self._build_event(config, "on_item_start", state)
+            if evt:
+                yield evt
+
+            yield event.step_finished(step_name=step_name, step_id=sid)
+
+    def get_step_name(self, node: dict, node_id: str) -> str:
+        return f"iterator:{node_id}"

{agstack-1.22.0 → agstack-1.23.0}/agstack/llm/flow/nodes/llm_chat_node.py

@@ -92,15 +92,17 @@ class LLMChatNodeHandler(NodeHandler):
         if not use_stream:
             # 非流式：走默认 execute 路径
             step_name = self.get_step_name(node, node_id)
-            yield event.step_started(step_name=step_name)
+            sid = str(uuid4())
+            yield event.step_started(step_name=step_name, step_id=sid)
             result = await self.execute(node, context)
             context.set_output(node_id, result)
-            yield event.step_finished(step_name=step_name)
+            yield event.step_finished(step_name=step_name, step_id=sid)
             return
 
         # 流式输出
         step_name = self.get_step_name(node, node_id)
-        yield event.step_started(step_name=step_name)
+        sid = str(uuid4())
+        yield event.step_started(step_name=step_name, step_id=sid)
 
         resolved_inputs = self.resolve_inputs(config, context)
         prompt_text = self._build_prompt(config.get("prompt", ""), resolved_inputs)
@@ -153,4 +155,4 @@ class LLMChatNodeHandler(NodeHandler):
         result_text = "".join(content_parts)
         context.set_output(node_id, {"result": result_text})
 
-        yield event.step_finished(step_name=step_name)
+        yield event.step_finished(step_name=step_name, step_id=sid)

{agstack-1.22.0 → agstack-1.23.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.22.0
+Version: 1.23.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.22.0 → agstack-1.23.0}/agstack.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ agstack/llm/flow/nodes/agent_node.py
 agstack/llm/flow/nodes/base.py
 agstack/llm/flow/nodes/detect_node.py
 agstack/llm/flow/nodes/echo_node.py
+agstack/llm/flow/nodes/iterator_node.py
 agstack/llm/flow/nodes/llm_chat_node.py
 agstack/llm/flow/nodes/llm_embed_node.py
 agstack/llm/flow/nodes/llm_rerank_node.py
@@ -70,6 +71,7 @@ agstack/security/crypt.py
 tests/test_cache_memory.py
 tests/test_cache_redis.py
 tests/test_flow_io.py
+tests/test_flow_iterator.py
 tests/test_flow_switch_subflow.py
 tests/test_messagebus_memory.py
 tests/test_messagebus_redis.py

{agstack-1.22.0 → agstack-1.23.0}/pyproject.toml

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

agstack-1.23.0/tests/test_flow_iterator.py

@@ -0,0 +1,501 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Iterator 节点及 Agent instructions 注入测试"""
+
+import asyncio
+
+from agstack.llm.flow.context import FlowContext
+from agstack.llm.flow.flow import Flow
+from agstack.llm.flow.nodes.iterator_node import IteratorNodeHandler
+from agstack.llm.flow.registry import registry
+from agstack.llm.flow.tool import Tool
+
+
+def run(coro):
+    return asyncio.get_event_loop().run_until_complete(coro)
+
+
+async def collect_events(flow: Flow, context: FlowContext) -> list[dict]:
+    events = []
+    async for evt in flow.stream(context):
+        events.append(evt)
+    return events
+
+
+# ── 辅助 mock tool ──
+
+
+def _echo_tool_fn(context, inputs):
+    return {"echo": inputs}
+
+
+def _failing_tool_fn(context, inputs):
+    raise RuntimeError("tool_failed")
+
+
+def setup_module():
+    """注册测试用 mock tools"""
+    registry.register_tool(
+        "test_echo",
+        Tool(name="test_echo", description="Echo inputs", function=_echo_tool_fn),
+    )
+    registry.register_tool(
+        "test_fail",
+        Tool(name="test_fail", description="Always fails", function=_failing_tool_fn),
+    )
+
+
+# ── IteratorNodeHandler 单元测试 ──
+
+
+class TestIteratorNodeHandler:
+    """iterator 节点处理器单元测试"""
+
+    def setup_method(self):
+        self.handler = IteratorNodeHandler()
+
+    def test_resolve_items_from_variable(self):
+        ctx = FlowContext(variables={"tasks": [{"type": "a"}, {"type": "b"}]})
+        config = {"items": "$v.tasks"}
+        items = self.handler._resolve_items(config, ctx)
+        assert items == [{"type": "a"}, {"type": "b"}]
+
+    def test_resolve_items_from_output(self):
+        ctx = FlowContext()
+        ctx.set_output("planner", {"tasks": [1, 2, 3]})
+        config = {"items": "$o.planner.tasks"}
+        items = self.handler._resolve_items(config, ctx)
+        assert items == [1, 2, 3]
+
+    def test_resolve_items_none_returns_empty(self):
+        ctx = FlowContext()
+        config = {"items": "$v.missing"}
+        items = self.handler._resolve_items(config, ctx)
+        assert items == []
+
+    def test_resolve_items_non_list_wraps(self):
+        ctx = FlowContext(variables={"single": "value"})
+        config = {"items": "$v.single"}
+        items = self.handler._resolve_items(config, ctx)
+        assert items == ["value"]
+
+    def test_set_item_output(self):
+        ctx = FlowContext()
+        state = {"items": ["a", "b", "c"], "index": 1, "collected": ["prev"]}
+        self.handler._set_item_output("loop", state, {"collect_to": "results"}, ctx)
+        output = ctx.outputs["loop"]
+        assert output["current_item"] == "b"
+        assert output["index"] == 1
+        assert output["count"] == 3
+        assert output["done"] is False
+        assert output["results"] == ["prev"]
+
+    def test_set_done_output(self):
+        ctx = FlowContext()
+        state = {"items": ["a", "b"], "index": 2, "collected": ["r1", "r2"]}
+        self.handler._set_done_output("loop", state, {"collect_to": "results"}, ctx)
+        output = ctx.outputs["loop"]
+        assert output["done"] is True
+        assert output["count"] == 2
+        assert output["results"] == ["r1", "r2"]
+
+    def test_build_event_with_interpolation(self):
+        config = {
+            "events": {
+                "on_start": {
+                    "name": "iteration_started",
+                    "value": {"total": "$count", "first": "$item"},
+                }
+            }
+        }
+        state = {"items": ["x", "y", "z"], "index": 0, "collected": []}
+        evt = self.handler._build_event(config, "on_start", state)
+        assert evt is not None
+        assert evt["type"] == "CUSTOM"
+        assert evt["name"] == "iteration_started"
+        assert evt["value"]["total"] == 3
+        assert evt["value"]["first"] == "x"
+
+    def test_build_event_missing_config_returns_none(self):
+        evt = self.handler._build_event({}, "on_start", {"items": [], "index": 0, "collected": []})
+        assert evt is None
+
+    def test_execute_returns_done(self):
+        """execute() 返回 done 状态（用于非 edge-driven 场景）"""
+        ctx = FlowContext(variables={"items": [1, 2, 3]})
+        node = {"id": "loop", "type": "iterator", "config": {"items": "$v.items"}}
+        result = run(self.handler.execute(node, ctx))
+        assert result["done"] is True
+        assert result["count"] == 3
+
+
+# ── Flow 集成测试：基本迭代 ──
+
+
+class TestIteratorFlowIntegration:
+    """iterator 节点 + edge-driven flow 集成测试"""
+
+    def test_basic_iteration(self):
+        """遍历 3 个 items，每轮调用 echo tool，收集结果"""
+        flow = Flow(
+            flow_id="test",
+            name="iter_test",
+            nodes=[
+                {
+                    "id": "loop",
+                    "type": "iterator",
+                    "config": {
+                        "items": "$v.tasks",
+                        "collect_to": "results",
+                    },
+                },
+                {
+                    "id": "do_work",
+                    "type": "tool",
+                    "config": {
+                        "tool_name": "test_echo",
+                        "inputs": {"query": "$o.loop.current_item"},
+                    },
+                },
+                {
+                    "id": "done_node",
+                    "type": "python",
+                    "config": {
+                        "code": "def main():\n    return {'status': 'done'}",
+                    },
+                },
+            ],
+            edges=[
+                {"source": "loop", "target": "do_work"},
+                {"source": "do_work", "target": "loop"},
+                {"source": "loop", "target": "done_node", "condition": "$o.loop.done"},
+            ],
+        )
+        ctx = FlowContext(variables={"tasks": ["task_a", "task_b", "task_c"]})
+        run(collect_events(flow, ctx))
+
+        # 验证迭代完成
+        loop_output = ctx.outputs["loop"]
+        assert loop_output["done"] is True
+        assert loop_output["count"] == 3
+        assert len(loop_output["results"]) == 3
+
+        # 验证每轮结果是 echo tool 的输出
+        for i, result in enumerate(loop_output["results"]):
+            assert result == {"echo": {"query": f"task_{chr(ord('a') + i)}"}}
+
+    def test_empty_items_goes_to_completion(self):
+        """空数组直接走 completion edge"""
+        flow = Flow(
+            flow_id="test",
+            name="iter_empty",
+            nodes=[
+                {
+                    "id": "loop",
+                    "type": "iterator",
+                    "config": {"items": "$v.tasks", "collect_to": "results"},
+                },
+                {"id": "body", "type": "tool", "config": {"tool_name": "test_echo", "inputs": {}}},
+                {
+                    "id": "end",
+                    "type": "python",
+                    "config": {"code": "def main():\n    return {'status': 'done'}"},
+                },
+            ],
+            edges=[
+                {"source": "loop", "target": "body"},
+                {"source": "body", "target": "loop"},
+                {"source": "loop", "target": "end", "condition": "$o.loop.done"},
+            ],
+        )
+        ctx = FlowContext(variables={"tasks": []})
+        run(collect_events(flow, ctx))
+
+        loop_output = ctx.outputs["loop"]
+        assert loop_output["done"] is True
+        assert loop_output["results"] == []
+        # end 节点应该被执行
+        assert "end" in ctx.outputs
+
+    def test_max_iterations_truncates(self):
+        """max_iterations 截断循环"""
+        flow = Flow(
+            flow_id="test",
+            name="iter_max",
+            nodes=[
+                {
+                    "id": "loop",
+                    "type": "iterator",
+                    "config": {
+                        "items": "$v.tasks",
+                        "collect_to": "results",
+                        "max_iterations": 2,
+                    },
+                },
+                {
+                    "id": "body",
+                    "type": "tool",
+                    "config": {"tool_name": "test_echo", "inputs": {"x": "$o.loop.current_item"}},
+                },
+                {
+                    "id": "end",
+                    "type": "python",
+                    "config": {"code": "def main():\n    return {'status': 'truncated'}"},
+                },
+            ],
+            edges=[
+                {"source": "loop", "target": "body"},
+                {"source": "body", "target": "loop"},
+                {"source": "loop", "target": "end", "condition": "$o.loop.done"},
+            ],
+        )
+        ctx = FlowContext(variables={"tasks": ["a", "b", "c", "d", "e"]})
+        run(collect_events(flow, ctx))
+
+        loop_output = ctx.outputs["loop"]
+        assert loop_output["done"] is True
+        assert len(loop_output["results"]) == 2
+
+    def test_error_tolerance(self):
+        """单项失败不中断循环，记录 error 后继续"""
+        flow = Flow(
+            flow_id="test",
+            name="iter_error",
+            nodes=[
+                {
+                    "id": "loop",
+                    "type": "iterator",
+                    "config": {"items": "$v.tasks", "collect_to": "results"},
+                },
+                {
+                    "id": "body",
+                    "type": "tool",
+                    "config": {"tool_name": "test_fail", "inputs": {}},
+                },
+                {
+                    "id": "end",
+                    "type": "python",
+                    "config": {"code": "def main():\n    return {'status': 'done'}"},
+                },
+            ],
+            edges=[
+                {"source": "loop", "target": "body"},
+                {"source": "body", "target": "loop"},
+                {"source": "loop", "target": "end", "condition": "$o.loop.done"},
+            ],
+        )
+        ctx = FlowContext(variables={"tasks": ["a", "b"]})
+        run(collect_events(flow, ctx))
+
+        loop_output = ctx.outputs["loop"]
+        assert loop_output["done"] is True
+        assert len(loop_output["results"]) == 2
+        # 每个结果都应该包含 error
+        for result in loop_output["results"]:
+            assert "error" in result
+
+    def test_custom_events_emitted(self):
+        """验证 CUSTOM 事件发射"""
+        flow = Flow(
+            flow_id="test",
+            name="iter_events",
+            nodes=[
+                {
+                    "id": "loop",
+                    "type": "iterator",
+                    "config": {
+                        "items": "$v.tasks",
+                        "collect_to": "results",
+                        "events": {
+                            "on_start": {"name": "loop_started", "value": {"total": "$count"}},
+                            "on_item_start": {"name": "item_begin", "value": {"idx": "$index"}},
+                            "on_item_end": {"name": "item_done", "value": {"idx": "$index"}},
+                        },
+                    },
+                },
+                {
+                    "id": "body",
+                    "type": "tool",
+                    "config": {"tool_name": "test_echo", "inputs": {}},
+                },
+                {
+                    "id": "end",
+                    "type": "python",
+                    "config": {"code": "def main():\n    return {'status': 'ok'}"},
+                },
+            ],
+            edges=[
+                {"source": "loop", "target": "body"},
+                {"source": "body", "target": "loop"},
+                {"source": "loop", "target": "end", "condition": "$o.loop.done"},
+            ],
+        )
+        ctx = FlowContext(variables={"tasks": ["x", "y"]})
+        events = run(collect_events(flow, ctx))
+
+        custom_events = [e for e in events if e.get("type") == "CUSTOM"]
+        custom_names = [e.get("name") for e in custom_events]
+
+        assert "loop_started" in custom_names
+        assert "item_begin" in custom_names
+        assert "item_done" in custom_names
+
+    def test_with_switch_routing(self):
+        """与 switch 节点组合实现按类型分发"""
+
+        # 注册两个不同的 tool
+        def tool_upper(context, inputs):
+            return {"result": inputs.get("text", "").upper()}
+
+        def tool_lower(context, inputs):
+            return {"result": inputs.get("text", "").lower()}
+
+        registry.register_tool(
+            "test_upper",
+            Tool(name="test_upper", description="Uppercase", function=tool_upper),
+        )
+        registry.register_tool(
+            "test_lower",
+            Tool(name="test_lower", description="Lowercase", function=tool_lower),
+        )
+
+        flow = Flow(
+            flow_id="test",
+            name="iter_switch",
+            nodes=[
+                {
+                    "id": "loop",
+                    "type": "iterator",
+                    "config": {"items": "$v.tasks", "collect_to": "results"},
+                },
+                {
+                    "id": "route",
+                    "type": "switch",
+                    "config": {
+                        "variable": "$o.loop.current_item.action",
+                        "cases": {"upper": "upper", "lower": "lower"},
+                    },
+                },
+                {
+                    "id": "do_upper",
+                    "type": "tool",
+                    "config": {
+                        "tool_name": "test_upper",
+                        "inputs": {"text": "$o.loop.current_item.text"},
+                    },
+                },
+                {
+                    "id": "do_lower",
+                    "type": "tool",
+                    "config": {
+                        "tool_name": "test_lower",
+                        "inputs": {"text": "$o.loop.current_item.text"},
+                    },
+                },
+                {
+                    "id": "end",
+                    "type": "python",
+                    "config": {"code": "def main():\n    return {'status': 'done'}"},
+                },
+            ],
+            edges=[
+                {"source": "loop", "target": "route"},
+                {"source": "route", "target": "do_upper", "condition": "$o.route.choice == upper"},
+                {"source": "route", "target": "do_lower", "condition": "$o.route.choice == lower"},
+                {"source": "do_upper", "target": "loop"},
+                {"source": "do_lower", "target": "loop"},
+                {"source": "loop", "target": "end", "condition": "$o.loop.done"},
+            ],
+        )
+        ctx = FlowContext(
+            variables={
+                "tasks": [
+                    {"action": "upper", "text": "hello"},
+                    {"action": "lower", "text": "WORLD"},
+                    {"action": "upper", "text": "foo"},
+                ]
+            }
+        )
+        run(collect_events(flow, ctx))
+
+        loop_output = ctx.outputs["loop"]
+        assert loop_output["done"] is True
+        assert loop_output["results"] == [
+            {"result": "HELLO"},
+            {"result": "world"},
+            {"result": "FOO"},
+        ]
+
+
+# ── Agent instructions 注入测试 ──
+
+
+class TestAgentInstructionsInjection:
+    """验证 Agent 节点 config.instructions 传递"""
+
+    def test_instructions_passthrough_via_kwargs(self):
+        """instructions 字段通过 _create_agent kwargs 机制传递到 Agent"""
+        from agstack.llm.flow.agent import Agent
+        from agstack.llm.flow.nodes.agent_node import AgentNodeHandler
+
+        # 注册一个测试 agent
+        class TestAgent(Agent):
+            def __init__(self, **kwargs):
+                super().__init__(name="test_agent", **kwargs)
+
+        registry.register_agent("test_agent", TestAgent)
+
+        handler = AgentNodeHandler()
+        ctx = FlowContext(variables={"custom_prompt": "You are a custom assistant."})
+        config = {
+            "agent_name": "test_agent",
+            "instructions": "$v.custom_prompt",
+            "inputs": {"input": "hello"},
+        }
+
+        agent = handler._create_agent(config, ctx)
+        assert agent.instructions == "You are a custom assistant."
+
+    def test_instructions_literal_string(self):
+        """instructions 字段为字面量字符串"""
+        from agstack.llm.flow.agent import Agent
+        from agstack.llm.flow.nodes.agent_node import AgentNodeHandler
+
+        class LiteralAgent(Agent):
+            def __init__(self, **kwargs):
+                super().__init__(name="literal_agent", **kwargs)
+
+        registry.register_agent("literal_agent", LiteralAgent)
+
+        handler = AgentNodeHandler()
+        ctx = FlowContext()
+        config = {
+            "agent_name": "literal_agent",
+            "instructions": "Be concise and direct.",
+            "inputs": {},
+        }
+
+        agent = handler._create_agent(config, ctx)
+        assert agent.instructions == "Be concise and direct."
+
+    def test_no_instructions_uses_default(self):
+        """不提供 instructions 时使用 Agent 默认值"""
+        from agstack.llm.flow.agent import Agent
+        from agstack.llm.flow.nodes.agent_node import AgentNodeHandler
+
+        class DefaultAgent(Agent):
+            def __init__(self, **kwargs):
+                kwargs.setdefault("instructions", "I am the default.")
+                super().__init__(name="default_agent", **kwargs)
+
+        registry.register_agent("default_agent", DefaultAgent)
+
+        handler = AgentNodeHandler()
+        ctx = FlowContext()
+        config = {
+            "agent_name": "default_agent",
+            "inputs": {},
+        }
+
+        agent = handler._create_agent(config, ctx)
+        assert agent.instructions == "I am the default."