Skip to content

Agent Zero AI framework

Keep goal operations out of disposable parallel workers

Alessandro2f1617352fc8
diff --git a/helpers/parallel_tools.py b/helpers/parallel_tools.py
index b2eb67a32..264601746 100644
--- a/helpers/parallel_tools.py
+++ b/helpers/parallel_tools.py
@@ -32,7 +32,7 @@ CHILD_PARALLEL_TOOL_NAME_KEY = "parallel_tool_name"
DEFAULT_MAX_CALLS = 8
DEFAULT_TIMEOUT_SECONDS = 300
POLL_INTERVAL_SECONDS = 0.5
-DISALLOWED_PARALLEL_TOOLS = {"document_query", "response"}
+DISALLOWED_PARALLEL_TOOLS = {"document_query", "response", "goal"}
TERMINAL_STATES = {"success", "error", "cancelled", "timeout"}
JobState = Literal["pending", "running", "success", "error", "cancelled", "timeout"]
@@ -102,12 +102,7 @@ def normalize_parallel_tool_calls(raw_calls: Any) -> list[NormalizedToolCall]:
except ValueError as exc:
raise ValueError(f"tool_calls[{index}] is not a valid tool call: {exc}") from exc
- if tool_name == "parallel":
- raise ValueError("`parallel` cannot be nested inside another `parallel` call.")
- if tool_name in DISALLOWED_PARALLEL_TOOLS:
- raise ValueError(
- f"`{tool_name}` cannot be used inside `parallel`; call it sequentially."
- )
+ _ensure_parallel_tool_allowed(tool_name)
calls.append(
NormalizedToolCall(
@@ -119,6 +114,15 @@ def normalize_parallel_tool_calls(raw_calls: Any) -> list[NormalizedToolCall]:
return calls
+def _ensure_parallel_tool_allowed(tool_name: str) -> None:
+ if tool_name == "parallel":
+ raise ValueError("`parallel` cannot be nested inside another `parallel` call.")
+ if tool_name in DISALLOWED_PARALLEL_TOOLS:
+ raise ValueError(
+ f"`{tool_name}` cannot be used inside `parallel`; call it sequentially."
+ )
+
+
def normalize_job_ids(raw_job_ids: Any) -> list[str]:
if raw_job_ids is None:
return []
@@ -218,6 +222,8 @@ async def start_parallel_jobs(
agent: "Agent",
calls: list[NormalizedToolCall],
) -> list[ParallelJob]:
+ for call in calls:
+ _ensure_parallel_tool_allowed(call.tool_name)
jobs: list[ParallelJob] = []
context = agent.context
job_store = _jobs_for_context(context)
@@ -540,8 +546,7 @@ async def execute_tool_call(
*,
log_item: "LogItem | None" = None,
) -> str:
- if tool_name == "parallel":
- raise ValueError("`parallel` cannot be nested inside a parallel worker.")
+ _ensure_parallel_tool_allowed(tool_name)
tool = _resolve_parallel_tool(agent, tool_name, tool_args, strict=True)
if not tool:
diff --git a/helpers/parallel_tools.py.dox.md b/helpers/parallel_tools.py.dox.md
index b96778478..24899cb55 100644
--- a/helpers/parallel_tools.py.dox.md
+++ b/helpers/parallel_tools.py.dox.md
@@ -25,7 +25,7 @@
- Wrapped tool-call items must use the same shape as normal tool calls: a tool name plus arguments.
- Normalization accepts full agent-reply-shaped objects when `tool_name` and `tool_args` are present; non-contract planning fields such as `thoughts` or `headline` are ignored.
- `tool_calls` should be an array, but normalization also accepts a valid JSON string encoding of that array to recover provider/model stringification.
-- Normalization rejects `document_query` and `response` inside `parallel`: document parsing and Q&A must run sequentially, while `response` must remain top-level so it can end the message loop.
+- Shared validation rejects `document_query`, `response`, and `goal` inside direct `parallel` workers: document parsing stays sequential, `response` ends the parent loop, and goals belong to the calling context. Validate the whole batch before registering jobs and recheck at direct dispatch. Retained subordinates keep their own state.
- `call_subordinate` jobs first enforce the actual calling agent's delegation policy, then call the same creation and execution functions as direct delegation in `tools/call_subordinate.py`; this helper does not construct or prompt a second kind of subordinate.
- Fresh parallel sibling calls create distinct `parent.number + 1` child agents. Their job snapshots expose stable `context_id` values that direct or parallel `reset=false` calls can continue after success or failure.
- Jobs retain their actual parent agent so parallel calls made by A1 create A2 rather than falling back to a context's A0.
diff --git a/prompts/agent.system.tool.parallel.md b/prompts/agent.system.tool.parallel.md
index dbb4560a9..fa9b6b02a 100644
--- a/prompts/agent.system.tool.parallel.md
+++ b/prompts/agent.system.tool.parallel.md
@@ -9,6 +9,7 @@ Rules:
- do not use for one simple call, dependent steps, ordered steps, shared mutable state, or state/tool-availability changes that must happen in the parent context
- never nest `parallel`
- Never include `document_query` in `tool_calls`; it is too heavy for parallel workers, so call it sequentially.
+- Call `goal` sequentially in the owning chat; direct parallel workers have a temporary context and cannot read or update the parent goal.
- Call `response` only as a top-level tool so it ends the message loop; never wrap it inside `parallel.tool_calls`.
- `call_subordinate` uses the same child lifecycle here as it does top-level; fresh siblings are next-level agents, and each job's `context_id` can be continued later with `reset: false`
- use `wait: false` only when you will collect results later with `job_ids`
diff --git a/tests/test_parallel_tool.py b/tests/test_parallel_tool.py
index f7ab7d6c7..ba4d15192 100644
--- a/tests/test_parallel_tool.py
+++ b/tests/test_parallel_tool.py
@@ -181,7 +181,7 @@ def test_normalize_parallel_tool_calls_rejects_nested_parallel() -> None:
)
[email protected]("tool_name", ["document_query", "response"])
[email protected]("tool_name", ["document_query", "response", "goal"])
def test_normalize_parallel_tool_calls_rejects_disallowed_tools(tool_name: str) -> None:
with pytest.raises(ValueError, match=rf"{tool_name}.*parallel"):
parallel_tools.normalize_parallel_tool_calls(
@@ -1202,3 +1202,18 @@ def test_parallel_result_json_is_compact() -> None:
)
assert result == '{"status":"success","jobs":[{"job_id":"wait-1","tool_name":"wait","state":"success"}]}'
+
+
+async def test_parallel_rejects_context_owned_tools_before_starting_any_job():
+ agent = _FakeAgent()
+ calls = [
+ parallel_tools.NormalizedToolCall(0, "search_engine", {"query": "a0"}),
+ parallel_tools.NormalizedToolCall(1, "goal", {"action": "create", "objective": "wrong owner"}),
+ ]
+ with pytest.raises(ValueError, match="goal.*sequentially"):
+ await parallel_tools.start_parallel_jobs(agent, calls)
+ assert agent.context.log.items == []
+ assert not agent.context.get_data(parallel_tools.PARALLEL_JOBS_KEY)
+ with pytest.raises(ValueError, match="goal.*sequentially"):
+ await parallel_tools.execute_tool_call(agent, "goal", {"action": "get"})