Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(pipeline): add new pipeline module and a `GoalPipeline` class (#2428)
DavdGaob182da398807
diff --git a/README.md b/README.mdindex 12cea1c62..209ac1ab0 100644--- a/README.md+++ b/README.md@@ -73,6 +73,8 @@ rather than constraining them with strict prompts and opinionated orchestrations## News<!-- BEGIN NEWS -->+- **[2026-08] `FEAT`:** Pipeline supported — run multiple agents by a fixed logic behind one event stream. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/pipeline) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/pipeline/overview)+- **[2026-08] `INTE`:** DingTalk channel supported. [Docs](https://docs.agentscope.io/latest/en/deploy/channel/dingtalk)- **[2026-08] `FEAT`:** Console supported — test and debug agents in the terminal. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/console) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/console)- **[2026-08] `INTE`:** Feishu (Lark) and Discord channels supported. [Feishu](https://docs.agentscope.io/latest/en/deploy/channel/feishu) | [Discord](https://docs.agentscope.io/latest/en/deploy/channel/discord)- **[2026-08] `FEAT`:** Channels supported — connect agents to IM platforms in agent service. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [Docs](https://docs.agentscope.io/latest/en/deploy/channel/overview)@@ -81,8 +83,6 @@ rather than constraining them with strict prompts and opinionated orchestrations- **[2026-07] `INTE`:** Daytona-based workspace/sandbox supported. [Docs](https://docs.agentscope.io/latest/en/building-blocks/workspace)- **[2026-07] `INTE`:** K8s, OpenSandbox-based workspace/sandbox supported. [Docs](https://docs.agentscope.io/latest/en/building-blocks/workspace)- **[2026-07] `INTE`:** ReMe long-term memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)-- **[2026-06] `FEAT`:** Agentic Memory supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory)-- **[2026-06] `FEAT`:** Distributed & Multi-Tenancy & Multi-Session RAG service supported. [Docs](https://docs.agentscope.io/latest/en/deploy/agent-team)<!-- END NEWS -->[More news →](./docs/NEWS.md)diff --git a/README_zh.md b/README_zh.mdindex 4d4cd1a40..9b7cfbe67 100644--- a/README_zh.md+++ b/README_zh.md@@ -72,6 +72,8 @@ AgentScope 的目标是充分发挥大模型的推理与工具调用能力,## 新闻<!-- BEGIN NEWS -->+- **[2026-08] `功能`:** 支持流水线 —— 按照固化逻辑运行多智能体,并向外提供统一接口。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/pipeline) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/pipeline/overview)+- **[2026-08] `集成`:** 支持钉钉(DingTalk)频道。[文档](https://docs.agentscope.io/latest/zh/deploy/channel/dingtalk)- **[2026-08] `功能`:** 支持 Console —— 在终端中测试与调试智能体。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/console) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/console)- **[2026-08] `集成`:** 支持飞书(Lark)与 Discord 频道。[飞书](https://docs.agentscope.io/latest/zh/deploy/channel/feishu) | [Discord](https://docs.agentscope.io/latest/zh/deploy/channel/discord)- **[2026-08] `功能`:** 支持消息频道 —— 将智能体接入即时通讯平台。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [文档](https://docs.agentscope.io/latest/zh/deploy/channel/overview)@@ -80,8 +82,6 @@ AgentScope 的目标是充分发挥大模型的推理与工具调用能力,- **[2026-07] `集成`:** 集成 Daytona 工作区/沙箱实现。 [文档](https://docs.agentscope.io/latest/en/building-blocks/workspace)- **[2026-07] `集成`:** 集成 K8s,OpenSandbox 工作区/沙箱实现。 [文档](https://docs.agentscope.io/latest/en/building-blocks/workspace)- **[2026-07] `集成`:** 集成 ReMe 长期记忆。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/reme) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)-- **[2026-06] `功能`:** 支持 Agentic Memory。 [样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/long_term_memory/agentic_memory) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory)-- **[2026-06] `功能`:** 支持分布式 & 多租户 & 多会话 RAG 服务。 [文档](https://docs.agentscope.io/latest/en/deploy/agent-team)<!-- END NEWS -->[更多新闻 →](./docs/NEWS_zh.md)diff --git a/docs/NEWS.md b/docs/NEWS.mdindex 015522270..c7b5b71fd 100644--- a/docs/NEWS.md+++ b/docs/NEWS.md@@ -2,6 +2,8 @@<!-- The first 10 items are automatically synced to README.md and README_zh.md via GitHub Actions. --><!-- To update news in READMEs, modify this file and push to trigger the workflow. -->+- **[2026-08] `FEAT`:** Pipeline supported — run multiple agents by a fixed logic behind one event stream. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/pipeline) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/pipeline/overview)+- **[2026-08] `INTE`:** DingTalk channel supported. [Docs](https://docs.agentscope.io/latest/en/deploy/channel/dingtalk)- **[2026-08] `FEAT`:** Console supported — test and debug agents in the terminal. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/console) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/console)- **[2026-08] `INTE`:** Feishu (Lark) and Discord channels supported. [Feishu](https://docs.agentscope.io/latest/en/deploy/channel/feishu) | [Discord](https://docs.agentscope.io/latest/en/deploy/channel/discord)- **[2026-08] `FEAT`:** Channels supported — connect agents to IM platforms in agent service. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [Docs](https://docs.agentscope.io/latest/en/deploy/channel/overview)diff --git a/docs/NEWS_zh.md b/docs/NEWS_zh.mdindex c4078c52f..148c5bd35 100644--- a/docs/NEWS_zh.md+++ b/docs/NEWS_zh.md@@ -2,6 +2,8 @@<!-- The first 10 items are automatically synced to README.md and README_zh.md via GitHub Actions. --><!-- To update news in READMEs, modify this file and push to trigger the workflow. -->+- **[2026-08] `功能`:** 支持流水线 —— 按照固化逻辑运行多智能体,并向外提供统一接口。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/pipeline) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/pipeline/overview)+- **[2026-08] `集成`:** 支持钉钉(DingTalk)频道。[文档](https://docs.agentscope.io/latest/zh/deploy/channel/dingtalk)- **[2026-08] `功能`:** 支持 Console —— 在终端中测试与调试智能体。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/console) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/console)- **[2026-08] `集成`:** 支持飞书(Lark)与 Discord 频道。[飞书](https://docs.agentscope.io/latest/zh/deploy/channel/feishu) | [Discord](https://docs.agentscope.io/latest/zh/deploy/channel/discord)- **[2026-08] `功能`:** 支持消息频道 —— 将智能体接入即时通讯平台。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) | [文档](https://docs.agentscope.io/latest/zh/deploy/channel/overview)diff --git a/examples/pipeline/goal/README.md b/examples/pipeline/goal/README.mdnew file mode 100644index 000000000..baf76a08a--- /dev/null+++ b/examples/pipeline/goal/README.md@@ -0,0 +1,46 @@+# Goal Pipeline++This example demonstrates `agentscope.pipeline.GoalPipeline`: run one+agent until a second agent agrees the goal has been reached.++## What the demo shows++`goal_pipeline.py` builds two agents over a shared `LocalWorkspace` and+loops them:++- **Executor** — writes the code, using the workspace's filesystem+ tools.+- **Verifier** — an ordinary `Agent`, not a special kind of object. Its+ verdict comes from structured output (`passed` plus a `message`+ explaining what is missing), so a check that has to read files or run+ commands does it with the same tools the executor has.+- **The loop** — a refusal goes back to the executor verbatim as+ feedback and it tries again, up to `max_iters` times.++Because both agents share one workspace, the verifier judges what was+actually written rather than what the executor claims it wrote.++## Quickstart++```bash+export DASHSCOPE_API_KEY=sk-...+python goal_pipeline.py+```++The pipeline is handed straight to `launch_console`, so the terminal+shows both agents' streams as they take turns.++## Resuming++`reply_stream` ends when a tool call needs human confirmation — nothing+is left suspended waiting. Feed the answer back in to carry on:++```python+async for event in pipe.reply_stream(user_confirm_result_event):+ ...+```++The event's `reply_id` says which of the two agents was parked, so the+caller does not have to track whose turn it was. The iteration budget+survives the round trip: resuming does not hand the run a fresh set of+attempts.diff --git a/examples/pipeline/goal/goal_pipeline.py b/examples/pipeline/goal/goal_pipeline.pynew file mode 100644index 000000000..e8643598e--- /dev/null+++ b/examples/pipeline/goal/goal_pipeline.py@@ -0,0 +1,77 @@+# -*- coding: utf-8 -*-+"""An example of the goal pipeline."""++import os+import asyncio++from agentscope.state import AgentState+from agentscope.permission import PermissionContext, PermissionMode+from agentscope.pipeline import GoalPipeline+from agentscope.agent import Agent+from agentscope.credential import DashScopeCredential+from agentscope.model import DashScopeChatModel+from agentscope.workspace import LocalWorkspace+from agentscope.console import launch_console+from agentscope.tool import Toolkit+++async def main() -> None:+ """The main function."""++ # Executor and verifier share the same workspace, so they can read/write+ # files to it.+ async with LocalWorkspace(+ workdir=os.path.join(os.path.dirname(__file__), "workspace"),+ ) as workspace:+ # Create the executor agent+ executor = Agent(+ name="Executor",+ system_prompt="You're a programmer named 'Executor'.",+ model=DashScopeChatModel(+ credential=DashScopeCredential(+ api_key=os.getenv("DASHSCOPE_API_KEY"),+ ),+ model="qwen3.8-max",+ ),+ toolkit=Toolkit(tools=await workspace.list_tools()),+ offloader=workspace,+ state=AgentState(+ permission_context=PermissionContext(+ mode=PermissionMode.BYPASS,+ ),+ ),+ )++ # Create the verifier agent+ verifier = Agent(+ name="Verifier",+ system_prompt="You're a programmer named 'Verifier'.",+ model=DashScopeChatModel(+ credential=DashScopeCredential(+ api_key=os.getenv("DASHSCOPE_API_KEY"),+ ),+ model="qwen3.8-max",+ ),+ toolkit=Toolkit(tools=await workspace.list_tools()),+ offloader=workspace,+ state=AgentState(+ permission_context=PermissionContext(+ mode=PermissionMode.BYPASS,+ ),+ ),+ )++ # The goal arrives with the task, not at construction: whatever+ # the pipeline is first asked to do is also what the verifier+ # judges against.+ pipe = GoalPipeline(+ executor=executor,+ verifier=verifier,+ )++ await launch_console(+ agent=pipe,+ )+++asyncio.run(main())diff --git a/src/agentscope/console/_console.py b/src/agentscope/console/_console.pyindex da67ffc01..6be5bfa87 100644--- a/src/agentscope/console/_console.py+++ b/src/agentscope/console/_console.py@@ -5,6 +5,7 @@ import signalfrom ._renderer import ConsoleRenderer, Verbosityfrom ..agent import Agent+from ..pipeline import PipelineProtocolfrom ..event import (ConfirmResult,RequireUserConfirmEvent,@@ -15,7 +16,7 @@ from ..message import Msg, UserMsgasync def _run_reply(- agent: Agent,+ agent: Agent | PipelineProtocol,renderer: ConsoleRenderer,inputs: Msg | UserConfirmResultEvent | UserInterruptEvent,) -> RequireUserConfirmEvent | None:@@ -93,7 +94,7 @@ async def _confirm(async def launch_console(- agent: Agent,+ agent: Agent | PipelineProtocol,user_name: str = "user",verbosity: Verbosity = "default",max_tool_result_lines: int | None = 20,@@ -114,8 +115,8 @@ async def launch_console(await launch_console(agent)Args:- agent (`Agent`):- The agent to interact with.+ agent (`Agent | PipelineProtocol`):+ The agent or pipeline to interact with.user_name (`str`, defaults to `"user"`):The name attached to the user's input messages, also usedas the input prompt.diff --git a/src/agentscope/pipeline/__init__.py b/src/agentscope/pipeline/__init__.pynew file mode 100644index 000000000..0a8195ef2--- /dev/null+++ b/src/agentscope/pipeline/__init__.py@@ -0,0 +1,10 @@+# -*- coding: utf-8 -*-+"""The pipeline module."""++from ._base import PipelineProtocol+from ._goal_pipeline import GoalPipeline++__all__ = [+ "PipelineProtocol",+ "GoalPipeline",+]diff --git a/src/agentscope/pipeline/_base.py b/src/agentscope/pipeline/_base.pynew file mode 100644index 000000000..1aa69ecce--- /dev/null+++ b/src/agentscope/pipeline/_base.py@@ -0,0 +1,32 @@+# -*- coding: utf-8 -*-+"""The base pipeline protocol."""++from typing import AsyncGenerator, Protocol++from ..event import (+ AgentEvent,+ ExternalExecutionResultEvent,+ UserConfirmResultEvent,+ UserInterruptEvent,+)+from ..message import Msg+++class PipelineProtocol(Protocol):+ """What a pipeline has to offer to go where an agent goes.++ Declared as a plain ``def`` returning an async generator rather than+ an ``async def``: such a function is called, not awaited, and an+ ``async def`` here would be satisfied by neither ``Agent`` nor any+ pipeline.+ """++ def reply_stream(+ self,+ inputs: Msg+ | list[Msg]+ | UserConfirmResultEvent+ | UserInterruptEvent+ | ExternalExecutionResultEvent,+ ) -> AsyncGenerator[AgentEvent | Msg, None]:+ """Reply to the given inputs and stream what happens."""diff --git a/src/agentscope/pipeline/_goal_pipeline.py b/src/agentscope/pipeline/_goal_pipeline.pynew file mode 100644index 000000000..f29c3e1fc--- /dev/null+++ b/src/agentscope/pipeline/_goal_pipeline.py@@ -0,0 +1,325 @@+# -*- coding: utf-8 -*-+"""The goal pipeline class."""++from copy import deepcopy+from typing import AsyncGenerator, Literal++from pydantic import BaseModel, Field++from .._logging import logger+from ..types import ReplyFinishedReason+from ..agent import Agent+from ..message import UserMsg, Msg, TextBlock, DataBlock+from ..event import (+ UserConfirmResultEvent,+ ExternalExecutionResultEvent,+ RequireExternalExecutionEvent,+ RequireUserConfirmEvent,+ UserInterruptEvent,+)+++class _ExecutionReport(BaseModel):+ """The output of an execution."""++ report: str = Field(+ description=(+ "An achievement report of the given goal. E.g. file paths, entry "+ "points, how-to-run, runtime environment, etc. "+ "So that a verifier can check if you have achieved the goal. "+ ),+ )+++class _VerificationResult(BaseModel):+ """The result of a verification."""++ result: Literal["pass", "fail", "impossible"] = Field(+ description=(+ "The verfication result, which can be 'pass', 'fail', or "+ "'impossible'. 'impossible' means the given goal is impossible to "+ "achieve, and the executor should stop trying."+ ),+ )++ message: str = Field(+ description=(+ "If not passed, the message should explain why it "+ "failed, and what needs to be fixed. List the specific "+ "issues that need to be addressed, including where to "+ "exactly find them (e.g., file paths, line numbers)."+ ),+ )+++class GoalPipeline:+ """The goal pipeline class that run an executor and verifier in a loop+ until the goal is achieved."""++ def __init__(+ self,+ executor: Agent,+ verifier: Agent,+ verifier_reset_context: bool = True,+ max_iters: int = 10,+ max_retries: int = 3,+ ) -> None:+ """Initialize the goal pipeline.++ Args:+ executor (`Agent`):+ The executor agent that performs the work.+ verifier (`Agent`):+ The verifier agent that checks the goal achievement.+ verifier_reset_context (`bool`, optional):+ Whether to reset the verifier's context after each iteration.+ Defaults to `True`.+ max_iters (`int`, optional):+ The maximum number of goal achievement attempts.+ max_retries (`int`, optional):+ The maximum number of retries for the executor and verifier+ agents to generate valid structured outputs. Defaults to `3`.+ """+ self.executor = executor+ self.verifier = verifier+ self.verifier_reset_context = verifier_reset_context+ self.max_iters = max_iters+ self.max_retries = max_retries+ # Rounds already judged. On the instance rather than in+ # ``reply_stream``, so a HITL resume does not restart the budget.+ self._iters = 0+ self._goal: None | list[TextBlock | DataBlock] = None++ async def reply_stream(+ self,+ inputs: Msg+ | list[Msg]+ | UserConfirmResultEvent+ | UserInterruptEvent+ | ExternalExecutionResultEvent,+ ) -> AsyncGenerator:+ """Run the goal pipeline.++ Args:+ inputs (`Msg | list[Msg] | UserConfirmResultEvent | \+ UserInterruptEvent | ExternalExecutionResultEvent`):+ The inputs to the pipeline, which can be a message, a list of+ messages, a user confirmation result event, a user interrupt+ event, or an external execution result event.++ Yields:+ `AgentEvent`:+ The events generated by the executor and verifier agents+ during the pipeline execution.+ """++ # Prepare inputs for executor and verifier+ executor_inputs, verifier_inputs = None, None+ if (+ isinstance(inputs, Msg)+ or isinstance(inputs, list)+ and all(isinstance(_, Msg) for _ in inputs)+ ):+ executor_inputs = deepcopy(inputs)+ # A fresh run, so the iteration budget starts over.+ self._iters = 0++ hint = (+ "<system-reminder>When you finish the goal, you should "+ "summarize your output (if any) so that a verifier can check "+ "whether you have achieved the goal (e.g., file paths, entry "+ "points, how-to-run, runtime environment, etc.)."+ "</system-reminder>"+ )++ if isinstance(inputs, Msg):+ self._goal = inputs.content+ executor_inputs.content.append(TextBlock(text=hint))+ else:+ self._goal = []+ for _ in inputs:+ self._goal.extend(_.content)+ executor_inputs.append(+ UserMsg("system", content=hint),+ )++ elif isinstance(+ inputs,+ (+ UserConfirmResultEvent,+ UserInterruptEvent,+ ExternalExecutionResultEvent,+ ),+ ):+ if inputs.reply_id == self.executor.state.reply_id:+ executor_inputs = inputs+ elif inputs.reply_id == self.verifier.state.reply_id:+ verifier_inputs = inputs+ else:+ raise ValueError(+ f"Invalid inputs with reply_id: {inputs.reply_id}. ",+ )++ if isinstance(inputs, UserInterruptEvent):+ parked = (+ self.verifier if verifier_inputs is not None else self.executor+ )+ async for _ in parked.reply_stream(inputs=inputs):+ yield _+ return++ # Start the pipeline loop+ while True:+ # Executor step+ break_loop = False+ execution_report = None+ if executor_inputs is not None:+ while execution_report is None:+ # Run the executor with the given inputs+ async for _ in self.executor.reply_stream(+ inputs=executor_inputs,+ structured_schema=_ExecutionReport,+ yield_final_msg=True,+ ):+ yield _+ if isinstance(+ _,+ (+ RequireExternalExecutionEvent,+ RequireUserConfirmEvent,+ ),+ ):+ break_loop = True+ elif (+ isinstance(_, Msg)+ and _.finished_reason+ == ReplyFinishedReason.COMPLETED+ and _.structured_output+ ):+ execution_report = _.structured_output.get(+ "report",+ )++ if break_loop:+ # Break the loop for hitl events+ break++ if execution_report is None:+ # Update the instruction+ executor_inputs = UserMsg(+ name="system",+ content=(+ "<system-reminder>You have failed to generate "+ "valid execution report. You should call the "+ "'GenerateStructuredOutput' tool with a valid "+ "structured output that matches the schema. "+ ),+ )++ if break_loop:+ # The executor parked, so there is nothing to verify yet.+ break++ # Verifier+ final_msg = None+ instruction = verifier_inputs or UserMsg(+ name="user",+ content=[+ TextBlock(+ text=(+ "<system-reminder>Now you should verify the work "+ "done by the executor. "+ "The goal is as follows, you should "+ "verify whether the executor has "+ "achieved the goal.\n<goal>"+ ),+ ),+ *(self._goal or []),+ TextBlock(+ text=(+ "</goal>\nThe executor's achievement report is as "+ f"follows:\n<report>{execution_report}</report>"+ "</system-reminder>"+ ),+ ),+ ],+ )+ verifier_inputs = None+ while final_msg is None:+ async for _ in self.verifier.reply_stream(+ inputs=instruction,+ structured_schema=_VerificationResult,+ yield_final_msg=True,+ ):+ if (+ isinstance(_, Msg)+ and _.finished_reason == ReplyFinishedReason.COMPLETED+ ):+ final_msg = _+ elif isinstance(+ _,+ (+ RequireExternalExecutionEvent,+ RequireUserConfirmEvent,+ ),+ ):+ break_loop = True+ yield _+ else:+ yield _++ if break_loop:+ # Escape the loop for hitl events+ break+ if final_msg is None:+ continue+ if final_msg.structured_output is None:+ # Update the instruction for valid verification result+ # TODO: support multimodal verification instruction+ final_msg = None+ instruction = UserMsg(+ name="system",+ content=(+ "<system-reminder>You have failed to "+ "generate valid verification result. "+ "You should call the "+ "'GenerateStructuredOutput' tool with "+ "a valid structured output that matches "+ "the schema. Recall the verification "+ "requirements as follows:\n"+ f"{self._goal}</system-reminder>"+ ),+ )+ elif final_msg.structured_output.get("result") in (+ "pass",+ "impossible",+ ):+ if final_msg.structured_output["result"] == "impossible":+ logger.info(+ "The verifier judged the goal impossible: %s",+ final_msg.structured_output.get("message"),+ )+ # Settled either way, so the loop ends here.+ break_loop = True+ else:+ self._iters += 1+ if self._iters >= self.max_iters:+ # Out of attempts; the work never passed+ break_loop = True+ break++ # Feedback to the executor for further improvement+ feedback = final_msg.structured_output.get("message")+ executor_inputs = UserMsg(+ name="system",+ content=(+ "<system-reminder>You've failed to pass the "+ "verification. Now recorrect your work based on "+ f"the following feedback:\n{feedback}"+ "</system-reminder>"+ ),+ )++ if break_loop:+ # Break the loop for hitl events or verification passed+ breakdiff --git a/tests/pipeline_goal_test.py b/tests/pipeline_goal_test.pynew file mode 100644index 000000000..552260596--- /dev/null+++ b/tests/pipeline_goal_test.py@@ -0,0 +1,275 @@+# -*- coding: utf-8 -*-+"""Test the goal pipeline."""+from types import SimpleNamespace+from typing import Any, AsyncGenerator+from unittest.async_case import IsolatedAsyncioTestCase++from agentscope.event import (+ ConfirmResult,+ RequireUserConfirmEvent,+ UserConfirmResultEvent,+)+from agentscope.message import Msg, ToolCallBlock, UserMsg+from agentscope.pipeline import GoalPipeline+from agentscope.types import ReplyFinishedReason+++def _report(text: str = "已完成,见 main.py") -> Msg:+ """An executor's final message carrying its achievement report."""+ return Msg(+ name="executor",+ content=[],+ role="assistant",+ finished_reason=ReplyFinishedReason.COMPLETED,+ structured_output={"report": text},+ )+++def _verdict(result: str, message: str = "") -> Msg:+ """A verifier's final message carrying a structured verdict."""+ return Msg(+ name="verifier",+ content=[],+ role="assistant",+ finished_reason=ReplyFinishedReason.COMPLETED,+ structured_output={"result": result, "message": message},+ )+++def _no_output(name: str) -> Msg:+ """A final message from an agent that never called the output tool."""+ return Msg(+ name=name,+ content=[],+ role="assistant",+ finished_reason=ReplyFinishedReason.COMPLETED,+ )+++def _confirm_request() -> RequireUserConfirmEvent:+ """A tool call parked on a human."""+ return RequireUserConfirmEvent(+ reply_id="executor-reply",+ tool_calls=[+ ToolCallBlock(id="call-1", name="write_file", input="{}"),+ ],+ )+++class StubAgent:+ """Replays one scripted batch of chunks per ``reply_stream`` call.++ Records what it was handed, so a test can assert the feedback and+ reminders the pipeline built reached the right agent.+ """++ def __init__(self, name: str, script: list[list[Any]]) -> None:+ """Initialize the stub with one script entry per call."""+ self.name = name+ self.script = script+ self.state = SimpleNamespace(reply_id=f"{name}-reply")+ self.received: list[Any] = []++ # pylint: disable=unused-argument+ async def reply_stream(+ self,+ inputs: Any = None,+ structured_schema: Any = None,+ yield_final_msg: bool = False,+ ) -> AsyncGenerator[Any, None]:+ """Yield the next batch, holding the final message back unless it+ was asked for, the way ``Agent.reply_stream`` does."""+ self.received.append(inputs)+ batch = self.script[min(len(self.received) - 1, len(self.script) - 1)]+ for chunk in batch:+ if isinstance(chunk, Msg) and not yield_final_msg:+ continue+ yield chunk+++class GoalPipelineTest(IsolatedAsyncioTestCase):+ """The goal pipeline test case."""++ async def asyncSetUp(self) -> None:+ """Prepare the input every test starts from."""+ self.query = UserMsg(name="user", content="写一个爬虫")++ async def _run(self, pipe: GoalPipeline, inputs: Any) -> list:+ """Drain one pipeline run into what it yielded."""+ return [chunk async for chunk in pipe.reply_stream(inputs)]++ async def test_passes_on_first_round(self) -> None:+ """A passing verdict ends the run, and the verifier is told both+ the goal and what the executor reported."""+ executor = StubAgent("executor", [[_report("见 main.py")]])+ verifier = StubAgent("verifier", [[_verdict("pass")]])+ pipe = GoalPipeline(executor, verifier)++ yielded = await self._run(pipe, self.query)++ self.assertListEqual(+ [chunk.structured_output for chunk in yielded],+ [{"report": "见 main.py"}],+ )+ told = verifier.received[0].get_text_content()+ self.assertIn("写一个爬虫", told)+ self.assertIn("见 main.py", told)++ async def test_refusal_reaches_the_executor(self) -> None:+ """A refusal is fed back verbatim and the run tries again."""+ executor = StubAgent("executor", [[_report()], [_report()]])+ verifier = StubAgent(+ "verifier",+ [[_verdict("fail", "缺 requirements.txt")], [_verdict("pass")]],+ )+ pipe = GoalPipeline(executor, verifier)++ await self._run(pipe, self.query)++ self.assertEqual(len(executor.received), 2)+ self.assertIn(+ "缺 requirements.txt",+ executor.received[1].get_text_content(),+ )++ async def test_stops_at_max_iters(self) -> None:+ """A verdict that never passes stops once the budget is spent."""+ executor = StubAgent("executor", [[_report()]])+ verifier = StubAgent("verifier", [[_verdict("fail", "还是不行")]])+ pipe = GoalPipeline(executor, verifier, max_iters=2)++ await self._run(pipe, self.query)++ self.assertEqual(len(executor.received), 2)+ self.assertEqual(len(verifier.received), 2)++ async def test_impossible_ends_the_run(self) -> None:+ """An impossible goal settles the run rather than retrying."""+ executor = StubAgent("executor", [[_report()]])+ verifier = StubAgent(+ "verifier",+ [[_verdict("impossible", "目标自相矛盾")]],+ )+ pipe = GoalPipeline(executor, verifier)++ await self._run(pipe, self.query)++ self.assertEqual(len(executor.received), 1)+ self.assertEqual(len(verifier.received), 1)++ async def test_reprompts_a_verifier_that_skips_the_tool(self) -> None:+ """A final message with no verdict is not a refusal: the verifier+ is reminded rather than the executor being sent back."""+ executor = StubAgent("executor", [[_report()]])+ verifier = StubAgent(+ "verifier",+ [[_no_output("verifier")], [_verdict("pass")]],+ )+ pipe = GoalPipeline(executor, verifier)++ await self._run(pipe, self.query)++ self.assertEqual(len(verifier.received), 2)+ self.assertIn(+ "GenerateStructuredOutput",+ verifier.received[1].get_text_content(),+ )+ # A malfunction is not charged to the executor.+ self.assertEqual(len(executor.received), 1)++ async def test_reprompts_an_executor_that_skips_the_tool(self) -> None:+ """The same for the executor: a missing report is asked for again+ rather than read through as if it were there."""+ executor = StubAgent(+ "executor",+ [[_no_output("executor")], [_report()]],+ )+ verifier = StubAgent("verifier", [[_verdict("pass")]])+ pipe = GoalPipeline(executor, verifier)++ await self._run(pipe, self.query)++ self.assertEqual(len(executor.received), 2)+ self.assertIn(+ "GenerateStructuredOutput",+ executor.received[1].get_text_content(),+ )+ self.assertEqual(len(verifier.received), 1)++ async def test_a_parked_executor_is_not_verified(self) -> None:+ """The work is unfinished while the executor waits on a human, so+ there is nothing for the verifier to judge yet."""+ request = _confirm_request()+ executor = StubAgent("executor", [[request]])+ verifier = StubAgent("verifier", [[_verdict("pass")]])+ pipe = GoalPipeline(executor, verifier)++ yielded = await self._run(pipe, self.query)++ self.assertListEqual(yielded, [request])+ self.assertListEqual(verifier.received, [])++ async def test_resumes_into_the_agent_that_parked(self) -> None:+ """The reply id sends the answer back to whoever asked for it."""+ request = _confirm_request()+ executor = StubAgent("executor", [[request], [_report()]])+ verifier = StubAgent("verifier", [[_verdict("pass")]])+ pipe = GoalPipeline(executor, verifier)++ await self._run(pipe, self.query)++ answer = UserConfirmResultEvent(+ reply_id="executor-reply",+ confirm_results=[+ ConfirmResult(confirmed=True, tool_call=request.tool_calls[0]),+ ],+ )+ await self._run(pipe, answer)++ self.assertEqual(executor.received[1], answer)+ self.assertEqual(len(verifier.received), 1)++ async def test_resume_keeps_the_iteration_budget(self) -> None:+ """Resuming does not hand the run a fresh set of attempts.++ Round one is refused and round two parks. With a budget of two,+ the resumed round is the last one — were the budget to restart,+ the executor would be sent back a fourth time.+ """+ executor = StubAgent(+ "executor",+ [[_report()], [_confirm_request()], [_report()]],+ )+ verifier = StubAgent(+ "verifier",+ [[_verdict("fail", "不行")], [_verdict("fail", "还是不行")]],+ )+ pipe = GoalPipeline(executor, verifier, max_iters=2)++ await self._run(pipe, self.query)+ await self._run(+ pipe,+ UserConfirmResultEvent(+ reply_id="executor-reply",+ confirm_results=[],+ ),+ )++ self.assertEqual(len(executor.received), 3)+ self.assertEqual(len(verifier.received), 2)++ async def test_rejects_an_unknown_reply_id(self) -> None:+ """An answer belonging to neither agent is a programming error,+ not something to guess at."""+ executor = StubAgent("executor", [[_report()]])+ verifier = StubAgent("verifier", [[_verdict("pass")]])+ pipe = GoalPipeline(executor, verifier)++ with self.assertRaises(ValueError):+ await self._run(+ pipe,+ UserConfirmResultEvent(+ reply_id="nobody",+ confirm_results=[],+ ),+ )