Skip to content

Build and run agents you can see, understand and trust.

feat(pipeline): add new pipeline module and a `GoalPipeline` class (#2428)

DavdGaob182da398807
diff --git a/README.md b/README.md
index 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.md
index 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.md
index 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.md
index 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.md
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index da67ffc01..6be5bfa87 100644
--- a/src/agentscope/console/_console.py
+++ b/src/agentscope/console/_console.py
@@ -5,6 +5,7 @@ import signal
from ._renderer import ConsoleRenderer, Verbosity
from ..agent import Agent
+from ..pipeline import PipelineProtocol
from ..event import (
ConfirmResult,
RequireUserConfirmEvent,
@@ -15,7 +16,7 @@ from ..message import Msg, UserMsg
async 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 used
as the input prompt.
diff --git a/src/agentscope/pipeline/__init__.py b/src/agentscope/pipeline/__init__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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
+ break
diff --git a/tests/pipeline_goal_test.py b/tests/pipeline_goal_test.py
new file mode 100644
index 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=[],
+ ),
+ )