Repository navigation
Sub-agents: the policy, the brief and the envelope - #318
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
SubAgentPolicyandAgentLimits(workflow/agents/policy.py, exported fromagentic_cli.workflow):max_active,max_runs_per_turnand per-runlimits(max_model_calls,timeout,max_tokens);DEFAULT_LIMITSholds 100 model calls. A type's limit left None keeps the policy's; a policy's ownlimitsreplace 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) onBaseCLIApp, every manager,WorkflowControllerand the factory;as_policyreads it at each entry point, before anything is built.AgentConfig.brief_requiredandAgentConfig.limits, checked byvalidate_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(ataskcall's arguments checked against the caller's types and the fields each needs), the task message,task's schema and description.INHERITED_CONTEXT_NOTEmoves here;adk/delegation.pyimports it.workflow/agents/envelope.py: the delegation result (success,agent,run,status,partial,result,error,cancelled_by) andread_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.