From 401c48560db9341a3fb14bd7e0cfbb6bd5819e3a Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:29:29 -0500
Subject: [PATCH 01/11] Sub-agents: the policy and a run's limits as
configuration
SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits
(max_model_calls, timeout, max_tokens; over() lays a type's limits over the
policy's, field by field) are frozen and refuse a value that is no limit as
they are made, naming the field. DEFAULT_LIMITS is 100 model calls.
as_policy() is the one reading of a subagents= argument. Exported from
agentic_cli.workflow and agentic_cli.workflow.agents.
---
src/agentic_cli/workflow/__init__.py | 3 +
src/agentic_cli/workflow/agents/__init__.py | 9 +-
src/agentic_cli/workflow/agents/policy.py | 123 +++++++++++++++++
tests/workflow/test_agent_policy.py | 138 ++++++++++++++++++++
4 files changed, 271 insertions(+), 2 deletions(-)
create mode 100644 src/agentic_cli/workflow/agents/policy.py
create mode 100644 tests/workflow/test_agent_policy.py
diff --git a/src/agentic_cli/workflow/__init__.py b/src/agentic_cli/workflow/__init__.py
index e5c25119..75f3d152 100644
--- a/src/agentic_cli/workflow/__init__.py
+++ b/src/agentic_cli/workflow/__init__.py
@@ -19,6 +19,7 @@
WorkflowEvent,
)
from agentic_cli.workflow.config import AgentConfig
+from agentic_cli.workflow.agents.policy import AgentLimits, SubAgentPolicy
from agentic_cli.workflow.model_settings import ModelSettings, ThinkingSettings
from agentic_cli.workflow.mcp import MCPServerConfig
from agentic_cli.workflow.factory import create_workflow_manager_from_settings
@@ -82,6 +83,8 @@ def __getattr__(name: str):
"translate_adk_yaml",
# Config
"AgentConfig",
+ "SubAgentPolicy",
+ "AgentLimits",
"ModelSettings",
"ThinkingSettings",
"MCPServerConfig",
diff --git a/src/agentic_cli/workflow/agents/__init__.py b/src/agentic_cli/workflow/agents/__init__.py
index cefd81b7..3996b458 100644
--- a/src/agentic_cli/workflow/agents/__init__.py
+++ b/src/agentic_cli/workflow/agents/__init__.py
@@ -1,10 +1,12 @@
-"""Sub-agents, as the framework keeps them: their runs.
+"""Sub-agents, as the framework keeps them: their runs, and how they run.
A sub-agent run is one piece of work a sub-agent does for its parent: one
delegation (its parent's tool call). ``runs`` names each run within its
-conversation and records it from its ``AGENT_RUN`` events.
+conversation and records it from its ``AGENT_RUN`` events; ``policy`` holds
+an app's sub-agent policy and a run's limits.
"""
+from agentic_cli.workflow.agents.policy import DEFAULT_LIMITS, AgentLimits, SubAgentPolicy
from agentic_cli.workflow.agents.runs import (
RESULT_MAX,
RUN_CANCELLED,
@@ -24,7 +26,9 @@
)
__all__ = [
+ "AgentLimits",
"AgentRuns",
+ "DEFAULT_LIMITS",
"RESULT_MAX",
"RUN_CANCELLED",
"RUN_COMPLETED",
@@ -35,6 +39,7 @@
"RUN_STARTED",
"RunRecord",
"SUBAGENT_ERROR_PREFIX",
+ "SubAgentPolicy",
"TITLE_MAX",
"result_head",
"run_label",
diff --git a/src/agentic_cli/workflow/agents/policy.py b/src/agentic_cli/workflow/agents/policy.py
new file mode 100644
index 00000000..711c20e5
--- /dev/null
+++ b/src/agentic_cli/workflow/agents/policy.py
@@ -0,0 +1,123 @@
+"""How an app's sub-agents run: its sub-agent policy, and a run's limits.
+
+An app passes a ``SubAgentPolicy`` as ``subagents=`` (to ``BaseCLIApp``, a
+workflow manager or ``create_workflow_manager_from_settings``); None there is
+``SubAgentPolicy()``, the policy every manager has unless it is given
+another. ``AgentLimits`` are one sub-agent run's limits: the policy holds
+every run's, and an agent type's own (``AgentConfig.limits``) lie over them
+field by field (``AgentLimits.over``), a field left None taking the
+policy's. Both are frozen, and refuse a value that is no limit as they are
+made, with a ``ValueError`` naming the field.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, fields, replace
+
+
+def _check_count(owner: str, name: str, value: object, *, optional: bool) -> None:
+ """Refuse ``value`` unless it is a positive int (or None, when ``optional``).
+
+ True and False are ints to Python, but no count: ``max_active=True``
+ is a mistake, not one.
+ """
+ if value is None and optional:
+ return
+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+ allowed = "a positive int or None" if optional else "a positive int"
+ raise ValueError(f"{owner}.{name} must be {allowed}, not {value!r}.")
+
+
+def _check_seconds(owner: str, name: str, value: object) -> None:
+ """Refuse ``value`` unless it is None or a positive, finite number of seconds."""
+ if value is None:
+ return
+ if (
+ isinstance(value, bool)
+ or not isinstance(value, (int, float))
+ or not math.isfinite(value)
+ or value <= 0
+ ):
+ raise ValueError(
+ f"{owner}.{name} must be a positive number of seconds or None, not {value!r}."
+ )
+
+
+@dataclass(frozen=True)
+class AgentLimits:
+ """One sub-agent run's limits; a field left None takes the policy's (on a
+ type), or means no limit (on the policy).
+
+ Attributes:
+ max_model_calls: The most model calls the run may make.
+ timeout: The most seconds the run may take.
+ max_tokens: The most tokens the run may use: its input plus output
+ tokens, as its usage counts them.
+ """
+
+ max_model_calls: int | None = None
+ timeout: float | None = None
+ max_tokens: int | None = None
+
+ def __post_init__(self) -> None:
+ _check_count("AgentLimits", "max_model_calls", self.max_model_calls, optional=True)
+ _check_seconds("AgentLimits", "timeout", self.timeout)
+ _check_count("AgentLimits", "max_tokens", self.max_tokens, optional=True)
+
+ def over(self, base: AgentLimits) -> AgentLimits:
+ """These limits over ``base``: each field of this one that is set,
+ else ``base``'s (a type's limits over the policy's).
+
+ A field left None never lifts a limit ``base`` sets.
+ """
+ own = {f.name: getattr(self, f.name) for f in fields(self)}
+ return replace(base, **{name: value for name, value in own.items() if value is not None})
+
+
+#: The policy's limits unless an app passes its own: a run makes at most 100 model calls.
+DEFAULT_LIMITS = AgentLimits(max_model_calls=100)
+
+
+@dataclass(frozen=True)
+class SubAgentPolicy:
+ """How an app's sub-agents run; ``SubAgentPolicy()`` is the default every manager gets.
+
+ Attributes:
+ max_active: How many sub-agent runs may work at once in a
+ conversation, at any depth.
+ max_runs_per_turn: How many sub-agent runs one turn may start.
+ limits: Every run's limits (``AgentLimits``), which an agent type's
+ own lie over.
+ """
+
+ max_active: int = 4
+ max_runs_per_turn: int = 20
+ limits: AgentLimits = DEFAULT_LIMITS
+
+ def __post_init__(self) -> None:
+ _check_count("SubAgentPolicy", "max_active", self.max_active, optional=False)
+ _check_count("SubAgentPolicy", "max_runs_per_turn", self.max_runs_per_turn, optional=False)
+ if not isinstance(self.limits, AgentLimits):
+ raise ValueError(
+ f"SubAgentPolicy.limits must be an AgentLimits, not {self.limits!r}."
+ )
+
+
+def as_policy(subagents: object) -> SubAgentPolicy:
+ """The policy a ``subagents=`` argument names: itself, or ``SubAgentPolicy()`` for None.
+
+ Every place that takes ``subagents=`` reads it through this, first, so a
+ wrong value fails where it was passed rather than when a manager is
+ built from it later.
+
+ Raises:
+ TypeError: ``subagents`` is neither a ``SubAgentPolicy`` nor None.
+ """
+ if subagents is None:
+ return SubAgentPolicy()
+ if isinstance(subagents, SubAgentPolicy):
+ return subagents
+ raise TypeError(
+ f"subagents must be a SubAgentPolicy or None, not {type(subagents).__name__}."
+ )
diff --git a/tests/workflow/test_agent_policy.py b/tests/workflow/test_agent_policy.py
new file mode 100644
index 00000000..70f1f39a
--- /dev/null
+++ b/tests/workflow/test_agent_policy.py
@@ -0,0 +1,138 @@
+"""How an app's sub-agents run: ``SubAgentPolicy`` and ``AgentLimits`` (``workflow/agents/policy.py``).
+
+Both are frozen and check their values as they are made: a limit is a
+positive int (a timeout: a positive number of seconds), True and False are
+no numbers there, and a policy's ``limits`` is an ``AgentLimits``. A type's
+limits lie over the policy's field by field (``over``): a field left None
+takes the policy's. ``as_policy`` is the one reading of a ``subagents=``
+argument.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import math
+
+import pytest
+
+import agentic_cli.workflow as workflow
+from agentic_cli.workflow import agents
+from agentic_cli.workflow.agents.policy import (
+ DEFAULT_LIMITS,
+ AgentLimits,
+ SubAgentPolicy,
+ as_policy,
+)
+
+
+class TestAgentLimits:
+ def test_every_field_is_none_by_default(self):
+ assert AgentLimits() == AgentLimits(max_model_calls=None, timeout=None, max_tokens=None)
+
+ def test_it_is_frozen(self):
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ AgentLimits().timeout = 5 # type: ignore[misc]
+
+ def test_positive_values_are_kept(self):
+ limits = AgentLimits(max_model_calls=3, timeout=1.5, max_tokens=10_000)
+ assert (limits.max_model_calls, limits.timeout, limits.max_tokens) == (3, 1.5, 10_000)
+
+ def test_a_whole_number_of_seconds_is_a_timeout(self):
+ assert AgentLimits(timeout=600).timeout == 600
+
+ @pytest.mark.parametrize("field", ["max_model_calls", "max_tokens"])
+ @pytest.mark.parametrize("value", [0, -1, 2.5, "5", True, False])
+ def test_a_count_must_be_a_positive_int(self, field, value):
+ with pytest.raises(ValueError) as exc:
+ AgentLimits(**{field: value})
+ message = str(exc.value)
+ assert f"AgentLimits.{field}" in message and "positive int" in message
+ assert repr(value) in message
+
+ @pytest.mark.parametrize("value", [0, -0.5, math.inf, math.nan, "30", True])
+ def test_a_timeout_must_be_a_positive_number_of_seconds(self, value):
+ with pytest.raises(ValueError) as exc:
+ AgentLimits(timeout=value)
+ message = str(exc.value)
+ assert "AgentLimits.timeout" in message and "positive number" in message
+
+ def test_over_takes_its_own_fields_where_set_and_the_base_elsewhere(self):
+ base = AgentLimits(max_model_calls=100, timeout=60)
+ mine = AgentLimits(timeout=600, max_tokens=50_000)
+ assert mine.over(base) == AgentLimits(max_model_calls=100, timeout=600, max_tokens=50_000)
+
+ def test_over_cannot_lift_a_limit_the_base_sets(self):
+ # None is "not set": the base's limit stands.
+ assert AgentLimits().over(DEFAULT_LIMITS) == DEFAULT_LIMITS
+
+ def test_over_a_base_without_limits_is_itself(self):
+ mine = AgentLimits(max_model_calls=5)
+ assert mine.over(AgentLimits()) == mine
+
+
+class TestSubAgentPolicy:
+ def test_the_defaults(self):
+ policy = SubAgentPolicy()
+ assert policy.max_active == 4
+ assert policy.max_runs_per_turn == 20
+ assert policy.limits is DEFAULT_LIMITS
+
+ def test_the_default_limits_are_a_hundred_model_calls(self):
+ assert DEFAULT_LIMITS == AgentLimits(max_model_calls=100)
+
+ def test_it_is_frozen(self):
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ SubAgentPolicy().max_active = 8 # type: ignore[misc]
+
+ def test_its_values_are_kept(self):
+ limits = AgentLimits(timeout=30)
+ policy = SubAgentPolicy(max_active=1, max_runs_per_turn=5, limits=limits)
+ assert (policy.max_active, policy.max_runs_per_turn, policy.limits) == (1, 5, limits)
+
+ @pytest.mark.parametrize("field", ["max_active", "max_runs_per_turn"])
+ @pytest.mark.parametrize("value", [0, -3, 1.0, None, "4", True])
+ def test_a_count_must_be_a_positive_int(self, field, value):
+ with pytest.raises(ValueError) as exc:
+ SubAgentPolicy(**{field: value})
+ message = str(exc.value)
+ assert f"SubAgentPolicy.{field}" in message and "positive int" in message
+ assert repr(value) in message
+
+ @pytest.mark.parametrize("value", [None, {"max_model_calls": 5}, 100])
+ def test_limits_must_be_an_agent_limits(self, value):
+ with pytest.raises(ValueError) as exc:
+ SubAgentPolicy(limits=value)
+ message = str(exc.value)
+ assert "SubAgentPolicy.limits" in message and "AgentLimits" in message
+
+ def test_policies_with_the_same_values_are_equal(self):
+ assert SubAgentPolicy() == SubAgentPolicy(limits=AgentLimits(max_model_calls=100))
+
+
+class TestAsPolicy:
+ def test_none_is_the_default_policy(self):
+ assert as_policy(None) == SubAgentPolicy()
+
+ def test_a_policy_is_itself(self):
+ policy = SubAgentPolicy(max_active=2)
+ assert as_policy(policy) is policy
+
+ @pytest.mark.parametrize("value", [{"max_active": 2}, SubAgentPolicy, AgentLimits(), 4])
+ def test_anything_else_is_a_type_error_naming_its_type(self, value):
+ with pytest.raises(TypeError) as exc:
+ as_policy(value)
+ message = str(exc.value)
+ assert "subagents must be a SubAgentPolicy or None" in message
+ assert type(value).__name__ in message
+
+
+class TestTheExports:
+ @pytest.mark.parametrize("package", [workflow, agents])
+ def test_both_packages_export_the_policy_and_the_limits(self, package):
+ assert {"SubAgentPolicy", "AgentLimits"} <= set(package.__all__)
+ assert package.SubAgentPolicy is SubAgentPolicy
+ assert package.AgentLimits is AgentLimits
+
+ def test_the_agents_package_exports_the_default_limits(self):
+ assert "DEFAULT_LIMITS" in agents.__all__
+ assert agents.DEFAULT_LIMITS is DEFAULT_LIMITS
From 3449aa3850be3bad6eb7da3577bb56745829ec26 Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:30:03 -0500
Subject: [PATCH 02/11] Sub-agents: the brief and its task message
A brief is a title, an objective and, where they help, the deliverable,
the constraints, what is known and when it is done. task_message lays the
filled fields out under a heading each; an inheriting type's ends with
INHERITED_CONTEXT_NOTE, which moves to agents/brief.py, text unchanged:
ADK's delegation imports it from there.
---
src/agentic_cli/workflow/adk/delegation.py | 16 +---
src/agentic_cli/workflow/agents/brief.py | 92 ++++++++++++++++++++
tests/workflow/test_agent_brief.py | 99 ++++++++++++++++++++++
3 files changed, 192 insertions(+), 15 deletions(-)
create mode 100644 src/agentic_cli/workflow/agents/brief.py
create mode 100644 tests/workflow/test_agent_brief.py
diff --git a/src/agentic_cli/workflow/adk/delegation.py b/src/agentic_cli/workflow/adk/delegation.py
index 449657b9..13fe7bc3 100644
--- a/src/agentic_cli/workflow/adk/delegation.py
+++ b/src/agentic_cli/workflow/adk/delegation.py
@@ -59,6 +59,7 @@
from agentic_cli.logging import Loggers
from agentic_cli.tools._core.delegation import TASK_TOOL
from agentic_cli.tools.registry import bind_tool_identity, get_registry
+from agentic_cli.workflow.agents.brief import INHERITED_CONTEXT_NOTE
from agentic_cli.workflow.config import AgentConfig, AgentGraphError
if TYPE_CHECKING:
@@ -66,21 +67,6 @@
logger = Loggers.workflow()
-#: The end of an inheriting sub-agent's instruction: whose conversation it
-#: reads, and which message is its task (Deep Agents' ``_FORK_TASK_PREAMBLE``,
-#: told the way ADK shows that conversation). Sent as written, as the whole
-#: prompt is (``manager._as_written``).
-INHERITED_CONTEXT_NOTE = (
- "You are a sub-agent: another agent has handed you a task. The conversation "
- "before the task is that agent's, shown so you know what has been established: "
- "the user's messages in it were addressed to that agent, not to you, and what "
- "that agent did is quoted, its call handing you this task included. Do not "
- "carry out those messages yourself or answer as that agent. Your task is the "
- "request that follows the conversation: complete it directly, and use the "
- "specific facts, figures and identifiers already established in the "
- "conversation rather than answering generically."
-)
-
def subagent_fields(config: AgentConfig) -> dict[str, Any]:
"""The ``LlmAgent`` fields that make ``config``'s agent a delegated sub-agent.
diff --git a/src/agentic_cli/workflow/agents/brief.py b/src/agentic_cli/workflow/agents/brief.py
new file mode 100644
index 00000000..0e194b4e
--- /dev/null
+++ b/src/agentic_cli/workflow/agents/brief.py
@@ -0,0 +1,92 @@
+"""A delegation's brief, and the task message a run starts from.
+
+A parent delegates with a brief: a title (a few words, for ``/agents`` and
+the status bar) and an objective, and, where they help, what to deliver,
+the constraints, what is already known and when the task is done
+(``BRIEF_FIELDS``). ``task_message`` lays a brief out as the first message
+of the run it starts (the system prompt stays the type's own); an
+inheriting type's ends with ``INHERITED_CONTEXT_NOTE``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+#: A brief's fields besides its title, in the order a task message lays them out.
+BRIEF_FIELDS = ("objective", "deliverable", "constraints", "known", "done_when")
+
+#: The heading of each field's section in a task message.
+_HEADINGS = {
+ "objective": "Objective",
+ "deliverable": "Deliverable",
+ "constraints": "Constraints",
+ "known": "What is already known",
+ "done_when": "Done when",
+}
+
+#: What an inheriting sub-agent is told of the conversation it reads: whose it
+#: is, and which message is its task (Deep Agents' ``_FORK_TASK_PREAMBLE``,
+#: told the way ADK shows that conversation). ``task_message`` ends an
+#: inheriting type's task message with it, and ADK's delegation ends an
+#: inheriting sub-agent's instruction with it (``adk/delegation.py``), sent as
+#: written, as the whole prompt is (``manager._as_written``).
+INHERITED_CONTEXT_NOTE = (
+ "You are a sub-agent: another agent has handed you a task. The conversation "
+ "before the task is that agent's, shown so you know what has been established: "
+ "the user's messages in it were addressed to that agent, not to you, and what "
+ "that agent did is quoted, its call handing you this task included. Do not "
+ "carry out those messages yourself or answer as that agent. Your task is the "
+ "request that follows the conversation: complete it directly, and use the "
+ "specific facts, figures and identifiers already established in the "
+ "conversation rather than answering generically."
+)
+
+
+@dataclass(frozen=True)
+class Brief:
+ """What a parent gives a sub-agent run to work from.
+
+ Attributes:
+ title: A few words naming the task, for ``/agents`` and the status bar.
+ objective: What the run is to do.
+ deliverable: What to return, and in what form.
+ constraints: Limits on how to do it.
+ known: What the parent already knows that the run needs: facts
+ found, decisions made, file paths and URLs, what was tried.
+ done_when: The criteria for the task being done.
+ """
+
+ title: str
+ objective: str
+ deliverable: str | None = None
+ constraints: str | None = None
+ known: str | None = None
+ done_when: str | None = None
+
+ def fields(self) -> dict[str, str]:
+ """The filled fields (None and empty ones left out): the title first,
+ then ``BRIEF_FIELDS``' order."""
+ return {
+ name: value
+ for name in ("title", *BRIEF_FIELDS)
+ if (value := getattr(self, name))
+ }
+
+
+def task_message(brief: Brief, *, inherit: bool = False) -> str:
+ """The first message of the run ``brief`` starts.
+
+ ``# Task:
``, then a section for each filled field (its heading
+ line, then its text), one blank line apart. An inheriting type's
+ (``inherit``) ends with ``INHERITED_CONTEXT_NOTE``: that run reads its
+ parent's conversation before this message.
+ """
+ sections = [f"# Task: {brief.title}"]
+ sections += [
+ f"## {_HEADINGS[name]}\n{text}"
+ for name, text in brief.fields().items()
+ if name != "title"
+ ]
+ if inherit:
+ sections.append(INHERITED_CONTEXT_NOTE)
+ return "\n\n".join(sections)
diff --git a/tests/workflow/test_agent_brief.py b/tests/workflow/test_agent_brief.py
new file mode 100644
index 00000000..8a33b64d
--- /dev/null
+++ b/tests/workflow/test_agent_brief.py
@@ -0,0 +1,99 @@
+"""A delegation's brief and its task message (``workflow/agents/brief.py``).
+
+A brief has a title and an objective, and may say what to deliver, the
+constraints, what is already known and when the task is done. The task
+message lays the filled fields out under one heading each, and an inheriting
+type's ends with ``INHERITED_CONTEXT_NOTE``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from agentic_cli.workflow.agents.brief import (
+ BRIEF_FIELDS,
+ INHERITED_CONTEXT_NOTE,
+ Brief,
+ task_message,
+)
+
+
+class TestTheBrief:
+ def test_the_fields_in_their_order(self):
+ assert BRIEF_FIELDS == ("objective", "deliverable", "constraints", "known", "done_when")
+
+ def test_only_the_title_and_the_objective_are_needed(self):
+ brief = Brief(title="Find the paper", objective="Find it.")
+ assert (brief.deliverable, brief.constraints, brief.known, brief.done_when) == (
+ None, None, None, None,
+ )
+
+ def test_it_is_frozen(self):
+ with pytest.raises(dataclasses.FrozenInstanceError):
+ Brief(title="t", objective="o").title = "u" # type: ignore[misc]
+
+ def test_fields_are_the_filled_ones_title_first(self):
+ brief = Brief(title="T", objective="O", known="K", deliverable="D")
+ assert list(brief.fields().items()) == [
+ ("title", "T"), ("objective", "O"), ("deliverable", "D"), ("known", "K"),
+ ]
+
+ def test_an_empty_field_is_not_filled(self):
+ assert Brief(title="T", objective="O", constraints="").fields() == {
+ "title": "T", "objective": "O",
+ }
+
+
+class TestTheTaskMessage:
+ def test_a_title_and_an_objective(self):
+ message = task_message(Brief(title="Find the paper", objective="Find the 2017 paper."))
+ assert message == "# Task: Find the paper\n\n## Objective\nFind the 2017 paper."
+
+ def test_every_section_in_its_order(self):
+ brief = Brief(
+ title="T", objective="O", deliverable="D", constraints="C", known="K", done_when="W",
+ )
+ assert task_message(brief) == (
+ "# Task: T\n\n"
+ "## Objective\nO\n\n"
+ "## Deliverable\nD\n\n"
+ "## Constraints\nC\n\n"
+ "## What is already known\nK\n\n"
+ "## Done when\nW"
+ )
+
+ def test_a_section_only_when_filled(self):
+ message = task_message(Brief(title="T", objective="O", done_when="W"))
+ assert message == "# Task: T\n\n## Objective\nO\n\n## Done when\nW"
+ assert "## Deliverable" not in message and "## Constraints" not in message
+
+ def test_a_field_of_several_lines_is_kept_as_written(self):
+ message = task_message(Brief(title="T", objective="O", known="- a\n- b"))
+ assert message.endswith("## What is already known\n- a\n- b")
+
+ def test_an_inheriting_types_message_ends_with_the_note(self):
+ message = task_message(Brief(title="T", objective="O"), inherit=True)
+ assert message == f"# Task: T\n\n## Objective\nO\n\n{INHERITED_CONTEXT_NOTE}"
+
+ def test_a_fresh_types_message_has_no_note(self):
+ assert INHERITED_CONTEXT_NOTE not in task_message(Brief(title="T", objective="O"))
+
+
+class TestTheInheritedNote:
+ def test_adk_delegation_uses_this_one(self):
+ pytest.importorskip("google.adk")
+ from agentic_cli.workflow.adk import delegation
+
+ assert delegation.INHERITED_CONTEXT_NOTE is INHERITED_CONTEXT_NOTE
+
+ def test_its_text(self):
+ assert INHERITED_CONTEXT_NOTE.startswith(
+ "You are a sub-agent: another agent has handed you a task. The conversation "
+ "before the task is that agent's"
+ )
+ assert INHERITED_CONTEXT_NOTE.endswith(
+ "use the specific facts, figures and identifiers already established in the "
+ "conversation rather than answering generically."
+ )
From d97cae92051b9cf34c35f53044edd1dfb933a3eb Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:31:25 -0500
Subject: [PATCH 03/11] Sub-agents: brief_required and limits on AgentConfig
brief_required names the brief fields an agent asks a delegation to fill
(the title and the objective are always needed); limits are its own
AgentLimits, over the policy's field by field. Both follow inherit_context,
so a positional AgentConfig still binds. validate_agent_graph checks them
(rules 11-13: brief field names, an AgentLimits, neither on the root), and
the agent YAML takes both, its limits read strictly.
---
src/agentic_cli/workflow/agent_loader.py | 41 +++++++-
src/agentic_cli/workflow/config.py | 82 +++++++++++++++-
tests/workflow/test_agent_loader.py | 69 +++++++++++++
tests/workflow/test_subagent_config.py | 120 +++++++++++++++++++++++
tests/workflow/test_subagent_context.py | 5 +-
5 files changed, 313 insertions(+), 4 deletions(-)
create mode 100644 tests/workflow/test_subagent_config.py
diff --git a/src/agentic_cli/workflow/agent_loader.py b/src/agentic_cli/workflow/agent_loader.py
index 79f38055..f76cd832 100644
--- a/src/agentic_cli/workflow/agent_loader.py
+++ b/src/agentic_cli/workflow/agent_loader.py
@@ -20,6 +20,8 @@
instruction_file: prompts/researcher.md
tools: [web_search]
inherit_context: false # true: also see the coordinator's conversation
+ brief_required: [objective, deliverable] # what a delegation must fill
+ limits: {max_model_calls: 30, timeout: 600} # over the policy's, per field
A top-level bare list of agents (without the ``agents:`` key) is also accepted.
Tool entries stay as strings here and are resolved to callables when the
@@ -32,13 +34,41 @@
from typing import Any
import yaml
-from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
+from agentic_cli.workflow.agents.policy import AgentLimits
from agentic_cli.workflow.config import AgentConfig
from agentic_cli.workflow.mcp import MCPServerConfig
from agentic_cli.workflow.model_settings import ModelSettings
+class LimitsSpec(BaseModel):
+ """YAML schema for an agent's ``limits`` (mapped to ``AgentLimits``).
+
+ Strict: a value is read as the YAML wrote it, so ``true`` is no count and
+ ``'30'`` no number. ``AgentLimits`` refuses a limit that is not positive.
+ """
+
+ model_config = ConfigDict(extra="forbid", strict=True)
+
+ max_model_calls: int | None = None
+ timeout: float | None = None
+ max_tokens: int | None = None
+
+ @model_validator(mode="after")
+ def _are_limits(self) -> "LimitsSpec":
+ self.to_limits()
+ return self
+
+ def to_limits(self) -> AgentLimits:
+ """These limits as an ``AgentLimits``."""
+ return AgentLimits(
+ max_model_calls=self.max_model_calls,
+ timeout=self.timeout,
+ max_tokens=self.max_tokens,
+ )
+
+
class AgentSpec(BaseModel):
"""YAML schema for a single agent (validated, then mapped to AgentConfig)."""
@@ -60,6 +90,9 @@ class AgentSpec(BaseModel):
sub_agents: list[str] = Field(default_factory=list)
include_state_tools: bool = True
inherit_context: bool = False
+ # None: AgentConfig's own default.
+ brief_required: list[str] | None = None
+ limits: LimitsSpec | None = None
class AgentsFile(BaseModel):
@@ -131,6 +164,11 @@ def load_agents_from_yaml(path: str | Path) -> list[AgentConfig]:
configs: list[AgentConfig] = []
for spec in spec_file.agents:
+ delegation: dict[str, Any] = {}
+ if spec.brief_required is not None:
+ delegation["brief_required"] = tuple(spec.brief_required)
+ if spec.limits is not None:
+ delegation["limits"] = spec.limits.to_limits()
configs.append(
AgentConfig(
name=spec.name,
@@ -144,6 +182,7 @@ def load_agents_from_yaml(path: str | Path) -> list[AgentConfig]:
skills=list(spec.skills),
include_state_tools=spec.include_state_tools,
inherit_context=spec.inherit_context,
+ **delegation,
)
)
return configs
diff --git a/src/agentic_cli/workflow/config.py b/src/agentic_cli/workflow/config.py
index eb19dda7..72c2d93d 100644
--- a/src/agentic_cli/workflow/config.py
+++ b/src/agentic_cli/workflow/config.py
@@ -4,12 +4,22 @@
from dataclasses import dataclass, field
from typing import Callable, Any, TYPE_CHECKING
+from agentic_cli.workflow.agents.brief import BRIEF_FIELDS
+from agentic_cli.workflow.agents.policy import AgentLimits
+
if TYPE_CHECKING:
from agentic_cli.config import BaseSettings
from agentic_cli.workflow.model_settings import ModelSettings
from agentic_cli.workflow.mcp import MCPServerConfig
+#: The brief fields a delegation must fill unless an agent asks for more.
+_DEFAULT_BRIEF_REQUIRED = ("objective",)
+
+#: What ``brief_required`` may name: the title, or a brief field.
+_BRIEF_NAMES = ("title", *BRIEF_FIELDS)
+
+
@dataclass
class AgentConfig:
"""Configuration for an agent in the workflow.
@@ -50,6 +60,16 @@ class AgentConfig:
replies to the user. True only on sub-agents, and in 0.7.0 only
on the root's own sub-agents without sub-agents of their own
(``validate_agent_graph`` checks it).
+ brief_required: The brief fields a delegation to this agent must
+ fill (``workflow/agents/brief.py``: ``objective``,
+ ``deliverable``, ``constraints``, ``known``, ``done_when``, or
+ ``title``); a brief always needs its title and its objective,
+ so the default asks for nothing more. Only on sub-agents: the
+ root is never delegated to.
+ limits: This agent's own run limits (``AgentLimits``), over the
+ policy's (``SubAgentPolicy.limits``) field by field: a field
+ left None takes the policy's. None (the default) takes the
+ policy's as they are. Only on sub-agents.
"""
name: str
@@ -63,6 +83,8 @@ class AgentConfig:
skills: list[str] = field(default_factory=list)
include_state_tools: bool = True
inherit_context: bool = False
+ brief_required: tuple[str, ...] = _DEFAULT_BRIEF_REQUIRED
+ limits: AgentLimits | None = None
def get_prompt(self, settings: "BaseSettings | None" = None) -> str:
"""Get the prompt string, calling the factory if the prompt is callable.
@@ -193,7 +215,12 @@ def validate_agent_graph(
the root's own sub-agents. In 0.7.0 a forked Deep Agents coordinator
is told that delegating will be refused, which is false for ours, so
a real model might never delegate; and below another sub-agent ADK
- would show it the main agent's whole conversation.
+ would show it the main agent's whole conversation;
+ 11. each agent's ``brief_required`` is a tuple (or list) of brief field
+ names: ``title``, or one of ``BRIEF_FIELDS``;
+ 12. each agent's ``limits`` is None or an ``AgentLimits``;
+ 13. the root sets neither ``brief_required`` (beyond its default, the
+ objective) nor ``limits``: it is never delegated to.
Args:
configs: The declared agents.
@@ -268,6 +295,7 @@ def validate_agent_graph(
"the extra root(s) to a coordinator's sub_agents."
)
_check_inherit_context(config_map, roots[0])
+ _check_delegation_fields(config_map, roots[0])
return AgentGraph(config_map=config_map, build_order=order, root_name=roots[0])
@@ -329,6 +357,58 @@ def _check_inherit_context(config_map: dict[str, AgentConfig], root: str) -> Non
)
+def _check_delegation_fields(config_map: dict[str, AgentConfig], root: str) -> None:
+ """Each agent's ``brief_required`` and ``limits`` are what they say, and the root sets neither.
+
+ Raises:
+ AgentGraphError: Naming the agent(s), the value and what to change.
+ """
+ unknown = [
+ f"{name!r} ({config.brief_required!r})"
+ for name, config in config_map.items()
+ if not _names_brief_fields(config.brief_required)
+ ]
+ if unknown:
+ raise AgentGraphError(
+ f"brief_required must be a tuple of brief field names "
+ f"({', '.join(_BRIEF_NAMES)}): {', '.join(unknown)}."
+ )
+
+ not_limits = [
+ f"{name!r} ({config.limits!r})"
+ for name, config in config_map.items()
+ if config.limits is not None and not isinstance(config.limits, AgentLimits)
+ ]
+ if not_limits:
+ raise AgentGraphError(
+ f"limits must be an AgentLimits or None: {', '.join(not_limits)}. "
+ "Write limits=AgentLimits(max_model_calls=..., timeout=..., max_tokens=...)."
+ )
+
+ config = config_map[root]
+ on_root = [
+ name
+ for name, is_set in (
+ ("brief_required", tuple(config.brief_required) != _DEFAULT_BRIEF_REQUIRED),
+ ("limits", config.limits is not None),
+ )
+ if is_set
+ ]
+ if on_root:
+ raise AgentGraphError(
+ f"Agent {root!r} is the root agent, but sets {' and '.join(on_root)}: "
+ "they apply to a delegation, and the root is never delegated to. "
+ "Remove them from the root."
+ )
+
+
+def _names_brief_fields(value: object) -> bool:
+ """Whether ``value`` is a tuple or list of brief field names (a string is neither)."""
+ return isinstance(value, (tuple, list)) and all(
+ isinstance(name, str) and name in _BRIEF_NAMES for name in value
+ )
+
+
def _topological_order(config_map: dict[str, AgentConfig]) -> tuple[str, ...]:
"""Order agent names so each follows its sub-agents.
diff --git a/tests/workflow/test_agent_loader.py b/tests/workflow/test_agent_loader.py
index f12d8538..9f0bb41e 100644
--- a/tests/workflow/test_agent_loader.py
+++ b/tests/workflow/test_agent_loader.py
@@ -12,6 +12,7 @@
create_workflow_manager_from_yaml,
load_agents_from_yaml,
)
+from agentic_cli.workflow.agents.policy import AgentLimits
from agentic_cli.workflow.base_manager import BaseWorkflowManager
@@ -103,6 +104,8 @@ def test_defaults(self, tmp_path):
assert cfg.model_settings is None
assert cfg.include_state_tools is True
assert cfg.inherit_context is False
+ assert cfg.brief_required == ("objective",)
+ assert cfg.limits is None
def test_a_sub_agents_inherit_context(self, tmp_path):
path = _write(
@@ -148,6 +151,72 @@ def test_the_old_context_key_is_refused(self, tmp_path, value):
assert "agents.0.context" in message
assert "Extra inputs are not permitted" in message
+ def test_a_sub_agents_brief_and_limits(self, tmp_path):
+ path = _write(
+ tmp_path,
+ """
+ agents:
+ - name: coordinator
+ instruction: Lead.
+ sub_agents: [researcher]
+ - name: researcher
+ instruction: Find facts.
+ brief_required: [objective, deliverable]
+ limits: {max_model_calls: 30, timeout: 600, max_tokens: 200000}
+ """,
+ )
+ configs = {c.name: c for c in load_agents_from_yaml(path)}
+ assert configs["researcher"].brief_required == ("objective", "deliverable")
+ assert configs["researcher"].limits == AgentLimits(
+ max_model_calls=30, timeout=600, max_tokens=200_000
+ )
+ assert configs["coordinator"].brief_required == ("objective",)
+ assert configs["coordinator"].limits is None
+
+ def test_limits_may_name_some_of_their_fields(self, tmp_path):
+ path = _write(
+ tmp_path, "agents:\n - name: a\n instruction: hi\n limits: {timeout: 90.5}\n"
+ )
+ assert load_agents_from_yaml(path)[0].limits == AgentLimits(timeout=90.5)
+
+ @pytest.mark.parametrize("limits, field, why", [
+ ("{max_model_calls: 0}", "max_model_calls", "must be a positive int"),
+ # Read as the YAML wrote them: true is no count, '5' no number.
+ ("{max_model_calls: true}", "max_model_calls", "valid integer"),
+ ("{max_model_calls: '5'}", "max_model_calls", "valid integer"),
+ ("{timeout: -1}", "timeout", "must be a positive number"),
+ ("{timeout: '30'}", "timeout", "valid number"),
+ ("{max_tokens: 1.5}", "max_tokens", "valid integer"),
+ ])
+ def test_a_limit_that_is_no_limit_is_rejected(self, tmp_path, limits, field, why):
+ path = _write(
+ tmp_path, f"agents:\n - name: a\n instruction: hi\n limits: {limits}\n"
+ )
+ with pytest.raises(ValidationError) as exc:
+ load_agents_from_yaml(path)
+ message = str(exc.value)
+ assert "agents.0.limits" in message and field in message and why in message
+
+ def test_an_unknown_limit_is_rejected(self, tmp_path):
+ path = _write(
+ tmp_path, "agents:\n - name: a\n instruction: hi\n limits: {steps: 5}\n"
+ )
+ with pytest.raises(ValidationError) as exc:
+ load_agents_from_yaml(path)
+ message = str(exc.value)
+ assert "agents.0.limits.steps" in message
+ assert "Extra inputs are not permitted" in message
+
+ def test_brief_required_is_a_list(self, tmp_path):
+ path = _write(
+ tmp_path,
+ "agents:\n - name: a\n instruction: hi\n brief_required: deliverable\n",
+ )
+ with pytest.raises(ValidationError) as exc:
+ load_agents_from_yaml(path)
+ message = str(exc.value)
+ assert "agents.0.brief_required" in message and "valid list" in message
+
def test_missing_prompt_raises(self, tmp_path):
path = _write(tmp_path, "agents:\n - name: a\n")
with pytest.raises(ValueError, match="must set 'prompt'"):
diff --git a/tests/workflow/test_subagent_config.py b/tests/workflow/test_subagent_config.py
new file mode 100644
index 00000000..5eac7209
--- /dev/null
+++ b/tests/workflow/test_subagent_config.py
@@ -0,0 +1,120 @@
+"""A sub-agent type's delegation fields: ``AgentConfig.brief_required`` and ``AgentConfig.limits``.
+
+``brief_required`` names the brief fields a delegation to the type must fill
+(the title and the objective are always needed); ``limits`` are the type's
+run limits, over the policy's field by field. ``validate_agent_graph``
+checks both for every backend: ``brief_required`` names brief fields,
+``limits`` is an ``AgentLimits``, and the root sets neither, since it is
+never delegated to.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from agentic_cli.workflow.agents.policy import AgentLimits
+from agentic_cli.workflow.config import AgentConfig, AgentGraphError, validate_agent_graph
+
+
+def team(**fields: dict[str, object]) -> list[AgentConfig]:
+ """A lead with two sub-agents; ``fields`` sets an agent's fields by its name."""
+ configs = [
+ AgentConfig(name="lead", prompt="p", sub_agents=["researcher", "writer"]),
+ AgentConfig(name="researcher", prompt="p"),
+ AgentConfig(name="writer", prompt="p"),
+ ]
+ return [dataclasses.replace(c, **fields.get(c.name, {})) for c in configs]
+
+
+class TestTheFields:
+ def test_a_delegation_needs_the_objective_by_default(self):
+ assert AgentConfig(name="a", prompt="p").brief_required == ("objective",)
+
+ def test_no_limits_of_its_own_by_default(self):
+ assert AgentConfig(name="a", prompt="p").limits is None
+
+ def test_they_follow_inherit_context(self):
+ # Appended: a positional AgentConfig(...) written before them still binds.
+ names = [f.name for f in dataclasses.fields(AgentConfig)]
+ assert names[-3:] == ["inherit_context", "brief_required", "limits"]
+
+ def test_they_are_kept(self):
+ limits = AgentLimits(timeout=60)
+ config = AgentConfig(
+ name="a", prompt="p", brief_required=("objective", "deliverable"), limits=limits,
+ )
+ assert (config.brief_required, config.limits) == (("objective", "deliverable"), limits)
+
+
+class TestTheGraphChecks:
+ def test_a_sub_agent_may_ask_for_more_of_the_brief(self):
+ configs = team(researcher={"brief_required": ("objective", "deliverable", "done_when")})
+ assert validate_agent_graph(configs).root_name == "lead"
+
+ def test_the_title_may_be_named_too(self):
+ assert validate_agent_graph(team(writer={"brief_required": ("title",)})).root_name == "lead"
+
+ def test_a_sub_agent_may_ask_for_nothing_more(self):
+ assert validate_agent_graph(team(writer={"brief_required": ()})).root_name == "lead"
+
+ def test_a_list_is_taken_as_well(self):
+ configs = team(writer={"brief_required": ["objective", "known"]})
+ assert validate_agent_graph(configs).root_name == "lead"
+
+ def test_a_sub_agent_may_have_limits_of_its_own(self):
+ configs = team(researcher={"limits": AgentLimits(max_model_calls=10, timeout=120)})
+ assert validate_agent_graph(configs).root_name == "lead"
+
+ @pytest.mark.parametrize("value", [("objective", "goal"), ("Deliverable",), (1,)])
+ def test_brief_required_names_brief_fields(self, value):
+ with pytest.raises(AgentGraphError) as exc:
+ validate_agent_graph(team(writer={"brief_required": value}))
+ message = str(exc.value)
+ assert "brief_required" in message and "'writer'" in message and repr(value) in message
+ assert "title, objective, deliverable, constraints, known, done_when" in message
+
+ @pytest.mark.parametrize("value", ["objective", None, {"objective"}])
+ def test_brief_required_is_a_tuple_or_a_list(self, value):
+ # A string would be read letter by letter.
+ with pytest.raises(AgentGraphError) as exc:
+ validate_agent_graph(team(writer={"brief_required": value}))
+ message = str(exc.value)
+ assert "brief_required" in message and "'writer'" in message and repr(value) in message
+
+ @pytest.mark.parametrize("value", [{"timeout": 60}, 60, "fast"])
+ def test_limits_is_an_agent_limits(self, value):
+ with pytest.raises(AgentGraphError) as exc:
+ validate_agent_graph(team(researcher={"limits": value}))
+ message = str(exc.value)
+ assert "limits" in message and "'researcher'" in message and repr(value) in message
+ assert "AgentLimits" in message
+
+ def test_the_root_keeps_the_default_brief(self):
+ # The default is indistinguishable from not setting it.
+ configs = team(lead={"brief_required": ["objective"]})
+ assert validate_agent_graph(configs).root_name == "lead"
+
+ @pytest.mark.parametrize("fields, named", [
+ ({"brief_required": ("objective", "deliverable")}, "brief_required"),
+ ({"limits": AgentLimits(timeout=60)}, "limits"),
+ ({"brief_required": (), "limits": AgentLimits()}, "brief_required and limits"),
+ ])
+ def test_the_root_sets_neither(self, fields, named):
+ with pytest.raises(AgentGraphError) as exc:
+ validate_agent_graph(team(lead=fields))
+ message = str(exc.value)
+ assert "'lead'" in message and f"sets {named}" in message
+ assert "never delegated to" in message
+
+ def test_a_single_agent_is_a_root_too(self):
+ with pytest.raises(AgentGraphError, match="'solo'.*sets limits"):
+ validate_agent_graph(
+ [AgentConfig(name="solo", prompt="p", limits=AgentLimits(timeout=1))]
+ )
+
+ def test_the_inherit_context_checks_come_first(self):
+ configs = team(lead={"inherit_context": True, "limits": AgentLimits(timeout=1)})
+ with pytest.raises(AgentGraphError, match="inherit_context"):
+ validate_agent_graph(configs)
diff --git a/tests/workflow/test_subagent_context.py b/tests/workflow/test_subagent_context.py
index b9e45528..1e8ef154 100644
--- a/tests/workflow/test_subagent_context.py
+++ b/tests/workflow/test_subagent_context.py
@@ -46,9 +46,10 @@ class TestTheField:
def test_it_is_false_by_default(self):
assert AgentConfig(name="a", prompt="p").inherit_context is False
- def test_it_is_the_last_field(self):
+ def test_it_follows_the_fields_of_0_6(self):
# Appended, so a positional AgentConfig(...) written for 0.6 still binds.
- assert [f.name for f in dataclasses.fields(AgentConfig)][-1] == "inherit_context"
+ names = [f.name for f in dataclasses.fields(AgentConfig)]
+ assert names.index("inherit_context") == names.index("include_state_tools") + 1
def test_the_old_names_are_gone(self):
# Never released, so no alias: a config written against a develop
From 805228894bc16ac62f6a19acb20b6d52b3d66186 Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:31:57 -0500
Subject: [PATCH 04/11] Sub-agents: read a task call's brief; task's schema and
description
read_brief checks a task call against the types its caller may start and
the type's brief_required, and a BriefError's text is the call's error
result (the agent type, an argument task has no, a field that is not text,
the fields missing, in that order). task_parameters and task_description
are task's schema and description for both backends: what a delegation is,
that parallel calls run in parallel, each type with its description (The
agent., with a warning, for one without), and a place for the
limits in force (limit_sentences).
---
src/agentic_cli/workflow/agents/brief.py | 178 ++++++++++++++++-
tests/workflow/test_agent_brief.py | 237 ++++++++++++++++++++++-
2 files changed, 407 insertions(+), 8 deletions(-)
diff --git a/src/agentic_cli/workflow/agents/brief.py b/src/agentic_cli/workflow/agents/brief.py
index 0e194b4e..09151723 100644
--- a/src/agentic_cli/workflow/agents/brief.py
+++ b/src/agentic_cli/workflow/agents/brief.py
@@ -1,20 +1,64 @@
-"""A delegation's brief, and the task message a run starts from.
+"""A delegation's brief, the task message a run starts from, and the task tool's text.
A parent delegates with a brief: a title (a few words, for ``/agents`` and
the status bar) and an objective, and, where they help, what to deliver,
the constraints, what is already known and when the task is done
-(``BRIEF_FIELDS``). ``task_message`` lays a brief out as the first message
-of the run it starts (the system prompt stays the type's own); an
-inheriting type's ends with ``INHERITED_CONTEXT_NOTE``.
+(``BRIEF_FIELDS``). ``read_brief`` reads one from a ``task`` call's
+arguments, against the agent types the caller may start; a brief that cannot
+start a run is a ``BriefError``, whose text is the call's error result.
+``task_message`` lays a brief out as the first message of the run it starts
+(the system prompt stays the type's own); an inheriting type's ends with
+``INHERITED_CONTEXT_NOTE``. ``task_parameters`` and ``task_description`` are
+``task``'s schema and description, the same for both backends.
"""
from __future__ import annotations
+from collections.abc import Mapping
from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from agentic_cli.logging import Loggers
+
+if TYPE_CHECKING:
+ from agentic_cli.workflow.agents.policy import SubAgentPolicy
+ from agentic_cli.workflow.config import AgentConfig
+
+logger = Loggers.workflow()
#: A brief's fields besides its title, in the order a task message lays them out.
BRIEF_FIELDS = ("objective", "deliverable", "constraints", "known", "done_when")
+#: ``task``'s arguments, in the order its schema lists them.
+_ARGUMENTS = ("agent_type", "title", *BRIEF_FIELDS)
+
+#: What ``task``'s schema tells the model of each field of the brief.
+_FIELD_DESCRIPTIONS = {
+ "title": "A few words naming the task, shown to the user while it runs.",
+ "objective": "What the sub-agent is to do.",
+ "deliverable": "What to return and in what form.",
+ "constraints": "Limits on how to do it.",
+ "known": (
+ "What you already know that the sub-agent needs: facts found, decisions "
+ "made, file paths and URLs, what was tried."
+ ),
+ "done_when": "The criteria for the task to be done.",
+}
+
+#: The opening of ``task``'s description: what a delegation is.
+_DELEGATION = (
+ "Hand a task to a sub-agent. The sub-agent works on it on its own, with its own "
+ "tools, and returns its result to you as this call's result; the user does not "
+ "see it, so tell the user what it means yourself. Several task calls in one "
+ "response run in parallel."
+)
+
+#: What a sub-agent sees, in ``task``'s description.
+_WHAT_IT_SEES = (
+ "A sub-agent sees only the brief you write, unless its line below says it sees "
+ "this conversation: put in the brief everything it needs to know."
+)
+
#: The heading of each field's section in a task message.
_HEADINGS = {
"objective": "Objective",
@@ -42,6 +86,10 @@
)
+class BriefError(ValueError):
+ """A ``task`` call whose brief cannot start a run; its text is the call's error result."""
+
+
@dataclass(frozen=True)
class Brief:
"""What a parent gives a sub-agent run to work from.
@@ -90,3 +138,125 @@ def task_message(brief: Brief, *, inherit: bool = False) -> str:
if inherit:
sections.append(INHERITED_CONTEXT_NOTE)
return "\n\n".join(sections)
+
+
+def read_brief(
+ arguments: Mapping[str, Any], types: Mapping[str, AgentConfig]
+) -> tuple[AgentConfig, Brief]:
+ """The agent type and the brief of a ``task`` call.
+
+ ``types`` are the agents the caller may start, by name (never empty: an
+ agent without any has no ``task``). Each text is stripped, and an empty
+ one counts as missing. The title and the objective are always needed;
+ the type's ``brief_required`` may ask for more.
+
+ Raises:
+ BriefError: ``agent_type`` is missing or not one of ``types``, an
+ argument ``task`` does not have, a field that is not text, or a
+ field the type needs is missing: in that order, and the fields
+ named in the order ``task``'s schema lists them.
+ """
+ names = ", ".join(types)
+ agent_type = arguments.get("agent_type")
+ if not isinstance(agent_type, str) or not agent_type.strip():
+ raise BriefError(f"task needs agent_type: one of {names}.")
+ agent_type = agent_type.strip()
+ config = types.get(agent_type)
+ if config is None:
+ raise BriefError(
+ f"Unknown agent_type '{agent_type}': the agents you can delegate to are {names}."
+ )
+ for name in arguments:
+ if name not in _ARGUMENTS:
+ raise BriefError(f"task has no argument '{name}'.")
+
+ texts: dict[str, str] = {}
+ for name in ("title", *BRIEF_FIELDS):
+ value = arguments.get(name)
+ if value is None:
+ continue
+ if not isinstance(value, str):
+ raise BriefError(f"The brief's {name} must be text.")
+ if value.strip():
+ texts[name] = value.strip()
+ needed = {"title", "objective", *config.brief_required}
+ missing = [name for name in ("title", *BRIEF_FIELDS) if name in needed and name not in texts]
+ if missing:
+ raise BriefError(f"The brief for '{agent_type}' is missing: {', '.join(missing)}.")
+ return config, Brief(**texts)
+
+
+def task_parameters(types: Mapping[str, AgentConfig]) -> dict[str, Any]:
+ """``task``'s arguments, as a JSON schema object: both backends build its schema from this.
+
+ ``agent_type`` is one of ``types`` (the agents the caller may start), each
+ named in its description with what it does; then the brief's title and
+ fields. The type, the title and the objective are required: what else a
+ type needs of the brief is said in its line, and ``read_brief`` checks it.
+ """
+ lines = "\n".join(_type_line(name, config) for name, config in types.items())
+ properties: dict[str, Any] = {
+ "agent_type": {
+ "type": "string",
+ "enum": list(types),
+ "description": f"The agent to hand the task to:\n{lines}",
+ },
+ }
+ for name in ("title", *BRIEF_FIELDS):
+ properties[name] = {"type": "string", "description": _FIELD_DESCRIPTIONS[name]}
+ return {
+ "type": "object",
+ "properties": properties,
+ "required": ["agent_type", "title", "objective"],
+ }
+
+
+def task_description(types: Mapping[str, AgentConfig], policy: SubAgentPolicy) -> str:
+ """``task``'s description, as the model reads it.
+
+ What a delegation is (the sub-agent works on its own and returns its
+ result; several calls in one response run in parallel), what a sub-agent
+ sees (the brief alone, unless its type inherits the conversation), the
+ limits in force (``limit_sentences``), and each of ``types`` with its
+ description. A type without a description is offered as "The
+ agent.", with one warning logged for it.
+ """
+ paragraphs = [_DELEGATION, _WHAT_IT_SEES]
+ limits = limit_sentences(policy)
+ if limits:
+ paragraphs.append(" ".join(limits))
+ lines = "\n".join(_type_line(name, config, warn=True) for name, config in types.items())
+ paragraphs.append(f"The agents you can hand a task to:\n{lines}")
+ return "\n\n".join(paragraphs)
+
+
+def limit_sentences(policy: SubAgentPolicy) -> list[str]:
+ """The sentences of ``task``'s description that state the limits a delegation enforces.
+
+ One sentence for each limit the framework enforces on a delegation, with
+ the number ``policy`` sets, in the order they apply; none while no limit
+ is enforced.
+ """
+ return []
+
+
+def _type_line(name: str, config: AgentConfig, *, warn: bool = False) -> str:
+ """How ``task`` offers ``config``: ``- (): ``.
+
+ The notes say that an inheriting type sees the caller's conversation and
+ which brief fields the type needs beyond the title and the objective. A
+ type without a description is "The agent.", logged when ``warn``.
+ """
+ description = config.description.strip()
+ if not description:
+ if warn:
+ logger.warning("subagent_without_description", agent=name)
+ description = f"The {name} agent."
+ notes = []
+ if config.inherit_context:
+ notes.append("sees this conversation, so the brief need not repeat it")
+ more = [field for field in BRIEF_FIELDS[1:] if field in config.brief_required]
+ if more:
+ notes.append(f"its brief also needs: {', '.join(more)}")
+ head = f"- {name} ({'; '.join(notes)})" if notes else f"- {name}"
+ return f"{head}: {description}"
diff --git a/tests/workflow/test_agent_brief.py b/tests/workflow/test_agent_brief.py
index 8a33b64d..66ea90fd 100644
--- a/tests/workflow/test_agent_brief.py
+++ b/tests/workflow/test_agent_brief.py
@@ -1,23 +1,59 @@
-"""A delegation's brief and its task message (``workflow/agents/brief.py``).
+"""A delegation's brief, its task message and the task tool's text (``workflow/agents/brief.py``).
A brief has a title and an objective, and may say what to deliver, the
-constraints, what is already known and when the task is done. The task
-message lays the filled fields out under one heading each, and an inheriting
-type's ends with ``INHERITED_CONTEXT_NOTE``.
+constraints, what is already known and when the task is done. ``read_brief``
+reads one from a ``task`` call's arguments, against the agent types the
+caller may start, and a brief that cannot start a run is a ``BriefError``
+whose text is the call's error result. The task message lays the filled
+fields out under one heading each, and an inheriting type's ends with
+``INHERITED_CONTEXT_NOTE``. ``task_parameters`` and ``task_description`` are
+the tool's schema and description, which both backends build ``task`` from.
"""
from __future__ import annotations
import dataclasses
+import json
import pytest
+from agentic_cli.workflow.agents import brief as brief_module
from agentic_cli.workflow.agents.brief import (
BRIEF_FIELDS,
INHERITED_CONTEXT_NOTE,
Brief,
+ BriefError,
+ read_brief,
+ task_description,
task_message,
+ task_parameters,
)
+from agentic_cli.workflow.agents.policy import SubAgentPolicy
+from agentic_cli.workflow.config import AgentConfig
+
+RESEARCHER = AgentConfig(name="researcher", prompt="p", description="Finds facts.")
+WRITER = AgentConfig(
+ name="writer", prompt="p", description="Writes the report.",
+ brief_required=("objective", "done_when", "deliverable"),
+)
+NOTES = AgentConfig(name="notes", prompt="p", inherit_context=True)
+TYPES = {"researcher": RESEARCHER, "writer": WRITER}
+
+
+@pytest.fixture
+def logged(monkeypatch) -> list[dict]:
+ """Every log call of ``agents/brief.py``, with its level."""
+ events: list[dict] = []
+
+ class Recorder:
+ def __getattr__(self, level: str):
+ def log(event: str, **fields) -> None:
+ events.append({"event": event, "log_level": level, **fields})
+
+ return log
+
+ monkeypatch.setattr(brief_module, "logger", Recorder())
+ return events
class TestTheBrief:
@@ -97,3 +133,196 @@ def test_its_text(self):
"use the specific facts, figures and identifiers already established in the "
"conversation rather than answering generically."
)
+
+
+class TestReadBrief:
+ def test_a_brief_for_a_type(self):
+ config, brief = read_brief(
+ {"agent_type": "researcher", "title": "Find it", "objective": "Find the paper."}, TYPES,
+ )
+ assert config is RESEARCHER
+ assert brief == Brief(title="Find it", objective="Find the paper.")
+
+ def test_each_text_is_stripped_and_an_empty_one_left_out(self):
+ _, brief = read_brief({
+ "agent_type": " researcher ", "title": " Find it\n", "objective": "\tFind the paper. ",
+ "known": " ", "constraints": None, "done_when": " Found. ",
+ }, TYPES)
+ assert brief == Brief(title="Find it", objective="Find the paper.", done_when="Found.")
+
+ def test_the_arguments_are_left_as_they_were(self):
+ arguments = {"agent_type": "researcher", "title": " T ", "objective": " O "}
+ read_brief(arguments, TYPES)
+ assert arguments == {"agent_type": "researcher", "title": " T ", "objective": " O "}
+
+ def test_it_is_a_value_error(self):
+ assert issubclass(BriefError, ValueError)
+
+ @pytest.mark.parametrize("arguments", [
+ {"title": "T", "objective": "O"},
+ {"agent_type": "", "title": "T", "objective": "O"},
+ {"agent_type": " ", "title": "T", "objective": "O"},
+ {"agent_type": 3, "title": "T", "objective": "O"},
+ {"agent_type": None, "title": "T", "objective": "O"},
+ ])
+ def test_no_agent_type(self, arguments):
+ with pytest.raises(BriefError) as exc:
+ read_brief(arguments, TYPES)
+ assert str(exc.value) == "task needs agent_type: one of researcher, writer."
+
+ def test_an_unknown_agent_type(self):
+ with pytest.raises(BriefError) as exc:
+ read_brief({"agent_type": "coder", "title": "T", "objective": "O"}, TYPES)
+ assert str(exc.value) == (
+ "Unknown agent_type 'coder': the agents you can delegate to are researcher, writer."
+ )
+
+ def test_a_type_the_caller_may_not_start_is_unknown(self):
+ # ``types`` are the caller's own: another agent's sub-agent is not one.
+ with pytest.raises(BriefError, match="Unknown agent_type 'writer'"):
+ read_brief({"agent_type": "writer", "title": "T", "objective": "O"},
+ {"researcher": RESEARCHER})
+
+ def test_an_argument_task_does_not_have(self):
+ with pytest.raises(BriefError) as exc:
+ read_brief({"agent_type": "researcher", "title": "T", "objective": "O",
+ "subagent_type": "researcher", "prompt": "x"}, TYPES)
+ assert str(exc.value) == "task has no argument 'subagent_type'."
+
+ @pytest.mark.parametrize("field", ["title", "objective", "known"])
+ @pytest.mark.parametrize("value", [3, ["a"], {"a": 1}, True])
+ def test_a_field_that_is_not_text(self, field, value):
+ arguments = {"agent_type": "researcher", "title": "T", "objective": "O", field: value}
+ with pytest.raises(BriefError) as exc:
+ read_brief(arguments, TYPES)
+ assert str(exc.value) == f"The brief's {field} must be text."
+
+ def test_the_title_and_the_objective_are_always_needed(self):
+ with pytest.raises(BriefError) as exc:
+ read_brief({"agent_type": "researcher", "objective": " "}, TYPES)
+ assert str(exc.value) == "The brief for 'researcher' is missing: title, objective."
+
+ def test_a_type_asks_for_more_named_in_the_schemas_order(self):
+ with pytest.raises(BriefError) as exc:
+ read_brief({"agent_type": "writer", "title": "T", "objective": "O", "known": "K"}, TYPES)
+ assert str(exc.value) == "The brief for 'writer' is missing: deliverable, done_when."
+
+ def test_a_type_that_asks_for_nothing_more_still_needs_both(self):
+ types = {"free": AgentConfig(name="free", prompt="p", brief_required=())}
+ with pytest.raises(BriefError, match="missing: title, objective"):
+ read_brief({"agent_type": "free"}, types)
+
+ def test_the_agent_type_is_read_first(self):
+ with pytest.raises(BriefError, match="Unknown agent_type"):
+ read_brief({"agent_type": "coder", "nope": 1}, TYPES)
+
+ def test_an_unknown_argument_before_a_missing_field(self):
+ with pytest.raises(BriefError, match="no argument 'nope'"):
+ read_brief({"agent_type": "researcher", "nope": 1}, TYPES)
+
+
+class TestTaskParameters:
+ def test_the_schema(self):
+ schema = task_parameters({"researcher": RESEARCHER, "writer": WRITER, "notes": NOTES})
+ assert schema == {
+ "type": "object",
+ "properties": {
+ "agent_type": {
+ "type": "string",
+ "enum": ["researcher", "writer", "notes"],
+ "description": (
+ "The agent to hand the task to:\n"
+ "- researcher: Finds facts.\n"
+ "- writer (its brief also needs: deliverable, done_when): Writes the report.\n"
+ "- notes (sees this conversation, so the brief need not repeat it): "
+ "The notes agent."
+ ),
+ },
+ "title": {
+ "type": "string",
+ "description": "A few words naming the task, shown to the user while it runs.",
+ },
+ "objective": {"type": "string", "description": "What the sub-agent is to do."},
+ "deliverable": {"type": "string", "description": "What to return and in what form."},
+ "constraints": {"type": "string", "description": "Limits on how to do it."},
+ "known": {
+ "type": "string",
+ "description": (
+ "What you already know that the sub-agent needs: facts found, decisions "
+ "made, file paths and URLs, what was tried."
+ ),
+ },
+ "done_when": {"type": "string", "description": "The criteria for the task to be done."},
+ },
+ "required": ["agent_type", "title", "objective"],
+ }
+
+ def test_it_is_json(self):
+ schema = task_parameters(TYPES)
+ assert json.loads(json.dumps(schema)) == schema
+
+ def test_its_arguments_are_the_ones_read_brief_reads(self):
+ properties = task_parameters(TYPES)["properties"]
+ assert list(properties) == ["agent_type", "title", *BRIEF_FIELDS]
+
+ def test_it_warns_of_nothing(self, logged):
+ task_parameters({"notes": NOTES})
+ assert logged == []
+
+
+class TestTaskDescription:
+ def test_the_description(self, logged):
+ text = task_description(TYPES, SubAgentPolicy())
+ assert text == (
+ "Hand a task to a sub-agent. The sub-agent works on it on its own, with its own "
+ "tools, and returns its result to you as this call's result; the user does not "
+ "see it, so tell the user what it means yourself. Several task calls in one "
+ "response run in parallel.\n\n"
+ "A sub-agent sees only the brief you write, unless its line below says it sees "
+ "this conversation: put in the brief everything it needs to know.\n\n"
+ "The agents you can hand a task to:\n"
+ "- researcher: Finds facts.\n"
+ "- writer (its brief also needs: deliverable, done_when): Writes the report."
+ )
+ assert logged == []
+
+ def test_an_inheriting_type_says_so(self):
+ text = task_description({"notes": NOTES, "researcher": RESEARCHER}, SubAgentPolicy())
+ assert "- notes (sees this conversation, so the brief need not repeat it): " in text
+ assert "- researcher: Finds facts." in text
+
+ def test_a_type_without_a_description_is_named_and_warned_of_once(self, logged):
+ text = task_description({"notes": NOTES, "researcher": RESEARCHER}, SubAgentPolicy())
+ assert text.endswith(": The notes agent.\n- researcher: Finds facts.")
+ assert logged == [
+ {"event": "subagent_without_description", "log_level": "warning", "agent": "notes"},
+ ]
+
+ def test_a_blank_description_is_none(self, logged):
+ blank = dataclasses.replace(RESEARCHER, description=" ")
+ assert task_description({"researcher": blank}, SubAgentPolicy()).endswith(
+ "- researcher: The researcher agent."
+ )
+ assert [e["agent"] for e in logged] == ["researcher"]
+
+ def test_it_states_no_limit_while_none_is_in_force(self):
+ # The policy's numbers are configuration here; the description says
+ # only what a delegation enforces.
+ policy = SubAgentPolicy(max_active=2, max_runs_per_turn=3)
+ text = task_description(TYPES, policy)
+ assert text == task_description(TYPES, SubAgentPolicy())
+ assert brief_module.limit_sentences(policy) == []
+
+ def test_the_limits_in_force_are_one_paragraph_before_the_agents(self, monkeypatch):
+ seen: list[SubAgentPolicy] = []
+
+ def sentences(policy: SubAgentPolicy) -> list[str]:
+ seen.append(policy)
+ return [f"At most {policy.max_active} at once.", "One more limit."]
+
+ monkeypatch.setattr(brief_module, "limit_sentences", sentences)
+ policy = SubAgentPolicy(max_active=2)
+ paragraphs = task_description(TYPES, policy).split("\n\n")
+ assert paragraphs[2] == "At most 2 at once. One more limit."
+ assert paragraphs[3].startswith("The agents you can hand a task to:")
+ assert seen == [policy]
From 8aa1ce973b443289b43a1e684f201b76c7407c04 Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:32:14 -0500
Subject: [PATCH 05/11] Sub-agents: a delegation's result envelope
envelope() is a run's end as its parent reads it: success only for a
completed run, the instance and run, the status, partial, the final text
and a one-line error, and who cancelled a cancelled run. read_envelope()
finds one in a delegation's result as either backend carries it (a dict,
or its JSON text) and never raises. The limit and interruption errors are
constants here.
---
src/agentic_cli/workflow/agents/envelope.py | 106 ++++++++++++++
tests/workflow/test_agent_envelope.py | 152 ++++++++++++++++++++
2 files changed, 258 insertions(+)
create mode 100644 src/agentic_cli/workflow/agents/envelope.py
create mode 100644 tests/workflow/test_agent_envelope.py
diff --git a/src/agentic_cli/workflow/agents/envelope.py b/src/agentic_cli/workflow/agents/envelope.py
new file mode 100644
index 00000000..d6eac814
--- /dev/null
+++ b/src/agentic_cli/workflow/agents/envelope.py
@@ -0,0 +1,106 @@
+"""A delegation's result envelope: how a sub-agent run's end reaches its parent.
+
+A blocking delegation's tool result is its run's envelope::
+
+ {"success": true, "agent": "researcher-2", "run": "researcher-2#1",
+ "status": "completed", "partial": false, "result": "", "error": null}
+
+``success`` is true only for a completed run, partial or not; any other end
+(``failed``, ``refused``, ``cancelled``, ``interrupted``) has a one-line
+``error`` and whatever text the run produced in ``result``, and a cancelled
+run's also says who cancelled it (``cancelled_by``: ``parent``, ``user`` or
+``limit``). ``read_envelope`` finds an envelope in a delegation's result as
+either backend's ``TOOL_RESULT`` carries it.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from agentic_cli.workflow.agents.runs import RUN_CANCELLED, RUN_COMPLETED, RUN_END_STATUSES
+from agentic_cli.workflow.sessions import RunRef
+
+#: A run that reached its most model calls: completed, its answer partial.
+STEP_LIMIT_ERROR = "step limit reached"
+#: A run cancelled at its time limit.
+TIME_LIMIT_ERROR = "time limit reached"
+#: A run cancelled at its token limit.
+TOKEN_LIMIT_ERROR = "token limit reached"
+#: A run its turn stopped (Ctrl+C), or a process or a manager that ended under it.
+INTERRUPTED_ERROR = "interrupted before it finished"
+#: Who may cancel a run: its parent, the user, or one of its limits.
+CANCELLED_BY = frozenset({"parent", "user", "limit"})
+
+#: The keys every envelope has, in the order it lists them.
+_KEYS = ("success", "agent", "run", "status", "partial", "result", "error")
+
+
+def envelope(
+ ref: RunRef,
+ status: str,
+ *,
+ result: str = "",
+ partial: bool = False,
+ error: str | None = None,
+ cancelled_by: str | None = None,
+) -> dict[str, Any]:
+ """The envelope of the run ``ref``, ended with ``status``.
+
+ ``error`` is made one line (its whitespace runs, line breaks among them,
+ each one space). ``cancelled_by`` is given exactly when ``status`` is
+ ``cancelled``.
+
+ Raises:
+ ValueError: ``ref`` is the root's own work (no run), ``status`` is
+ no run's end, or ``cancelled_by`` is missing, misplaced or not
+ one of ``CANCELLED_BY``.
+ """
+ if ref.run is None:
+ raise ValueError("An envelope is a sub-agent run's; the root's own work has none.")
+ if status not in RUN_END_STATUSES:
+ raise ValueError(
+ f"An envelope is made at a run's end: {status!r} is not one of "
+ f"{', '.join(sorted(RUN_END_STATUSES))}."
+ )
+ if (status == RUN_CANCELLED) != (cancelled_by is not None):
+ raise ValueError(
+ "cancelled_by names who cancelled a cancelled run, and only a cancelled run: "
+ f"status {status!r}, cancelled_by {cancelled_by!r}."
+ )
+ if cancelled_by is not None and cancelled_by not in CANCELLED_BY:
+ raise ValueError(
+ f"cancelled_by must be one of {', '.join(sorted(CANCELLED_BY))}, not {cancelled_by!r}."
+ )
+ value: dict[str, Any] = {
+ "success": status == RUN_COMPLETED,
+ "agent": ref.instance,
+ "run": ref.run,
+ "status": status,
+ "partial": partial,
+ "result": result,
+ "error": None if error is None else " ".join(error.split()),
+ }
+ if cancelled_by is not None:
+ value["cancelled_by"] = cancelled_by
+ return value
+
+
+def read_envelope(value: Any) -> dict[str, Any] | None:
+ """The envelope in a delegation's result, as either backend's ``TOOL_RESULT`` carries it.
+
+ ``value`` is a dict (ADK's function response), or the JSON text of one
+ (a Deep Agents ``ToolMessage``'s content). A copy of it when it has the
+ envelope's keys; None for anything else: the error result of a call
+ that started no run, any other result, text that does not parse. Never
+ raises.
+ """
+ if isinstance(value, str):
+ try:
+ value = json.loads(value)
+ except (ValueError, RecursionError):
+ return None
+ if not isinstance(value, Mapping) or not all(key in value for key in _KEYS):
+ return None
+ return dict(value)
diff --git a/tests/workflow/test_agent_envelope.py b/tests/workflow/test_agent_envelope.py
new file mode 100644
index 00000000..4a040be7
--- /dev/null
+++ b/tests/workflow/test_agent_envelope.py
@@ -0,0 +1,152 @@
+"""A delegation's result envelope (``workflow/agents/envelope.py``).
+
+A blocking delegation returns its run's envelope: whether it succeeded (only
+a completed run did, partial or not), its instance and run, its status,
+whether its answer is partial, its final text and a one-line error, and for
+a cancelled run who cancelled it. ``read_envelope`` finds one in a
+delegation's result as either backend's ``TOOL_RESULT`` carries it (a dict,
+or the JSON text of one), and never raises.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from agentic_cli.workflow.agents.envelope import (
+ CANCELLED_BY,
+ INTERRUPTED_ERROR,
+ STEP_LIMIT_ERROR,
+ TIME_LIMIT_ERROR,
+ TOKEN_LIMIT_ERROR,
+ envelope,
+ read_envelope,
+)
+from agentic_cli.workflow.agents.runs import (
+ RUN_CANCELLED,
+ RUN_COMPLETED,
+ RUN_FAILED,
+ RUN_INTERRUPTED,
+ RUN_REFUSED,
+ RUN_STARTED,
+)
+from agentic_cli.workflow.sessions import RunRef, root_run
+
+RESEARCHER = RunRef("researcher", "researcher-2", "researcher-2#1", None, 1)
+
+
+class TestTheTexts:
+ def test_the_errors(self):
+ assert STEP_LIMIT_ERROR == "step limit reached"
+ assert TIME_LIMIT_ERROR == "time limit reached"
+ assert TOKEN_LIMIT_ERROR == "token limit reached"
+ assert INTERRUPTED_ERROR == "interrupted before it finished"
+
+ def test_who_cancels(self):
+ assert CANCELLED_BY == frozenset({"parent", "user", "limit"})
+
+
+class TestEnvelope:
+ def test_a_completed_run(self):
+ assert envelope(RESEARCHER, RUN_COMPLETED, result="Found it.") == {
+ "success": True, "agent": "researcher-2", "run": "researcher-2#1",
+ "status": "completed", "partial": False, "result": "Found it.", "error": None,
+ }
+
+ def test_the_keys_in_their_order(self):
+ assert list(envelope(RESEARCHER, RUN_COMPLETED)) == [
+ "success", "agent", "run", "status", "partial", "result", "error",
+ ]
+
+ def test_a_partial_answer_is_a_success(self):
+ value = envelope(RESEARCHER, RUN_COMPLETED, result="So far…", partial=True,
+ error=STEP_LIMIT_ERROR)
+ assert (value["success"], value["partial"], value["error"]) == (
+ True, True, "step limit reached",
+ )
+
+ @pytest.mark.parametrize("status", [RUN_FAILED, RUN_REFUSED, RUN_INTERRUPTED])
+ def test_any_other_end_is_no_success(self, status):
+ value = envelope(RESEARCHER, status, result="half", error="why")
+ assert (value["success"], value["status"], value["result"], value["error"]) == (
+ False, status, "half", "why",
+ )
+ assert "cancelled_by" not in value
+
+ @pytest.mark.parametrize("by", ["parent", "user", "limit"])
+ def test_a_cancelled_run_says_who_cancelled_it(self, by):
+ value = envelope(RESEARCHER, RUN_CANCELLED, result="so far", error=TIME_LIMIT_ERROR,
+ cancelled_by=by)
+ assert value == {
+ "success": False, "agent": "researcher-2", "run": "researcher-2#1",
+ "status": "cancelled", "partial": False, "result": "so far",
+ "error": "time limit reached", "cancelled_by": by,
+ }
+
+ def test_the_error_is_one_line(self):
+ value = envelope(RESEARCHER, RUN_FAILED, error="400 Bad Request:\n {\"error\":\n \"bad\"}\n")
+ assert value["error"] == '400 Bad Request: {"error": "bad"}'
+
+ def test_it_is_json(self):
+ value = envelope(RESEARCHER, RUN_CANCELLED, cancelled_by="user", error="stopped")
+ assert json.loads(json.dumps(value)) == value
+
+ def test_the_root_has_none(self):
+ with pytest.raises(ValueError, match="sub-agent run"):
+ envelope(root_run("lead"), RUN_COMPLETED)
+
+ @pytest.mark.parametrize("status", [RUN_STARTED, "running", "done"])
+ def test_only_a_runs_end(self, status):
+ with pytest.raises(ValueError, match=repr(status)):
+ envelope(RESEARCHER, status)
+
+ def test_a_cancelled_run_needs_who_cancelled_it(self):
+ with pytest.raises(ValueError, match="cancelled_by"):
+ envelope(RESEARCHER, RUN_CANCELLED)
+
+ def test_who_cancelled_is_one_of_three(self):
+ with pytest.raises(ValueError, match="'model'"):
+ envelope(RESEARCHER, RUN_CANCELLED, cancelled_by="model")
+
+ def test_only_a_cancelled_run_names_who_cancelled_it(self):
+ with pytest.raises(ValueError, match="cancelled_by"):
+ envelope(RESEARCHER, RUN_FAILED, cancelled_by="user")
+
+
+class TestReadEnvelope:
+ def test_a_dict(self):
+ value = envelope(RESEARCHER, RUN_COMPLETED, result="Found it.")
+ assert read_envelope(value) == value
+
+ def test_its_json_text(self):
+ value = envelope(RESEARCHER, RUN_CANCELLED, cancelled_by="parent", error="stopped")
+ assert read_envelope(json.dumps(value)) == value
+ assert read_envelope(f" {json.dumps(value)}\n") == value
+
+ def test_a_copy(self):
+ value = envelope(RESEARCHER, RUN_COMPLETED)
+ read = read_envelope(value)
+ assert read == value and read is not value
+
+ def test_a_cut_envelope_is_still_one(self):
+ # The tool result cap keeps a dict's keys and adds its note.
+ value = {**envelope(RESEARCHER, RUN_COMPLETED, result="…"), "truncated": "see file"}
+ assert read_envelope(value) == value
+
+ @pytest.mark.parametrize("value", [
+ {"success": False, "error": "task needs agent_type: one of researcher."},
+ {"result": "Found it."},
+ "Found it.",
+ "{not json",
+ "[1, 2]",
+ "null",
+ "",
+ None,
+ 42,
+ ["success", "agent", "run", "status", "partial", "result", "error"],
+ b'{"success": true}',
+ "[" * 100_000,
+ ])
+ def test_anything_else_is_none(self, value):
+ assert read_envelope(value) is None
From 101dca211fdf0b4623ac0d7bc71c1354bcff9f2f Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:33:43 -0500
Subject: [PATCH 06/11] Sub-agents: every manager keeps the policy it is built
with
BaseWorkflowManager takes subagents= (keyword; a SubAgentPolicy, None for
the default) and keeps it as subagent_policy, read-only and provisional,
for its life, a model switch included. The ADK and Deep Agents managers
pass it on; the LangGraph manager takes it too and its delegation leaves it
unread. The factory checks it before it imports a backend and passes it to
whichever backend it builds, a native ADK app's too.
---
src/agentic_cli/workflow/adk/manager.py | 6 +
src/agentic_cli/workflow/base_manager.py | 24 +++
.../workflow/deepagents/manager.py | 6 +
src/agentic_cli/workflow/factory.py | 11 ++
src/agentic_cli/workflow/langgraph/manager.py | 7 +
.../workflow/test_subagent_policy_plumbing.py | 144 ++++++++++++++++++
6 files changed, 198 insertions(+)
create mode 100644 tests/workflow/test_subagent_policy_plumbing.py
diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py
index 31fc1a1a..e2dfd204 100644
--- a/src/agentic_cli/workflow/adk/manager.py
+++ b/src/agentic_cli/workflow/adk/manager.py
@@ -88,6 +88,7 @@
from agentic_cli.models import Provider, ResolvedModel, RoleMap
from agentic_cli.workflow.adk.build import ADKBuild
+ from agentic_cli.workflow.agents.policy import SubAgentPolicy
from agentic_cli.workflow.sessions import SessionRef
@@ -210,6 +211,8 @@ def __init__(
model: str | None = None,
on_event: Callable[[WorkflowEvent], WorkflowEvent | None] | None = None,
adk_config_path: str | None = None,
+ *,
+ subagents: SubAgentPolicy | None = None,
) -> None:
"""Initialize the workflow manager.
@@ -230,6 +233,8 @@ def __init__(
differs: the app runs as one built from configs
(``workflow/adk/build.py``). Library-only for now: no
``BaseCLIApp`` starts such an app.
+ subagents: How the sub-agents run (``subagent_policy``); None is
+ ``SubAgentPolicy()`` (see ``BaseWorkflowManager``).
"""
if adk_config_path and agent_configs:
# ADK builds the agents from the YAML: configs beside it would be
@@ -246,6 +251,7 @@ def __init__(
app_name=app_name,
model=model,
on_event=on_event,
+ subagents=subagents,
)
_check_app_name(self.app_name)
self._adk_config_path = adk_config_path
diff --git a/src/agentic_cli/workflow/base_manager.py b/src/agentic_cli/workflow/base_manager.py
index 0e511294..04c89436 100644
--- a/src/agentic_cli/workflow/base_manager.py
+++ b/src/agentic_cli/workflow/base_manager.py
@@ -49,6 +49,7 @@
resolve_model,
)
from agentic_cli.workflow.config import AgentConfig
+from agentic_cli.workflow.agents.policy import SubAgentPolicy, as_policy
from agentic_cli.workflow.agents.runs import AgentRuns
from agentic_cli.workflow.usage import (
PURPOSE_MEMORY_EXTRACTION,
@@ -371,6 +372,11 @@ async def process(self, message, user_id, session_id=None):
#: None outside one. A class default, as ``_keeping_store`` is.
_services_closing: "list[asyncio.Future[None]] | None" = None
+ #: How this manager's sub-agents run (``subagent_policy``): the one
+ #: ``__init__`` was given. A class default, so a manager made without
+ #: ``__init__`` (a test harness's ``__new__``) has the default policy.
+ _subagent_policy: SubAgentPolicy = SubAgentPolicy()
+
def __init__(
self,
agent_configs: list[AgentConfig],
@@ -378,6 +384,8 @@ def __init__(
app_name: str | None = None,
model: str | None = None,
on_event: Callable[[WorkflowEvent], WorkflowEvent | None] | None = None,
+ *,
+ subagents: SubAgentPolicy | None = None,
) -> None:
"""Initialize the workflow manager base.
@@ -399,9 +407,15 @@ def __init__(
default-tier model in ``settings.models``, else of the first
provider with a key.
on_event: Optional hook to transform/filter events before yielding.
+ subagents: How this manager's sub-agents run
+ (``subagent_policy``); None is ``SubAgentPolicy()``.
+
+ Raises:
+ TypeError: ``subagents`` is neither a ``SubAgentPolicy`` nor None.
"""
from agentic_cli.config import get_settings
+ self._subagent_policy = as_policy(subagents)
self._agent_configs = agent_configs
self._settings = settings or get_settings()
self._app_name = app_name or self._settings.app_name
@@ -514,6 +528,16 @@ def agent_configs(self) -> list[AgentConfig]:
"""Get the agent configurations."""
return self._agent_configs
+ @property
+ def subagent_policy(self) -> SubAgentPolicy:
+ """How this manager's sub-agents run (provisional): the ``subagents=``
+ it was built with, ``SubAgentPolicy()`` without one.
+
+ Read-only: a manager keeps its policy for its life, a model switch
+ (``reinitialize``) included; another policy is another manager's.
+ """
+ return self._subagent_policy
+
@property
def agent_runs(self) -> AgentRuns:
"""This manager's sub-agent runs, kept by conversation (provisional).
diff --git a/src/agentic_cli/workflow/deepagents/manager.py b/src/agentic_cli/workflow/deepagents/manager.py
index 9ccc0aec..9cf9a283 100644
--- a/src/agentic_cli/workflow/deepagents/manager.py
+++ b/src/agentic_cli/workflow/deepagents/manager.py
@@ -93,6 +93,7 @@
from langgraph.checkpoint.base import BaseCheckpointSaver
from langgraph.graph.state import CompiledStateGraph
+ from agentic_cli.workflow.agents.policy import SubAgentPolicy
from agentic_cli.workflow.sessions import SessionInfo, SessionRef
logger = Loggers.workflow()
@@ -133,6 +134,8 @@ def __init__(
app_name: str | None = None,
model: str | None = None,
on_event: Callable[[WorkflowEvent], WorkflowEvent | None] | None = None,
+ *,
+ subagents: SubAgentPolicy | None = None,
) -> None:
"""Initialize the workflow manager.
@@ -145,6 +148,8 @@ def __init__(
or a model id (see ``BaseWorkflowManager``).
on_event: Optional hook to transform or drop events before they
are yielded.
+ subagents: How the sub-agents run (``subagent_policy``); None is
+ ``SubAgentPolicy()`` (see ``BaseWorkflowManager``).
"""
super().__init__(
agent_configs=agent_configs,
@@ -152,6 +157,7 @@ def __init__(
app_name=app_name,
model=model,
on_event=on_event,
+ subagents=subagents,
)
# The checkpointer, and what owns its connection and the session
diff --git a/src/agentic_cli/workflow/factory.py b/src/agentic_cli/workflow/factory.py
index d06e8f87..a22c7d2d 100644
--- a/src/agentic_cli/workflow/factory.py
+++ b/src/agentic_cli/workflow/factory.py
@@ -15,10 +15,12 @@
from typing import TYPE_CHECKING, Any, Callable
from agentic_cli.logging import Loggers
+from agentic_cli.workflow.agents.policy import as_policy
from agentic_cli.workflow.settings import OrchestratorType
if TYPE_CHECKING:
from agentic_cli.config import BaseSettings
+ from agentic_cli.workflow.agents.policy import SubAgentPolicy
from agentic_cli.workflow.base_manager import BaseWorkflowManager
from agentic_cli.workflow.config import AgentConfig
@@ -127,6 +129,8 @@ def create_workflow_manager_from_settings(
adk_config_mode: str = "native",
orchestrator: "str | OrchestratorType | None" = None,
session_store: str | None = None,
+ *,
+ subagents: "SubAgentPolicy | None" = None,
**kwargs,
) -> "BaseWorkflowManager":
"""Factory function to create the appropriate workflow manager based on settings.
@@ -153,12 +157,16 @@ def create_workflow_manager_from_settings(
session_store: The session store the manager keeps conversations in
(``BaseWorkflowManager.session_store``), when it is not the one
the settings name: a CLI run keeps the store it started with.
+ subagents: How the manager's sub-agents run (a ``SubAgentPolicy``;
+ None is ``SubAgentPolicy()``), passed to whichever backend it builds.
**kwargs: Additional arguments passed to the specific manager.
Returns:
The orchestrator's ``BaseWorkflowManager``.
Raises:
+ TypeError: ``subagents`` is no ``SubAgentPolicy``, before any backend
+ is imported.
ImportError: If the orchestrator's extra is not installed.
ValueError: ``orchestrator`` is no orchestrator.
@@ -167,6 +175,7 @@ def create_workflow_manager_from_settings(
configs = [AgentConfig(name="agent", prompt="...")]
manager = create_workflow_manager_from_settings(configs, settings)
"""
+ policy = as_policy(subagents)
orchestrator = (
orchestrator_of(settings) if orchestrator is None else OrchestratorType(orchestrator)
)
@@ -191,6 +200,7 @@ def create_workflow_manager_from_settings(
app_name=app_name,
model=model,
adk_config_path=adk_config_path,
+ subagents=policy,
**kwargs,
), session_store)
@@ -200,6 +210,7 @@ def create_workflow_manager_from_settings(
settings=settings,
app_name=app_name,
model=model,
+ subagents=policy,
**_backend_kwargs(orchestrator, settings, session_store),
**kwargs,
), session_store)
diff --git a/src/agentic_cli/workflow/langgraph/manager.py b/src/agentic_cli/workflow/langgraph/manager.py
index c5d87afb..99758b6b 100644
--- a/src/agentic_cli/workflow/langgraph/manager.py
+++ b/src/agentic_cli/workflow/langgraph/manager.py
@@ -33,6 +33,7 @@
if TYPE_CHECKING:
from agentic_cli.config import BaseSettings
+ from agentic_cli.workflow.agents.policy import SubAgentPolicy
logger = Loggers.workflow()
@@ -114,6 +115,8 @@ def __init__(
model: str | None = None,
checkpointer: Literal["memory", "postgres", "sqlite"] | None = "memory",
on_event: Callable[[WorkflowEvent], WorkflowEvent | None] | None = None,
+ *,
+ subagents: SubAgentPolicy | None = None,
) -> None:
"""Initialize the LangGraph workflow manager.
@@ -128,6 +131,9 @@ def __init__(
"memory" for in-memory, "postgres" for PostgreSQL,
"sqlite" for SQLite. None to disable checkpointing.
on_event: Optional hook to transform/filter events before yielding.
+ subagents: Taken as the other backends take it, and kept
+ (``subagent_policy``); LangGraph's own delegation does not
+ read it.
"""
# First, so a manager that fails to build still says it is deprecated;
# blamed on the caller, whose module Python's filters then judge.
@@ -138,6 +144,7 @@ def __init__(
app_name=app_name,
model=model,
on_event=on_event,
+ subagents=subagents,
)
# LangGraph's gate tracks no outside content: every memory write asks.
self._outside_marks = OutsideContentMarks(always=LANGGRAPH_MARK)
diff --git a/tests/workflow/test_subagent_policy_plumbing.py b/tests/workflow/test_subagent_policy_plumbing.py
new file mode 100644
index 00000000..bfd4db2a
--- /dev/null
+++ b/tests/workflow/test_subagent_policy_plumbing.py
@@ -0,0 +1,144 @@
+"""Every workflow manager keeps the sub-agent policy it is built with (``subagents=``).
+
+``BaseWorkflowManager`` takes ``subagents=`` (a ``SubAgentPolicy``, or None
+for ``SubAgentPolicy()``) and keeps it as ``subagent_policy``, read-only;
+the ADK and Deep Agents managers pass it on, and the LangGraph manager takes
+it too, which its own delegation leaves unread. The factory passes it to
+whichever backend it builds. A value that is no policy is a ``TypeError``
+where it is passed: the factory's comes before any backend is imported.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+
+import pytest
+
+pytest.importorskip("google.adk")
+
+from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402
+from agentic_cli.workflow.agents.policy import AgentLimits, SubAgentPolicy # noqa: E402
+from agentic_cli.workflow.config import AgentConfig # noqa: E402
+from agentic_cli.workflow.factory import create_workflow_manager_from_settings # noqa: E402
+from agentic_cli.workflow.settings import OrchestratorType # noqa: E402
+from tests.conftest import MockContext # noqa: E402
+
+POLICY = SubAgentPolicy(max_active=2, max_runs_per_turn=5, limits=AgentLimits(timeout=60))
+CONFIGS = [AgentConfig(name="solo", prompt="p")]
+
+
+def _needs(extra: str):
+ return pytest.mark.skipif(
+ importlib.util.find_spec(extra) is None, reason=f"needs the {extra} extra"
+ )
+
+
+def adk() -> type:
+ return GoogleADKWorkflowManager
+
+
+def deepagents() -> type:
+ from agentic_cli.workflow.deepagents import DeepAgentsWorkflowManager
+
+ return DeepAgentsWorkflowManager
+
+
+def langgraph() -> type:
+ from agentic_cli.workflow.langgraph import LangGraphWorkflowManager
+
+ return LangGraphWorkflowManager
+
+
+BACKENDS = [
+ pytest.param(adk, id="adk"),
+ pytest.param(deepagents, id="deepagents", marks=_needs("deepagents")),
+ pytest.param(langgraph, id="langgraph", marks=_needs("langgraph")),
+]
+ORCHESTRATORS = [
+ pytest.param(OrchestratorType.ADK, id="adk"),
+ pytest.param(OrchestratorType.DEEPAGENTS, id="deepagents", marks=_needs("deepagents")),
+ pytest.param(OrchestratorType.LANGGRAPH, id="langgraph", marks=_needs("langgraph")),
+]
+
+
+class TestTheManager:
+ @pytest.mark.parametrize("backend", BACKENDS)
+ def test_it_keeps_the_policy_it_is_given(self, backend, mock_context):
+ manager = backend()(agent_configs=CONFIGS, settings=mock_context.settings, subagents=POLICY)
+ assert manager.subagent_policy is POLICY
+
+ @pytest.mark.parametrize("backend", BACKENDS)
+ def test_without_one_it_has_the_default(self, backend, mock_context):
+ manager = backend()(agent_configs=CONFIGS, settings=mock_context.settings)
+ assert manager.subagent_policy == SubAgentPolicy()
+
+ @pytest.mark.parametrize("backend", BACKENDS)
+ def test_none_is_the_default(self, backend, mock_context):
+ manager = backend()(agent_configs=CONFIGS, settings=mock_context.settings, subagents=None)
+ assert manager.subagent_policy == SubAgentPolicy()
+
+ @pytest.mark.parametrize("backend", BACKENDS)
+ def test_a_value_that_is_no_policy_is_a_type_error(self, backend, mock_context):
+ with pytest.raises(TypeError, match="subagents must be a SubAgentPolicy or None, not dict"):
+ backend()(agent_configs=CONFIGS, settings=mock_context.settings,
+ subagents={"max_active": 2})
+
+ def test_it_is_read_only(self, mock_context):
+ manager = GoogleADKWorkflowManager(agent_configs=CONFIGS, settings=mock_context.settings)
+ with pytest.raises(AttributeError):
+ manager.subagent_policy = POLICY # type: ignore[misc]
+
+ def test_a_manager_made_without_its_constructor_has_the_default(self):
+ # A test harness's ``__new__``.
+ manager = GoogleADKWorkflowManager.__new__(GoogleADKWorkflowManager)
+ assert manager.subagent_policy == SubAgentPolicy()
+
+ async def test_a_model_switch_keeps_it(self, monkeypatch, tmp_path):
+ monkeypatch.chdir(tmp_path)
+ with MockContext(google_api_key="a-test-key") as context:
+ manager = GoogleADKWorkflowManager(
+ agent_configs=CONFIGS, settings=context.settings, model="gemini-2.5-flash",
+ subagents=POLICY,
+ )
+ await manager.initialize_services()
+ try:
+ await manager.reinitialize(model="gemini-2.5-pro", preserve_sessions=True)
+ assert manager.is_initialized
+ assert manager.subagent_policy is POLICY
+ finally:
+ await manager.cleanup()
+
+
+class TestTheFactory:
+ @pytest.mark.parametrize("orchestrator", ORCHESTRATORS)
+ def test_the_backend_it_builds_gets_the_policy(self, orchestrator, mock_context):
+ manager = create_workflow_manager_from_settings(
+ CONFIGS, mock_context.settings, orchestrator=orchestrator, subagents=POLICY,
+ )
+ assert manager.backend_type == orchestrator.value
+ assert manager.subagent_policy is POLICY
+
+ def test_without_one_the_default(self, mock_context):
+ manager = create_workflow_manager_from_settings(CONFIGS, mock_context.settings)
+ assert manager.subagent_policy == SubAgentPolicy()
+
+ def test_a_native_adk_app_gets_it_too(self, tmp_path, mock_context):
+ manager = create_workflow_manager_from_settings(
+ [], mock_context.settings, adk_config_path=str(tmp_path / "root_agent.yaml"),
+ subagents=POLICY,
+ )
+ assert isinstance(manager, GoogleADKWorkflowManager)
+ assert manager.subagent_policy is POLICY
+
+ @_needs("deepagents")
+ def test_a_value_that_is_no_policy_fails_before_a_backend_is_imported(
+ self, monkeypatch, mock_context
+ ):
+ # Without the extra, the backend's import would fail with the
+ # install hint: the wrong argument is named first.
+ monkeypatch.setitem(sys.modules, "agentic_cli.workflow.deepagents", None)
+ with pytest.raises(TypeError, match="subagents must be a SubAgentPolicy or None, not int"):
+ create_workflow_manager_from_settings(
+ CONFIGS, mock_context.settings, orchestrator="deepagents", subagents=4,
+ )
From 43d87137daf24819611a0833f2eabb59608fb4d1 Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:34:46 -0500
Subject: [PATCH 07/11] Sub-agents: an app's policy reaches every manager it
builds
BaseCLIApp takes subagents= and hands it to its WorkflowController, which
passes it to each manager it builds: the first start's, and the one a
conversation on another backend starts, whether the workflow runs or is
down. A value that is no policy is a TypeError before the app builds
anything. The factory's test fakes take the new keyword.
---
src/agentic_cli/cli/app.py | 12 ++-
src/agentic_cli/cli/workflow_controller.py | 13 +++
tests/cli/test_conversation_switch.py | 2 +-
tests/cli/test_resume_on_its_backend.py | 2 +-
tests/cli/test_subagent_policy.py | 111 +++++++++++++++++++++
5 files changed, 137 insertions(+), 3 deletions(-)
create mode 100644 tests/cli/test_subagent_policy.py
diff --git a/src/agentic_cli/cli/app.py b/src/agentic_cli/cli/app.py
index d1bae4e4..6cf8de35 100644
--- a/src/agentic_cli/cli/app.py
+++ b/src/agentic_cli/cli/app.py
@@ -67,6 +67,7 @@
from agentic_cli.config import BaseSettings
from agentic_cli.logging import Loggers, configure_logging, log_lines_to
from agentic_cli.workflow.adk.log_filters import install_log_filters
+from agentic_cli.workflow.agents.policy import as_policy
from agentic_cli.workflow.factory import check_backend, orchestrator_of
from agentic_cli.workflow.session_readers import reader_backends
from agentic_cli.workflow.settings import OrchestratorType
@@ -80,6 +81,7 @@
from agentic_cli.cli.job_monitor import JobMonitor
from agentic_cli.settings_persistence import SettingsSaveResult
from agentic_cli.workflow import GoogleADKWorkflowManager, EventType, WorkflowEvent
+ from agentic_cli.workflow.agents.policy import SubAgentPolicy
from agentic_cli.workflow.base_manager import BaseWorkflowManager
from agentic_cli.workflow.context import CompactResult
from agentic_cli.workflow.sessions import SessionInfo
@@ -341,6 +343,8 @@ def __init__(
agent_configs: list["AgentConfig"],
settings: BaseSettings,
session_id: str | None = None,
+ *,
+ subagents: "SubAgentPolicy | None" = None,
) -> None:
"""Initialize the CLI application.
@@ -352,11 +356,16 @@ def __init__(
library use and tests); without it a fresh id is generated.
``main()`` takes ``--continue`` and ``--resume ``
instead (``session_start``).
+ subagents: How the sub-agents run (a ``SubAgentPolicy``; None is
+ ``SubAgentPolicy()``): every workflow manager the app builds
+ gets it, a new conversation's on another backend included.
Raises:
- TypeError: The app still defines ``get_styles()``, which
+ TypeError: ``subagents`` is neither a ``SubAgentPolicy`` nor
+ None, or the app still defines ``get_styles()``, which
``get_theme(name)`` replaced.
"""
+ policy = as_policy(subagents)
if any("get_styles" in vars(cls) for cls in type(self).__mro__ if cls is not object):
raise TypeError(_GET_STYLES_REMOVED)
@@ -394,6 +403,7 @@ def __init__(
self._workflow_controller = WorkflowController(
agent_configs=agent_configs,
settings=settings,
+ subagents=policy,
)
self._workflow_controller.usage_tracker = self._usage_tracker
self._message_processor = MessageProcessor()
diff --git a/src/agentic_cli/cli/workflow_controller.py b/src/agentic_cli/cli/workflow_controller.py
index c54691fc..9ce415fc 100644
--- a/src/agentic_cli/cli/workflow_controller.py
+++ b/src/agentic_cli/cli/workflow_controller.py
@@ -18,6 +18,7 @@
from typing import TYPE_CHECKING, AsyncIterator
from agentic_cli.logging import Loggers
+from agentic_cli.workflow.agents.policy import as_policy
# Re-export the factory for backward compatibility
from agentic_cli.workflow.factory import create_workflow_manager_from_settings # noqa: F401
@@ -27,6 +28,7 @@
if TYPE_CHECKING:
from agentic_cli.cli.usage_tracker import UsageTracker
from agentic_cli.config import BaseSettings
+ from agentic_cli.workflow.agents.policy import SubAgentPolicy
from agentic_cli.workflow.base_manager import BaseWorkflowManager
from agentic_cli.workflow.config import AgentConfig
from thinking_prompt import ThinkingPromptSession
@@ -145,13 +147,22 @@ def __init__(
self,
agent_configs: list["AgentConfig"],
settings: "BaseSettings",
+ *,
+ subagents: "SubAgentPolicy | None" = None,
) -> None:
"""Initialize the workflow controller.
Args:
agent_configs: List of agent configurations for the workflow
settings: Application settings instance
+ subagents: The sub-agent policy every manager it builds gets
+ (the first start's, and each ``switch_backend``'s); None is
+ ``SubAgentPolicy()``.
+
+ Raises:
+ TypeError: ``subagents`` is neither a ``SubAgentPolicy`` nor None.
"""
+ self._subagents = as_policy(subagents)
self._settings = settings
self._agent_configs = agent_configs
self._app_name = settings.app_name
@@ -170,6 +181,7 @@ def _create_workflow() -> "BaseWorkflowManager":
app_name=self._app_name,
orchestrator=self.backend,
session_store=self.store,
+ subagents=self._subagents,
)
self._create_fn = _create_workflow
@@ -696,6 +708,7 @@ async def _swap_orchestrator(self, backend: str) -> None:
app_name=self._app_name,
orchestrator=backend,
session_store=self.store,
+ subagents=self._subagents,
)
lend = getattr(old_workflow, "lend_services", None)
loan = lend() if callable(lend) else None
diff --git a/tests/cli/test_conversation_switch.py b/tests/cli/test_conversation_switch.py
index 0d6df6af..24af5a91 100644
--- a/tests/cli/test_conversation_switch.py
+++ b/tests/cli/test_conversation_switch.py
@@ -415,7 +415,7 @@ def builds(cls, monkeypatch, fails) -> list:
built: list = []
def create(agent_configs, settings, app_name=None, model=None, orchestrator=None,
- session_store=None):
+ session_store=None, subagents=None):
backend = orchestrator or getattr(settings.orchestrator, "value", settings.orchestrator)
manager = cls.Manager(backend, fails(len(built), backend))
manager.session_store = session_store # the store it was built for
diff --git a/tests/cli/test_resume_on_its_backend.py b/tests/cli/test_resume_on_its_backend.py
index 50aaf591..8907438b 100644
--- a/tests/cli/test_resume_on_its_backend.py
+++ b/tests/cli/test_resume_on_its_backend.py
@@ -140,7 +140,7 @@ def manager(self, backend: str) -> Manager:
return manager
def create(self, agent_configs, settings, app_name=None, model=None, orchestrator=None,
- session_store=None):
+ session_store=None, subagents=None):
backend = orchestrator or settings.orchestrator.value
manager = self.manager(backend)
self.built.append(manager)
diff --git a/tests/cli/test_subagent_policy.py b/tests/cli/test_subagent_policy.py
new file mode 100644
index 00000000..6b83ff6e
--- /dev/null
+++ b/tests/cli/test_subagent_policy.py
@@ -0,0 +1,111 @@
+"""An app's sub-agent policy reaches every manager it builds (``BaseCLIApp(subagents=)``).
+
+The app hands its ``subagents=`` to its ``WorkflowController``, which passes
+it to each manager it builds: the first start's, and the one a conversation
+on another backend starts (``switch_backend``), while the workflow runs or
+while it is down. A value that is no policy is a ``TypeError`` before the
+app builds anything. These run the real ADK and Deep Agents managers,
+offline: no turn is taken, so no model is called.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("google.adk")
+pytest.importorskip("deepagents")
+
+from agentic_cli.cli import AppInfo # noqa: E402
+from agentic_cli.cli import app as app_module # noqa: E402
+from agentic_cli.cli.app import BaseCLIApp # noqa: E402
+from agentic_cli.cli.workflow_controller import WorkflowController # noqa: E402
+from agentic_cli.config import BaseSettings # noqa: E402
+from agentic_cli.workflow.agents.policy import AgentLimits, SubAgentPolicy # noqa: E402
+from agentic_cli.workflow.base_manager import BaseWorkflowManager # noqa: E402
+from agentic_cli.workflow.config import AgentConfig # noqa: E402
+
+POLICY = SubAgentPolicy(max_active=1, max_runs_per_turn=3, limits=AgentLimits(max_tokens=9_000))
+
+
+@pytest.fixture(autouse=True)
+def configured(tmp_path: Path, monkeypatch) -> list:
+ """A temporary cwd and HOME with a fake Claude key, and an app that leaves
+ no logging configuration or warning hook behind: the calls the app made
+ to ``configure_logging``."""
+ (tmp_path / "home").mkdir()
+ (tmp_path / "project").mkdir()
+ monkeypatch.setenv("HOME", str(tmp_path / "home"))
+ monkeypatch.chdir(tmp_path / "project")
+ for variable in ("GOOGLE_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY"):
+ monkeypatch.delenv(variable, raising=False)
+ monkeypatch.setenv("ANTHROPIC_API_KEY", "a-test-key")
+ calls: list = []
+ monkeypatch.setattr(app_module, "configure_logging", lambda *a, **k: calls.append(a))
+ monkeypatch.setattr(app_module, "install_log_filters", lambda: None)
+ return calls
+
+
+def app(**kwargs) -> BaseCLIApp:
+ return BaseCLIApp(
+ app_info=AppInfo(name="Policy test", version="0"),
+ agent_configs=[AgentConfig(name="solo", prompt="Answer.", include_state_tools=False)],
+ settings=BaseSettings(session_store="memory", default_model="claude-sonnet-4-6"),
+ **kwargs,
+ )
+
+
+async def started(controller: WorkflowController) -> BaseWorkflowManager:
+ """The manager ``controller``'s start builds, once it is ready."""
+ await controller.start_background_init()
+ assert await controller.ensure_initialized() is True, controller.init_error
+ return controller.workflow
+
+
+class TestEveryManagerTheAppBuilds:
+ async def test_the_first_one_gets_the_policy(self):
+ controller = app(subagents=POLICY)._workflow_controller
+ try:
+ workflow = await started(controller)
+ assert workflow.backend_type == "adk"
+ assert workflow.subagent_policy is POLICY
+ finally:
+ await controller.close()
+
+ async def test_a_conversation_on_another_backend_keeps_it(self):
+ controller = app(subagents=POLICY)._workflow_controller
+ try:
+ first = await started(controller)
+ await controller.switch_backend("deepagents")
+ workflow = controller.workflow
+ assert workflow is not first and workflow.backend_type == "deepagents"
+ assert workflow.subagent_policy is POLICY
+ finally:
+ await controller.close()
+
+ async def test_a_switch_while_the_workflow_is_down_keeps_it(self):
+ controller = app(subagents=POLICY)._workflow_controller
+ try:
+ await controller.switch_backend("deepagents")
+ workflow = await started(controller)
+ assert workflow.backend_type == "deepagents"
+ assert workflow.subagent_policy is POLICY
+ finally:
+ await controller.close()
+
+
+class TestAValueThatIsNoPolicy:
+ def test_the_app_refuses_it_before_it_builds_anything(self, configured, monkeypatch):
+ built: list = []
+ monkeypatch.setattr(app_module, "WorkflowController", lambda *a, **k: built.append(k))
+ with pytest.raises(TypeError, match="subagents must be a SubAgentPolicy or None, not type"):
+ app(subagents=SubAgentPolicy)
+ assert configured == [] and built == []
+
+ def test_the_controller_refuses_it(self):
+ with pytest.raises(TypeError, match="subagents must be a SubAgentPolicy or None, not dict"):
+ WorkflowController(
+ [AgentConfig(name="solo", prompt="p")], BaseSettings(session_store="memory"),
+ subagents={"max_active": 1},
+ )
From c102de3591050bee4c0d338d0d403060edf6a035 Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:41:35 -0500
Subject: [PATCH 08/11] Docs: the sub-agent policy, the delegation fields and
subagents=
CHANGELOG entries for SubAgentPolicy and AgentLimits, AgentConfig's
brief_required and limits, and subagents= on the app, the managers and the
factory; CLAUDE.md's structure lines for agents/policy.py, brief.py and
envelope.py, the config, the agent YAML loader, the factory, the base
manager, the controller and the app.
---
CHANGELOG.md | 40 ++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 13 +++++++------
2 files changed, 47 insertions(+), 6 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 102f3fe1..2a2e3359 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -559,6 +559,46 @@ the start of the entry's title.
### Added
+- **`SubAgentPolicy` and `AgentLimits`: an app's sub-agent policy and a
+ run's limits** (`agentic_cli.workflow`, and `agentic_cli.workflow.agents`
+ with `DEFAULT_LIMITS`). Frozen dataclasses. `SubAgentPolicy` holds an
+ app's numbers for its sub-agents: `max_active` (4, the runs working at
+ once in a conversation, at any depth), `max_runs_per_turn` (20, the runs
+ one turn may start) and `limits`, every run's `AgentLimits`
+ (`DEFAULT_LIMITS`, `AgentLimits(max_model_calls=100)`, unless the app sets
+ its own). `AgentLimits` holds a run's `max_model_calls`, `timeout`
+ (seconds) and `max_tokens` (input plus output), each None for no limit of
+ its own, and `over(base)` lays one over another field by field: a field
+ left None takes the base's, so an agent type's limits never lift the
+ policy's. Construction refuses, with a `ValueError` naming the field, a
+ limit that is not a positive int (a timeout: a positive, finite number;
+ `True` and `False` are no numbers here) and a policy whose `limits` is
+ not an `AgentLimits`.
+- **`AgentConfig.brief_required` and `AgentConfig.limits`.**
+ `brief_required` (default `("objective",)`) names the brief fields the
+ agent asks a delegation to fill: `objective`, `deliverable`,
+ `constraints`, `known`, `done_when` or `title` (a brief always has its
+ title and its objective); `limits` (default None) is the agent's own
+ `AgentLimits`, over the policy's field by field. Both come after
+ `inherit_context`, so a positional `AgentConfig(...)` still binds, and
+ the framework's agent YAML takes them: `brief_required: [objective,
+ deliverable]`, `limits: {max_model_calls: 30, timeout: 600, max_tokens:
+ 200000}` (each limit read as written, so `true` or `'30'` is refused, as
+ is a key that is no limit). `validate_agent_graph` raises
+ `AgentGraphError` for a `brief_required` that is not a tuple or list of
+ those names, a `limits` that is not an `AgentLimits`, and either set on
+ the root, which is never delegated to.
+- **`subagents=`: the sub-agent policy, given to the app, a manager or the
+ factory.** `BaseCLIApp`, `BaseWorkflowManager` (the ADK, Deep Agents and
+ LangGraph managers pass it on) and `create_workflow_manager_from_settings`
+ take `subagents=` (keyword; a `SubAgentPolicy`, None for
+ `SubAgentPolicy()`). A manager keeps it for its life, a model switch
+ included: `BaseWorkflowManager.subagent_policy` (read-only, provisional).
+ Every manager an app builds gets the app's (`WorkflowController(subagents=)`),
+ a conversation's on another backend included. Anything else is a
+ `TypeError` where it is passed: the factory's before any backend is
+ imported, the app's before it builds anything. LangGraph's delegation
+ does not read it.
- **A sub-agent's questions and permission prompts name it, on both
backends.** `UserInputRequest.run` is the sub-agent run that asks (a
`RunRef`; None for the root's own), filled by `request_user_input` from
diff --git a/CLAUDE.md b/CLAUDE.md
index feee29d8..fdc1b9fc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,7 +30,7 @@ agentic-cli/
│ ├── protected_paths.py # The locations no tool reaches (credential stores, never-writable files and dirs, the project's .git/.env files/.{app_name}, ~/.{app_name} with its .env and settings.json): the engine's builtin denies and the OS sandbox's policy are both built from it (stdlib only)
│ ├── logging.py # configure_logging (third-party loggers quieted there, google_genai.types too: no import sets a level); LOG_STREAM, which every logger writes to (structlog through _LineLogger, no lock); log_lines_to(sink): each line to a sink instead of stderr
│ ├── cli/
-│ │ ├── app.py # BaseCLIApp (main(): the command line, add_arguments/from_args, exit_status; session_start: how run() begins, the run's own conversation loaded before the prompt, also when the workflow did not start (_adopt_its_own: an id the app was given held from the start, one the run made from its first write); its resume once the prompt is up (_open_on_startup, holding the turn lock from before the prompt takes a line: a turn typed ahead waits and runs there; Ctrl+C there ends the app; --continue passes over conversations another process holds, _newest_free, the one chosen held beside the run's own until the switch); --continue and --resume find the conversation's backend from every installed backend's reader before the workflow is built (_start_on_its_backend: the run builds that backend once); the --resume hint at exit (the run's store named after a session_store change; the backend only when no reader reads it, LangGraph: --resume opens a conversation on its own); the session it builds; get_theme(name); /settings: _build_ui_items, apply_settings and save_settings delegate to cli/settings_ui.py (SettingsUI: an app's override applies); run() installs the ADK log filters first (workflow/adk/log_filters.py: an app built but never run installs none); the LangGraph deprecation notice; start_new_session(backend=None): /new [backend] (the settings' orchestrator by default; another backend: the memories proposed, WorkflowController.switch_backend, then the switch to the new id at its place; a Ctrl+C once it runs opens its conversation first); a line typed runs in ConversationCore.run_turn (on _turn_parts: the app's parts as they are), then the jobs at the turn's end through the app's own resume_finished_jobs(); compact() (ConversationCore.compact), start_new_session() and resume_session(): /compact, /new and /resume, under the conversation's turn lock (_turn_lock: ConversationCore.turn_lock; pick_session(), the picker, is not: it waits on a dialog); session_store=memory keeps one conversation at a time (Place.kept; session_store: the run's store): /new drops the one left once the switch is made, after its memories are proposed (_drop: its delete_session, shielded; on another backend the manager released takes it along; one it cannot confirm gone, the workflow down or its lookup or delete raising, is remembered and dropped once a workflow is ready: before the next turn, or right after the turn whose own start revives the workflow, and always before that turn's delivery of finished jobs, /compact and the next /new, never while it is the open one: ConversationCore.drop_left), and resume_session, pick_session, --resume (status 1) and --continue (a new conversation) are refused with NOT_KEPT, before any look-up; every installed backend's conversations (list_conversations, delete_conversation, session_backend; cli/stored_conversations.py): the picker names each row's backend and returns a PickedConversation, and /resume opens a conversation on the backend that keeps it (_open_elsewhere: held there, memories proposed, switch_backend with the run's services, then the switch at its place; an id two backends keep opens on the running one, the other named); every change of conversation through ConversationCore.switch (_conversation; _session_id and _turned forward to it); the session_id setter deprecated (its synchronous part, switch_now, and a DeprecationWarning); a conversation's memories proposed once per conversation used (_turned); the memory proposals waiting, said at startup and after /new and /resume (_name_waiting_proposals); resume_finished_jobs(): ConversationCore.deliver_finished_jobs, the jobs waiting named at startup by ConversationCore.waiting_jobs (_name_its_waiting_jobs))
+│ │ ├── app.py # BaseCLIApp (subagents=: the SubAgentPolicy every manager the app builds gets, through its WorkflowController; main(): the command line, add_arguments/from_args, exit_status; session_start: how run() begins, the run's own conversation loaded before the prompt, also when the workflow did not start (_adopt_its_own: an id the app was given held from the start, one the run made from its first write); its resume once the prompt is up (_open_on_startup, holding the turn lock from before the prompt takes a line: a turn typed ahead waits and runs there; Ctrl+C there ends the app; --continue passes over conversations another process holds, _newest_free, the one chosen held beside the run's own until the switch); --continue and --resume find the conversation's backend from every installed backend's reader before the workflow is built (_start_on_its_backend: the run builds that backend once); the --resume hint at exit (the run's store named after a session_store change; the backend only when no reader reads it, LangGraph: --resume opens a conversation on its own); the session it builds; get_theme(name); /settings: _build_ui_items, apply_settings and save_settings delegate to cli/settings_ui.py (SettingsUI: an app's override applies); run() installs the ADK log filters first (workflow/adk/log_filters.py: an app built but never run installs none); the LangGraph deprecation notice; start_new_session(backend=None): /new [backend] (the settings' orchestrator by default; another backend: the memories proposed, WorkflowController.switch_backend, then the switch to the new id at its place; a Ctrl+C once it runs opens its conversation first); a line typed runs in ConversationCore.run_turn (on _turn_parts: the app's parts as they are), then the jobs at the turn's end through the app's own resume_finished_jobs(); compact() (ConversationCore.compact), start_new_session() and resume_session(): /compact, /new and /resume, under the conversation's turn lock (_turn_lock: ConversationCore.turn_lock; pick_session(), the picker, is not: it waits on a dialog); session_store=memory keeps one conversation at a time (Place.kept; session_store: the run's store): /new drops the one left once the switch is made, after its memories are proposed (_drop: its delete_session, shielded; on another backend the manager released takes it along; one it cannot confirm gone, the workflow down or its lookup or delete raising, is remembered and dropped once a workflow is ready: before the next turn, or right after the turn whose own start revives the workflow, and always before that turn's delivery of finished jobs, /compact and the next /new, never while it is the open one: ConversationCore.drop_left), and resume_session, pick_session, --resume (status 1) and --continue (a new conversation) are refused with NOT_KEPT, before any look-up; every installed backend's conversations (list_conversations, delete_conversation, session_backend; cli/stored_conversations.py): the picker names each row's backend and returns a PickedConversation, and /resume opens a conversation on the backend that keeps it (_open_elsewhere: held there, memories proposed, switch_backend with the run's services, then the switch at its place; an id two backends keep opens on the running one, the other named); every change of conversation through ConversationCore.switch (_conversation; _session_id and _turned forward to it); the session_id setter deprecated (its synchronous part, switch_now, and a DeprecationWarning); a conversation's memories proposed once per conversation used (_turned); the memory proposals waiting, said at startup and after /new and /resume (_name_waiting_proposals); resume_finished_jobs(): ConversationCore.deliver_finished_jobs, the jobs waiting named at startup by ConversationCore.waiting_jobs (_name_its_waiting_jobs))
│ │ ├── commands.py # Command, CommandRegistry
│ │ ├── job_monitor.py # JobMonitor: the status bar's jobs segment (running, queued, a finished job's note, ↻N: waiting_jobs' rule, can_resume answers kept 30 s (the other backends' look too: kept_elsewhere), forgotten after /sessions --delete or when the workflow is replaced), one tick every 2 s, its JobManager.list() on a worker thread
│ │ ├── conversation.py # ConversationCore: the conversation the turns run in (its id, turned, its lock at its Place: the backend and store, the store the run's for its whole life (Place.kept: not the memory store, where the CLI keeps one conversation at a time and NOT_KEPT says why nothing else opens), the backend recorded as the app starts, for a new conversation on another backend, and on a /settings change of the orchestrator while the workflow is down, its next start builds afresh and nothing of the conversation is stored (SettingsUI._move_here, WorkflowController.next_start_builds), never read from the settings in between; deferred: an id this run made (the start's, /new's, an orchestrator change's) is in no store, so it is held from its first write, hold_to_write under the turn lock before a turn, a job's notice or /compact (_held_to_write; a run in which no turn runs makes no lock file: a line typed while the workflow is down takes the hold before its retried start; a lock that cannot be taken, an OSError, leaves it unheld, said once, and the write goes on); fresh: nothing of it stored, opened_empty (an id this run made, or one a load found empty) and not written (no turn of it ran on a ready workflow), the one condition for another backend); switch: the one protocol (/new on any backend, /resume, startup, the same id in another place while the workflow is down): the target's lock taken (another process's refused), memories proposed, the workflow loads it (a stored one gone: not made, or, made already in another place, opened empty: gone), then made at once (lock, id, task list, usage counters) or let go, a workflow that took it given the old one back; made before the load when there is no other conversation to stay in (the same id, or another place: a new or stored conversation on another backend); a Ctrl+C at any await leaves one conversation held; switch_now: the deprecated session_id setter's part; turn_lock: what writes to the conversation and every switch take it; run_turn, compact and run_job_resume: a turn (echoed, held to write, turned, written once it reached a ready workflow; run_turn says whether it ran, whatever the processor returns), /compact and a finished job's notice under it, on TurnParts (the app's parts as they are); deliver_finished_jobs: each job that waits here (cli/waiting_jobs.py's rule, which waiting_jobs names them by, the other backends' look through TurnParts.kept_elsewhere), every JobManager call on a worker thread, a delivery claimed only once it can reach the agent (process_resume(claim=), after the readiness check and can_resume; _claim_delivery: a claim a Ctrl+C stopped is handed back, JobManager.release_resume), a failure before the claim said once per job and conversation when the CLI tells jobs on its own (telling_on_its_own); to_drop/drop_left: the conversations /new left on the memory store that the store may still hold (the workflow down, a lookup or delete that raised), dropped through TurnParts.drop under the turn lock once a workflow is ready, before a turn, /compact or a delivery uses it (after a turn or /compact that started it), one try per point, done once the store has it no more (a workflow without supports_sessions has none), the open one skipped; a delivery with none to drop takes no turn lock
@@ -38,7 +38,7 @@ agentic-cli/
│ │ ├── builtin_commands.py # /help (by category; /help : its usage and examples), /status (the main agent's context rows: context_budget; why the workflow did not start: app.workflow_error; tokens by agent: the main agent, each sub-agent with its runs, the side calls by purpose, from the manager's usage ledger), /models (ModelsCommand: the list, each model's facts and sources, Status for an entry left out, the providers in use; /models searches the full listings; refresh), /sessions (every installed backend's, a Backend column; --delete= on the backend that keeps it, --backend= for an id two keep; on the memory store NOT_KEPT, no table, --delete refused), /resume [] (sessions; refused on the memory store), /jobs (resume: finished jobs), /compact [focus], /new [backend] (an unknown backend or a missing extra refused: check_backend), ...
│ │ ├── agents_command.py # /agents: the open conversation's sub-agent runs (agent_runs.records under workflow.session_ref(app.session_id)) in a table, each followed by the runs it started (instance, type, status: running, completed (partial) for a cut answer, the end as recorded; run, title, tokens in/out from the usage ledger, usage_of, live for a running run; time); /agents : one instance or run (type, parent, title; each run's status and time, its result's first lines, its error, its tokens by model); the records live in memory with the manager, so a conversation resumed after a restart or a backend switch lists none; a module of its own, as /memory's
│ │ ├── memory_command.py # /memory: the list (a picker like /resume's), one memory (Delete, History), /memory , history (Restore), inbox (Accept/Discard/Skip), stale; proposals_line; Enter's button is Close or Skip, and Delete acts only on the memory as shown
-│ │ ├── workflow_controller.py # WorkflowController (lazy/background init; the session store of every manager of the run, store, fixed at its first start; the backend it runs, backend: the settings' orchestrator at its first start, then switch_backend's (a conversation on another backend, new or opened: the new manager started first on the run's services lent, given over by the old one and published at once, the old one released in the controller's task, a cancel stops only the wait; a failed start or give leaves the old one with its services; while down, a manager a failed reinitialization kept lends its services to the next build, _lender, and is released once they are given); reinitialize, a model switch, always in place; the status bar names the main agent's model)
+│ │ ├── workflow_controller.py # WorkflowController (lazy/background init; subagents=: the SubAgentPolicy every manager it builds gets, a switch_backend's too; the session store of every manager of the run, store, fixed at its first start; the backend it runs, backend: the settings' orchestrator at its first start, then switch_backend's (a conversation on another backend, new or opened: the new manager started first on the run's services lent, given over by the old one and published at once, the old one released in the controller's task, a cancel stops only the wait; a failed start or give leaves the old one with its services; while down, a manager a failed reinitialization kept lends its services to the next build, _lender, and is released once they are given); reinitialize, a model switch, always in place; the status bar names the main agent's model)
│ │ ├── session_resume.py # What /resume shows: the picker (picker: each row's backend once one is another's; PickedConversation, the id a str naming its backend), the "Resumed:" line ("Resumed on :" on another backend), the replay of the last 10 messages
│ │ ├── stored_conversations.py # StoredConversations: one look at every installed backend's stored conversations (the running workflow's own, each other backend's SessionReader, opened and closed with the look): rows merged newest first, each naming its backend; where(id), delete; a backend not read (its extra missing, its store failing) left out and named in notes; a failing store warned of in the log at each look the user asks for, once a run for the app's own (warned: the job monitor's, a finished job's)
│ │ ├── session_args.py # --continue / --resume → SessionStart (BaseCLIApp.main() adds them; start: new, continue, resume; SessionArgumentParser: --resume without its id names --continue and /resume)
@@ -49,8 +49,8 @@ agentic-cli/
│ │ ├── waiting_jobs.py # Which finished jobs wait to be told in the open conversation: one rule (JobRecord.awaiting_resume, then its own, no conversation's, or a gone conversation's: can_resume, then the other installed backends' readers, opens_anywhere: one another backend keeps is not gone, its job waits for it) for the deliveries, ↻N and the startup line
│ │ └── usage_tracker.py # Token usage / status bar: ctx = the main agent's last prompt over its context_trigger (a call with a purpose, a sub-agent's, a summary's or a side call's, never moves it); the token segment the open conversation's total, every call of its turns; format_usage: /status's rows by agent and /agents 's tokens by model
│ ├── workflow/
-│ │ ├── base_manager.py # BaseWorkflowManager (abstract; _load_models: load the catalog, then resolve every model (the configs', then _resolve_extra_models: a backend's agents built without configs, leniently), once, no retry (the background refresh started after a successful init checks the models the settings name); _compute_budgets right after it, before any service is built: each agent's context numbers, ContextBudgetError for a window too small to work in, for a backend that says _manages_context (ADK, whoever built its agents, and Deep Agents; LangGraph has none); the lifecycle: cleanup, reinitialize and the one release, _release_resources: the base's state reset, the backend's hooks _detach_backend/_detach_store (skipped while _keeping keeps the store), the services detached and their closes started on a worker thread, then every closer and the services waited for last (shielded), in one shielded task; the turn: _turn, every turn's entry (log context, _turn_admission, _workflow_context; the sub-agent runs it leaves open, a cancel's or a failure's, recorded interrupted as it ends: agent_runs, workflow/agents/runs.py), and the templates over the backend's hooks: resume_with_job_result (the job's result read on a worker thread, job_notice → _deliver_job_notice), can_resume (_record_resumable, _conversation_exists), compact (→ _compact_turn), supports_job_resume/supports_compact derived from them; services (services.py's ServiceSet behind the forwards: _services, _build_services(_into), _get_service_tool_map, _close_services, _keeping) and the hand-over: lend_services → initialize_services(services=loan) → give_services (no turn while a manager holds services it does not own); service detection, tool assembly; context_budget/root_agent_name; the usage ledgers (usage: the open conversation's, usage_of; _turn counts each turn in its conversation's and gives a run a cancel leaves open what it used) and side calls (_report_side_call: generate_simple's usage, its purpose from usage.side_call, summarize's tool, on_session_end's memory_extraction outside any turn, recorded in its conversation's ledger and, in a turn, reported through its live events, never to a turn that has ended: turn_has_ended); summarize and fact extraction: a prompt over the default model's room, at the resolved max_tokens, cut in the middle, never under MIN_PROMPT_ROOM, _fit_prompt; the memory index behind the forwards _memory_index_now/_memory_index_cached/_memory_index_cap/_forget_memory_index and _index_snapshots (memory_index.py's MemoryIndex; the release clears it))
-│ │ ├── factory.py # create_workflow_manager_from_settings (_BACKENDS: orchestrator → "module:Class" + extra, imported when chosen; orchestrator=: another backend than the settings'; session_store=: the store a manager is built for, BaseWorkflowManager.session_store, the settings' by default); orchestrator_of; check_backend (an unknown name, a missing extra)
+│ │ ├── base_manager.py # BaseWorkflowManager (abstract; subagents=: its SubAgentPolicy, subagent_policy, read-only, kept for its life; _load_models: load the catalog, then resolve every model (the configs', then _resolve_extra_models: a backend's agents built without configs, leniently), once, no retry (the background refresh started after a successful init checks the models the settings name); _compute_budgets right after it, before any service is built: each agent's context numbers, ContextBudgetError for a window too small to work in, for a backend that says _manages_context (ADK, whoever built its agents, and Deep Agents; LangGraph has none); the lifecycle: cleanup, reinitialize and the one release, _release_resources: the base's state reset, the backend's hooks _detach_backend/_detach_store (skipped while _keeping keeps the store), the services detached and their closes started on a worker thread, then every closer and the services waited for last (shielded), in one shielded task; the turn: _turn, every turn's entry (log context, _turn_admission, _workflow_context; the sub-agent runs it leaves open, a cancel's or a failure's, recorded interrupted as it ends: agent_runs, workflow/agents/runs.py), and the templates over the backend's hooks: resume_with_job_result (the job's result read on a worker thread, job_notice → _deliver_job_notice), can_resume (_record_resumable, _conversation_exists), compact (→ _compact_turn), supports_job_resume/supports_compact derived from them; services (services.py's ServiceSet behind the forwards: _services, _build_services(_into), _get_service_tool_map, _close_services, _keeping) and the hand-over: lend_services → initialize_services(services=loan) → give_services (no turn while a manager holds services it does not own); service detection, tool assembly; context_budget/root_agent_name; the usage ledgers (usage: the open conversation's, usage_of; _turn counts each turn in its conversation's and gives a run a cancel leaves open what it used) and side calls (_report_side_call: generate_simple's usage, its purpose from usage.side_call, summarize's tool, on_session_end's memory_extraction outside any turn, recorded in its conversation's ledger and, in a turn, reported through its live events, never to a turn that has ended: turn_has_ended); summarize and fact extraction: a prompt over the default model's room, at the resolved max_tokens, cut in the middle, never under MIN_PROMPT_ROOM, _fit_prompt; the memory index behind the forwards _memory_index_now/_memory_index_cached/_memory_index_cap/_forget_memory_index and _index_snapshots (memory_index.py's MemoryIndex; the release clears it))
+│ │ ├── factory.py # create_workflow_manager_from_settings (_BACKENDS: orchestrator → "module:Class" + extra, imported when chosen; orchestrator=: another backend than the settings'; session_store=: the store a manager is built for, BaseWorkflowManager.session_store, the settings' by default; subagents=: the SubAgentPolicy the manager gets, checked before a backend is imported); orchestrator_of; check_backend (an unknown name, a missing extra)
│ │ ├── session_readers.py # SessionReader: a backend's stored conversations read without its manager (list/info/exists/delete/aclose, rows naming the backend), opened from the settings and a store (open_session_reader: the backend's own session code, adk/sessions.py::open_sessions and deepagents/sessions.py::open_sessions, imported on a worker thread; no agents, models or services; a sqlite store not made yet reads empty and is not made, Deep Agents not even imported for it; a database without its backend's tables, looked at read-only, reads empty, nothing written to it: no table, no journal mode); none for the memory store or LangGraph; ImportError (the install hint) for a missing extra; reader_backends
│ │ ├── service_registry.py # get_service/require_service + ContextVar registry; the registry keys and KNOWN_SERVICE_KEYS, read from services.py's table
│ │ ├── services.py # The services a manager builds: SERVICES, one ServiceSpec each (key, build, close, tools, declarable, always, built_with, rebind; builders import lazily); ServiceSet: one manager's (build_into, publish, carried, release, tool_map, not_owned: borrowed or given away, never closed there); ServiceLoan: a hand-over between managers (rebind: the engine's workflow/per_call, the KB's summarizer)
@@ -60,7 +60,8 @@ agentic-cli/
│ │ ├── live_events.py # LiveEvents, merged: events reported inside a turn (reporting/report) reach its stream as they happen; on_stop: a consumer that stops early, before the source is cancelled; emit gives an event that names no run the active one (get_active_run)
│ │ ├── usage.py # Token usage: normalized_tokens, the one place a provider's report becomes the counts every LLM_USAGE carries (prompt_tokens every input token, cache included; completion_tokens every output token, thinking included): adk_tokens (ADK's, by provider kind: Gemini's and ADK's Claude adapter's thinking apart from the candidates, OpenAI's inside; an unknown kind's apart), adk_usage_event (the one place ADK's usage becomes an LLM_USAGE: the event processor, the summarizer, generate_simple, the raw log), langchain_tokens (every partner package's, langchain-openai's priority and flex tiers' parts too), llm_usage_event; PURPOSE_* (none: the root's step; subagent, summarization, tool, memory_extraction, side_call) and side_call (what a caller's side calls are for); UsageLedger (a conversation's calls, a row each, each with its latency_ms: totals by run, agent, model, purpose and turn; a row's turn its conversation's while a turn of it runs, as the manager counts them, None in another conversation's turn or a task its turn outlived; by_agent, by_purpose, by_model, run_usage), UsageLedgers (a manager's, by conversation, filed under the turn a call is made in; for the manager's life: a backend switch's new manager starts afresh)
│ │ ├── interrupts.py # What a call a cancel or a crash left open is answered with; OpenCalls (each manager's record, kept by conversation: only that conversation's turns clear it; within it by the run that made each call, run=, the active run by default); unrecorded: a call no record holds; job_for_call: a job of the turn's conversation and of the run whose call it answers (started_by) only
-│ │ ├── config.py # AgentConfig
+│ │ ├── config.py # AgentConfig (brief_required: the brief fields it asks a delegation to fill; limits: its own AgentLimits, over the policy's), AgentGraph, validate_agent_graph (rules 1-13, the first failure the most fundamental; 11-13: brief_required names brief fields, limits is an AgentLimits, the root sets neither)
+│ │ ├── agent_loader.py # load_agents_from_yaml: the framework's agent YAML → AgentConfig (unknown keys refused; brief_required, limits: {max_model_calls, timeout, max_tokens} read strictly, AgentLimits checking them); create_workflow_manager_from_yaml
│ │ ├── settings.py # Workflow/tool settings schema; models, model_providers, model_roles and permissions in Annotated form (an app's override warns nothing); _merge_shipped_entries: the app's models and model_providers, then the sources', field by field, and the app's permissions before the sources' (at load only); permissions: the union of every trusted source's rules, each list concatenated, a duplicate once (_source_sections reads each source's value as the sources hook filed it)
│ │ ├── context.py # ContextBudget/context_budget: when to summarize (window or the 128k floor, budget, trigger, keep; both backends, the CLI); FailedSummaries: a range whose summary failed is skipped for the rest of its turn (keyed by its live events, weakly) until it grows by MIN_SAVING of the trigger; SUMMARY_FAILED: the one warning a failed summary gives, on both backends; is_context_overflow, overflow_message, subagent_overflow_message (a sub-agent's overflow warning, both backends); prompt_room/cut_middle/MIN_PROMPT_ROOM: a side call's prompt in characters its model takes
│ │ ├── retry.py # is_rate_limit_error: a provider's 429 told from other failures (a failed turn's ERROR says so: rate_limited, which the CLI reports); no retry logic, the provider clients retry (retry_max_attempts, retry_initial_delay)
@@ -81,7 +82,7 @@ agentic-cli/
│ │ │ ├── capabilities.py # Capability, EXEMPT
│ │ │ ├── matchers.py # PathMatcher, URLMatcher, ShellMatcher, StringGlobMatcher
│ │ │ └── rules.py, store.py, prompt.py (build_request(run=): a sub-agent's prompt opens with its run; is_permission_request: by its perm- id)
-│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX, run_ended (the one run-end decision, both processors': failed only on Error running sub-agent: … or the framework's own error result, the sub-agent's answer never read for success; refused or partial by the outcome mark), show_as_delegation (a delegation's TOOL_RESULT shown alike on both backends); outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal)
+│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX, run_ended (the one run-end decision, both processors': failed only on Error running sub-agent: … or the framework's own error result, the sub-agent's answer never read for success; refused or partial by the outcome mark), show_as_delegation (a delegation's TOOL_RESULT shown alike on both backends); outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE, which adk/delegation.py imports), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts
│ │ ├── adk/ # ADK orchestrator
│ │ │ ├── manager.py # GoogleADKWorkflowManager (the agents built from configs or, adk_config_path, by ADK from a native YAML (library-only: no BaseCLIApp starts one; loaded once per manager at the first _validate_agent_graph (_native_root: the settings' keys exported first; a retry, a model switch and a start after cleanup build on the same tree, whose toolsets the closed runner left reusable), its agents' models resolved leniently in _resolve_extra_models, the base's hook, its registered tools' services detected; configs passed with it ignored, adk_native_configs_ignored): the only difference; _do_initialize builds the app from the tree alone, _build_app → ADKBuild, through the hooks _plugin_chain (the whole chain, top to bottom, its head _init_plugins), _compaction_config (None for a root without a budget), _context_cache_config, _agent_model_refs; the event processor built from the build; a config-built agent's prompt as an instruction provider, sent as written: no `{name}` state injection; _compact_turn: ADK's compaction once, in the base's compact turn; supports_compact False once built for a root without a budget (_no_compact_support says why); the job resume hooks: _conversation_exists (the session read without its events, num_recent_events=0), _deliver_job_notice (the notice, for every app); _run_config: the agents' synchronous tools run in ADK's tool thread pool, 8 workers; _run_and_stream: a run that fails yields the turn's one ERROR, last, none after an ERROR already yielded; _end_returned_runs: before the turn clears its record (a stop, after unsealed; a failure), each open run whose delegation returned ends with its result, not interrupted)
│ │ │ ├── build.py # ADKBuild (root, reply_agents, plugins, compaction, cache, models); load_native_root (from_config at validation; what ADK cannot load, wrapped as AgentGraphError naming the file, ADK's error the cause; a root that is not an LlmAgent, a name used twice in the tree and a task-mode agent refused, AgentGraphError naming it; ensure_direct_anthropic); what the run reads of any tree: reply_agents (the root and the chat-mode agents it can transfer to), delegated_agents (each agent's single-turn sub-agents, by its name), own_after_tool_agents (left out by the cap)
From a48fbf24783924d3c90aae9e9457a2ee427ee663 Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:51:04 -0500
Subject: [PATCH 09/11] Sub-agents: a timeout too large for a float is refused
by name
math.isfinite raises OverflowError for an int no float can hold, so
AgentLimits(timeout=10**400) failed with "int too large to convert to
float" instead of the field's own ValueError. Such an int is now no
finite number of seconds, refused as inf is.
---
src/agentic_cli/workflow/agents/policy.py | 11 ++++++++++-
tests/workflow/test_agent_policy.py | 8 ++++++++
2 files changed, 18 insertions(+), 1 deletion(-)
diff --git a/src/agentic_cli/workflow/agents/policy.py b/src/agentic_cli/workflow/agents/policy.py
index 711c20e5..41b9b1ba 100644
--- a/src/agentic_cli/workflow/agents/policy.py
+++ b/src/agentic_cli/workflow/agents/policy.py
@@ -36,7 +36,7 @@ def _check_seconds(owner: str, name: str, value: object) -> None:
if (
isinstance(value, bool)
or not isinstance(value, (int, float))
- or not math.isfinite(value)
+ or not _is_finite(value)
or value <= 0
):
raise ValueError(
@@ -44,6 +44,15 @@ def _check_seconds(owner: str, name: str, value: object) -> None:
)
+def _is_finite(value: int | float) -> bool:
+ """Whether ``value`` is finite as a float: an int too large for a float is not
+ (``math.isfinite`` raises ``OverflowError`` for it)."""
+ try:
+ return math.isfinite(value)
+ except OverflowError:
+ return False
+
+
@dataclass(frozen=True)
class AgentLimits:
"""One sub-agent run's limits; a field left None takes the policy's (on a
diff --git a/tests/workflow/test_agent_policy.py b/tests/workflow/test_agent_policy.py
index 70f1f39a..fa120bca 100644
--- a/tests/workflow/test_agent_policy.py
+++ b/tests/workflow/test_agent_policy.py
@@ -56,6 +56,14 @@ def test_a_timeout_must_be_a_positive_number_of_seconds(self, value):
message = str(exc.value)
assert "AgentLimits.timeout" in message and "positive number" in message
+ def test_an_int_too_large_for_a_float_is_no_timeout(self):
+ # Refused as inf is, naming the field: no float holds it, so no
+ # clock can wait for it.
+ with pytest.raises(ValueError) as exc:
+ AgentLimits(timeout=10**400)
+ message = str(exc.value)
+ assert "AgentLimits.timeout" in message and "positive number of seconds" in message
+
def test_over_takes_its_own_fields_where_set_and_the_base_elsewhere(self):
base = AgentLimits(max_model_calls=100, timeout=60)
mine = AgentLimits(timeout=600, max_tokens=50_000)
From 44d581e328ce3a68515192e04b8371dc49934a9b Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:51:31 -0500
Subject: [PATCH 10/11] Sub-agents: brief_required's error says a list is taken
too
validate_agent_graph accepts a tuple or a list of brief field names, but
its error said "a tuple". The message now says "a tuple or list", and the
shape test pins it.
---
src/agentic_cli/workflow/config.py | 2 +-
tests/workflow/test_subagent_config.py | 1 +
2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/src/agentic_cli/workflow/config.py b/src/agentic_cli/workflow/config.py
index 72c2d93d..7c853413 100644
--- a/src/agentic_cli/workflow/config.py
+++ b/src/agentic_cli/workflow/config.py
@@ -370,7 +370,7 @@ def _check_delegation_fields(config_map: dict[str, AgentConfig], root: str) -> N
]
if unknown:
raise AgentGraphError(
- f"brief_required must be a tuple of brief field names "
+ f"brief_required must be a tuple or list of brief field names "
f"({', '.join(_BRIEF_NAMES)}): {', '.join(unknown)}."
)
diff --git a/tests/workflow/test_subagent_config.py b/tests/workflow/test_subagent_config.py
index 5eac7209..ff8fa8e4 100644
--- a/tests/workflow/test_subagent_config.py
+++ b/tests/workflow/test_subagent_config.py
@@ -82,6 +82,7 @@ def test_brief_required_is_a_tuple_or_a_list(self, value):
validate_agent_graph(team(writer={"brief_required": value}))
message = str(exc.value)
assert "brief_required" in message and "'writer'" in message and repr(value) in message
+ assert "must be a tuple or list of brief field names" in message
@pytest.mark.parametrize("value", [{"timeout": 60}, 60, "fast"])
def test_limits_is_an_agent_limits(self, value):
From bcbe3493ac32b109bbddf61802479dd5bd656e75 Mon Sep 17 00:00:00 2001
From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com>
Date: Tue, 17 Nov 2026 14:52:33 -0500
Subject: [PATCH 11/11] Docs: how a type's limits and a policy's own lie over
the defaults
The CHANGELOG said an agent type's limits "never lift" the policy's, which
reads as "never exceed". It now says it plainly: a type's field left None
keeps the policy's limit, and a type may set its own, higher or lower, but
cannot remove one the policy sets; AgentLimits.over's docstring says the
same. The CHANGELOG and SubAgentPolicy.limits' docstring add that a
policy's own limits replace DEFAULT_LIMITS whole (no model-call limit
unless they set one) and that .over(DEFAULT_LIMITS) keeps the 100 calls,
which a test pins.
---
CHANGELOG.md | 20 ++++++++++++--------
src/agentic_cli/workflow/agents/policy.py | 9 +++++++--
tests/workflow/test_agent_policy.py | 6 ++++++
3 files changed, 25 insertions(+), 10 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2a2e3359..801595fa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -566,14 +566,18 @@ the start of the entry's title.
once in a conversation, at any depth), `max_runs_per_turn` (20, the runs
one turn may start) and `limits`, every run's `AgentLimits`
(`DEFAULT_LIMITS`, `AgentLimits(max_model_calls=100)`, unless the app sets
- its own). `AgentLimits` holds a run's `max_model_calls`, `timeout`
- (seconds) and `max_tokens` (input plus output), each None for no limit of
- its own, and `over(base)` lays one over another field by field: a field
- left None takes the base's, so an agent type's limits never lift the
- policy's. Construction refuses, with a `ValueError` naming the field, a
- limit that is not a positive int (a timeout: a positive, finite number;
- `True` and `False` are no numbers here) and a policy whose `limits` is
- not an `AgentLimits`.
+ its own). A policy's own `limits` replace `DEFAULT_LIMITS` whole:
+ `SubAgentPolicy(limits=AgentLimits(timeout=60))` has no model-call limit,
+ while `AgentLimits(timeout=60).over(DEFAULT_LIMITS)` keeps the 100 calls.
+ `AgentLimits` holds a run's `max_model_calls`, `timeout` (seconds) and
+ `max_tokens` (input plus output), each None for no limit of its own, and
+ `over(base)` lays one over another field by field: a field left None
+ takes the base's. So an agent type's field left None keeps the policy's
+ limit, and a type may set its own, higher or lower, but cannot remove a
+ limit the policy sets. Construction refuses, with a `ValueError` naming
+ the field, a limit that is not a positive int (a timeout: a positive,
+ finite number; `True` and `False` are no numbers here) and a policy whose
+ `limits` is not an `AgentLimits`.
- **`AgentConfig.brief_required` and `AgentConfig.limits`.**
`brief_required` (default `("objective",)`) names the brief fields the
agent asks a delegation to fill: `objective`, `deliverable`,
diff --git a/src/agentic_cli/workflow/agents/policy.py b/src/agentic_cli/workflow/agents/policy.py
index 41b9b1ba..dff67f9b 100644
--- a/src/agentic_cli/workflow/agents/policy.py
+++ b/src/agentic_cli/workflow/agents/policy.py
@@ -78,7 +78,8 @@ def over(self, base: AgentLimits) -> AgentLimits:
"""These limits over ``base``: each field of this one that is set,
else ``base``'s (a type's limits over the policy's).
- A field left None never lifts a limit ``base`` sets.
+ A field left None keeps the limit ``base`` sets; a field set
+ replaces it, higher or lower. No field removes one.
"""
own = {f.name: getattr(self, f.name) for f in fields(self)}
return replace(base, **{name: value for name, value in own.items() if value is not None})
@@ -97,7 +98,11 @@ class SubAgentPolicy:
conversation, at any depth.
max_runs_per_turn: How many sub-agent runs one turn may start.
limits: Every run's limits (``AgentLimits``), which an agent type's
- own lie over.
+ own lie over. A policy's own replace ``DEFAULT_LIMITS`` whole:
+ ``SubAgentPolicy(limits=AgentLimits(timeout=60))`` has no
+ model-call limit, while
+ ``AgentLimits(timeout=60).over(DEFAULT_LIMITS)`` keeps the 100
+ calls.
"""
max_active: int = 4
diff --git a/tests/workflow/test_agent_policy.py b/tests/workflow/test_agent_policy.py
index fa120bca..48e23761 100644
--- a/tests/workflow/test_agent_policy.py
+++ b/tests/workflow/test_agent_policy.py
@@ -116,6 +116,12 @@ def test_limits_must_be_an_agent_limits(self, value):
def test_policies_with_the_same_values_are_equal(self):
assert SubAgentPolicy() == SubAgentPolicy(limits=AgentLimits(max_model_calls=100))
+ def test_its_own_limits_replace_the_default_limits_whole(self):
+ # As the docstring says: laid over DEFAULT_LIMITS, they keep its 100 calls.
+ assert SubAgentPolicy(limits=AgentLimits(timeout=60)).limits.max_model_calls is None
+ kept = SubAgentPolicy(limits=AgentLimits(timeout=60).over(DEFAULT_LIMITS)).limits
+ assert kept == AgentLimits(max_model_calls=100, timeout=60)
+
class TestAsPolicy:
def test_none_is_the_default_policy(self):