diff --git a/CHANGELOG.md b/CHANGELOG.md index 102f3fe1..801595fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -559,6 +559,50 @@ 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). 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`, + `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) 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/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/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/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/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/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/brief.py b/src/agentic_cli/workflow/agents/brief.py new file mode 100644 index 00000000..09151723 --- /dev/null +++ b/src/agentic_cli/workflow/agents/brief.py @@ -0,0 +1,262 @@ +"""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``). ``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", + "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." +) + + +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. + + 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) + + +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 <name> + 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``: ``- <name> (<notes>): <description>``. + + 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 <name> 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/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": "<final text>", "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/src/agentic_cli/workflow/agents/policy.py b/src/agentic_cli/workflow/agents/policy.py new file mode 100644 index 00000000..dff67f9b --- /dev/null +++ b/src/agentic_cli/workflow/agents/policy.py @@ -0,0 +1,137 @@ +"""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 _is_finite(value) + or value <= 0 + ): + raise ValueError( + f"{owner}.{name} must be a positive number of seconds or None, not {value!r}." + ) + + +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 + 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 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}) + + +#: 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. 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 + 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/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/config.py b/src/agentic_cli/workflow/config.py index eb19dda7..7c853413 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 or list 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/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/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}, + ) diff --git a/tests/workflow/test_agent_brief.py b/tests/workflow/test_agent_brief.py new file mode 100644 index 00000000..66ea90fd --- /dev/null +++ b/tests/workflow/test_agent_brief.py @@ -0,0 +1,328 @@ +"""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. ``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: + 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." + ) + + +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] 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 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_agent_policy.py b/tests/workflow/test_agent_policy.py new file mode 100644 index 00000000..48e23761 --- /dev/null +++ b/tests/workflow/test_agent_policy.py @@ -0,0 +1,152 @@ +"""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_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) + 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)) + + 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): + 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 diff --git a/tests/workflow/test_subagent_config.py b/tests/workflow/test_subagent_config.py new file mode 100644 index 00000000..ff8fa8e4 --- /dev/null +++ b/tests/workflow/test_subagent_config.py @@ -0,0 +1,121 @@ +"""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 + 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): + 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 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, + )