Skip to content

Sub-agents: the policy, the brief and the envelope - #318

Merged
shoom1 merged 11 commits into
developfrom
feature/subagent-policy
Nov 17, 2026
Merged

shoom1 merged 11 commits into
developfrom
feature/subagent-policy

Conversation

@shoom1

@shoom1 shoom1 commented Nov 17, 2026

Copy link
Copy Markdown
Owner

The configuration a delegation reads, and the pure pieces a delegation is made of. Nothing runs differently yet: no backend reads the policy, the brief or the envelope.

  • SubAgentPolicy and AgentLimits (workflow/agents/policy.py, exported from agentic_cli.workflow): max_active, max_runs_per_turn and per-run limits (max_model_calls, timeout, max_tokens); DEFAULT_LIMITS holds 100 model calls. A type's limit left None keeps the policy's; a policy's own limits replace the defaults whole. Construction refuses a limit that is not positive, a bool, or an infinite or NaN timeout, naming the class and field.
  • subagents= (keyword-only) on BaseCLIApp, every manager, WorkflowController and the factory; as_policy reads it at each entry point, before anything is built.
  • AgentConfig.brief_required and AgentConfig.limits, checked by validate_agent_graph (rules 11-13) and read from the agent YAML (limits: strictly typed).
  • workflow/agents/brief.py: the brief (title, objective, deliverable, constraints, known, done_when), read_brief (a task call's arguments checked against the caller's types and the fields each needs), the task message, task's schema and description. INHERITED_CONTEXT_NOTE moves here; adk/delegation.py imports it.
  • workflow/agents/envelope.py: the delegation result (success, agent, run, status, partial, result, error, cancelled_by) and read_envelope.

Tests: new tests written first and seen failing; the full offline suite passes in the worktree except TestChildImportOrigin, which fails the same way on develop under the worktree wrapper.

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.
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.
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.
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
<name> agent., with a warning, for one without), and a place for the
limits in force (limit_sentences).
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.
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.
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.
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.
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.
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.
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.
@shoom1
shoom1 merged commit c264250 into develop Nov 17, 2026
5 of 6 checks passed
@shoom1
shoom1 deleted the feature/subagent-policy branch November 17, 2026 23:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant