diff --git a/CHANGELOG.md b/CHANGELOG.md index 801595fa..c1a4c2ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -71,12 +71,20 @@ the start of the entry's title. - A `filesystem.*`, `http.*` or `shell.*` capability needs `target_arg=` or `target=`, and `task` is a reserved tool name. (Changed: **A resource capability…**; Added: **`task` is a reserved…**) -- In an ADK app built from configs, a sub-agent is called as a tool and - returns (no `transfer_to_agent`), seeing only its request unless +- In an ADK app built from configs, a sub-agent is called through `task` and + returns (no `transfer_to_agent`), seeing only its task unless `inherit_context=True`; a synchronous tool must be safe in a worker thread beside other calls; a prompt's `{name}` is not filled from session state. (Changed: **ADK sub-agents are delegated…**, **On ADK, synchronous…**, **On ADK, an agent's prompt…**) +- On both backends a coordinator delegates with `task(agent_type=, title=, + objective=, ...)` and reads the run's envelope, a JSON object, as the + call's result: a prompt that names a sub-agent's own tool + (`researcher(request=...)`) or Deep Agents' `description` and + `subagent_type` should name `task` and the brief's fields, and code that + read a delegation's `TOOL_RESULT` as text reads `metadata["result"]["result"]`. + (Changed: **One `task` tool on both backends…**, **A delegation's result + is the run's envelope…**) - A native ADK YAML app (`adk_config_path`) needs an `LlmAgent` root, agent names unique across its tree and no task-mode agent; agent configs passed with it are ignored, so name its tools in the YAML; a YAML ADK cannot load @@ -591,7 +599,10 @@ the start of the entry's title. 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. + the root, which is never delegated to. A delegation's brief is read + against it: a `task` call that leaves a required field empty starts no + run, and its caller reads which ("The brief for 'researcher' is missing: + deliverable."). - **`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` @@ -627,8 +638,8 @@ the start of the entry's title. run, title, tokens in/out (from the usage ledger, so a run still going shows what it has used so far) and time. `/agents ` shows one instance (`researcher-2`) or run (`researcher-2#1`): its type, parent and title, - then each run's status and time, the first lines of its result, its error - and its tokens by model. The runs are the manager's records, kept in + then each run's status and time, the other fields of its brief, the first + lines of its result, its error and its tokens by model. The runs are the manager's records, kept in memory with it: a conversation resumed from an earlier run of the app, or after a backend switch, lists none. During a turn each line of the events box names the sub-agent run at work (`researcher-2 › Calling: web_fetch`), @@ -673,24 +684,25 @@ the start of the entry's title. sub-agent, and a run two levels down, are told apart. ADK's `TOOL_CALL` and `TOOL_RESULT` carry `tool_call_id`, as Deep Agents' did. A sub-agent run's start and end are an event of their own, `EventType.AGENT_RUN` - (`WorkflowEvent.agent_run`; `metadata["status"]` `started`, with its title, - the first line of its request, then `completed` (`partial` for an answer - cut at its output limit), `refused`, `failed` or `interrupted`, with the - first 200 characters of its result; a run fails - on `Error running sub-agent: …` or the framework's own error result, an - error `ToolMessage` on Deep Agents, the error dict of a raised or denied - call on ADK, and the sub-agent's answer is never read for success, so an - answer that is JSON saying it failed completes), and each + (`WorkflowEvent.agent_run`; `metadata["status"]` `started`, with its + brief's title, the brief's filled fields (`brief`), who started it + (`started_by`: `agent:`, `agent:root` for the main agent) and + how it runs (`mode`: `blocking`, its caller waiting for it), then + `completed` (`partial` for an answer cut at its output limit), `refused`, + `failed` or `interrupted`, with the first 200 characters of its result; a + run fails when it cannot finish (a model call of its fails, its request no + longer fits its model's window, or its model gives no answer), and the + sub-agent's answer is never read for success, so an answer that is JSON + saying it failed completes), the same on both backends: the framework + starts and ends every run (`workflow/agents/delegate.py`), each at its own + end, so of two parallel delegations the faster ends first. Each manager records its runs by conversation (`BaseWorkflowManager.agent_runs`, - provisional: `records(ref)`, `record(ref, id)`); a run a stopped or failed - turn leaves open is recorded `interrupted`. On ADK a delegation that - finished beside a slower one in the same model step ends with the slower - one's (ADK hands a step's parallel function responses back in one event, - after the last), where Deep Agents ends each at its own result; a turn - stopped or failed before then ends it from the record, with its result, - not `interrupted`. `get_active_run()` (exported + provisional: `records(ref)`, `record(ref, id)`; a record has the brief, + `started_by`, `mode` and, for a cancelled run, `cancelled_by`); a run a + stopped or failed turn leaves open is recorded `interrupted`. + `get_active_run()` (exported from `agentic_cli.workflow` with `RunRef` and `root_run`) is the sub-agent - run whose call is in progress, None in the root's own: a sub-agent's + run at work, None in the root's own: a sub-agent's tools, permission checks and questions see it. A consumer that does not know `AGENT_RUN` ignores it; the CLI ignores it. @@ -970,15 +982,15 @@ the start of the entry's title. `ImportError` with that install hint. MCP tools, raw LLM logging, Agent Skills and job resume run on it too (the entries below), and `examples/hello_deepagents.py` is the hello example on it. - - **Delegation.** A coordinator delegates through Deep Agents' `task` tool - (`description`, the brief; `subagent_type`, the sub-agent's name), which - lists each sub-agent as `- name: description`; one without a - description is offered as "The agent." with a warning. A - sub-agent sees the brief and the coordinator's `plan` and `tasks`, and - one with `inherit_context=True` the conversation too (see - `AgentConfig.inherit_context`); its last text is the call's result, and - its own text shows as activity, not as the reply. Two sub-agents may run - at once. + - **Delegation.** A coordinator delegates through the framework's `task` + tool, as on ADK (see Changed: **One `task` tool on both backends…**): + each sub-agent's graph is built on its own and runs apart from its + coordinator's stream, in a task of its own, from the task message, the + coordinator's `plan` and `tasks`, and for one with + `inherit_context=True` the conversation too (see + `AgentConfig.inherit_context`); its last text is the envelope's result, + and its own text shows as activity, not as the reply. Two sub-agents may + run at once. - **Tools.** Every tool call, in every agent, passes the permission gate, which identifies the tool by the object the registry issued and asks through the input callback, sub-agents' calls included. A tool that @@ -1034,10 +1046,9 @@ the start of the entry's title. conversation that still does not fit ends the turn with one `ERROR`, `error_code` `CONTEXT_OVERFLOW`: "This conversation no longer fits 's context window. Use /compact or /new." (a sub-agent's fails - only its `task` call: its parent reads the error and its run fails, - where ADK answers it with text and its run completes; the user's - warning is ADK's, ": the request no longer fits 's - context window.", `CONTEXT_OVERFLOW`). The checkpoint + only its run, as on ADK: the user is warned ": the request no + longer fits 's context window.", `CONTEXT_OVERFLOW`, and its + parent reads those words as the run's error). The checkpoint keeps every message. Each summary is a `CONTEXT_TRIMMED` event (`source="summarization"`) with the summary call's own `LLM_USAGE` (`purpose="summarization"`), which the status bar adds to the totals @@ -1051,9 +1062,9 @@ the start of the entry's title. Sessions saved by the LangGraph backend do not carry over: they stay in `{workspace}/checkpoints.db`, untouched, and switching the orchestrator starts a new conversation, as it always has. -- **`task` is a reserved tool name**: the framework declares it for Deep - Agents' delegation tool, so registering another tool named `task` raises, - whichever backend runs. +- **`task` is a reserved tool name**: the framework declares it for its + delegation tool, on both backends, so registering another tool named + `task` raises, whichever backend runs. - **MCP servers' tools on Deep Agents** (`AgentConfig.mcp_servers`, the same `MCPServerConfig` as on ADK). Each agent's servers open when the workflow initializes, one session per agent and server, and a model switch reopens @@ -1185,8 +1196,8 @@ the start of the entry's title. window. While the summary is written the CLI shows "Summarizing the earlier conversation…", and the summary's usage and a `CONTEXT_TRIMMED` (`source="summarization"`) follow. - Only the main agent's conversation is summarized: a sub-agent past its own - trigger leaves the shared session alone. ADK's own pass after each turn is + Only the main agent's conversation is summarized: a sub-agent's run, on a + child session of its own, is trimmed by the fit guard instead. ADK's own pass after each turn is switched off (`NoAfterTurnCompactionRunner`), so the prompt never waits for a summary after the answer. A summary that fails is one warning a turn, "Could not summarize the earlier conversation; the agent goes on @@ -1243,8 +1254,10 @@ the start of the entry's title. result is still cut, its note says the full output could not be saved, and the log warns once per folder. Reading a saved output back cuts it again without a second file. Every result is covered: registered, MCP and - skill tools, `job_result`, and a sub-agent's answer (Deep Agents' `task`, - and on ADK the tool named after the sub-agent). ADK's + skill tools, `job_result`, and a sub-agent run's envelope (`task`'s + result, on both backends). A string that holds a JSON object (the + envelope, a framework tool's dict in a Deep Agents `ToolMessage`) is cut + as that dict and given back as JSON, so its parent reads JSON still. ADK's `ToolResultCapPlugin` caps every agent but one with `after_tool_callback`s of its own (a native ADK YAML app's), which ADK would skip once it cut; Deep Agents' `ToolResultCapMiddleware` sits between the permission gate @@ -1252,32 +1265,26 @@ the start of the entry's title. tool's own limits stay; this is the net beneath them. ADK's Claude and OpenAI Responses adapters send a model only a result's `content`, or else its `result`, so on ADK the note is put there as well. -- **`AgentConfig.inherit_context`: a sub-agent sees the request alone, or its +- **`AgentConfig.inherit_context`: a sub-agent sees its task alone, or its parent's conversation too**, set per agent on ADK and Deep Agents (`inherit_context:` in the framework's agent YAML too). False, the default, - sees only the request its parent gives it; True also sees the parent's + sees only the task its parent gives it; True also sees the parent's conversation as it stands, after any summary and without the parent's - reasoning. On ADK an inheriting sub-agent is built with - `include_contents="default"`, which ADK keeps for a `single_turn` agent - only when it is set, and sees its parent's turns as quoted context; ADK - sends it the user's turns as plain user messages, so its instruction ends - with a note (`delegation.INHERITED_CONTEXT_NOTE`) that the conversation is - its parent's and its task the request after it, as Deep Agents' preamble - frames a fork's: without it, Claude at times answered the user's request - to the coordinator instead of its own. On - Deep Agents it is a fork (`mode="fork"`, beta in Deep Agents, whose - `LangChainBetaWarning` is logged at debug, `deepagents_fork_beta`, rather - than printed): the coordinator's conversation without the message that - called `task`, then Deep Agents' preamble and the brief; its own - summarization compacts an inherited conversation too large for its - model, and `ForeignReasoningMiddleware` leaves out the reasoning of AI - messages another agent wrote, so a fork is never sent its coordinator's. + reasoning, the same way on both backends: the run starts from that + conversation, less the message that called `task`, then its task message, + which ends with a note (`agents/brief.py::INHERITED_CONTEXT_NOTE`) that the + conversation is its parent's and its task the message the note ends: + without it, Claude at times answered the user's request to the + coordinator instead of its own. On ADK the conversation's events are + copied into the run's child session; on Deep Agents they are the run's + input messages, which its own summarization compacts when they are too + large for its model, and `ForeignReasoningMiddleware` leaves out the + reasoning of AI messages another agent wrote, so the run is never sent its + coordinator's. `validate_agent_graph` raises `AgentGraphError` for `inherit_context=True` - on the root, on an agent with sub-agents of its own (in 0.7.0: Deep - Agents tells a fork that delegating "will be refused", which a - coordinator would believe) or on an agent below another sub-agent (it is - for the main agent's own sub-agents), and for a value that is not True or - False. + on the root, on an agent with sub-agents of its own or on an + agent below another sub-agent (it is for the main agent's own + sub-agents), and for a value that is not True or False. - **`BaseWorkflowManager.context_budget(agent_name=None)` and `root_agent_name`**: an agent's context numbers as its backend summarizes and trims by them, the root agent's by default. A frozen `ContextBudget` @@ -1534,6 +1541,49 @@ the start of the entry's title. ### Changed +- **One `task` tool on both backends, which takes a brief.** **Breaking:** + ADK offered one tool per sub-agent (`researcher(request=...)`) and Deep + Agents its own `task(description=, subagent_type=)`; now every agent + with sub-agents is offered the framework's `task`, the same on both + (`workflow/agents/brief.py`): `agent_type`, one of its own sub-agents, + each listed in the tool's description with what it does and the brief + fields it requires, then the brief, `title` and `objective` (required), + `deliverable`, `constraints`, `known` and `done_when`. The run's first + message is the task message, `# Task: ` and a section per filled + field (`## Objective`, `## Deliverable`, `## Constraints`, `## What is + already known`, `## Done when`). A call whose brief misses a field its + type requires, or names a type that is not the caller's, starts no run: + its result is `{"success": false, "error": ...}` naming what to fix. A + run starts from the conversation's `plan` and `tasks`, and the changes it + makes to them reach its caller's state when it returns (the status bar's + task list moves then). On ADK each sub-agent type runs on a runner of its + own over the manager's session service, on a child session of the run + (app `<app_name>--agents`, id `<conversation id>/<instance>`), which no + conversation list shows, and, an agent of its own there, its system + instruction gets ADK's identity line after its prompt as the root's does + (`You are an agent. Your internal name is "<name>".`, then its + description); on Deep Agents each type's graph runs apart from + its caller's stream, in a task of its own (Deep Agents' + `SubAgentMiddleware` and its fork are no longer used). +- **A delegation's result is the run's envelope, JSON, rather than bare + text, on both backends.** The parent reads `{"success": <completed>, + "agent": "<instance>", "run": "<run id>", "status": "<status>", + "partial": <bool>, "result": "<its last text>", "error": <null or one + line>}`: a failed run's `error` is the provider's reason (where ADK said + "Dynamic node <agent> failed"), a refused run's `a model refused the + request` with the refusal notice as its `result`, an interrupted run's + `interrupted before it finished`. No delegation is an error result any + more ("Error running sub-agent: …" is gone): the envelope says how the + run ended. A run's result is its last text, a reply that also called a + tool included, so an empty final answer after it leaves that text; a run + that wrote none completes with an empty result, shown `No answer` (an + inheriting run's result is only what it wrote, never a reply from the + conversation it read). The envelope is written unescaped + (`ensure_ascii=False`), and one over `tool_result_max_chars` is cut as a + dict, its `result` shortened and the note under `truncated`, so it stays + JSON. The delegation's `TOOL_RESULT` carries the envelope as + `metadata["result"]`. + - **Every `LLM_USAGE` counts the same way on both backends.** `prompt_tokens` is every input token, cache reads and writes included, and `completion_tokens` every output token, thinking included @@ -1939,9 +1989,9 @@ the start of the entry's title. cache), and sent uncached. If that fails too, the main agent's turn ends with one `ERROR`, `error_code` `CONTEXT_OVERFLOW`: "This conversation no longer fits <model>'s context window. Use /compact or /new.", as on Deep Agents, and - no reply is stored; a sub-agent tells its coordinator it could not do the - task, and the user gets one warning, "<agent>: the request no longer fits - <model>'s context window.". Any other model error, and one that fails + no reply is stored; a sub-agent's run fails, with one warning, "<agent>: + the request no longer fits <model>'s context window.", whose words its + coordinator reads as the run's error. Any other model error, and one that fails the retry, is the turn's one `ERROR`, the provider's own. The tracebacks ADK logs for a failed summary, model call or retry are logged at debug by the CLI, since the user is told otherwise: on ADK's @@ -1950,31 +2000,29 @@ the start of the entry's title. (`adk_overflow_plugin_failed`) loggers. Until now every failed model call printed one over the terminal. - **ADK sub-agents are delegated to and return, as on Deep Agents.** - **Breaking:** an agent built from a config that is not the root runs in - ADK's `single_turn` mode, with transfers to its parent and peers off. Its - parent calls it through a tool named after it, `<agent>(request=...)`, - and reads its last text as the call's result, `{"result": ...}`, in the - same turn; the root answers the user, and the next turn starts at the - root. No agent built from a config is offered `transfer_to_agent` any - more, so a sub-agent no longer takes over the conversation on later - turns. Sub-agents see only the request, where they saw the whole - conversation (set `inherit_context=True` for that). + **Breaking:** an agent built from a config is no ADK sub-agent of its + parent: each is built on its own, and its parent calls it through the + framework's `task` tool (see **One `task` tool on both backends…**) and + reads its run's envelope as the call's result, in the same turn; the root + answers the user, and the next turn starts at the root. No agent built + from a config is offered `transfer_to_agent` any more, so a sub-agent no + longer takes over the conversation on later turns. Sub-agents see only + their task, where they saw the whole conversation (set + `inherit_context=True` for that). `inherit_context` is for the main agent's own sub-agents in 0.7.0: `validate_agent_graph` refuses it below another sub-agent, on every - backend, since ADK would show such an agent the main agent's whole - conversation rather than its parent's. A prompt + backend. A prompt that names `transfer_to_agent` should say to delegate to the agent instead, as the research demo's coordinator now does; an app that relied on a specialist keeping the conversation routes follow-ups through the - main agent. The tool is ADK's private `_SingleTurnAgentTool`, which calls - no function the permission plugin can verify, so the framework binds each - one ADK builds for a sub-agent the framework built to the exempt `task` - declaration; an application's `AgentTool`, a subclass or a look-alike of - the same name is denied, and the sub-agent's own tool calls are gated as - before. A sub-agent named like one of its parent's tools fails to start - with `AgentGraphError`, since ADK's tool would shadow the parent's, and - one without a description is offered as "The <name> agent.", with a - warning (`adk_subagent_without_description`), as on Deep Agents. A + main agent. The tool is the framework's (`adk/task_tool.py::TaskTool`), + bound to the exempt `task` declaration where it is made; an application's + `AgentTool`, a subclass or a look-alike of the same name is denied, and + the sub-agent's own tool calls are gated as before. A delegating agent + whose own tools include one named `task` fails to start with + `AgentGraphError`, as on Deep Agents, and a sub-agent without a + description is offered as "The <name> agent.", with a warning + (`subagent_without_description`). A sub-agent's long-running tools are not wrapped as ADK's `LongRunningFunctionTool`: ADK pauses the whole invocation on a pending long-running call, inside a delegation too, which left the turn without a @@ -1996,17 +2044,15 @@ the start of the entry's title. (`recent_messages`) reads only the user's and the main agent's text, not a job notice. A sub-agent whose model call or run fails does not end the turn, on either - backend: its coordinator is handed "Error running sub-agent: …" as the - call's error result (ADK's delegation tool's words; on ADK its reason is - ADK's own, "Dynamic node <agent> failed"), and the user gets - a recoverable `ERROR`, `<agent> failed: <the provider's reason>`, with its - error code, while the coordinator answers. Only the main agent's own - failure ends the turn; cancelling still stops it all. A sub-agent's - request still too long for its model is warned of in the same words on - both backends, `<agent>: the request no longer fits <model>'s context - window.`, `error_code` `CONTEXT_OVERFLOW`; on ADK its call is answered - with text ("I could not do this task: …") and its run completes, on Deep - Agents its parent reads the error and the run fails. + backend: its run fails, its coordinator reads the provider's reason in + the run's envelope, and the user gets a recoverable `ERROR`, + `<instance> failed: <the provider's reason>` (`researcher-1 failed: …`), + with its error code, while the coordinator answers. Only the main + agent's own failure ends the turn; cancelling still stops it all. A + sub-agent's request still too long for its model fails its run on both + backends, with one warning, `<agent>: the request no longer fits + <model>'s context window.`, `error_code` `CONTEXT_OVERFLOW`, the words + its coordinator reads as the run's error. - **Models are named by reference or role, and resolved once, at startup.** `default_model`, `AgentConfig.model`, `Manager(model=...)` and `reinitialize(model=...)` take a `provider:model` reference or a bare model @@ -2862,10 +2908,10 @@ step; each entry says what to use instead. sub-agent's answer as "Result: 1 items" (its delegation tool hands back `{"result": text}`) and Deep Agents as up to 200 characters of the whole answer. Both now show its first line - (`tool_summaries.delegation_summary`), and a sub-agent that failed as a - failed result, `Failed: <reason>` (on ADK too, where it was a success - holding "Error running sub-agent: …"). `metadata["result"]` is unchanged. - The tool's name still differs: ADK's is the sub-agent's. + (`tool_summaries.delegation_summary`), and a run that failed or was + refused as a failed result (`Failed: <reason>` for a failure; on ADK it + was a success holding "Error running sub-agent: …"), as the run's + envelope says (`metadata["result"]`, a dict). - **The raw LLM log times each model call on its own, and names its run.** On ADK, a call's `latency_ms` was measured from a clock kept by invocation, which every call of a turn shares: with parallel delegations @@ -2886,7 +2932,7 @@ step; each entry says what to use instead. `completed` and `partial`, and one recoverable warning names it ("researcher-1's answer was cut off at the output limit"). Both backends judge by `workflow/agents/outcome.py`. On ADK, `SubAgentOutcomePlugin` (in - the chain of a tree that delegates) reads the answer's `finish_reason` + each sub-agent's runner's chain) reads the answer's `finish_reason` (Claude's `refusal` and a Chat Completions `content_filter` arrive as `SAFETY`, Gemini's blocks as themselves), the `error_code` ADK gives an answer with no content (a Gemini prompt's block reason), the reason an @@ -2912,11 +2958,13 @@ step; each entry says what to use instead. id alone) and dropped from the next request, and a call that had finished beside it lost its result. The record of a turn's calls (`OpenCalls`) now keeps each call under the run that made it (`run=`, by default - `get_active_run()`). On ADK a stopped turn answers, as it ends, the calls - ADK's seals missed, from that record, and the framework's answer to calls - left open pairs a result with a call on its own branch. The stopped - delegation is answered "Interrupted by the user before it finished", at - any depth, and a call that finished beside it keeps its result. + `get_active_run()`). On ADK a sub-agent's calls are on its run's own + child session, which its runner seals as it stops; a stopped turn + answers, as it ends, the calls ADK's seals missed, from that record, and + the framework's answer to calls left open pairs a result with a call on + its own branch. The stopped delegation is answered "Interrupted by the + user before it finished", at any depth, and a call that finished beside + it keeps its result. - **A `/settings` model picker offers the model it shows.** A picker showed its role's model even when that model was not among its choices (in 0.6, a `default_model` the model list did not include; now one the list leaves diff --git a/CLAUDE.md b/CLAUDE.md index fdc1b9fc..3f6d96c2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,7 +36,7 @@ agentic-cli/ │ │ ├── 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 │ │ ├── conversation_lock.py # ConversationLock: one process per stored conversation (flock under <sessions_dir>/locks/; ConversationCore holds it and refuses one held elsewhere; /sessions --delete too, through conversation_held) │ │ ├── builtin_commands.py # /help (by category; /help <command>: 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 <text> searches the full listings; refresh), /sessions (every installed backend's, a Backend column; --delete=<id> on the backend that keeps it, --backend=<name> for an id two keep; on the memory store NOT_KEPT, no table, --delete refused), /resume [<id>] (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 <id>: 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 +│ │ ├── 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 <id>: one instance or run (type, parent, title; each run's status and time, its brief's other fields, 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 <id>, 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; 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 <backend>:" on another backend), the replay of the last 10 messages @@ -49,14 +49,14 @@ 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 <id>'s tokens by model │ ├── workflow/ -│ │ ├── 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)) +│ │ ├── base_manager.py # BaseWorkflowManager (abstract; subagents=: its SubAgentPolicy, subagent_policy, read-only, kept for its life; _delegations: its Delegations (agents/delegate.py), made on first use over agent_runs, the policy, the agents' configs, the usage ledgers and _run_agent, the backend's hook that runs one sub-agent run; _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) │ │ ├── memory_index.py # MemoryIndex: the memory index the root's requests carry, one snapshot per conversation (now: taken once, off the event loop; cached: never reading; forget: /resume, a summary and /compact; clear: the release; cap: memory_index_max_bytes, or a tenth of the root's budget: MEMORY_INDEX_BUDGET_SHARE, MEMORY_INDEX_MIN_BYTES); reads the manager's settings, memory store, the root's memory tools (_root_memory_tools) and its room live, through callables, and takes a snapshot at the manager's _memory_index_cap (limit=), so a subclass's cap is the one asked; imports no backend │ │ ├── outside_content.py # OutsideContentMarks (per conversation, first tool wins), brings_outside_content, the note -│ │ ├── events.py # WorkflowEvent, EventType; WorkflowEvent.turn_failed: a failed turn's one ERROR (rate_limited, error_type); WorkflowEvent.run: the agent run that wrote it (RunRef; None: the manager's own); AGENT_RUN (WorkflowEvent.agent_run): a sub-agent run's start and end (an end with what the run used, by model: usage=); UserInputRequest.run: the sub-agent run that asks (request_user_input fills it from get_active_run()) +│ │ ├── events.py # WorkflowEvent, EventType; WorkflowEvent.turn_failed: a failed turn's one ERROR (rate_limited, error_type); WorkflowEvent.run: the agent run that wrote it (RunRef; None: the manager's own); AGENT_RUN (WorkflowEvent.agent_run): a sub-agent run's start (brief=, started_by=, mode=) and end (an end with what the run used, by model: usage=; cancelled_by= for a cancelled run); UserInputRequest.run: the sub-agent run that asks (request_user_input fills it from get_active_run()) │ │ ├── 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 @@ -73,7 +73,7 @@ agentic-cli/ │ │ ├── checkpointers.py # open_checkpointer (memory/sqlite/postgres) for the LangChain backends; open_store: the LangGraph store of the same kind beside it (sqlite: the same file, its own connection; a setup that lost a migration race to another process run again), Deep Agents' session index; deepagents_sqlite_path (deepagents_sqlite_location: where, without making it); private_sqlite_file: ADK's sessions.db and Deep Agents' checkpoints.db made owner-only before they open (an older one at the default location tightened, with the -journal/-wal/-shm beside it; an existing file sqlite_uri names left as it is) │ │ ├── llm_log.py # LLMLogWriter (raw_llm_logging JSONL, 0700/0600) + redact_secrets: ADK and Deep Agents; a sub-agent's record names its run (run: the event's RunRef) │ │ ├── tool_errors.py # tool_error_result / unknown_tool_result: ADK's error shapes, for ADK and Deep Agents -│ │ ├── tool_output.py # cap_tool_result: a result over tool_result_max_chars cut (head and tail, a note), its full output saved in ./.{app_name}/tool-output/ for read_file; both backends +│ │ ├── tool_output.py # cap_tool_result: a result over tool_result_max_chars cut (head and tail, a note; a string holding a JSON object cut as its dict and given back as JSON, json_object), its full output saved in ./.{app_name}/tool-output/ for read_file; both backends │ │ ├── summary_prompt.py # SUMMARY_PROMPT (LangChain's DEFAULT_SUMMARY_PROMPT, copied with its MIT notice: ADK runs without LangChain), SUMMARY_PREFIX, summary_prompt/with_focus; both backends │ │ ├── sessions.py # SessionRef; SessionInfo (a session list's row; backend: a reader's rows and the CLI's name theirs) and session_title; ConversationChangedError (ADK's stale session); the active turn; the active sub-agent run (RunRef, root_run, get_active_run: None in the root's own calls); the active tool call (ToolCallRef); the turn's span (open_turn_scope/close_turn_scope, turn_has_ended: a task that outlived its turn); instance_of (a run's instance, None for the root's: a job's started_by) │ │ ├── mcp.py # MCPServerConfig → to_adk_toolset / to_langchain_connection @@ -82,38 +82,38 @@ 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 <agent>-<n> 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 +│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names <agent>-<n> 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 (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: <error>; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named, its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut, refused, failed for an error or a raise, with one recoverable ERROR <instance> failed: <reason>, or RunFailed's own words), interrupted on a cancel; the envelope as the result), DelegationRequest, AgentRun, RunAnswer, RunFailed, started_by; 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), 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) -│ │ │ ├── branches.py # A sub-agent run on ADK: the branch it runs on (<agent>@<call id>, dot-nested under its parent's): delegations, branch_run, parent_branch_run -│ │ │ ├── delegation.py # Sub-agents as single_turn tools of their parent; binding those tools to task -│ │ │ ├── compaction.py # AgentCliSummarizer (main agent only; summary_range, render_events; its usage normalized, timed and recorded in the conversation's ledger, ledgers, as soon as the call answers: an empty summary's too; on_written: a summary written drops the conversation's memory index snapshot), MainAgentPlugin (the running agent; given the manager's runs, its branch's run as the active run as it starts, and its parent's again as it ends or fails: a delegated sub-agent runs inside its parent's call), NoAfterTurnCompactionRunner, compact_session +│ │ │ ├── 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; the agents: _create_agents builds each config's agent on its own (_agents, by name; no ADK sub_agents), a delegating one with a TaskTool (its own tool named task: AgentGraphError); a runner per sub-agent type (_agent_runners: NoAfterTurnCompactionRunner on App(name=child_app(app_name), root_agent=the type's agent, plugins=_agent_plugin_chain(agent), the app's context cache, no compaction) over the session service, closed with the main runner by _detach_backend, rebuilt by every initialization); _run_agent, the base's hook: the run's child session (_child_session: run.state, an inheriting run's copied events; one an earlier process left, replaced), the type's runner on the task message with an abort signal set before it is closed, a run-mode ADKEventProcessor, the raw log's records reported as they come (_report_raw_log); a model's failure raised as the provider's (_plugin_cause), an overflow RunFailed, a reply that is no answer RunAnswer(error=), the shared keys it changed read back) +│ │ │ ├── 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), own_after_tool_agents (left out by the cap) +│ │ │ ├── task_tool.py # TaskTool: the framework's task on ADK (a BaseTool; its declaration task_parameters' JSON schema, parameters_json_schema; its description task_description; bound to the task declaration, an exact TaskTool only): a call → Delegations.delegate, the run's shared-key changes written to the caller's state, the envelope returned as JSON text (ADK's OpenAI Responses adapter sends only a dict's result); SHARED_KEYS (plan, tasks, the outside-content mark); inherited_events (an inheriting run's history: the session's root-visible events, copied) +│ │ │ ├── compaction.py # AgentCliSummarizer (main agent only; summary_range, render_events; its usage normalized, timed and recorded in the conversation's ledger, ledgers, as soon as the call answers: an empty summary's too; on_written: a summary written drops the conversation's memory index snapshot), MainAgentPlugin (the running agent, first in every chain), NoAfterTurnCompactionRunner, compact_session │ │ │ ├── fit_guard_plugin.py # FitGuardPlugin: a request over its agent's budget has its oldest turns left out (drop_turns); what opens the conversation, the memory index then a summary (protected_head, never dropped), folded into the next user text (fold_summary); request_as_seen -│ │ │ ├── overflow_plugin.py # OverflowPlugin (OVERFLOW_PLUGIN_FAILED: ADK's wrapper of its errors, which the manager unwraps): a provider's overflow summarized (the root; the retry: the summary and the turns it kept) or trimmed, retried once (the retry timed around its own request: call_clock.mark_latency), then CONTEXT_OVERFLOW for an agent that replies (reply_agents), a sub-agent's text answer otherwise +│ │ │ ├── overflow_plugin.py # OverflowPlugin (OVERFLOW_PLUGIN_FAILED: ADK's wrapper of its errors, which the manager unwraps): a provider's overflow summarized (the root; the retry: the summary and the turns it kept) or trimmed, retried once (the retry timed around its own request: call_clock.mark_latency), then CONTEXT_OVERFLOW: overflow_message for an agent that replies (reply_agents), subagent_overflow_message for a sub-agent's run (root None on its runner), which fails it │ │ │ ├── memory_index_plugin.py # MemoryIndexPlugin: the conversation's memory index first in the root's requests (before the overflow handler and the fit guard, which keep and fold it) -│ │ │ ├── sessions.py # A conversation's row in its session state (agentic_cli.title, agentic_cli.turns), saved with each user turn (run_async(state_delta=)); typed_prompts; ServiceSessions: the session hooks over a session service (the manager's and its reader's); make_session_service, session_db_url; open_sessions (a reader's store: empty without ADK's sessions table, looked at read-only) -│ │ │ ├── event_processor.py # ADKEventProcessor (each call's LLM_USAGE normalized by its model's provider kind, kinds (an agent without one: an unknown kind's), with its latency (call_clock's mark), and recorded in the conversation's ledger before on_event, a run's end with what it used; reply_agents: the agents whose text is the reply; another's, a sub-agent's, marked as activity; a reply that is no answer, NO_ANSWER_CODES, → the turn's ERROR; a failed result, an MCP isError one too, → a failed TOOL_RESULT naming its error, as on Deep Agents; TASK_PROGRESS after a tool call that changed the task list, its state delta's tasks, as on Deep Agents: start_turn forgets the list reported; every event names its run, its branch's (adk/branches.py) or the agent's own at depth 0, TOOL_CALL and TOOL_RESULT their tool_call_id, and a delegation's call (to one of the caller's own single-turn sub-agents: any other call is no run) and result an AGENT_RUN: started, then, by run_ended, completed (partial, and one warning, for an answer SubAgentOutcomePlugin marked cut), failed ("Error running sub-agent: …", or the framework's error dict: the answer, under result, is never read for success), refused (marked refused) or interrupted (a stopped turn's seal), recorded in the manager's runs; end_returned_run: a delegation that finished beside a slower one, which ADK hands back only with it (a step's parallel results come in one event, after the last), ended from the record when the turn stops or fails first; the delegation's TOOL_RESULT shown as on Deep Agents: show_as_delegation) +│ │ │ ├── sessions.py # A conversation's row in its session state (agentic_cli.title, agentic_cli.turns), saved with each user turn (run_async(state_delta=)); typed_prompts; ServiceSessions: the session hooks over a session service (the manager's and its reader's); make_session_service, session_db_url; open_sessions (a reader's store: empty without ADK's sessions table, looked at read-only); CHILD_APP_SUFFIX, child_app (<app_name>--agents: the sub-agent runs' app, which no conversation list reads), child_session_id (<conversation id>/<instance>, a ValueError past ADK's 128 characters) +│ │ │ ├── event_processor.py # ADKEventProcessor (each call's LLM_USAGE normalized by its model's provider kind, kinds (an agent without one: an unknown kind's), with its latency (call_clock's mark), and recorded in the conversation's ledger before on_event, a run's end with what it used; reply_agents: the agents whose text is the reply; another's, a sub-agent's, marked as activity; a reply that is no answer, NO_ANSWER_CODES, → the turn's ERROR; a failed result, an MCP isError one too, → a failed TOOL_RESULT naming its error, as on Deep Agents; TASK_PROGRESS after a tool call that changed the task list, its state delta's tasks, as on Deep Agents: start_turn forgets the list reported; every event names its run, the agent's own at depth 0, TOOL_CALL and TOOL_RESULT their tool_call_id; a task call's TOOL_RESULT shown as on Deep Agents, from its envelope: show_as_delegation; run=: a processor for one sub-agent run, on its child session, every event that run's, a sub-agent's text activity, no TASK_PROGRESS (the root's reports the list as the run returns), its last answer with text, its outcome mark and its failure kept (answer, outcome, failure: an overflow, a reply that is no answer but an empty one) for _run_agent) │ │ │ ├── model_factory.py # build_adk_model: ResolvedModel → ADK model, config, planner │ │ │ ├── openai_compatible.py # OpenAICompatibleLlm (the configured providers: openrouter and openai_compatible kinds; reasoning text; OpenRouter's reasoning_details kept on the thought part (thought_signature, with the model that wrote them) and sent back on that turn's assistant message to that model only; a Chat Completions refusal, streamed or not, as the text ADK's Responses adapter makes of one, "OpenAI refusal: <text>"; no field sent as null; OpenRouter's cache writes, which ADK's usage mapping drops, kept on the usage as cache_creation_input_tokens) │ │ │ ├── anthropic_llm.py # DirectAnthropicLlm: bare claude-* strings → direct API (registered once per process, when a native YAML app is loaded: ensure_direct_anthropic) │ │ │ ├── permission_plugin.py # PermissionPlugin (gates tool calls; marks the conversation when an allowed call brings outside content, written to the session state at the model calls of the agents that reply); tool_definition: a tool object's registry identity, the gate's and the tool result cap's -│ │ │ ├── interrupted_calls_plugin.py # InterruptedCallsPlugin: a cancelled turn's seals worded (finished results kept, as the cap cut them), each seal answered as the run its branch names, each running call marked by its branch and id; unsealed: the calls ADK's seals missed (they pair by id alone), answered as the turn stops, from the record, as their branch's run's; left_open: a crash's calls answered at the next turn (a result pairs with a call on its own branch only; a job's state only for the root's own call, a sub-agent's run being numbered no more), and a stop's whose answers could not be written, as the user's; returned: a finished call's result from the record, as ADK stores it and the model reads it +│ │ │ ├── interrupted_calls_plugin.py # InterruptedCallsPlugin: a cancelled turn's seals worded (finished results kept, as the cap cut them), each seal answered as the active run's (a sub-agent run's runner seals its child session in the run's task), each running call marked by its invocation and id; unsealed: the calls ADK's seals missed (they pair by id alone: a native YAML app's branches), answered as the turn stops, from the record; left_open: a crash's calls answered at the next turn (a result pairs with a call on its own branch only; a job's state only for the root's own call, a sub-agent's run being numbered no more), and a stop's whose answers could not be written, as the user's; returned: a finished call's result from the record, as ADK stores it and the model reads it │ │ │ ├── task_progress_plugin.py # TaskProgressPlugin: deprecated and unused (DeprecationWarning; the event processor reports task progress), removed in 0.8.0 │ │ │ ├── tool_error_plugin.py # Tool exception → error result (turn survives); a call to an unknown tool name → ADK's own text (is_unknown_tool: ADK's stand-in, which the gate lets through), recorded in OpenCalls since ADK skips its after-tool callbacks, so a cancelled turn keeps it │ │ │ ├── tool_result_cap_plugin.py # ToolResultCapPlugin: every tool result through cap_tool_result (after InterruptedCallsPlugin), but an agent's with after-tool callbacks of its own (skip_agents), which ADK skips once a plugin answered │ │ │ ├── context_cache_plugin.py # One Gemini cache attempt a turn │ │ │ ├── foreign_reasoning_plugin.py # No model is sent another provider's thoughts -│ │ │ ├── subagent_outcome_plugin.py # SubAgentOutcomePlugin: a sub-agent's final answer a model refused or cut, rewritten in place (the refusal notice; the text and the cut-off note) and marked (custom_metadata agentic_cli_outcome), which the event processor ends its run by; what it reads: finish_reason, error_code, an OTHER stop's JSON reason, the text "OpenAI refusal: <text>"; in the chain of a tree that delegates, after the raw log; the root's answers untouched +│ │ │ ├── subagent_outcome_plugin.py # SubAgentOutcomePlugin: a sub-agent's final answer a model refused or cut, rewritten in place (the refusal notice; the text and the cut-off note) and marked (custom_metadata agentic_cli_outcome), which the run's event processor ends it by; what it reads: finish_reason, error_code, an OTHER stop's JSON reason, the text "OpenAI refusal: <text>"; in each sub-agent type's runner's chain (_agent_plugin_chain), after the raw log; the root's answers untouched │ │ │ ├── log_filters.py # install_log_filters: what ADK would print over the CLI logged at debug instead (the warnings hook, filters by logger name: see Console Output); imports no ADK (the package loads LLMLoggingPlugin on first use); the plugin-manager filter reads overflow_plugin.OVERFLOW_PLUGIN_FAILED as a record comes; BaseCLIApp.run() installs them, once │ │ │ ├── call_clock.py # Every model call timed: CallClock (a clock per call, under its EventActions, held through an error until the answer a later plugin gives; the raw log keeps one too), CallSentPlugin (last: starts it as the request goes out), CallLatencyPlugin (second, after MainAgentPlugin: marks the answer, custom_metadata[LATENCY_KEY], which the event processor reads, call_latency; an answer already marked keeps its mark: mark_latency, the overflow retry's); no adapter sends it │ │ │ └── plugins.py # LLM traffic logging (raw_llm_logging): requests as sent (SentRequestLoggingPlugin, after the fit guard); each record names its agent's model, the agent and its sub-agent run (the active run); latency per model call (call_clock.CallClock: a clock under the call's EventActions, as the fit guard keeps its copies); usage records go to the file only (the stream's LLM_USAGE is the event processor's), counted as the stream's (adk_usage_event, by the agent's kind: kinds); the summary call and the overflow retry are not logged on ADK (a follow-up) │ │ ├── deepagents/ # Deep Agents orchestrator (deepagents extra); imports neither adk/ nor langgraph/ -│ │ │ ├── manager.py # DeepAgentsWorkflowManager (turns, sessions, the release hooks: the agents and MCP sessions, the checkpointer and index; MCP, skills, the job resume hooks (_conversation_exists, _deliver_job_notice), _compact_turn) -│ │ │ ├── agent_builder.py # build_agent_tree: one create_agent per AgentConfig, bottom-up; task via SubAgentMiddleware (inherit_context = a fork) -│ │ │ ├── middleware.py # InterruptedCallsMiddleware (each call recorded and answered as the active run's), PermissionMiddleware, ToolResultCapMiddleware, ToolCallErrorMiddleware (a failed task call: ADK's "Error running sub-agent: <reason>" and a live recoverable ERROR, an overflow's in ADK's words), ActiveToolCallMiddleware (a task call to one of the agent's own sub-agents is also the active run of the sub-agent it starts), ForeignReasoningMiddleware, ContextOverflowMiddleware, MemoryIndexMiddleware (the root's memory index first in the first human message of each request), SubAgentOutcomeMiddleware (outermost on every sub-agent's model side: a refused or cut final answer rewritten, its reasoning kept, and marked, response_metadata["agentic_cli"]["outcome"], beside the other marks; a call that raises passes); mark_latency/answer_latency: the run callback's mark of how long a call took, response_metadata["agentic_cli"]["latency_ms"]; only the gate has a synchronous tool or model wrapper (it denies the sync tool call), the rest wrap with the async ones (`InterruptedCallsMiddleware.before_agent` is a node hook, synchronous, run on async turns too): turns run through `astream`, and a synchronous run of a graph fails at the first without a sync wrapper, LangChain's NotImplementedError +│ │ │ ├── manager.py # DeepAgentsWorkflowManager (turns, sessions, the release hooks: the agents and MCP sessions, the checkpointer and index; MCP, skills, the job resume hooks (_conversation_exists, _deliver_job_notice), _compact_turn; _run_agent, the base's hook: the type's graph (_agent_graphs) astreamed in the run's task with var_child_runnable_config cleared, so its chunks reach its own loop alone, through a run-mode processor and a RunCallback of its own; the answer the last AIMessage with text, its outcome mark, the shared keys it changed by Deep Agents' _is_unchanged rule (copied), an overflow RunFailed) +│ │ │ ├── agent_builder.py # build_agent_tree: one create_agent per AgentConfig, each on its own (graphs=: kept by name for _run_agent; the root's alone checkpointed); a delegating agent's task from task_tool.build_task_tool (delegations=), its own tool named task an AgentGraphError +│ │ │ ├── middleware.py # InterruptedCallsMiddleware (each call recorded and answered as the active run's), PermissionMiddleware, ToolResultCapMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware (each call the active tool call around its tool), ForeignReasoningMiddleware, ContextOverflowMiddleware, MemoryIndexMiddleware (the root's memory index first in the first human message of each request), SubAgentOutcomeMiddleware (outermost on every sub-agent's model side: a refused or cut final answer rewritten, its reasoning kept, and marked, response_metadata["agentic_cli"]["outcome"], beside the other marks; a call that raises passes); mark_latency/answer_latency: the run callback's mark of how long a call took, response_metadata["agentic_cli"]["latency_ms"]; only the gate has a synchronous tool or model wrapper (it denies the sync tool call), the rest wrap with the async ones (`InterruptedCallsMiddleware.before_agent` is a node hook, synchronous, run on async turns too): turns run through `astream`, and a synchronous run of a graph fails at the first without a sync wrapper, LangChain's NotImplementedError │ │ │ ├── tools.py # to_langchain_tools: a callable → StructuredTool whose .func/.coroutine is it -│ │ │ ├── event_processor.py # DeepAgentsEventProcessor (stream → WorkflowEvent, each call's LLM_USAGE, with its latency (answer_latency), recorded in the conversation's usage ledger before on_event, a run's end with what it used; by agent and run: a namespace's run from the tasks stream's task call; AGENT_RUN at a task call to one of the caller's own sub-agents (any other type runs none: no run) and at its result (failed: an error ToolMessage, the sub-agent's answer never read for success, as on ADK; refused, or partial with one warning, by SubAgentOutcomeMiddleware's mark), recorded in the manager's runs; the task call's TOOL_RESULT shown as on ADK: show_as_delegation; a failed turn names the innermost failure no task call answered); RunCallback (every model call timed, its answer marked with its latency before any middleware sees it; a summary's usage recorded in the conversation's ledger; what a node reports inside itself, through the turn's `LiveEvents`: required; `compact()` called outside a reporting context gets one nobody reads) +│ │ │ ├── task_tool.py # build_task_tool: the framework's task on Deep Agents (a StructuredTool over task_parameters' JSON schema, bound to the task declaration): a call → Delegations.delegate, whose shared-key changes and envelope (JSON, the ToolMessage) come back as one Command; SHARED_KEYS; inherited_messages (an inheriting run's history: the state's messages, the summary event applied, less the message that called task) +│ │ │ ├── event_processor.py # DeepAgentsEventProcessor (stream → WorkflowEvent, each call's LLM_USAGE, with its latency (answer_latency), recorded in the conversation's usage ledger before on_event, a run's end with what it used; every event its processor's agent's and run's (run=: a processor for one sub-agent run, its text activity, no TASK_PROGRESS), from the root namespace's items only (a graph a tool runs streams in its own); the task call's TOOL_RESULT shown as on ADK, from its envelope: show_as_delegation); RunCallback (every model call timed, its answer marked with its latency before any middleware sees it; a summary's usage recorded in the conversation's ledger; what a node reports inside itself, through the turn's `LiveEvents`: required; `compact()` called outside a reporting context gets one nobody reads) │ │ │ ├── sessions.py # thread_id(SessionRef), CheckpointSessions (rows from an index in the store beside the checkpointer, written as a turn starts (its input counted: a killed process still lists it), then from the newest root checkpoint as it ends and after /compact; a database from before it scanned once per app and user), job notifications; open_sessions: a store's conversations for a reader, without the manager (empty without the checkpoints table, looked at read-only before any setup) │ │ │ ├── summarization.py # Each agent's thresholds from its budget (the manager's _budgets, given to build_agent_tree(budgets=); context_budget when none); NoArchiveBackend; history filters; compact()'s cut, summary and event (marked: the count reported before it is no trigger, _should_summarize); OverflowMapped: the summary model's overflows as ContextOverflowError, inside its retry; a request's count includes the memory index (index=), and a summary written drops its snapshot before the request goes on (on_written=) │ │ │ ├── mcp_tools.py # MCPSessions: one owner task per (agent, server); the mcp identity map; a call fails once its session ends (_while_open: mcp's stdio client can leave one unanswered) @@ -149,7 +149,7 @@ agentic-cli/ │ │ │ ├── planning.py # save_plan/get_plan core (+ checkbox parsing) │ │ │ ├── tasks.py # save_tasks/get_tasks core (+ progress parsing) │ │ │ ├── state_tools.py # Declares save_plan/get_plan/save_tasks/get_tasks (declare_tool) -│ │ │ └── delegation.py # Declares task, Deep Agents' delegation tool: a reserved name +│ │ │ └── delegation.py # Declares task, the framework's delegation tool on both backends: a reserved name │ │ ├── adk/state_tools.py # ADK-native plan/task tools (ToolContext.state) │ │ ├── langgraph/state_tools.py # LangGraph-library plan/task tools (Command/InjectedState): Deep Agents and LangGraph │ │ ├── skills/ # Agent Skills: SkillStore, the ADK toolset (toolset.py) @@ -247,10 +247,10 @@ Workflow: - **UI-agnostic workflow**: WorkflowEvent objects can be consumed by any UI ### Key Design Patterns -- **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`. An exception that still escapes a tool is a bug, but it costs one call rather than the turn: on ADK, `workflow/adk/tool_error_plugin.py::ToolErrorPlugin` turns it into an error dict; on Deep Agents, `workflow/deepagents/middleware.py::ToolCallErrorMiddleware`, inside the permission gate, gives the same result, `{"success": false, "error": "<tool> failed: <Type>: <message>"}` cut to 500 characters (both use `workflow/tool_errors.py`). A call to a tool name the agent does not have gets ADK's own text, its first two lines (`unknown_tool_result`: "nope failed: ValueError: Tool 'nope' not found." and the agent's tools by name), logged `tool_not_found` at info (the model's mistake): on ADK the permission gate lets ADK's stand-in through (`is_unknown_tool`: a bare `BaseTool` described "Tool not found", which runs nothing; contract-tested) and `ToolErrorPlugin` answers its lookup error; on Deep Agents the gate answers it. It catches `Exception`, never `BaseException`, so cancelling still cancels; an exception out of `task` (a sub-agent's model or run failing, its summary or overflow included: its own tools' errors are results already) is answered as ADK's delegation tool answers it, `Error running sub-agent: <reason>` with `status="error"`, and reported at once through the turn's live events as one recoverable `ERROR`, `<agent> failed: <reason>`, the sub-agent's run's: the coordinator carries on. A sub-agent's overflow (still too long after its summary) is warned of in the words of ADK's overflow handler, `<agent>: the request no longer fits <model>'s context window.` with `error_code` `CONTEXT_OVERFLOW` (`context.py::subagent_overflow_message`, both backends); what differs: ADK answers the sub-agent's model call with text ("I could not do this task: …"), so its run completes, while on Deep Agents the parent reads the error and the run fails. A refusal is no exception here (the framework adds no `ModelRefusalMiddleware`): a sub-agent whose final answer a model refused ends its run `refused`, and its parent reads Deep Agents 0.7.34's notice ("The subagent stopped because a model refused the request. … Retrying the same request is unlikely to succeed; rephrase it or continue without it."), on both backends and whichever deepagents the pin installs (0.7.28 has no notice of its own; 0.7.34+ finds no refusal block left to word again); an answer cut at the output limit keeps its text, followed by `[cut off at the output limit]`, and its run ends `completed` and `partial`, with one recoverable warning ("<instance>'s answer was cut off at the output limit"); the answer's thoughts or reasoning are kept. ADK's `SubAgentOutcomePlugin` and Deep Agents' `SubAgentOutcomeMiddleware` rewrite and mark the answer, by `workflow/agents/outcome.py`. On ADK the plugin reads the answer's `finish_reason` (Claude's `refusal` and a Chat Completions `content_filter` arrive as `SAFETY`, `max_tokens` and `length` as `MAX_TOKENS`, Gemini's as themselves), the `error_code` ADK sets on an answer with no content (a Gemini prompt's `block_reason`), the `reason` an `OTHER` stop names in its JSON error message (ADK's OpenAI Responses adapter's `incomplete_details`, `content_filter` among them) and a text part `OpenAI refusal: <text>` (that adapter's refusal, and `OpenAICompatibleLlm`'s of a Chat Completions `refusal`, which ADK's class drops). On Deep Agents the middleware reads `response_metadata`'s `stop_reason` (ChatAnthropic), `finish_reason` (ChatOpenAI, ChatGoogleGenerativeAI), `incomplete_details.reason` (the Responses API) and `prompt_feedback.block_reason` (a Gemini prompt block), and a refusal the answer holds (a refusal block, standard or `non_standard`, or `additional_kwargs["refusal"]`). The root's own answers reach the user as their model gave them: on ADK a root's refusal with no answer (Claude's, Gemini's) is still the turn's one `ERROR` ("<model> returned no answer"), and a root on OpenRouter or an OpenAI-compatible server replies "OpenAI refusal: <text>". On ADK a sub-agent's model failure is answered the same way: ADK's `_SingleTurnAgentTool` hands its parent "Error running sub-agent: …" (its reason ADK's wrapper's, "Dynamic node <agent> failed"), and `ADKEventProcessor` turns the sub-agent's error event into the recoverable `ERROR` (config-built apps). On both backends the root's own failure leaves the run: the turn's one `ERROR`, which Deep Agents' processor attributes to the innermost failure no `task` call answered. A gate or error result goes back as the call's `ToolMessage` with `status="error"`. LangGraph's `ToolNode` runs with `handle_tool_errors=True`. -- **Tool result cap**: every tool result passes `workflow/tool_output.py::cap_tool_result` (registered, MCP and skill tools, `job_result`, a sub-agent's answer on either backend): one over `tool_result_max_chars` is cut to its shape and as much of its head and tail as fits (the kept length is bisected, since JSON escapes vary), with a note (under `truncated`, or appended to a string) pointing at its full output in `./.{app_name}/tool-output/`, written for `read_file` to page by lines (lines over 2,000 characters split). On ADK, `workflow/adk/tool_result_cap_plugin.py::ToolResultCapPlugin` is registered after `InterruptedCallsPlugin`, since ADK stops at the first `after_tool_callback` that returns a value, and it leaves out an agent with `after_tool_callback`s of its own (a native YAML app's, `build.own_after_tool_agents`), which ADK would skip once the cap answered. ADK's Claude and OpenAI Responses adapters send only a result's `content`, else its `result`, so the plugin also puts the note there (`_note_where_sent`). On Deep Agents, `ToolResultCapMiddleware` sits between the permission gate and `ToolCallErrorMiddleware`, so an error result is capped too, and reads a `ToolMessage` (a JSON object cut as a dict, other text as a string, text blocks joined into the first) and each `ToolMessage` of a `Command`. A call of the framework's `read_file` (by identity, as each gate resolves tools) on a saved output is cut without a second save. Saving never fails the call (`tool_output_not_saved` warns once per folder, then debug), and a cap that raises leaves the result uncut (`tool_result_cap_failed` at warning, its traceback at debug). -- **Summarizing on ADK (main agent only)**: every app's App (a native ADK YAML app's too, when its root's model has a context budget) has ADK's `EventsCompactionConfig` with `workflow/adk/compaction.py::AgentCliSummarizer` at the root's trigger (`context_budget`, as on Deep Agents); ADK checks before every agent's model call, and `MainAgentPlugin` (the first plugin) records the running agent in a ContextVar, so the summarizer writes only for the root: a sub-agent compacting the shared session lost its brief and looped (100 requests in one turn, offline). The summarizer picks its own range before paying for anything (`summary_range`: the newest `keep` tokens and the current turn kept, a cut only where a user turn starts, never parting a call from its result, long-running calls excepted since ADK re-injects them, nor leaving a kept event stamped inside the range; none for a saving under 20% of the trigger, the seed left out of it), writes on the root's own model (`_simple_model(SUMMARY_MAX_TOKENS, agent=root)`, thinking off) with `workflow/summary_prompt.py`, the rendering sized to that model's window (the middle cut, `MIDDLE_OMITTED`, the seed kept whole), and returns **user-role** text starting `SUMMARY_PREFIX` (a model-role first message is one Claude refuses), which the fit guard folds, after the memory index when the request has one, into the next user text (`fold_summary`), so no request holds two user messages in a row. `last_kept_turns` and `last_error` are for its callers: a manual summarizer warns of nothing itself. It reports through the turn's live events (`_run_and_stream` iterates the runner through `live_events.merged` under `reporting(live)`); any failure is one recoverable `ERROR` a turn, never raised to ADK. `NoAfterTurnCompactionRunner` overrides ADK's private `Runner._run_post_invocation_compaction` (contract-tested), so the prompt never waits for a summary after the answer. `FitGuardPlugin` is the last plugin (but `SentRequestLoggingPlugin`, which logs a request as sent, and `CallSentPlugin`, which starts the call's clock) and `OverflowPlugin` the one before it (`MemoryIndexPlugin`, when the root has a memory tool and `memory_index_enabled` is on, the one before that: it puts the conversation's memory index snapshot first in the root's requests, never in the session): the guard leaves a request's oldest turns out when it is over its agent's budget (keeping the newest turn and what opens the conversation, the memory index then a summary: `protected_head`) and keeps each request as it came in (`request_as_seen`: one copy per model call, under the call's `EventActions`, which ADK passes to all three of its callbacks, since two parallel delegations to one sub-agent share the invocation and the agent name; each run drops what a cancelled call left), and the overflow handler, on a provider's overflow, summarizes now (the root, through `compact_session`, ADK's private `_run_compaction_for_token_threshold_config`; `_summarize_now` returns `WrittenSummary(text, kept_turns)`, and the retry is the index, the summary and those turns) or trims to half the budget (a sub-agent, or nothing to summarize), builds the retry from the guard's copy without the context cache, retries once on the agent's `canonical_model`, then answers the root with `LlmResponse(error_code="CONTEXT_OVERFLOW")`, never model text (ADK would store it as the reply), which `ADKEventProcessor` maps to the turn's `ERROR`; a retry that fails otherwise propagates, and `_run_and_stream` unwraps ADK's plugin-manager `RuntimeError` to the provider's error; a sub-agent answers with text ("I could not do this task: …") and one live recoverable `ERROR`, with no `error_code` on its response (that would be a second warning). A native ADK YAML app gets all of it: only the building of its agents differs (`workflow/adk/build.py`). Its chat-mode sub-agents keep transferring, and an agent the root transfers to replies to the user (`build.reply_agents`: its text is the reply, recent_messages reads it, its overflow is the turn's clear error, its calls write the outside-content mark); the summary and the memory index stay the root's, so such an agent is trimmed by the fit guard, not summarized. An agent's own callbacks (a native app's) run after every plugin, and only when none answered: its before-model callbacks see the request after the fit guard, and the cap leaves out an agent with after-tool callbacks. A main agent whose model does not resolve through the catalog has no budget and no summary. -- **Sub-agents delegate and return**: on both backends a sub-agent is a tool call of its parent's that returns its last text in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text, and a sub-agent without a description is offered as "The <name> agent." with a warning. `AgentConfig.inherit_context` sets what it sees: False (the default) the request alone, True its parent's conversation too; `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root and, in 0.7.0, on an agent with sub-agents (Deep Agents tells a fork that delegating "will be refused") or below another sub-agent. On ADK (`workflow/adk/delegation.py`) every config-built agent but the root is `single_turn` with both `disallow_transfer_*` set, so ADK offers none of them `transfer_to_agent`, and an inheriting one passes `include_contents="default"` explicitly (ADK forces `"none"` on a `single_turn` agent unless the field was set) and ends the agent's instruction with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task: ADK sends it the user's turns as plain user messages); a sub-agent named like one of its parent's tools fails the build. On Deep Agents a fresh sub-agent is isolated and an inheriting one a fork (`mode="fork"`; its `LangChainBetaWarning` filtered to a debug log, `deepagents_fork_beta`), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. +- **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`. An exception that still escapes a tool is a bug, but it costs one call rather than the turn: on ADK, `workflow/adk/tool_error_plugin.py::ToolErrorPlugin` turns it into an error dict; on Deep Agents, `workflow/deepagents/middleware.py::ToolCallErrorMiddleware`, inside the permission gate, gives the same result, `{"success": false, "error": "<tool> failed: <Type>: <message>"}` cut to 500 characters (both use `workflow/tool_errors.py`). A call to a tool name the agent does not have gets ADK's own text, its first two lines (`unknown_tool_result`: "nope failed: ValueError: Tool 'nope' not found." and the agent's tools by name), logged `tool_not_found` at info (the model's mistake): on ADK the permission gate lets ADK's stand-in through (`is_unknown_tool`: a bare `BaseTool` described "Tool not found", which runs nothing; contract-tested) and `ToolErrorPlugin` answers its lookup error; on Deep Agents the gate answers it. It catches `Exception`, never `BaseException`, so cancelling still cancels. `task` raises nothing into it: a sub-agent's model or run failing (its summary or overflow included: its own tools' errors are results already) fails the run, whose envelope its parent reads (`error`: the provider's reason; on ADK out of ADK's plugin wrapper), reported at once through the turn's live events as one recoverable `ERROR`, `<instance> failed: <reason>`, the run's: the coordinator carries on. A sub-agent's overflow (still too long after its summary or trim) fails its run, on both backends, in the words of ADK's overflow handler, `<agent>: the request no longer fits <model>'s context window.` with `error_code` `CONTEXT_OVERFLOW` (`context.py::subagent_overflow_message`): ADK's `OverflowPlugin` answers the run's model call with it, Deep Agents' manager raises it (`RunFailed`). A refusal is no exception here (the framework adds no `ModelRefusalMiddleware`): a sub-agent whose final answer a model refused ends its run `refused`, and its parent reads, as its envelope's result, Deep Agents 0.7.34's notice ("The subagent stopped because a model refused the request. … Retrying the same request is unlikely to succeed; rephrase it or continue without it."), on both backends and whichever deepagents the pin installs (0.7.28 has no notice of its own; 0.7.34+ finds no refusal block left to word again); an answer cut at the output limit keeps its text, followed by `[cut off at the output limit]`, and its run ends `completed` and `partial`, with one recoverable warning ("<instance>'s answer was cut off at the output limit"); the answer's thoughts or reasoning are kept. ADK's `SubAgentOutcomePlugin` and Deep Agents' `SubAgentOutcomeMiddleware` rewrite and mark the answer, by `workflow/agents/outcome.py`. On ADK the plugin reads the answer's `finish_reason` (Claude's `refusal` and a Chat Completions `content_filter` arrive as `SAFETY`, `max_tokens` and `length` as `MAX_TOKENS`, Gemini's as themselves), the `error_code` ADK sets on an answer with no content (a Gemini prompt's `block_reason`), the `reason` an `OTHER` stop names in its JSON error message (ADK's OpenAI Responses adapter's `incomplete_details`, `content_filter` among them) and a text part `OpenAI refusal: <text>` (that adapter's refusal, and `OpenAICompatibleLlm`'s of a Chat Completions `refusal`, which ADK's class drops). On Deep Agents the middleware reads `response_metadata`'s `stop_reason` (ChatAnthropic), `finish_reason` (ChatOpenAI, ChatGoogleGenerativeAI), `incomplete_details.reason` (the Responses API) and `prompt_feedback.block_reason` (a Gemini prompt block), and a refusal the answer holds (a refusal block, standard or `non_standard`, or `additional_kwargs["refusal"]`). The root's own answers reach the user as their model gave them: on ADK a root's refusal with no answer (Claude's, Gemini's) is still the turn's one `ERROR` ("<model> returned no answer"), and a root on OpenRouter or an OpenAI-compatible server replies "OpenAI refusal: <text>". On both backends the root's own failure leaves the run: the turn's one `ERROR`. A gate or error result goes back as the call's `ToolMessage` with `status="error"`. LangGraph's `ToolNode` runs with `handle_tool_errors=True`. +- **Tool result cap**: every tool result passes `workflow/tool_output.py::cap_tool_result` (registered, MCP and skill tools, `job_result`, a delegation's envelope on either backend): one over `tool_result_max_chars` is cut to its shape and as much of its head and tail as fits (the kept length is bisected, since JSON escapes vary), with a note (under `truncated`, or appended to a string) pointing at its full output in `./.{app_name}/tool-output/`, written for `read_file` to page by lines (lines over 2,000 characters split). A string that holds a JSON object (`json_object`: a delegation's envelope, which both task tools write unescaped, `ensure_ascii=False`; a framework tool's dict in a Deep Agents `ToolMessage`) is cut as that dict and given back as its JSON text, so the parent reads JSON still, on both backends. On ADK, `workflow/adk/tool_result_cap_plugin.py::ToolResultCapPlugin` is registered after `InterruptedCallsPlugin`, since ADK stops at the first `after_tool_callback` that returns a value, and it leaves out an agent with `after_tool_callback`s of its own (a native YAML app's, `build.own_after_tool_agents`), which ADK would skip once the cap answered. ADK's Claude and OpenAI Responses adapters send only a result's `content`, else its `result`, so the plugin also puts the note there (`_note_where_sent`). On Deep Agents, `ToolResultCapMiddleware` sits between the permission gate and `ToolCallErrorMiddleware`, so an error result is capped too, and reads a `ToolMessage` (its text cut by the cap's string rule, text blocks joined into the first) and each `ToolMessage` of a `Command`. A call of the framework's `read_file` (by identity, as each gate resolves tools) on a saved output is cut without a second save. Saving never fails the call (`tool_output_not_saved` warns once per folder, then debug), and a cap that raises leaves the result uncut (`tool_result_cap_failed` at warning, its traceback at debug). +- **Summarizing on ADK (main agent only)**: every app's App (a native ADK YAML app's too, when its root's model has a context budget) has ADK's `EventsCompactionConfig` with `workflow/adk/compaction.py::AgentCliSummarizer` at the root's trigger (`context_budget`, as on Deep Agents); ADK checks before every agent's model call, and `MainAgentPlugin` (the first plugin) records the running agent in a ContextVar, so the summarizer writes only for the root (a sub-agent's run, on its type's runner, has no compaction config at all: a sub-agent compacting the shared session lost its brief and looped, 100 requests in one turn, offline). The summarizer picks its own range before paying for anything (`summary_range`: the newest `keep` tokens and the current turn kept, a cut only where a user turn starts, never parting a call from its result, long-running calls excepted since ADK re-injects them, nor leaving a kept event stamped inside the range; none for a saving under 20% of the trigger, the seed left out of it), writes on the root's own model (`_simple_model(SUMMARY_MAX_TOKENS, agent=root)`, thinking off) with `workflow/summary_prompt.py`, the rendering sized to that model's window (the middle cut, `MIDDLE_OMITTED`, the seed kept whole), and returns **user-role** text starting `SUMMARY_PREFIX` (a model-role first message is one Claude refuses), which the fit guard folds, after the memory index when the request has one, into the next user text (`fold_summary`), so no request holds two user messages in a row. `last_kept_turns` and `last_error` are for its callers: a manual summarizer warns of nothing itself. It reports through the turn's live events (`_run_and_stream` iterates the runner through `live_events.merged` under `reporting(live)`); any failure is one recoverable `ERROR` a turn, never raised to ADK. `NoAfterTurnCompactionRunner` overrides ADK's private `Runner._run_post_invocation_compaction` (contract-tested), so the prompt never waits for a summary after the answer. `FitGuardPlugin` is the last plugin (but `SentRequestLoggingPlugin`, which logs a request as sent, and `CallSentPlugin`, which starts the call's clock) and `OverflowPlugin` the one before it (`MemoryIndexPlugin`, when the root has a memory tool and `memory_index_enabled` is on, the one before that: it puts the conversation's memory index snapshot first in the root's requests, never in the session): the guard leaves a request's oldest turns out when it is over its agent's budget (keeping the newest turn and what opens the conversation, the memory index then a summary: `protected_head`) and keeps each request as it came in (`request_as_seen`: one copy per model call, under the call's `EventActions`, which ADK passes to all three of its callbacks: each sub-agent run is an invocation of its own on a child session, but two runs of one type share that type's runner and its plugins, and a run drops only what its own cancelled calls left, as it ends), and the overflow handler, on a provider's overflow, summarizes now (the root, through `compact_session`, ADK's private `_run_compaction_for_token_threshold_config`; `_summarize_now` returns `WrittenSummary(text, kept_turns)`, and the retry is the index, the summary and those turns) or trims to half the budget (a sub-agent, or nothing to summarize), builds the retry from the guard's copy without the context cache, retries once on the agent's `canonical_model`, then answers the root with `LlmResponse(error_code="CONTEXT_OVERFLOW")`, never model text (ADK would store it as the reply), which `ADKEventProcessor` maps to the turn's `ERROR`; a retry that fails otherwise propagates, and `_run_and_stream` unwraps ADK's plugin-manager `RuntimeError` to the provider's error; a sub-agent's call that still does not fit is answered with an error response too, `CONTEXT_OVERFLOW` and `subagent_overflow_message`, which its run's processor keeps as the run's failure: the run ends `failed` with those words (`RunFailed`), its parent reads them in the envelope, and the user is warned once, by the framework's delegation (`agents/delegate.py`), as on Deep Agents. A native ADK YAML app gets all of it: only the building of its agents differs (`workflow/adk/build.py`). Its chat-mode sub-agents keep transferring, and an agent the root transfers to replies to the user (`build.reply_agents`: its text is the reply, recent_messages reads it, its overflow is the turn's clear error, its calls write the outside-content mark); the summary and the memory index stay the root's, so such an agent is trimmed by the fit guard, not summarized. An agent's own callbacks (a native app's) run after every plugin, and only when none answered: its before-model callbacks see the request after the fit guard, and the cap leaves out an agent with after-tool callbacks. A main agent whose model does not resolve through the catalog has no budget and no summary. +- **Sub-agents delegate and return**: on both backends a sub-agent run is a call of its parent's `task` tool (the framework's: `tools/_core/delegation.py` declares it, `workflow/agents/delegate.py` runs it) that returns in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text. `task` takes `agent_type` (one of the caller's own sub-agents) and a brief (`workflow/agents/brief.py`: `title`, `objective`, `deliverable`, `constraints`, `known`, `done_when`), its schema and description the same on both backends (`task_parameters`, `task_description`: a line per type with its description, "The <name> agent." with a warning, `subagent_without_description`, for one without, and the fields `AgentConfig.brief_required` asks for); `read_brief` checks a call against them, and one that cannot start a run is the call's `{"success": false, "error": …}`, no run started or numbered. `Delegations.delegate` (the manager's `_delegations`) does the rest, alike on both: it names the run (`AgentRuns.run_for`), reports its `AGENT_RUN` start (title, brief, `started_by`, `mode`) and end through the turn's live events and the records, and runs the backend's hook, `_run_agent(AgentRun)`, in a task of its own, where the run is the active run and no tool call is, so each run ends at its own end. The run's first message is the task message (`task_message`); it starts from the conversation's `plan` and `tasks` (`AgentRun.state`), and the keys it changed come back to its caller's state (`RunAnswer.state`). It ends as the `RunAnswer` says: its last text (a reply that also called a tool included; none at all, an empty result shown `No answer`), `refused` or `partial` by the outcome mark, `failed` for an error or a raise (one recoverable `ERROR`, `<instance> failed: <reason>`, or the hook's own words, `RunFailed`: an overflow's); and the call's result is the run's envelope as JSON (`workflow/agents/envelope.py`), shown by `show_as_delegation`. A cancel of the caller's task stops the run's task first and ends the run `interrupted`. `AgentConfig.inherit_context` sets what a run sees: False (the default) its task alone, True its parent's conversation too, read once as the run starts (the conversation after any summary, less the message that called `task`), before the task message, which then ends with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task); `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root and, in 0.7.0, on an agent with sub-agents or below another sub-agent. On ADK (`workflow/adk/task_tool.py::TaskTool`) every config-built agent is built on its own, with no ADK `sub_agents`, so ADK offers none `transfer_to_agent`, and gets ADK's identity line ("You are an agent. Your internal name is …"); a delegating agent has one `TaskTool`. Each sub-agent type runs on its own runner (`App(name=child_app(app_name))`, the type's agent its root, `_agent_plugin_chain`: the main chain configured for a sub-agent, no memory index, no summary, `SubAgentOutcomePlugin`; every plugin's per-call state keyed by invocation) over the manager's session service, on a child session per run (`child_session_id`: `<conversation id>/<instance>`; an inheriting run's gets the conversation's events copied, `task_tool.inherited_events`), under an app no conversation list reads. On Deep Agents (`workflow/deepagents/task_tool.py::build_task_tool`) each type's graph is built on its own, and a run `astream`s it in its task with `var_child_runnable_config` cleared, so its chunks reach its own loop alone, never its parent's stream; an inheriting run's history is the parent's messages with Deep Agents' summary event applied (`SummarizationMiddleware._apply_event_to_messages`, private: `tests/workflow/deepagents/test_compact.py` pins it), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. - **Token usage**: every model call the framework makes is one `LLM_USAGE`, on both backends, side calls included (`generate_simple`: `summarize`'s, `purpose` `tool`; `on_session_end`'s, `memory_extraction`, outside any turn; an app's own, `side_call`, or what its caller names with `workflow/usage.py::side_call`), its counts normalized where it is made (`normalized_tokens`: `prompt_tokens` every input token, cache reads and writes included; `completion_tokens` every output token, thinking included; ADK's read by its model's provider kind, `adk_usage_event`/`adk_tokens`, since Gemini and ADK's Claude adapter keep the thinking apart from the candidates and OpenAI's count it inside, an agent of no known kind read as apart; Deep Agents' by LangChain's one convention, `langchain_tokens`; the raw log's usage records alike), and timed (`latency_ms`: on ADK from the request to the answer, `workflow/adk/call_clock.py`'s plugins marking the answer's `custom_metadata`; on Deep Agents by the turn's `RunCallback`, which marks the answer's `response_metadata["agentic_cli"]`, beside the outcome mark; a side call, a summary and the overflow retry around their own request; no adapter sends either mark). Each is recorded in its conversation's ledger (`UsageLedger`; `BaseWorkflowManager.usage`/`usage_of`, in memory for the manager's life: a backend switch's new manager starts afresh, as with `agent_runs`) where it is made, before `on_event` (the event processors, ADK's summarizer, as soon as its call answers, Deep Agents' `RunCallback`, `_report_side_call`), under the run it is made in and its conversation's turn while one runs (as the manager counts them, `/compact` and job notices included: not `SessionInfo.turns`; none in another conversation's turn or from a task its turn outlived, which `_report_side_call` reports to no one); a sub-agent run's `AGENT_RUN` end carries what it used, by model (`metadata["usage"]`, `RunRecord.usage`). The CLI's status bar sums the events it sees (the open conversation's total, on any backend); `/status` shows the ledger by agent. LangGraph (deprecated) records no ledger. - **Tool registration**: Use `@register_tool(category=..., capabilities=..., description=...)` decorator. `capabilities=` is required — pass `EXEMPT` for tools that need no permission check or a list of `Capability(name, target_arg=...)` tuples the engine matches against rules. Tools are auto-discovered via the global `ToolRegistry`. A tool in `AgentConfig.tools` that the registry did not issue is denied at every call; building the agents names it once (`tool_not_registered`, per agent and tool: `BaseWorkflowManager._name_unregistered`): a plain callable, a `FunctionTool`/`StructuredTool` judged by the function it runs (as the gates unwrap it), an app's own tool class; ADK's own tool objects excepted (a built-in runs inside the model). `outside_content=True` (or a function of the call's arguments) declares that a call brings content from outside the user and the project into the conversation (a page, a document, a program's output): once the gate allows one, a memory write in that conversation is approved per call (see Permissions); an application's tools are unmarked unless they declare it, and a variant must declare the same flag as its tool. - **Async tools never block the event loop**: a synchronous tool runs on a worker thread on both backends; an async tool runs on the event loop itself, where a blocking call (DNS, a connect, a file lock's wait, a sleep, a subprocess wait, PDF parsing, page conversion, embedding) freezes the whole app, Ctrl+C included. An async tool runs its slow work with `asyncio.to_thread`. `tests/tools/test_async_tools_never_block.py` lists every async tool (the registry's, the factories' service-bound variants, Deep Agents' skill tools), so a new one fails until it is listed, and calls each through the loop guard (`tests/loop_guard.py`). @@ -258,15 +258,15 @@ Workflow: - **Permission targets vs. patterns**: a tool argument is a *target*, a rule's target is a *pattern*. Matchers canonicalize them with different methods: `canonicalize_pattern` expands `${workdir}`/`${home}`/`${app_name}` and anchors relative filesystem patterns to the project; `canonicalize_target` expands nothing and resolves a path exactly as the tool will. Any tool that takes a path argument must resolve it with `agentic_cli.paths.resolve_path` (the same function `PathMatcher.canonicalize_target` uses), so the engine judges the location the tool acts on. A URL, pattern or target, is `agentic_cli.urls.canonical_url` of it (`URLMatcher`; a pattern keeps its `*`/`**`): the URL httpx sends, so `/x/../admin`, `/%61dmin`, `host.` and `host。com` are the page and host they reach; one httpx cannot send raises `ValueError` (a target is denied, a rule or saved grant skipped with `permission_rule_skipped`). `web_fetch`'s blocked domains compare the same host (`URLValidator`, `canonical_host` for each entry), and `PinnedTransport` resolves and sets the TLS name from `request.url.raw_host`, the host the Host header names. `tests/tools/test_path_contract.py` fails when a new filesystem tool has no contract case. Filesystem, `http.*` and shell capabilities must name their resource (`target_arg=` or a fixed `target=`): registering a tool with a targetless one raises `ValueError` (it would resolve to the wildcard, which is never remembered as a grant), and saved `http.read *`-style grants are dropped on load. Filesystem grants cover the named directory (a file's own directory), never `/`, home itself or anything above it (compared caseless): a file directly in home is granted exactly. The prompt names each exact target, then, when a session or "always" grant would cover more, `(for this session / always: all of <scope>)`; a sub-agent run's prompt opens with that run (`researcher-2 (researcher, run 1) wants to use …`: the engine builds it with `get_active_run()`, which both gates run inside, and the request carries it, `UserInputRequest.run`), and its grants are shared by every agent; an `http.read` grant covers the URL's site (`engine.site_scope`: `https://host/**`, the exact canonical host, HTTPS, no IP literals or local names). A deny rule is matched with the matcher's `matches_deny`: a `filesystem.*` deny ignores case and Unicode normalization (`PathMatcher.matches_deny`, NFC then casefold: on APFS `./.ENV` is `./.env`), the other matchers deny as they allow; an allow compares case, so another spelling of an allowed path asks. A grant is a literal target matched as a pattern, so it is remembered only when the literal part of its rule (the scope directory or exact path, `*` `?`; an exact URL, as `engine._is_literal_url`; a site scope is literal; any other target whole, `*` `?` `[`) holds no wildcard character (`engine.is_storable_grant`); otherwise the prompt offers "Allow once" and "Deny" and says why, and a saved allow whose literal part holds one is dropped on load (`permission_glob_grant_dropped`, `engine.is_literal_saved_grant`), as is a saved filesystem grant on `/`, home or above it (`permission_broad_grant_dropped`, `engine.is_bounded_saved_grant`). - **Service registry**: Tools access services and shared state via `get_service(key)` from `workflow.service_registry`. A single ContextVar holds a `dict[str, Any]` set by the workflow manager during processing. Complex services (KnowledgeBase, SandboxManager, MemoryStore) are lazily created; simple state (plan string, task list) lives directly in the registry dict. - **Manager detection**: tools declare their own service needs — `@register_tool(..., requires="knowledge_base")` (or a tuple for several) — and the key is validated against `service_registry.KNOWN_SERVICE_KEYS` at registration (only *constructible* services are declarable). `BaseWorkflowManager._detect_required_managers()` reads that metadata off the registry for each agent's tools (by registry identity, so `register(func, name=...)`'s original callable still declares its services); `_build_services()` then lazily constructs only the services actually needed, into a local dict that is released in full if a later constructor raises (nothing is published, so nothing else could close it). Each framework service is one row of `workflow/services.py::SERVICES` (`ServiceSpec`: how it is built, how it is closed, the tools it gives, whether a tool may declare it, how its references to its owner move), and `KNOWN_SERVICE_KEYS` and the closers are read from that table. A downstream tool may request any framework-provided service without editing the framework; there is no mechanism for registering new service *types* (a backend that builds one of its own overrides `_build_services_into`, `_get_service_tool_map` and `_SYNC_SERVICE_CLOSERS`). -- **Canonical tool names + permission identity**: `ToolDefinition.name` is the single identity. `register_tool(name="public_name")` wraps the callable so `func.__name__` is the registered name (backends derive the model-visible name from the callable). Permission gating **and tool assembly** resolve through a **registry-owned identity binding**: each `ToolRegistry` owns a `id(obj) → (weakref, definition)` map (`registry.bind_identity()`/`identify()`; the module-level `tools.registry.bind_tool_identity()`/`identify_tool()` answer for `get_registry()`). Every hit is confirmed with `is` against the weak reference, so neither a name, a class name, nor a forged `__eq__`/`__hash__` can stand in for it, and a recycled address inherits nothing. Identity is **per registry** — a tool registered into an application's own `ToolRegistry` is not one of the framework's, so it stays untouched during assembly and is denied at permission time — which is also what lets a short-lived registry, its definitions and their closures be garbage collected. Everything the framework issues is bound at its construction site: registered callables, factory service-bound variants, renamed wrappers, and the native ADK tool objects the framework builds (skill tools, in `tools/skills/toolset.py`; each sub-agent's delegation tool, in `workflow/adk/delegation.py`). ADK appends its private `_SingleTurnAgentTool` (named after the sub-agent, no `.func`) to a parent's tools in the parent's constructor, so `_build_agent` binds them right after `LlmAgent(...)` returns, to the exempt `task` declaration (`tools/_core/delegation.py`): only `type(t) is _SingleTurnAgentTool and t.agent is` a child the framework built and passed in. An application's `AgentTool`, a subclass, a same-named look-alike, a second `_SingleTurnAgentTool` around the framework's own child, or one around an agent the framework did not build stays unbound and is denied; `tests/workflow/test_adk_delegation.py` pins each, and contract tests pin the private class and its `agent` attribute. `workflow/adk/permission_plugin.py` unwraps `.func` only for the exact ADK types whose contract is to call it (`FunctionTool`, `LongRunningFunctionTool`, and ADK's own `TransferToAgentTool`), and gates genuine `McpTool` instances (`isinstance`, since ADK creates them on connect) under a synthetic `mcp` capability. `TransferToAgentTool` is a `FunctionTool` **subclass** ADK auto-injects into an agent that can transfer (a native ADK YAML app's: config-built agents delegate instead); matching only exact `FunctionTool` denied the built-in routing tool as unregistered, so delegation could not work at all. It is trusted on exactly the same terms as the others — ADK constructs it as `super().__init__(func=transfer_to_agent)` and overrides only `_get_declaration()` (to add the agent-name enum), never `run_async`, so what it invokes is still exactly `self.func`. Listing the **exact class** keeps every other subclass, forged object and same-named tool denied; no name authority is restored. Deep Agents' `PermissionMiddleware` follows the same rules: bound objects first, then `.coroutine`/`.func` of an **exact** `StructuredTool` only (`workflow/deepagents/tools.py::to_langchain_tools` builds one whose `.func`/`.coroutine` *is* the registered callable, and hides a `tool_context` parameter, passing `None`, so an ADK-style tool loads unchanged). The objects it builds or receives are bound where they are made: the `task` tool `SubAgentMiddleware` creates, to the `task` declaration (`tools/_core/delegation.py`), right after the middleware is built; the LangChain skill tools (`tools/skills/langchain_tools.py`), to the definitions `tools/skills/permissions.py` registers for ADK's, so ADK and Deep Agents gate them alike; and each MCP tool, in the manager's own map (`mcp_tools.MCPSessions.identify`, consulted before the registry, never the registry itself), to a synthetic definition under the `mcp` capability with the tool's (prefixed) name as the target. Anything unbound is denied — and, in assembly (service detection, service-tool substitution, canonicalization, long-running wrapping), left exactly as the application supplied it: a plain callable named `kb_search` is not the framework's tool and must not be given its services, its service-bound variant, or its long-running contract. Substitution additionally requires the service variant to *be* that same definition (`identify_tool(variant) is definition`); factories bind each closure to the exact module-level tool it re-binds, so a tool an application has taken over keeps its own implementation. -- **One name, one tool**: `ToolRegistry.register()` raises on any name that is already registered — matching capabilities are *not* grounds for sharing one, since they say nothing about the docstring or the model-visible schema. Sharing is declared, never inferred: `declare_tool(name, ...)` (exported from `agentic_cli.tools`) declares a tool that has **no backend-neutral implementation** (`ToolDefinition.func is None`), and each backend registers its own with `register_tool(..., variant_of=name)` — same identity and permission contract, its own signature and docstring. Re-declaring the same contract is idempotent; changing its description or capabilities raises. `definition.variants` is ordered by defining module, so it never depends on import order, and assembly substitutes a variant's canonical callable via `registry.canonical_for()` (never `None`). A `replace=True` retires the previous definition's callables, and retired backend variants are excluded from `include_state_tools` injection, so the model never sees two tools with one name. That is how the ADK and LangGraph `save_plan`/`get_plan`/`save_tasks`/`get_tasks` coexist (declared in `tools/_core/state_tools.py`); previously they contested the name and import order decided the winner. Deep Agents' delegation tool `task` is declared the same way (`tools/_core/delegation.py`, at `agentic_cli.tools` import, before any application tool registers), so an application's `register_tool(name="task")` raises on every backend, and a Deep Agents coordinator whose own tools include one named `task`, or an agent with skills whose own tools use a skill tool's name, fails to build with `AgentGraphError`. A bare-name reference to a declared-only tool raises "ambiguous" rather than guessing a backend. `replace=True` takes a name over deliberately and **retires the old definition's identities**, so its callables resolve to nothing (denied, and left alone by assembly) rather than inheriting the replacement's capabilities. +- **Canonical tool names + permission identity**: `ToolDefinition.name` is the single identity. `register_tool(name="public_name")` wraps the callable so `func.__name__` is the registered name (backends derive the model-visible name from the callable). Permission gating **and tool assembly** resolve through a **registry-owned identity binding**: each `ToolRegistry` owns a `id(obj) → (weakref, definition)` map (`registry.bind_identity()`/`identify()`; the module-level `tools.registry.bind_tool_identity()`/`identify_tool()` answer for `get_registry()`). Every hit is confirmed with `is` against the weak reference, so neither a name, a class name, nor a forged `__eq__`/`__hash__` can stand in for it, and a recycled address inherits nothing. Identity is **per registry** — a tool registered into an application's own `ToolRegistry` is not one of the framework's, so it stays untouched during assembly and is denied at permission time — which is also what lets a short-lived registry, its definitions and their closures be garbage collected. Everything the framework issues is bound at its construction site: registered callables, factory service-bound variants, renamed wrappers, and the native ADK tool objects the framework builds (skill tools, in `tools/skills/toolset.py`; the delegation tool, `workflow/adk/task_tool.py::TaskTool`, bound to the exempt `task` declaration (`tools/_core/delegation.py`) as it is made, an exact `TaskTool` only). An application's `AgentTool`, a `TaskTool` subclass or a same-named look-alike stays unbound and is denied; `tests/workflow/test_adk_delegation.py` pins each, and contract tests pin what of ADK's `BaseTool` it relies on. `workflow/adk/permission_plugin.py` unwraps `.func` only for the exact ADK types whose contract is to call it (`FunctionTool`, `LongRunningFunctionTool`, and ADK's own `TransferToAgentTool`), and gates genuine `McpTool` instances (`isinstance`, since ADK creates them on connect) under a synthetic `mcp` capability. `TransferToAgentTool` is a `FunctionTool` **subclass** ADK auto-injects into an agent that can transfer (a native ADK YAML app's: config-built agents delegate instead); matching only exact `FunctionTool` denied the built-in routing tool as unregistered, so delegation could not work at all. It is trusted on exactly the same terms as the others — ADK constructs it as `super().__init__(func=transfer_to_agent)` and overrides only `_get_declaration()` (to add the agent-name enum), never `run_async`, so what it invokes is still exactly `self.func`. Listing the **exact class** keeps every other subclass, forged object and same-named tool denied; no name authority is restored. Deep Agents' `PermissionMiddleware` follows the same rules: bound objects first, then `.coroutine`/`.func` of an **exact** `StructuredTool` only (`workflow/deepagents/tools.py::to_langchain_tools` builds one whose `.func`/`.coroutine` *is* the registered callable, and hides a `tool_context` parameter, passing `None`, so an ADK-style tool loads unchanged). The objects it builds or receives are bound where they are made: the `task` tool `build_task_tool` makes (`workflow/deepagents/task_tool.py`), to the `task` declaration (`tools/_core/delegation.py`), as it is made; the LangChain skill tools (`tools/skills/langchain_tools.py`), to the definitions `tools/skills/permissions.py` registers for ADK's, so ADK and Deep Agents gate them alike; and each MCP tool, in the manager's own map (`mcp_tools.MCPSessions.identify`, consulted before the registry, never the registry itself), to a synthetic definition under the `mcp` capability with the tool's (prefixed) name as the target. Anything unbound is denied — and, in assembly (service detection, service-tool substitution, canonicalization, long-running wrapping), left exactly as the application supplied it: a plain callable named `kb_search` is not the framework's tool and must not be given its services, its service-bound variant, or its long-running contract. Substitution additionally requires the service variant to *be* that same definition (`identify_tool(variant) is definition`); factories bind each closure to the exact module-level tool it re-binds, so a tool an application has taken over keeps its own implementation. +- **One name, one tool**: `ToolRegistry.register()` raises on any name that is already registered — matching capabilities are *not* grounds for sharing one, since they say nothing about the docstring or the model-visible schema. Sharing is declared, never inferred: `declare_tool(name, ...)` (exported from `agentic_cli.tools`) declares a tool that has **no backend-neutral implementation** (`ToolDefinition.func is None`), and each backend registers its own with `register_tool(..., variant_of=name)` — same identity and permission contract, its own signature and docstring. Re-declaring the same contract is idempotent; changing its description or capabilities raises. `definition.variants` is ordered by defining module, so it never depends on import order, and assembly substitutes a variant's canonical callable via `registry.canonical_for()` (never `None`). A `replace=True` retires the previous definition's callables, and retired backend variants are excluded from `include_state_tools` injection, so the model never sees two tools with one name. That is how the ADK and LangGraph `save_plan`/`get_plan`/`save_tasks`/`get_tasks` coexist (declared in `tools/_core/state_tools.py`); previously they contested the name and import order decided the winner. The framework's delegation tool `task` is declared the same way (`tools/_core/delegation.py`, at `agentic_cli.tools` import, before any application tool registers), so an application's `register_tool(name="task")` raises on every backend, and a coordinator whose own tools include one named `task` (on both backends), or a Deep Agents agent with skills whose own tools use a skill tool's name, fails to build with `AgentGraphError`. A bare-name reference to a declared-only tool raises "ambiguous" rather than guessing a backend. `replace=True` takes a name over deliberately and **retires the old definition's identities**, so its callables resolve to nothing (denied, and left alone by assembly) rather than inheriting the replacement's capabilities. - **Turn/lifecycle concurrency**: a manager runs one turn at a time — `process()`/`resume_with_job_result()`, and `compact()` (`/compact`), enter through `_turn()` (the base's: the conversation named in the log context, then `_turn_admission()`, which holds `_turn_lock`, then `_workflow_context()`; job resume, `can_resume` and `compact` are the base's templates over the backend's hooks), and `reinitialize`/`cleanup` (the base's, for ADK and Deep Agents: a backend implements only the release's hooks) hold `_lifecycle_lock` **and** `_turn_lock` (`initialize_services` only `_lifecycle_lock`). Lock order is lifecycle → turn; a turn initializes *before* taking the turn lock, which is what keeps the two from deadlocking — and because of that a cleanup can land in between, so admission re-checks `_backend_ready()` while holding the turn lock and reinitializes once (or fails cleanly) rather than running against released resources. Initialization is transactional: services are built on a worker thread into a *local* dict and published only while the attempt still owns init (a cancelled attempt releases what the thread went on to build), and a failed attempt rolls back. A failed in-place reinitialization leaves the manager uninitialized; the controller reports `FAILED` and refuses to hand it out, but **keeps** it so a retry can revive it with its preserved (possibly in-memory) sessions intact. `WorkflowController` serializes init/reinitialize/swap/close on its own lifecycle lock, and a background init that finishes after `close()` releases its manager instead of publishing it. - **HITL callback is context-local**: `set_input_callback()` stores into a per-manager `ContextVar`, so a second consumer installing its callback cannot capture a running turn's prompt, and one consumer's `clear_input_callback()` cannot unregister another's. `MessageProcessor` cancels and awaits its consumer task **before** clearing the callback, so no tool is left asking a question nobody owns. And the callback answers only inside its turn: a task a turn started (`asyncio.create_task` copies the context, the callback with it) that asks after the turn ended gets `UserInputUnavailable` (`request_user_input`; the turn's span, `workflow/sessions.py::open_turn_scope`/`close_turn_scope`, opened and closed by `_workflow_context`, which the copy carries), as with no approver: a question goes unanswered and a permission ASK is denied by the engine's no-approver rule. - **Code that may run on the host is approved per call**: CPython has no in-process sandbox, so `execute_python` runs inside the OS sandbox or not at all by default (`os_sandbox_strict` true: no backend, a failed wrap, or a sandbox tool that fails as it starts (the runner's first stderr line, `_STARTED_MARKER`, never came) is a refusal that keeps its cause and ends with `executor.how_to_run`: sandbox-exec, bwrap and Ubuntu 24.04's user namespaces, none on Windows, and the opt-out where it lives, `exec_policy.sandbox_opt_out`: `~/.{app_name}/settings.json` or the env variable, since the project file and `/settings` cannot set it), and the module set is chosen from the path a call takes (`executor.py::_choose_run`, then `validate_code(allowed_modules=)`). The engine never imports `tools/`: `BaseWorkflowManager` passes `PermissionEngine(uncontained=tools.exec_policy.uncontained_exec_capabilities)`, called with the settings at each check (a settings change applies at once). For a capability it names, `engine.unstorable_reason` is `UNCONTAINED` (the one decision, shared with the prompt: only "Allow once" and "Deny", with its note), and `_evaluate` skips allow rules from grants (`SESSION`, and `PROJECT`, the user's `project_grants.json`), so a grant from when the code ran contained approves nothing; a `USER` rule still applies. A prompt for `*.exec` shows all of the code (the dialog body scrolls). - **No harness-level turn replay**: ADK persists a turn's input during invocation setup, and Deep Agents' checkpointer at the turn's first step, so the CLI never re-invokes an event source. Retries belong to the provider client (`HttpRetryOptions`). `MessageProcessor` returns a typed `TurnResult`. A turn that fails yields one `ERROR` and returns, on both backends (the base `process()`'s contract; `WorkflowEvent.turn_failed`: the error's text, `rate_limited`, `error_type`); an `ERROR` the turn already yielded that is not recoverable is its one; a cancel still raises, and a turn that cannot start (initialization, admission, or its conversation cannot be read) raises before any event. The CLI says a rate limit from the event as it does from a manager that raises. -- **Interrupted calls**: Ctrl+C stops the whole turn (loop, model calls, tools, sub-agents), and every call the model made gets exactly one result (`workflow/interrupts.py`, the texts and `OpenCalls`, each manager's record, kept by conversation and by the run that made each call (the root's own, or a sub-agent's: a provider that numbers its call ids per agent gives a sub-agent's call its parent's delegation's id): a call's result as it finished, a call `asking` at its permission prompt, both gates marking it; a conversation whose turn the user cancelled): a finished call keeps its result, a running one or a delegation is `INTERRUPTED_BY_USER`, one at its prompt `NOT_RUN`, one whose job was submitted the job's state (`job_started`); a cancel with no call open leaves `MARKER` as the main agent's reply; a call nothing answered (a crash, an old session) is `INTERRUPTED`. On ADK the turn runs with `abort_signal`, set by `live_events.merged(on_stop=)` before the runner is cancelled, so ADK seals the invocation in its own branches; `merged` waits for its source to close, a repeated cancel too (up to `STOP_GRACE`), and `process()`/`resume_with_job_result()` close their inner generators with `aclosing`, so a run never outlives its turn. `adk/interrupted_calls_plugin.py::InterruptedCallsPlugin` (before `ToolResultCapPlugin`, every app) sets the active tool call around each call (`before_tool_callback`, so a question marks it `asking`), records results with their `state_delta`/`artifact_delta` in `after_tool_callback` (not a long-running starter's `None`: its job answers it), keeps the cap's cut of one (`ToolResultCapPlugin.on_cut`, so a seal sends that cut and its full output is saved once) and rewrites the seals (`error_code` `INVOCATION_ABORTED`, contract-tested) in `on_event_callback`, carrying those deltas, each seal answered from the record of the run its branch names (a seal is written outside that run). ADK's seals pair a result with a call by id alone, so a call whose id a sub-agent's result used is left open: the manager answers those as the stopped turn ends, before it clears the record, the same way (`_answer_unsealed`, shielded; `unsealed`, once ADK's seals are written), so a call that finished beside a delegation keeps its result; then a delegation that returned without its result event (ADK hands a step's parallel results back after the last) ends its run with that result, not `interrupted` (`_end_returned_runs`). `left_open` answers leftovers when `process()` starts (every app: a task-mode agent's delegation, which ADK keeps open on purpose, is refused at build, and ADK's client calls for a human, `adk_request_confirmation`/`_credential`/`_input`, are answered as interrupted, since the manager offers no way to answer them), a result pairing with a call on its own branch only; one a stop left because its answers could not be written is answered `INTERRUPTED_BY_USER` (the manager records the stop). On Deep Agents `InterruptedCallsMiddleware` takes `PatchToolCallsMiddleware`'s place, first in every stack: it records each final `ToolMessage` with the rest of its `Command` update (outermost tool wrapper) and answers open calls in `before_agent`, returning those updates too; the root adds `MARKER` before the new input when the message before it is no reply (a `HumanMessage` or a tool result). Background jobs are not part of the turn: they keep running. Nor is a synchronous tool's function (a sandbox cell, `compile_document`, `execute_python`): it runs in a worker thread on both backends (ADK's tool thread pool, LangChain's executor), which Python cannot stop, so its call is answered at once but the function runs on to its end, keeps its sandbox session busy (the session's next call waits for it) and holds the process's exit until it returns (the sandbox's cleanup stops a cell). So is a knowledge-base ingest's store step (`kb_ingest_text`, `kb_ingest_file`, `ingest_arxiv_paper`: `KnowledgeBase._store` runs `ingest_document` in `asyncio.to_thread`): a cancelled ingest is answered `INTERRUPTED_BY_USER` and still stores its document, so a model that retries it stores a second copy; a cancelled `sidecar` or `backfill_sidecars` keeps its lock or flag until its thread's call ends (`memory/kb/manager.py::_Threads`). +- **Interrupted calls**: Ctrl+C stops the whole turn (loop, model calls, tools, sub-agents), and every call the model made gets exactly one result (`workflow/interrupts.py`, the texts and `OpenCalls`, each manager's record, kept by conversation and by the run that made each call (the root's own, or a sub-agent's: a provider that numbers its call ids per agent gives a sub-agent's call its parent's delegation's id): a call's result as it finished, a call `asking` at its permission prompt, both gates marking it; a conversation whose turn the user cancelled): a finished call keeps its result, a running one or a delegation is `INTERRUPTED_BY_USER`, one at its prompt `NOT_RUN`, one whose job was submitted the job's state (`job_started`); a cancel with no call open leaves `MARKER` as the main agent's reply; a call nothing answered (a crash, an old session) is `INTERRUPTED`. On ADK the turn runs with `abort_signal`, set by `live_events.merged(on_stop=)` before the runner is cancelled, so ADK seals the invocation in its own branches; `merged` waits for its source to close, a repeated cancel too (up to `STOP_GRACE`), and `process()`/`resume_with_job_result()` close their inner generators with `aclosing`, so a run never outlives its turn. `adk/interrupted_calls_plugin.py::InterruptedCallsPlugin` (before `ToolResultCapPlugin`, every app) sets the active tool call around each call (`before_tool_callback`, so a question marks it `asking`), records results with their `state_delta`/`artifact_delta` in `after_tool_callback` (not a long-running starter's `None`: its job answers it), keeps the cap's cut of one (`ToolResultCapPlugin.on_cut`, so a seal sends that cut and its full output is saved once) and rewrites the seals (`error_code` `INVOCATION_ABORTED`, contract-tested) in `on_event_callback`, carrying those deltas, each seal answered from the record of the active run (a sub-agent run's runner stops, and seals its child session, in the run's own task). ADK's seals pair a result with a call by id alone, so a call whose id another call's result used, on another branch of the session (a native ADK YAML app's agents), is left open: the manager answers those as the stopped turn ends, before it clears the record, the same way (`_answer_unsealed`, shielded; `unsealed`, once ADK's seals are written), so a call that finished keeps its result. `left_open` answers leftovers when `process()` starts (every app: a task-mode agent's delegation, which ADK keeps open on purpose, is refused at build, and ADK's client calls for a human, `adk_request_confirmation`/`_credential`/`_input`, are answered as interrupted, since the manager offers no way to answer them), a result pairing with a call on its own branch only; one a stop left because its answers could not be written is answered `INTERRUPTED_BY_USER` (the manager records the stop). On Deep Agents `InterruptedCallsMiddleware` takes `PatchToolCallsMiddleware`'s place, first in every stack: it records each final `ToolMessage` with the rest of its `Command` update (outermost tool wrapper) and answers open calls in `before_agent`, returning those updates too; the root adds `MARKER` before the new input when the message before it is no reply (a `HumanMessage` or a tool result). Background jobs are not part of the turn: they keep running. Nor is a synchronous tool's function (a sandbox cell, `compile_document`, `execute_python`): it runs in a worker thread on both backends (ADK's tool thread pool, LangChain's executor), which Python cannot stop, so its call is answered at once but the function runs on to its end, keeps its sandbox session busy (the session's next call waits for it) and holds the process's exit until it returns (the sandbox's cleanup stops a cell). So is a knowledge-base ingest's store step (`kb_ingest_text`, `kb_ingest_file`, `ingest_arxiv_paper`: `KnowledgeBase._store` runs `ingest_document` in `asyncio.to_thread`): a cancelled ingest is answered `INTERRUPTED_BY_USER` and still stores its document, so a model that retries it stores a second copy; a cancelled `sidecar` or `backfill_sidecars` keeps its lock or flag until its thread's call ends (`memory/kb/manager.py::_Threads`). - **Session identity**: durable sessions are addressed by `SessionRef(app_name, user_id, session_id)` (`workflow/sessions.py`). Every session hook (`session_exists`/`list_sessions`/`session_info`/`delete_session`/`recent_messages`/`load_session`) takes an optional `user_id`, defaulting to `settings.default_user` only when the caller omits it. `list_sessions(limit=)` returns `SessionInfo` rows, newest first, and `session_info` one conversation's or None: the title is the first prompt (`session_title`), the turns what the user typed (a job's notice or resume, a delegated request and a summary are none), `updated` when it last changed. ADK keeps the title and the turns in two session-state keys saved with each user turn (`workflow/adk/sessions.py`, `run_async(state_delta=)`; a conversation from before them is read from its events and never written back, which would move it in the list), Deep Agents keeps them in a session index, a LangGraph store beside the checkpointer (`workflow/deepagents/sessions.py`: each row written as a turn starts, its input counted, then from the newest root checkpoint as it ends and after `/compact`, so a listing reads no checkpoint; a database from before the index scanned once per app and user), LangGraph knows only the id; ADK's `delete_session` looks the session up first, so an unknown id is False. Backends without a session store leave `supports_sessions` False, and the base hooks raise `NotImplementedError` rather than answering with a misleading `False`/`[]`. Deep Agents keys each conversation's checkpointer thread by the whole triple (`workflow/deepagents/sessions.py::thread_id`, `json.dumps([app_name, user_id, session_id])`) and stores it in each checkpoint's metadata, so the backfill's scan filters by app and user and keeps the root namespace; sub-agents are compiled with `checkpointer=False` and store none (an older version's sit under `tools:<task-id>`, and `delete_session` removes them with the thread and the row, returning False for an unknown id). A backend's conversations are read without its manager through its `SessionReader` (`workflow/session_readers.py::open_session_reader`: the backend's own session code over its store, opened from the settings), so the CLI lists, opens and deletes the conversations of every installed backend (`cli/stored_conversations.py`): each row names its backend (`SessionInfo.backend`), and a conversation another backend keeps opens there (no index joins the stores, and an id two backends keep is two conversations). -- **Active turn**: the in-flight `(user, session)` is a `ContextVar` (`workflow/sessions.py::get_active_turn`), set with a token by `_workflow_context()`, which every turn enters through `_turn()` — concurrent turns on one manager stay isolated and nesting restores the outer turn. The tool call in progress is another (`get_active_tool_call()`, a `ToolCallRef(call_id, name)`), set by Deep Agents' `ActiveToolCallMiddleware`, innermost in the tool stack (after the gate and the error middleware, so only a call the gate let through runs as one); on ADK, `InterruptedCallsPlugin.before_tool_callback` sets it around each call (ADK's stand-in for an unknown tool name excepted) and its `after_tool_callback` resets it. The sub-agent run in progress is a third (`get_active_run()`, a `RunRef`; None in the root's own calls), set on ADK by `MainAgentPlugin.before_agent_callback` from the agent's invocation branch, and the parent's set again by its `after_agent_callback` and `on_agent_error_callback` (ADK runs a delegated sub-agent inside its parent's call, whose after-tool callbacks are the parent's), and on Deep Agents by `ActiveToolCallMiddleware` around a `task` call to one of the agent's own sub-agents (the whole sub-agent runs inside it): a sub-agent's model calls, tool calls, permission checks and questions see it. `JobManager.submit(resume_on_complete=True)` takes `call_id` from the active tool call when the tool passed none, and `call_name` when that is None too; every `submit` records the sub-agent run in progress as the job's `started_by` (`instance_of(get_active_run())`). +- **Active turn**: the in-flight `(user, session)` is a `ContextVar` (`workflow/sessions.py::get_active_turn`), set with a token by `_workflow_context()`, which every turn enters through `_turn()` — concurrent turns on one manager stay isolated and nesting restores the outer turn. The tool call in progress is another (`get_active_tool_call()`, a `ToolCallRef(call_id, name)`), set by Deep Agents' `ActiveToolCallMiddleware`, innermost in the tool stack (after the gate and the error middleware, so only a call the gate let through runs as one); on ADK, `InterruptedCallsPlugin.before_tool_callback` sets it around each call (ADK's stand-in for an unknown tool name excepted) and its `after_tool_callback` resets it. The sub-agent run in progress is a third (`get_active_run()`, a `RunRef`; None in the root's own calls), set by `Delegations.delegate` in the run's own task (`workflow/agents/delegate.py`), on both backends, where the run's runner or graph runs (with no tool call active there): a sub-agent's model calls, tool calls, permission checks and questions see it. `JobManager.submit(resume_on_complete=True)` takes `call_id` from the active tool call when the tool passed none, and `call_name` when that is None too; every `submit` records the sub-agent run in progress as the job's `started_by` (`instance_of(get_active_run())`). - **Job notifications**: both backends tell a finished job through the base's `resume_with_job_result` (a template: the record names its conversation, a turn of it (`_turn`), the conversation there (`_conversation_exists`), the job's result read on a worker thread (`JobManager.result` takes the jobs directory's cross-process lock), the notice `job_notice`, told by the backend's `_deliver_job_notice`; `can_resume` makes the same checks without the turn), and the CLI resumes where `supports_job_resume` and `can_resume` say so. On ADK a finished job is told to the conversation (the root, or a native app's agent the root transferred it to) as one user-role text, `tools/jobs/resume.py::job_notice` (the Deep Agents notice below), whoever started it: its call already has a result (the root's "pending", or a sub-agent's job id), and a second result for the call itself made ADK's rearranger send the call, that result and nothing between, so the root answered without the turns since. A native ADK YAML app's job is told the same way (it used to answer its pending call as a `FunctionResponse`, and needed `record.call_id`); a call still open (a starter that returned nothing) is answered first (`_answer_left_open`). A sub-agent's long-running tools are not wrapped (`_build_agent` wraps the root's only): ADK pauses the whole invocation on a pending long-running call, inside a delegation too, so a sub-agent's starter returns the job id as an ordinary result. ADK's `recent_messages` leaves the notice out by its header, since ADK keeps no mark on a message. The CLI delivers only the jobs that wait for the current conversation, by one rule (`cli/waiting_jobs.py`) for the deliveries, the status bar's `↻N` and the line startup says: a finished job flagged `resume_on_complete` whose delivery is still `PENDING` (`JobRecord.awaiting_resume`: not one being delivered), that is this conversation's, or has none, or whose conversation is gone, `can_resume` saying so and no other installed backend's store keeping it (`waiting_jobs.opens_anywhere`, `BaseCLIApp._kept_elsewhere`) (those two told it is unavailable): another conversation's waits until it is opened, `/resume` (`resume_session`) telling them when `job_auto_resume` is on, startup only naming them (`_name_its_waiting_jobs`: outside the input handler Ctrl+C cannot stop a turn); the status bar's `↻N` counts them whatever the setting (`↻N: /jobs resume` when it is off; its `can_resume` answers kept 30 s, forgotten after `/sessions --delete`, a conversation `/new` drops on the memory store, or a new conversation on another backend). On Deep Agents a finished job's result cannot be the pending call's second result (the call already has its `pending` one, and Anthropic and OpenAI take one result per call), so `resume_with_job_result` runs a turn whose input is one `HumanMessage`: `tools/jobs/resume.py::JOB_NOTICE_HEADER`, the ask (`job_notice_ask`: for the root's own job `JOB_NOTICE_ASK`, tell the user what it means: without it a model may say nothing; for a sub-agent's, `JOB_NOTICE_ASK_FOR`, the same ask naming the sub-agent), then `job_result_payload(record, result)` as JSON, a line each (`job_notice`), marked `response_metadata={"agentic_cli": {"kind": "job_result", "job_id": ...}}` (`workflow/deepagents/sessions.py::job_notification`). No provider adapter sends that field; `recent_messages`, and so fact extraction, leaves the message out; the checkpoint keeps it for the model. The root agent receives every job, a sub-agent's too (its run ended when its `task` returned), and the notice names the sub-agent whose call started it (`JobRecord.started_by`, its instance, from the active run at submit; `job_notice_ask`: "A background job researcher-2 started has finished…", the root's own `JOB_NOTICE_ASK`). `can_resume` needs the record's session and user and the conversation's thread, not a call id. - **Resource ownership**: one release, `BaseWorkflowManager._release_resources` (cleanup, reinitialize and a failed initialization's rollback run it): it resets the base's state (`_initialized`, budgets, index snapshots, the catalog detached), takes the backend's closers from `_detach_backend()` (ADK: the runner, which closes the agents' MCP toolsets; Deep Agents: the agents' MCP sessions, handed over to a fresh `MCPSessions`) and `_detach_store()` (ADK: the session service; Deep Agents: the checkpointer, the session index and their connections), detaches the services through `_cleanup_managers` (the release's services hook: a backend's override runs; outside a release, as in LangGraph's cleanup, it closes them in place) and starts closing them on a worker thread (their closers block: `docker rm -f`, a kernel shutdown, the jobs directory's lock; on the loop they froze the app), then runs the closers (backend, store, catalog, then the services' close waited for last under a shield of its own: a hanging service close holds none of the rest, and a shutdown's cancel cancels no close not yet started) in one task awaited under a shield, each isolated (`_aclose_owned` for a duck-typed `aclose()`/`close()`): a cancel stops only the wait. The hooks are synchronous: one that returns an awaitable is closed and fails the release with a `TypeError`, after the rest is released. An override of `_release_resources` reads `self._keeping_store` to know whether a switch keeps the store. `cleanup()` is idempotent; `WorkflowController.close()` is the single shutdown path (cancel init → shut executor → clean manager). `reinitialize(preserve_sessions=True)` (a model switch) runs inside `_keeping(True)` (`_carrying_services` is its other name): the store is not detached and the services are carried, since session grants, sandbox kernels, jobs, knowledge bases and the conversations belong to the conversation, not the model, so neither the release nor a failed attempt's rollback closes them (a retry continues the conversation); the backend's own resources (ADK's runner, Deep Agents' MCP sessions) close and reopen. `_release_resources(keep_session_service=/keep_checkpointer=)` keeps the store, with a `DeprecationWarning`, until 0.8.0. LangGraph keeps its own `cleanup`/`reinitialize`. A run's services can move to a manager of either backend: `loan = old.lend_services()` (the table's services `old` owns, but itself), `await new.initialize_services(services=loan)` (borrowed, published, only what is missing built; no release of `new` closes them, so a failed, cancelled or abandoned start leaves `old` owning and using them), `await old.give_services(loan)` (between turns: inside one of `old`'s it raises `RuntimeError`; under `old`'s lifecycle and turn locks and `new`'s lifecycle lock: `new` owns them, each row's `rebind` moves the permission engine's `workflow`/`per_call` and the knowledge base's summarizer to it, and `old`'s release drops them unclosed). A manager holding services it does not own runs no turn (`_turn_admission` raises `RuntimeError`): the engine's per-call check reads its owner's outside-content marks, so `new` runs none before the give and `old` none after it until its release. The CLI's `WorkflowController.switch_backend` (a conversation opened or started on another backend) hands the run's services over so: lend, start, give, publish at once, release the old one. - **Memory package boundary**: `agentic_cli/memory/` (the knowledge base in `memory/kb/`, the memory store in `memory/store/`, shared embeddings and atomic writes in `memory/_core/`) imports nothing from the rest of agentic-cli, and `kb` and `store` never import each other. The rest of agentic-cli uses only `agentic_cli.memory` and `agentic_cli.memory.kb`; `workflow/memory_services.py` is the one place settings become package arguments. The workflow exposes one `KnowledgeBase` (`memory.kb.knowledge_base`, provisional) over the project and user scopes, and one `EmbeddingService` for both scopes (the memory store searches by keyword). `tests/memory/test_boundary.py` enforces all of it, and tests under `tests/memory/` import only the package. A knowledge base summarizes only with the `summarizer=` it was given; the workflow passes itself when `knowledge_base_summarize` is on. Importing the package loads no other agentic_cli module (`tests/memory/test_loads_alone.py`), because the package root `agentic_cli/__init__.py` loads its exports on first use (PEP 562 `__getattr__`): nothing may be imported there eagerly, since Python runs it before every `agentic_cli.*` import. @@ -274,7 +274,7 @@ Workflow: ### Console Output All console output must go through `ThinkingPromptSession` methods. Never use `rich.Console` or `print()` directly. -Log lines (structlog's and the stdlib logging's, which `configure_logging` points at `logging.py::LOG_STREAM`) and Python warnings go to stderr, but while the prompt runs, when stderr is the terminal (not `2>file`), `cli/app.py::_log_lines_above_prompt` adds each line to the session (`add_rich`), so it prints above the prompt: at once on the loop's thread (in order with the session's output), handed to the loop from any other; a line logged while one is shown goes to stderr. Written to stderr it landed on the prompt line and broke the screen. What is noise for a user is still logged at debug, so `BaseCLIApp.run()` installs `workflow/adk/log_filters.py::install_log_filters` (once per process; an app built but never run, a library user's or the test suite's, installs none, and importing the module imports no ADK: the filters attach by logger name): ADK's experimental notices, `[EXPERIMENTAL] feature … is enabled` and `[EXPERIMENTAL] <Class>: …` (a class ADK marks experimental, such as the `GeminiContextCacheManager` a caching Gemini agent builds), are logged at debug (`adk_experimental_feature`), and every other warning goes to the previous `warnings.showwarning`, written to `LOG_STREAM`; a filter on ADK's runner logger (`google_adk.google.adk.runners`) logs its "has no context_cache_config" advice at debug too (`adk_uncached_agent_transfer`). ADK gives that advice only to an app whose agents can transfer (a native ADK YAML app with sub-agents: config-built agents delegate) and that has no context cache: the ADK manager sets one (`_context_cache_config`) whenever `prompt_caching_enabled` is on and an agent runs on Claude or Gemini (for a native ADK YAML app, the models ADK runs its agents on, as resolved through the catalog), so the filter is for apps with caching off or no caching model. A filter on ADK's context-cache logger (`google_adk.google.adk.models.gemini_context_cache_manager`) logs a Gemini cache it could not create or delete at debug (`adk_cache_create_failed`, `adk_cache_cleanup_failed`): the turn goes on uncached. Filters on four ADK loggers log failure tracebacks at debug: compaction (`google_adk.google.adk.apps.compaction`, "Event compaction failed", `adk_compaction_failed`), node (`google_adk.google.adk.workflow._node_runner`, "Node execution failed", `adk_node_failed`), runner (`google_adk.google.adk.runners`, exactly "Root node %s failed.", `adk_root_node_failed`; "was cancelled" records pass) and plugin manager (`google_adk.google.adk.plugins.plugin_manager`, "Error in plugin 'context_overflow'": `overflow_plugin.OVERFLOW_PLUGIN_FAILED`, read as a record comes, `adk_overflow_plugin_failed`): the summarizer warns the user itself, and a failed model call or retry reaches the user as an `ERROR` event or the turn's error. A filter on ADK's rearranger (`google_adk.google.adk.flows.llm_flows.tools._rearranger`, "Dropping function calls with no matching function response", `adk_dropped_open_calls`) logs its warning on a call without a result at debug: the next turn answers such a call. Any other ADK warning that lands over the UI is handled the same narrow way, never by silencing the whole `google_adk` logger tree. Deep Agents' "Offloading conversation history to backend failed" warning and log (its summarization has no archive here, and the checkpoint keeps every message) are filtered as narrowly, to one debug log (`deepagents_history_not_archived`), by `workflow/deepagents/summarization.py::install_history_filters`. The LangGraph manager's `DeprecationWarning` is blamed on its caller (`stacklevel=2`), so Python's default filters keep it off the terminal when the factory builds it; a CLI user is told through the session instead (`cli/settings_ui.py::_warn_if_langgraph`: at startup, and on a `/settings` switch to `langgraph`). +Log lines (structlog's and the stdlib logging's, which `configure_logging` points at `logging.py::LOG_STREAM`) and Python warnings go to stderr, but while the prompt runs, when stderr is the terminal (not `2>file`), `cli/app.py::_log_lines_above_prompt` adds each line to the session (`add_rich`), so it prints above the prompt: at once on the loop's thread (in order with the session's output), handed to the loop from any other; a line logged while one is shown goes to stderr. Written to stderr it landed on the prompt line and broke the screen. What is noise for a user is still logged at debug, so `BaseCLIApp.run()` installs `workflow/adk/log_filters.py::install_log_filters` (once per process; an app built but never run, a library user's or the test suite's, installs none, and importing the module imports no ADK: the filters attach by logger name): ADK's experimental notices, `[EXPERIMENTAL] feature … is enabled` and `[EXPERIMENTAL] <Class>: …` (a class ADK marks experimental, such as the `GeminiContextCacheManager` a caching Gemini agent builds), are logged at debug (`adk_experimental_feature`), and every other warning goes to the previous `warnings.showwarning`, written to `LOG_STREAM`; a filter on ADK's runner logger (`google_adk.google.adk.runners`) logs its "has no context_cache_config" advice at debug too (`adk_uncached_agent_transfer`). ADK gives that advice only to an app whose agents can transfer (a native ADK YAML app with sub-agents: config-built agents delegate) and that has no context cache: the ADK manager sets one (`_context_cache_config`) whenever `prompt_caching_enabled` is on and an agent runs on Claude or Gemini (for a native ADK YAML app, the models ADK runs its agents on, as resolved through the catalog), so the filter is for apps with caching off or no caching model. A filter on ADK's context-cache logger (`google_adk.google.adk.models.gemini_context_cache_manager`) logs a Gemini cache it could not create or delete at debug (`adk_cache_create_failed`, `adk_cache_cleanup_failed`): the turn goes on uncached. Filters on four ADK loggers log failure tracebacks at debug: compaction (`google_adk.google.adk.apps.compaction`, "Event compaction failed", `adk_compaction_failed`), node (`google_adk.google.adk.workflow._node_runner`, "Node execution failed", `adk_node_failed`), runner (`google_adk.google.adk.runners`, exactly "Root node %s failed.", `adk_root_node_failed`; "was cancelled" records pass) and plugin manager (`google_adk.google.adk.plugins.plugin_manager`, "Error in plugin 'context_overflow'": `overflow_plugin.OVERFLOW_PLUGIN_FAILED`, read as a record comes, `adk_overflow_plugin_failed`): the summarizer warns the user itself, and a failed model call or retry reaches the user as an `ERROR` event or the turn's error. A filter on ADK's rearranger (`google_adk.google.adk.flows.llm_flows.tools._rearranger`, "Dropping function calls with no matching function response", `adk_dropped_open_calls`) logs its warning on a call without a result at debug: the next turn answers such a call. A filter on ADK's agent router (`google_adk.google.adk.agents._agent_router`, "Event from an unknown agent", `adk_inherited_unknown_author`) logs at debug the warning ADK gives for each copied event of an inheriting sub-agent run whose author the run's tree lacks: the run goes on. Any other ADK warning that lands over the UI is handled the same narrow way, never by silencing the whole `google_adk` logger tree. Deep Agents' "Offloading conversation history to backend failed" warning and log (its summarization has no archive here, and the checkpoint keeps every message) are filtered as narrowly, to one debug log (`deepagents_history_not_archived`), by `workflow/deepagents/summarization.py::install_history_filters`. The LangGraph manager's `DeprecationWarning` is blamed on its caller (`stacklevel=2`), so Python's default filters keep it off the terminal when the factory builds it; a CLI user is told through the session instead (`cli/settings_ui.py::_warn_if_langgraph`: at startup, and on a `/settings` switch to `langgraph`). Available session methods: - `session.add_response(text, markdown=True)` - Display text/markdown response diff --git a/README.md b/README.md index 5401edbe..d12a21ef 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic │ + PermissionPlugin, LLMLoggingPlugin, ToolResultCapPlugin │ ├─────────────────────────────────────────────────────────────────────┤ │ DeepAgentsWorkflowManager (deepagents extra) │ -│ + PermissionMiddleware, SubAgentMiddleware (task), summarization │ +│ + PermissionMiddleware, summarization │ ├─────────────────────────────────────────────────────────────────────┤ │ LangGraphWorkflowManager (langgraph extra; deprecated) │ │ + wrap_tool_for_permission, native ToolNode │ @@ -334,15 +334,16 @@ ADK integrations: `OpenAIResponsesLlm`, and `OpenAICompatibleLlm` for the providers in `model_providers` (OpenRouter and OpenAI-compatible hosts), which shows their reasoning text -- **Delegation** — a sub-agent runs in ADK's `single_turn` mode: its parent - calls it as a tool named after it and gets its answer back in the same turn +- **Delegation** — its parent calls the framework's `task` tool with a + brief; the sub-agent runs on a runner of its own, on a child session of + the run, and its parent gets the run's envelope back in the same turn (see [Sub-agent context](#sub-agent-context)) - **Summarizing** — ADK's `EventsCompactionConfig` with the framework's summarizer: the main agent's conversation is summarized on its own model once a prompt reaches the trigger Deep Agents uses (the smaller of `context_summarize_at` of the input budget and `context_max_tokens`), keeping the current turn and the newest 12% of that word for word; a - sub-agent never summarizes the shared session. The fit guard leaves the + sub-agent's run, on its own child session, is never summarized. The fit guard leaves the oldest turns out of a request still over its agent's budget, and a request the provider refuses as too long is summarized or trimmed and retried once, then ends in one clear error (see @@ -358,7 +359,7 @@ ADK integrations: ### DeepAgentsWorkflowManager Builds each agent as a LangChain `create_agent` graph with selected Deep -Agents middleware (its `task` delegation and its summarization) and, on +Agents middleware (its summarization) and, on Claude, LangChain's Anthropic prompt caching. Deep Agents' file tools, virtual filesystem and `write_todos` are not used: the agents run on the framework's tools, permission engine and models, as on ADK. Best for: @@ -378,13 +379,14 @@ manager = DeepAgentsWorkflowManager( What it supports: - **Delegation through `task`**: a coordinator (an agent with `sub_agents`) - gets Deep Agents' `task` tool, which lists each sub-agent as - `- name: description`, so give sub-agents real descriptions. A sub-agent - sees the brief the coordinator writes and the coordinator's plan and tasks; - with `inherit_context=True` it is a fork that also continues the - coordinator's conversation (see [Sub-agent context](#sub-agent-context)). - Its last answer is the call's result, and the coordinator answers the user. - Two sub-agents can run at once. `task` is a reserved tool name. + gets the framework's `task` tool, as on ADK (see + [Sub-agent context](#sub-agent-context)). Each sub-agent's graph runs + apart from its coordinator's, in a task of its own, from the brief the + coordinator writes and the coordinator's plan and tasks; with + `inherit_context=True` it also starts from the coordinator's + conversation. Its run's envelope is the call's result, and the + coordinator answers the user. Two sub-agents can run at once. `task` is a + reserved tool name. - **The permission gate on every call**: `PermissionMiddleware`, in every agent's stack, identifies each tool by the object the registry issued and asks through the input callback, for sub-agents' calls too. A tool that @@ -401,12 +403,10 @@ What it supports: 12% of that word for word. A model whose window is unknown counts as 128,000 tokens. A request the provider refuses as too long is summarized and retried once; a conversation that still does not fit ends the turn - with one error naming the model. A sub-agent's fails only its `task` - call: its parent reads the error, its run fails, and the user is warned - as on ADK, `<agent>: the request no longer fits <model>'s context - window.` (ADK answers the sub-agent's call with text instead, "I could not - do this task: …", and its run completes). The checkpoint keeps every - message. + with one error naming the model. A sub-agent's fails only its run, as on + ADK: the user is warned `<agent>: the request no longer fits <model>'s + context window.`, and its parent reads those words as the run's error. + The checkpoint keeps every message. - **Prompt caching** on Claude, as on ADK (see [Prompt caching](#prompt-caching)). - **MCP tools, Agent Skills, raw LLM logging and job resume**, from the same `AgentConfig.mcp_servers`, `AgentConfig.skills`, `raw_llm_logging` and @@ -417,10 +417,6 @@ What it supports: it, as on ADK. How it differs from ADK: -- **The delegation tool's name**: a sub-agent is delegated to and returns - on both backends, but the coordinator calls `task` on Deep Agents and a - tool named after the sub-agent on ADK (see - [Sub-agent context](#sub-agent-context)). - **No Gemini explicit caches**: Gemini runs on its implicit caching, which is automatic and bills no storage. - **No code-execution events**: `CODE_EXECUTION`, `EXECUTABLE_CODE` and @@ -479,8 +475,8 @@ Requires: `pip install agentic-cli[langgraph]` |---------|------------|-------------|------------------------| | Install | Core | `deepagents` extra | `langgraph` extra | | Model providers | Gemini, Claude, GPT (Responses API), and OpenRouter and OpenAI-compatible hosts (`model_providers`) | The same | The same | -| Delegation | `<sub-agent>(request=...)`: the sub-agent answers its parent, the coordinator answers the user | `task`: the same | Routing between agent nodes | -| Sub-agent context | `inherit_context` false or true | `inherit_context` false or true (a fork) | Ignored | +| Delegation | `task(agent_type=, title=, objective=, ...)`: the sub-agent's run answers its parent with its envelope, the coordinator answers the user | The same | Routing between agent nodes | +| Sub-agent context | `inherit_context` false or true | The same | Ignored | | State persistence | SQLite (default), PostgreSQL, or memory | The same, as a LangGraph checkpointer | Memory, PostgreSQL, or SQLite | | Thinking support | Every model with a thinking knob, one set of levels | The same | The same | | Prompt caching | Claude (three breakpoints) and Gemini (server-side caches) | Claude (three breakpoints) | Claude on Anthropic's API (one breakpoint) | @@ -1266,12 +1262,14 @@ configs = [coordinator, researcher, analyst] | `prompt` | str \| Callable | System instruction; a callable may take no arguments or a single `settings` argument | | `tools` | list[Callable] | Available tool functions | | `sub_agents` | list[str] | Names of agents this one can delegate to | -| `description` | str | Short description for routing (defaults to `""`). On Deep Agents the coordinator's `task` tool lists it; without one the agent is "The <name> agent." | +| `description` | str | Short description for routing (defaults to `""`). The coordinator's `task` tool lists it; without one the agent is "The <name> agent." | | `model` | str \| None | A model reference (`anthropic:claude-sonnet-5-5`), a bare model id, or a role (`fast`); without one, the `default` role (see [Models and providers](#models-and-providers)) | | `model_settings` | ModelSettings \| None | The agent's thinking, `max_tokens`, sampling settings and `extra` (see [Thinking](#thinking)) | | `mcp_servers` | list[MCPServerConfig] | MCP servers whose tools the agent gets (ADK and Deep Agents) | | `skills` | list[str] | Agent Skills: a skill folder's absolute path, or a name under `skills_dirs` (ADK and Deep Agents; never looked up in the working directory) | -| `inherit_context` | bool | What a sub-agent sees when its parent delegates to it: the request alone (`False`, the default) or its parent's conversation too (`True`); see [Sub-agent context](#sub-agent-context) (ADK and Deep Agents) | +| `inherit_context` | bool | What a sub-agent sees when its parent delegates to it: its task alone (`False`, the default) or its parent's conversation too (`True`); see [Sub-agent context](#sub-agent-context) (ADK and Deep Agents) | +| `brief_required` | tuple[str, ...] | The brief fields a delegation to this agent must fill (default `("objective",)`; `title` and `objective` are always required): any of `deliverable`, `constraints`, `known`, `done_when`. A `task` call that leaves one empty starts no run, and its caller reads which. Not on the root | +| `limits` | AgentLimits \| None | The agent's own per-run limits (`max_model_calls`, `timeout` in seconds, `max_tokens`), laid over the app's `SubAgentPolicy.limits` field by field. Configuration: validated and kept with the agent, but no run is stopped by them. Not on the root | The agent graph is validated before anything is allocated — ahead of model discovery and service creation. Duplicate names, unknown `sub_agents` @@ -1281,9 +1279,8 @@ offending agents. Exactly one agent may be unreferenced: the runner starts from a single root, so agents under any other root would never run. `inherit_context=True` on the root, on an agent with sub-agents of its own or on an agent below another sub-agent, and an `inherit_context` that is not True -or False, raise it too, and on ADK, -when the agents are built, so does a sub-agent named like one of its parent's -tools. Agents are built in dependency order, so declaration order does not +or False, raise it too, and, when the agents are built, so does a coordinator +whose own tools include one named `task`. Agents are built in dependency order, so declaration order does not matter. Then every agent's model is resolved, with the default model, before anything is built: an agent whose model cannot run fails startup, named in the error. @@ -1296,70 +1293,81 @@ signatures, `async def` factories, and non-string results raise ### Sub-agent context A sub-agent is a task its parent hands off and gets back in the same turn, on -both backends. The parent calls it with a request; the sub-agent works with its -own prompt, tools and model, and its last answer is the call's result. Only the -main agent replies to the user: a sub-agent's own text shows in the events box -under its name (and is left out of fact extraction), its answer passes the +both backends. The parent calls the framework's `task` tool, the same on both: +`agent_type`, one of its own sub-agents, and a brief, `title` and `objective` +(required), `deliverable`, `constraints`, `known` (what the parent already +knows that the task needs) and `done_when`. The sub-agent's run starts from its +task message, the brief as sections (`# Task: <title>`, `## Objective`, …), and +from the conversation's plan and tasks (its changes to them come back to its +parent); it works with its own prompt, tools and model, and its parent reads +its run's envelope as the call's result, a JSON object: + +```json +{"success": true, "agent": "researcher-1", "run": "researcher-1#1", + "status": "completed", "partial": false, "result": "X is 42.", "error": null} +``` + +`status` is `completed` (`partial` for an answer cut at its output limit), +`refused`, `failed` (`error`: the provider's reason) or `interrupted`, and +`result` is the run's last text. Only the main agent replies to the user: a +sub-agent's own text shows in the events box under its run's name (and is +left out of fact extraction), its envelope passes the [tool result cap](#tool-results), and the next turn starts at the main agent again. Delegating needs no permission; each tool the sub-agent calls is gated -like the main agent's. Give each sub-agent a `description`: its parent chooses -by it, and one without is offered as "The <name> agent.", with a warning. +like the main agent's. Give each sub-agent a `description`: `task`'s +description lists each type with it, and one without is offered as "The +<name> agent.", with a warning. A type's `brief_required` names the brief +fields its parent must fill: a call that leaves one empty starts no run, and +the parent reads which (`{"success": false, "error": "The brief for +'researcher' is missing: deliverable."}`). Each sub-agent's `inherit_context` sets what it sees: | `inherit_context` | The sub-agent sees | |-------------------|--------------------| -| `False` (the default) | The request alone (and on Deep Agents the parent's plan and tasks) | -| `True` | Also its parent's conversation as it stands: after any summary, without the parent's reasoning | +| `False` (the default) | Its task message alone (and the conversation's plan and tasks) | +| `True` | First its parent's conversation as it stands: after any summary, without the parent's reasoning; its task message then ends with a note that the conversation is its parent's | ```python coordinator = AgentConfig( name="coordinator", prompt="Delegate research to researcher and reviews to reviewer, each with a " - "complete request; they report back to you, and you answer the user.", + "complete brief; they report back to you, and you answer the user.", sub_agents=["researcher", "reviewer"], ) researcher = AgentConfig(name="researcher", prompt="Find facts.", - description="Finds facts.") # the request alone + description="Finds facts.") # the brief alone reviewer = AgentConfig(name="reviewer", prompt="Check what was said.", description="Reviews the conversation.", inherit_context=True) ``` -- **Prompts say "delegate to X".** The tool the parent calls is named after - the sub-agent on ADK (`researcher(request=...)`) and is `task` on Deep - Agents, so a coordinator's prompt should tell it to delegate to an agent - with a complete request, never name a tool. A fresh sub-agent knows only - what the request says. An inheriting one sees the conversation, not its +- **Prompts say "delegate to X".** A coordinator's prompt should tell it to + delegate to an agent with a complete brief. A fresh sub-agent knows only + what the brief says. An inheriting one sees the conversation, not its parent's instructions: it keeps its own prompt, so put what it must know in - the request too. (On Deep Agents the coordinator's `task` tool says a fork - inherits its system prompt; it does not.) A specialist's prompt should - have it report its result, not address the user: its answer goes to its - parent. -- **On ADK**, a sub-agent runs in ADK's `single_turn` mode with transfers - off, so no agent built from a config is offered `transfer_to_agent`; an - inheriting one is shown its parent's turns as quoted context. **On Deep - Agents**, a fresh sub-agent is isolated and an inheriting one is a fork - (Deep Agents' `mode="fork"`, in beta): the conversation, then Deep Agents' - preamble and the request. Its own summarization compacts an inherited - conversation too large for its model. + the brief too. A specialist's prompt should have it report its result, not + address the user: its answer goes to its parent. +- **On ADK**, each agent is built on its own, with no ADK sub-agents, so no + agent built from a config is offered `transfer_to_agent`; each sub-agent + type runs on a runner of its own, each run on a child session (app + `<app_name>--agents`, id `<conversation id>/<instance>`), which + `/sessions` never lists; an inheriting run's child session starts with + the conversation's events. **On Deep Agents**, each sub-agent's graph runs + apart from its parent's, in a task of its own; an inheriting run starts + from the conversation's messages, which its own summarization compacts + when they are too large for its model. - **The limits in 0.7.0.** `inherit_context` is for sub-agents only, and - only for an agent without sub-agents of its own: Deep Agents tells a forked - sub-agent that delegating "will be refused", which a coordinator would - believe. And only for the main agent's own sub-agents: below - another sub-agent, ADK would show it the main agent's whole conversation, - what its fresh parent was kept from. A sub-agent on ADK cannot share its - name with one of its parent's tools. Each raises `AgentGraphError` at - startup. + only for the main agent's own sub-agents that have none of their own. A + coordinator cannot have a tool of its own named `task`. Each raises + `AgentGraphError` at startup. - **A sub-agent's failure.** A sub-agent whose model call fails does not - end the turn, on either backend: its parent is handed "Error running - sub-agent: …" as the call's error result, the user sees a warning, - `<agent> failed: <the provider's reason>`, and the parent answers. Only - the main agent's own failure ends the turn. (On ADK, ADK's delegation - tool words the parent's reason "Dynamic node <agent> failed".) A - sub-agent's request too long for its model is warned of alike, `<agent>: - the request no longer fits <model>'s context window.`; on ADK the - sub-agent answers "I could not do this task: …" and its run completes, - on Deep Agents the parent reads the error and the run fails. + end the turn, on either backend: its run fails, its parent reads the + provider's reason in the envelope, the user sees a warning, + `<instance> failed: <the provider's reason>` (`researcher-1 failed: …`), + and the parent answers. Only the main agent's own failure ends the turn. + A sub-agent's request too long for its model fails its run alike, with the + warning `<agent>: the request no longer fits <model>'s context window.`, + the words its parent reads as the run's error. - **A sub-agent's job.** A long-running tool on a sub-agent (a job starter) returns the job's id at once, and the sub-agent answers its parent in the same turn. When the job finishes, the main agent is told, in a message of @@ -1458,7 +1466,8 @@ are `AgentConfig`'s, and an unknown one is an error: | `model`, `model_settings` | A model reference or role, and `ModelSettings` as a mapping (`temperature`, `max_tokens`, `thinking: {mode: high}`, ...) | | `tools` | A list of names: a registered tool's name (`web_search`, or your own), or a dotted path `my_pkg.tools.fn` to a function registered with `@register_tool` | | `mcp_servers`, `skills` | As on `AgentConfig`: MCP servers (`name`, `transport`, `command`/`args` or `url`, ...) and skill names | -| `sub_agents`, `inherit_context` | The agents it may delegate to, and what a sub-agent sees: `false` (the request alone, the default) or `true` (its parent's conversation too; see [Sub-agent context](#sub-agent-context)) | +| `sub_agents`, `inherit_context` | The agents it may delegate to, and what a sub-agent sees: `false` (its task alone, the default) or `true` (its parent's conversation too; see [Sub-agent context](#sub-agent-context)) | +| `brief_required`, `limits` | As on `AgentConfig`: `brief_required: [objective, deliverable]`, `limits: {max_model_calls: 30, timeout: 600, max_tokens: 200000}` (each limit read as written; validated and kept, but no run is stopped by them) | | `include_state_tools` | `true` by default: the plan and task tools are added | - **A tool is a name, resolved when the manager is built.** A bare name is @@ -1642,7 +1651,7 @@ Variants share one identity and one permission contract while keeping their own signature and docstring, and a bare name that maps to several variants raises rather than silently picking one by import order. -The framework reserves `task`, Deep Agents' delegation tool, whichever backend +The framework reserves `task`, its delegation tool, whichever backend runs: registering another tool named `task` raises. ### Capabilities @@ -1985,8 +1994,8 @@ the rest, and the stored session keeps every message. A model whose window is unknown counts as 128,000 tokens. While a summary is written the CLI shows "Summarizing the earlier conversation…". -On ADK only the main agent's conversation is summarized: a sub-agent leaves -the shared session alone (on Deep Agents each agent summarizes its own). A +On ADK only the main agent's conversation is summarized: a sub-agent's run, +on its own child session, is not (on Deep Agents each agent summarizes its own). A request still over its agent's budget (the summary follows the previous call's size, a sub-agent may run on a smaller model) has its oldest whole turns left out of that request, never a tool call without its result, with @@ -2036,7 +2045,7 @@ folder), the call still succeeds: the result is cut, its note says the full output could not be saved, and the log warns once per folder. Every result passes the cap: registered tools, MCP and skill tools, -`job_result`, and a sub-agent's answer. Each tool's own limits +`job_result`, and a sub-agent run's envelope. Each tool's own limits stay (`web_fetch` returns a summary, `grep` a number of matches); the cap is the net beneath them. On ADK it is the `ToolResultCapPlugin`, for every agent but one with `after_tool_callbacks` of its own (a native ADK YAML @@ -2358,6 +2367,7 @@ agentic-cli/ │ │ ├── service_registry.py # Unified service ContextVar for tools │ │ ├── events.py # WorkflowEvent, EventType │ │ ├── config.py # AgentConfig +│ │ ├── agents/ # Sub-agents: delegate.py (the framework's task: the brief read, the run started and ended, its envelope), brief.py, envelope.py, runs.py, policy.py, outcome.py │ │ ├── settings.py # WorkflowSettingsMixin │ │ ├── retry.py # is_rate_limit_error: a provider's 429 (the provider clients retry) │ │ ├── tool_summaries.py # Tool result one-liner summaries @@ -2376,7 +2386,7 @@ agentic-cli/ │ │ ├── adk/ │ │ │ ├── manager.py # GoogleADKWorkflowManager │ │ │ ├── build.py # ADKBuild; a native ADK YAML app loaded and checked; the agents that reply -│ │ │ ├── delegation.py # Sub-agents as single_turn tools; their permission binding +│ │ │ ├── task_tool.py # TaskTool: the framework's task on ADK │ │ │ ├── compaction.py # AgentCliSummarizer: the main agent's conversation summarized │ │ │ ├── fit_guard_plugin.py # FitGuardPlugin: a request over its budget trimmed to fit │ │ │ ├── overflow_plugin.py # OverflowPlugin: a provider's overflow retried once, or one clear error @@ -2391,7 +2401,8 @@ agentic-cli/ │ │ │ └── tool_result_cap_plugin.py # ToolResultCapPlugin (the tool result cap) │ │ ├── deepagents/ # The Deep Agents backend (deepagents extra) │ │ │ ├── manager.py # DeepAgentsWorkflowManager -│ │ │ ├── agent_builder.py # One create_agent graph per AgentConfig; task delegation +│ │ │ ├── agent_builder.py # One create_agent graph per AgentConfig, each on its own +│ │ │ ├── task_tool.py # build_task_tool: the framework's task on Deep Agents │ │ │ ├── middleware.py # Permission gate, result cap, tool errors, active tool call, foreign reasoning │ │ │ ├── tools.py # Framework tools → LangChain tools │ │ │ ├── event_processor.py # The stream → WorkflowEvents; the run callback @@ -2437,7 +2448,7 @@ agentic-cli/ │ │ │ ├── planning.py │ │ │ ├── tasks.py │ │ │ ├── state_tools.py # save_plan / get_plan / save_tasks / get_tasks, declared -│ │ │ └── delegation.py # task, declared (Deep Agents' delegation tool) +│ │ │ └── delegation.py # task, declared (the framework's delegation tool) │ │ ├── adk/state_tools.py # ADK-native planning/task tools │ │ ├── langgraph/state_tools.py # LangGraph-library planning/task tools (Deep Agents, LangGraph) │ │ ├── skills/ # Agent Skills: SkillStore, ADK toolset, LangChain tools (langchain_tools.py) diff --git a/src/agentic_cli/cli/agents_command.py b/src/agentic_cli/cli/agents_command.py index 85cdef5e..a43b76b5 100644 --- a/src/agentic_cli/cli/agents_command.py +++ b/src/agentic_cli/cli/agents_command.py @@ -6,8 +6,9 @@ ``completed (partial)``), its run, its title, the tokens it used, and how long it ran (or has been running). ``/agents <id>`` shows one instance (``researcher-2``) or one run (``researcher-2#1``): its type, its parent, -its title, then each run's status, the first lines of its result, its error -and its tokens by model. +its title, then each run's status, the fields of its brief its parent filled +(its objective, deliverable, constraints, what was known, when it is done), +the first lines of its result, its error and its tokens by model. The runs are the manager's records (``BaseWorkflowManager.agent_runs``, ``workflow/agents/runs.py``) and the tokens its usage ledger's @@ -30,6 +31,7 @@ from agentic_cli.cli.commands import Command, CommandCategory from agentic_cli.cli.usage_tracker import format_tokens, format_usage from agentic_cli.workflow.agents import RUN_COMPLETED, RUN_STARTED +from agentic_cli.workflow.agents.brief import BRIEF_FIELDS from agentic_cli.workflow.agents.runs import run_number if TYPE_CHECKING: @@ -143,6 +145,9 @@ def _one(records: list["RunRecord"], ledger: "UsageLedger") -> Panel: now = _now() for record in records: table.add_row(f"Run {_run_number(record)}", f"{_status(record)} · {_duration(record, now)}") + for name in BRIEF_FIELDS: + if record.brief.get(name): + table.add_row(f" {_label(name)}", Text(record.brief[name])) if record.result: table.add_row(" Result", Text(_first_lines(record.result))) if record.error: @@ -185,6 +190,11 @@ def _status(record: "RunRecord") -> str: return record.status +def _label(field: str) -> str: + """A brief field's label: ``done_when`` is ``Done when``.""" + return field.replace("_", " ").capitalize() + + def _run_number(record: "RunRecord") -> str: """The run's number within its instance: ``#1`` of ``researcher-2#1``.""" return "#" + run_number(record.ref.run or "") diff --git a/src/agentic_cli/tools/_core/delegation.py b/src/agentic_cli/tools/_core/delegation.py index fa0585d5..16ca3b74 100644 --- a/src/agentic_cli/tools/_core/delegation.py +++ b/src/agentic_cli/tools/_core/delegation.py @@ -1,10 +1,12 @@ """The declaration of ``task``, the tool a coordinator delegates with. -On the Deep Agents backend, a coordinator delegates to its sub-agents through a -``task`` tool that Deep Agents' ``SubAgentMiddleware`` builds. It has no -backend-neutral implementation, so only its contract is declared here: the -name, the description and the permission declaration. The backend binds the -object it builds to this declaration (``bind_tool_identity``), which is how the +On both backends a coordinator delegates to its sub-agents through the +framework's ``task`` tool (``workflow/agents/delegate.py``), which each backend +builds in its own form: ADK's ``workflow/adk/task_tool.py::TaskTool``, Deep +Agents' ``workflow/deepagents/task_tool.py::build_task_tool``. It has no +backend-neutral callable, so only its contract is declared here: the name, the +description and the permission declaration. Each backend binds the object it +builds to this declaration (``bind_tool_identity``), which is how the permission gate knows it. Delegation itself needs no permission: each tool the sub-agent calls is gated diff --git a/src/agentic_cli/workflow/adk/branches.py b/src/agentic_cli/workflow/adk/branches.py deleted file mode 100644 index 3b0dc8b5..00000000 --- a/src/agentic_cli/workflow/adk/branches.py +++ /dev/null @@ -1,51 +0,0 @@ -"""A sub-agent run's identity on ADK: the branch its work runs on. - -ADK runs a sub-agent its parent delegated to (``_SingleTurnAgentTool``) on -the branch ``<agent>@<call id>``, its parent's call that started it, under -the parent's own branch, dot-joined: a leaf two levels down runs on -``middle@toolu_c1.leaf@toolu_m1``. Every event of the run carries the branch -(``Event.branch``), and every callback of it sees it -(``callback_context.branch``). The root, and an agent the root transfers to, -run on no such branch. -""" - -from __future__ import annotations - -from typing import TYPE_CHECKING - -if TYPE_CHECKING: - from agentic_cli.workflow.agents.runs import AgentRuns - from agentic_cli.workflow.sessions import RunRef, SessionRef - - -def delegations(branch: str | None) -> list[tuple[str, str]]: - """The delegations ``branch`` runs in, outermost first: ``(agent, call id)``. - - A segment without ``@`` (a workflow node's) is no delegation. - """ - found: list[tuple[str, str]] = [] - for segment in (branch or "").split("."): - agent, at, call_id = segment.rpartition("@") - if at and agent and call_id: - found.append((agent, call_id)) - return found - - -def branch_run( - runs: "AgentRuns", conversation: "SessionRef | None", branch: str | None -) -> "RunRef | None": - """The run ``branch`` is, each delegation under the one before it; None for none.""" - run: RunRef | None = None - for agent, call_id in delegations(branch): - run = runs.run_for(conversation, run, call_id, agent) - return run - - -def parent_branch_run( - runs: "AgentRuns", conversation: "SessionRef | None", branch: str | None -) -> "RunRef | None": - """The run that made the delegation ``branch`` is: its parent's; None for the root's.""" - run: RunRef | None = None - for agent, call_id in delegations(branch)[:-1]: - run = runs.run_for(conversation, run, call_id, agent) - return run diff --git a/src/agentic_cli/workflow/adk/build.py b/src/agentic_cli/workflow/adk/build.py index dd100aa8..bfa3d731 100644 --- a/src/agentic_cli/workflow/adk/build.py +++ b/src/agentic_cli/workflow/adk/build.py @@ -11,9 +11,9 @@ turn at it. Their text is the reply, the conversation they hold is the user's, and a conversation their model no longer takes is the turn's error; only the root's is summarized, and only the root carries the memory - index. A single-turn sub-agent is a tool of its parent's (every agent - built from configs but the root is one): its text is its work, and the - agents under it run inside its call. + index. Agents built from configs have no ADK sub-agents: the root is the + one that replies, and each of its sub-agents runs on a runner of its own + (``GoogleADKWorkflowManager._run_agent``). - **The agents with after-tool callbacks of their own** (``own_after_tool_agents``, a native ADK YAML app's): ADK runs them only when no plugin answered the call, so the result cap leaves these agents' @@ -162,27 +162,6 @@ def reply_agents(root: Any) -> frozenset[str]: return frozenset(names) -def delegated_agents(root: Any) -> dict[str, frozenset[str]]: - """Each agent in ``root``'s tree that delegates, and the sub-agents it delegates to. - - A delegation is a single-turn sub-agent: its parent calls it like a tool - named after it and reads its answer as the result (the event processor - names each such call's run). Only the agent's own count: a call another - agent makes of that name runs no sub-agent (ADK answers an unknown tool). - Empty for a tree that delegates nowhere. - """ - delegating: dict[str, frozenset[str]] = {} - for agent in walk(root): - own = frozenset( - sub_agent.name - for sub_agent in getattr(agent, "sub_agents", None) or () - if _mode(sub_agent) == _SINGLE_TURN - ) - if own: - delegating[agent.name] = own - return delegating - - def own_after_tool_agents(root: Any) -> frozenset[str]: """The agents in ``root``'s tree with after-tool callbacks of their own.""" return frozenset( diff --git a/src/agentic_cli/workflow/adk/call_clock.py b/src/agentic_cli/workflow/adk/call_clock.py index 643e8843..0736010e 100644 --- a/src/agentic_cli/workflow/adk/call_clock.py +++ b/src/agentic_cli/workflow/adk/call_clock.py @@ -2,15 +2,16 @@ ADK makes an ``EventActions`` for each model call and hands that object to all three of its model callbacks (before, after, on error), so a call is -timed under its identity, as the fit guard keeps its copy of a request: -parallel delegations to one sub-agent share their invocation and their -agent's name, and a clock kept by either timed one call from another's -request. The clock holds the object, so its id goes to no other call while -this one is out. A failed call keeps its clock: a plugin after the one that +timed under its identity, as the fit guard keeps its copy of a request: a +clock kept by invocation or agent name could time one call from another +call's request. The clock holds the object, so its id goes to no other call +while this one is out. A failed call keeps its clock: a plugin after the one that reads it may answer the error (the overflow handler), and that answer reaches -``after_model_callback`` like any response. Each run lets go of what another -invocation left: an error nobody answered, and a call cancelled mid-request, -which before google-adk 2.14 fires no callback. +``after_model_callback`` like any response. As each run ends (ADK's +``after_run_callback``, a stopped one's too, or ``on_run_error_callback``) +it lets go of what it left: an error nobody answered, and a call cancelled +mid-request, which before google-adk 2.14 fires no callback. Only its own: +two runs of one sub-agent type share their runner's clock at once. ``CallClock`` is that clock; the raw log (``LLMLoggingPlugin``) keeps one. Every app times every call with two plugins sharing another (the manager's @@ -77,10 +78,10 @@ def elapsed(self, callback_context: "CallbackContext", *, done: bool) -> float | clock = clocks.pop(id(actions), None) if done else clocks.get(id(actions)) return None if clock is None else (time.perf_counter() - clock.started) * 1000 - def keep_only(self, invocation: str | None) -> None: - """Let go of every clock another invocation left (turns run one at a time).""" + def forget(self, invocation: str | None) -> None: + """Let go of every clock ``invocation`` left; another run's stay.""" self._clocks = { - key: clock for key, clock in self._clocks.items() if clock.invocation == invocation + key: clock for key, clock in self._clocks.items() if clock.invocation != invocation } def clear(self) -> None: @@ -137,10 +138,14 @@ async def on_model_error_callback( # reaches after_model_callback, timed, and lets it go. return None - async def before_run_callback( - self, *, invocation_context: "InvocationContext" + async def after_run_callback(self, *, invocation_context: "InvocationContext") -> None: + self.clock.forget(invocation_context.invocation_id) + return None + + async def on_run_error_callback( + self, *, invocation_context: "InvocationContext", error: Exception ) -> None: - self.clock.keep_only(invocation_context.invocation_id) + self.clock.forget(invocation_context.invocation_id) return None diff --git a/src/agentic_cli/workflow/adk/compaction.py b/src/agentic_cli/workflow/adk/compaction.py index a17af22b..d3d88752 100644 --- a/src/agentic_cli/workflow/adk/compaction.py +++ b/src/agentic_cli/workflow/adk/compaction.py @@ -11,10 +11,10 @@ ``AgentCliSummarizer`` is that summarizer: - **The main agent only.** ``MainAgentPlugin`` records the agent that is - running (``running_agent()``), and nothing is written for another one. A - delegated sub-agent's check would compact the shared session under it: one - that sees only its request then lost its brief and looped (100 requests in - one turn, offline). A sub-agent too big for its own model is the fit guard's. + running (``running_agent()``), and nothing is written for another one (a + native ADK YAML app's agent the root transferred to). A sub-agent runs on + a runner of its own, whose app summarizes nothing: one too big for its own + model is the fit guard's. - **The range** (``summary_range``) keeps the newest ``keep`` tokens word for word and cuts where a user turn starts, never between a call and its result, never inside the current turn. It is chosen before anything is @@ -78,7 +78,6 @@ from agentic_cli.logging import Loggers from agentic_cli.workflow import live_events -from agentic_cli.workflow.adk.branches import branch_run, parent_branch_run from agentic_cli.workflow.adk.model_factory import generate_text from agentic_cli.workflow.context import ( ESTIMATE_MARGIN, @@ -91,7 +90,6 @@ usage_fields, ) from agentic_cli.workflow.events import WorkflowEvent -from agentic_cli.workflow.sessions import get_active_turn, set_active_run from agentic_cli.workflow.summary_prompt import SUMMARY_PREFIX, summary_prompt from agentic_cli.workflow.usage import PURPOSE_SUMMARIZATION, UsageLedgers, adk_usage_event @@ -102,7 +100,6 @@ from agentic_cli.config import BaseSettings from agentic_cli.models import ProviderKind, ResolvedModel - from agentic_cli.workflow.agents.runs import AgentRuns from agentic_cli.workflow.context import ContextBudget logger = Loggers.workflow() @@ -137,58 +134,21 @@ def running_agent() -> str | None: class MainAgentPlugin(BasePlugin): """Records the running agent before ADK runs it, for ``running_agent()``. - Given the manager's runs, it also makes the sub-agent run the agent is - the active run (``workflow.sessions.get_active_run``) as it starts: the - run its branch names (``workflow/adk/branches.py``), None for the root; - the agent's model calls, tool calls, permission checks and questions see - it. ADK runs a delegated sub-agent inside its parent's call - (``run_node``, in that call's own task), so as the sub-agent ends, or - fails, its parent's run is made the active one again: the call's - after-tool callbacks are the parent's. It is set by value, the parent's - run from the branch, so no token from the start's context is needed. - Since it is first in the chain and its after-agent callback returns - nothing, every later plugin's ``after_agent_callback`` (awaited after it, - in the same context), and a native app agent's own after-agent - callbacks, see the parent's run, not the ending agent's. - - ``running_agent()`` keeps the sub-agent's name in that call's task until - the task ends; only the summarizer reads it, at an agent's model call, - which never runs in a tool call's task. + First in every chain (the conversation's runner's and each sub-agent + type's), so every later plugin runs after it. The record stays in the + task the agent runs in until that task ends; only the summarizer reads + it, at an agent's model call. """ - def __init__(self, runs: "AgentRuns | None" = None) -> None: + def __init__(self) -> None: super().__init__(name="main_agent") - self._runs = runs async def before_agent_callback( self, *, agent: "BaseAgent", callback_context: "CallbackContext" ) -> None: _running_agent.set(agent.name) - if self._runs is not None: - branch = getattr(callback_context, "branch", None) - set_active_run(branch_run(self._runs, get_active_turn(), branch)) return None - async def after_agent_callback( - self, *, agent: "BaseAgent", callback_context: "CallbackContext" - ) -> None: - self._parents_again(callback_context) - return None - - async def on_agent_error_callback( - self, *, agent: "BaseAgent", callback_context: "CallbackContext", error: Exception - ) -> None: - # ADK calls it for an exception that leaves the agent, before - # re-raising it (a delegation's tool answers "Error running - # sub-agent: ..."); after_agent_callback is not called then. - self._parents_again(callback_context) - - def _parents_again(self, callback_context: "CallbackContext") -> None: - """Make the run that made this agent's delegation the active one again.""" - if self._runs is not None: - branch = getattr(callback_context, "branch", None) - set_active_run(parent_branch_run(self._runs, get_active_turn(), branch)) - class NoAfterTurnCompactionRunner(Runner): """ADK's runner without its compaction pass after each turn. diff --git a/src/agentic_cli/workflow/adk/context_cache_plugin.py b/src/agentic_cli/workflow/adk/context_cache_plugin.py index 8a264ce5..5233493b 100644 --- a/src/agentic_cli/workflow/adk/context_cache_plugin.py +++ b/src/agentic_cli/workflow/adk/context_cache_plugin.py @@ -7,6 +7,10 @@ or hangs, would pay a failed create (up to its 60-second bound) at every step. ``ContextCachePlugin`` ends caching for the rest of an agent's turn once a call that could have made a cache ends without one; the next turn tries again. +Its state is kept by invocation and let go of as that run ends, well +(``after_run_callback``) or failing (``on_run_error_callback``, after which +ADK runs no ``after_run_callback``): a sub-agent run is an invocation of its +type's runner, and two runs of one type share this plugin at once. """ from __future__ import annotations @@ -65,7 +69,15 @@ async def after_model_callback( return None async def after_run_callback(self, *, invocation_context: InvocationContext) -> None: - invocation = invocation_context.invocation_id + self._forget(invocation_context.invocation_id) + + async def on_run_error_callback( + self, *, invocation_context: InvocationContext, error: Exception + ) -> None: + self._forget(invocation_context.invocation_id) + + def _forget(self, invocation: str) -> None: + """Let go of what ``invocation`` kept; another run's stays.""" self._spent = {key for key in self._spent if key[0] != invocation} self._could_cache = { key: value for key, value in self._could_cache.items() if key[0] != invocation diff --git a/src/agentic_cli/workflow/adk/delegation.py b/src/agentic_cli/workflow/adk/delegation.py deleted file mode 100644 index 13fe7bc3..00000000 --- a/src/agentic_cli/workflow/adk/delegation.py +++ /dev/null @@ -1,155 +0,0 @@ -"""Delegation on ADK: a sub-agent is a tool its parent calls, and it returns. - -An agent built from an ``AgentConfig`` that is not the root runs in ADK's -``single_turn`` mode (:func:`subagent_fields`). In its parent's constructor -ADK offers it to the parent as a tool named after it, taking a ``request`` -string; the parent calls it, the sub-agent runs its own tool loop on its own -model, and its last text comes back as the call's result, -``{"result": <text>}``, in the same turn. The root then answers the user, and -the next turn starts at the root again. Transfers to the parent and peers -are off, so with no chat-mode children ADK offers no agent built from a -config ``transfer_to_agent``. This is how Deep Agents' ``task`` already -works, so both backends delegate alike. - -A sub-agent's long-running tools are not wrapped as ADK's -``LongRunningFunctionTool``: ADK pauses the whole invocation on a pending -long-running call, inside a delegation too, so the parent would never be -re-entered. A sub-agent's job starter is an ordinary call that returns the -job's id, and the finished job is told to the root agent -(``BaseWorkflowManager.resume_with_job_result``), as on Deep Agents. - -The parent chooses a sub-agent by its tool's description, ADK's -``agent.description``: one without a description is offered as -"The <name> agent.", with a warning, as on Deep Agents. - -What the sub-agent sees follows ``AgentConfig.inherit_context``: False (the -default) only the request, True its parent's conversation too, other agents' -turns quoted as context and without their thoughts. ADK gives a -``single_turn`` agent ``include_contents="none"`` unless the field was set -explicitly, so an inheriting agent passes ``"default"`` explicitly and a -fresh one passes nothing. ADK sends an inheriting agent the user's turns as -plain user messages, so its instruction ends with -:data:`INHERITED_CONTEXT_NOTE` (:func:`subagent_instruction`), as Deep Agents -frames a fork's task: without it the agent could take the user's request to -its parent as its own and answer as the parent. - -The tool ADK builds is its private ``_SingleTurnAgentTool``, which calls no -``func`` the permission plugin could verify. The framework built the parent -and the child, so it binds each such tool to the exempt delegation -declaration (``tools/_core/delegation.py``, Deep Agents' ``task``) right -after the parent is built (:func:`bind_delegation_tools`), as it binds the -skill tools it builds: only the exact ``_SingleTurnAgentTool`` whose -``agent`` is a child the framework passed in. An application's ``AgentTool``, -a subclass, a look-alike of the same name, or one around an agent the -framework did not build stays unbound, and the gate denies it. Delegation -itself needs no permission: the sub-agent's own tool calls pass the same -gate. - -A native ADK YAML app (``adk_config_path``) is built by ADK and none of this -applies: its agents keep transferring. -""" - -from __future__ import annotations - -from typing import TYPE_CHECKING, Any - -from google.adk.tools import BaseTool -from google.adk.tools.agent_tool import _SingleTurnAgentTool - -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: - from google.adk.agents import LlmAgent - -logger = Loggers.workflow() - - -def subagent_fields(config: AgentConfig) -> dict[str, Any]: - """The ``LlmAgent`` fields that make ``config``'s agent a delegated sub-agent. - - Its description is what its parent reads in the delegation tool, so an - agent without one is offered under a placeholder, and the omission is - logged. - """ - description = config.description.strip() - if not description: - logger.warning("adk_subagent_without_description", agent=config.name) - description = f"The {config.name} agent." - fields: dict[str, Any] = { - "description": description, - "mode": "single_turn", - "disallow_transfer_to_parent": True, - "disallow_transfer_to_peers": True, - } - if config.inherit_context: - # Explicitly: ADK keeps include_contents only when it was set. - fields["include_contents"] = "default" - return fields - - -def subagent_instruction(config: AgentConfig, prompt: str) -> str: - """The instruction of ``config``'s sub-agent, whose own prompt is ``prompt``. - - An inheriting one is told whose conversation it reads - (:data:`INHERITED_CONTEXT_NOTE`); a fresh one sees only its task. - """ - if not config.inherit_context: - return prompt - return f"{prompt}\n\n{INHERITED_CONTEXT_NOTE}" if prompt.strip() else INHERITED_CONTEXT_NOTE - - -def check_delegation_names(config: AgentConfig, tools: list[Any]) -> None: - """Refuse a sub-agent named like one of its parent's own tools. - - ADK names the delegation tool after the sub-agent and appends it last, - so a tool of the parent's with that name would be shadowed: offered to - the model, but never called. ``tools`` are the parent's assembled tools: - a function tool counts by its ``__name__``, an ADK tool by its ``name``, - a skill toolset by its tools' names. An MCP toolset's tools are known - only once it connects, so they are not checked here. - - Raises: - AgentGraphError: Naming the parent and the clashing sub-agent(s). - """ - clashes = sorted(set(config.sub_agents) & _tool_names(tools)) - if clashes: - raise AgentGraphError( - f"Agent {config.name!r} delegates to sub-agent(s) " - f"{', '.join(repr(name) for name in clashes)} through a tool ADK names " - "after each, and has a tool of its own by that name; rename the " - "sub-agent or the tool." - ) - - -def bind_delegation_tools(agent: "LlmAgent", children: list[Any]) -> None: - """Bind each delegation tool ADK built for one of ``children`` to ``task``. - - Call it right after ``agent`` is constructed: ADK appends the tools in - its constructor. Only the exact ``_SingleTurnAgentTool`` whose ``agent`` - is one of ``children`` (the objects the framework built and passed in) - is bound; nothing else in ``agent.tools`` is touched. - """ - declaration = get_registry().get(TASK_TOOL) - for tool in agent.tools: - if type(tool) is _SingleTurnAgentTool and any( - tool.agent is child for child in children - ): - bind_tool_identity(tool, declaration) - - -def _tool_names(tools: list[Any]) -> set[str]: - from google.adk.tools.skill_toolset import SkillToolset - - names: set[str] = set() - for tool in tools: - if isinstance(tool, SkillToolset): - names.update(skill_tool.name for skill_tool in tool._tools) - elif isinstance(tool, BaseTool): - names.add(tool.name) - elif callable(tool): - names.add(getattr(tool, "__name__", "")) - return names diff --git a/src/agentic_cli/workflow/adk/event_processor.py b/src/agentic_cli/workflow/adk/event_processor.py index 2ec358f7..d00bfb31 100644 --- a/src/agentic_cli/workflow/adk/event_processor.py +++ b/src/agentic_cli/workflow/adk/event_processor.py @@ -12,22 +12,15 @@ from google.genai import types +from agentic_cli.tools._core.delegation import TASK_TOOL from agentic_cli.tools._core.tasks import task_progress_data -from agentic_cli.workflow.adk.branches import branch_run from agentic_cli.workflow.adk.call_clock import call_latency -from agentic_cli.workflow.adk.interrupted_calls_plugin import ABORTED from agentic_cli.workflow.adk.subagent_outcome_plugin import OUTCOME_KEY -from agentic_cli.workflow.agents.outcome import cut_off_warning -from agentic_cli.workflow.agents.runs import ( - RUN_STARTED, - AgentRuns, - run_ended, - run_title, - show_as_delegation, -) +from agentic_cli.workflow.agents.envelope import read_envelope +from agentic_cli.workflow.agents.runs import show_as_delegation from agentic_cli.workflow.context import OVERFLOW_ERROR_CODE, ContextBudget, usage_fields from agentic_cli.workflow.events import WorkflowEvent, EventType -from agentic_cli.workflow.sessions import RunRef, get_active_turn, root_run +from agentic_cli.workflow.sessions import RunRef, root_run from agentic_cli.workflow.usage import UsageLedgers, adk_usage_event from agentic_cli.logging import Loggers @@ -49,6 +42,9 @@ _NORMAL_FINISH = frozenset( {types.FinishReason.STOP.value, types.FinishReason.FINISH_REASON_UNSPECIFIED.value} ) +#: ADK's code for a reply with nothing in it: no parts, or only thoughts or +#: blank text (``apply_empty_response_policy``). +_NO_CONTENT = "MODEL_RETURNED_NO_CONTENT" class ADKEventProcessor: @@ -56,24 +52,18 @@ class ADKEventProcessor: Owns an optional on_event callback for event transformation/filtering. + One processor reads the conversation's own runner (the manager's, one + per initialization); one made for a sub-agent run (``run=``) reads that + run's, on its child session (``GoogleADKWorkflowManager._run_agent``). + Only the agents that reply to the user write the reply (``reply_agents``): the root, and every chat-mode agent it can transfer to, which takes the conversation (a native ADK YAML app's). An event - another agent wrote (a sub-agent its parent delegated to, - ``workflow/adk/delegation.py``) is its work: its text is marked + another agent wrote is its work: its text is marked ``metadata["agent"]``/``["subagent"]`` (the CLI shows it as activity, not as the reply), and its call's usage is ``purpose="subagent"``, since that - prompt is the sub-agent's brief, not the conversation's context. A - sub-agent's failed model call does not end the turn on ADK: ADK's - delegation tool hands its parent "Error running sub-agent: …" and the - parent carries on. ADK records the provider's reason on the sub-agent's - error event, which becomes a recoverable ``ERROR``, "<agent> failed: - <reason>", so the user is told why. The parent does not read that - reason, unlike on Deep Agents: ADK's private delegation tool - (``_SingleTurnAgentTool``) catches the wrapper error its node runner - raises, so the parent reads "Error running sub-agent: Dynamic node - <agent> failed". With neither a root nor reply agents, nothing is - marked. + prompt is the sub-agent's brief, not the conversation's context. With + neither a root nor reply agents, nothing is marked. A call's ``LLM_USAGE`` is credited to the agent that made it, the event's author: ``metadata["agent"]``, that agent's own model (``models``; the @@ -87,19 +77,24 @@ class ADKEventProcessor: read as an unknown kind's), and it is recorded in the conversation's ledger (``ledgers``) as it is made, before ``on_event``, with how long the call took (``latency_ms``: the mark ``CallLatencyPlugin`` puts on - the answer, ``workflow/adk/call_clock.py``). A sub-agent run's end - carries what the run used, by model (``metadata["usage"]``). + the answer, ``workflow/adk/call_clock.py``). A tool's result is a failed ``TOOL_RESULT`` when it says so (``success`` false, an ``error`` value) or is an MCP tool's error result (``isError``), - its error in ``metadata["error"]``, as on Deep Agents. + its error in ``metadata["error"]``, as on Deep Agents. A ``task`` call's + result is the JSON text of what the delegation returned + (``adk/task_tool.py``), read back as its dict, as Deep Agents reads its + ``ToolMessage``; an envelope is shown as every backend shows one + (``agents/runs.py::show_as_delegation``). A tool that wrote the session's task list (``save_tasks``: ``tasks`` in the event's state delta) is followed by ``TASK_PROGRESS``, after its result, when the list differs from the one this turn last reported (``start_turn`` forgets it), as on Deep Agents: a call that changed nothing reports nothing, and a list whose tasks are all done stays in the - session for ``get_tasks``. + session for ``get_tasks``. A sub-agent run's list is the conversation's, + which its ``task`` call writes back as it returns: the conversation's + processor reports it then. A conversation the model of an agent that replies no longer takes ends its turn with an error response from the overflow handler @@ -117,37 +112,24 @@ class ADKEventProcessor: is mapped: ADK records one for an exception that then leaves the run, which the manager reports as the turn's one ``ERROR``. - Every event an agent wrote names its run (``WorkflowEvent.run``): the run - of the delegation its branch names (``workflow/adk/branches.py``), else - the agent's own at depth 0 (``root_run`` for the root; an agent the root - transfers to is ``RunRef(<name>, <name>, None, None, 0)``); the user's - message names none, nor does the turn's own ``ERROR``. A tool's call and - result name the call (``tool_call_id``), as on Deep Agents. A call that - delegates to one of the calling agent's own single-turn sub-agents - (``delegates``, by the caller, the event's author: ADK names the tool - after the sub-agent) is followed by the ``AGENT_RUN`` that starts the - sub-agent's run, and its result by the one that ends it, as on Deep - Agents (``agents/runs.py::run_ended``): ``failed`` for ADK's answer for - a sub-agent that failed (``Error running sub-agent: …``) or the - framework's error result (a dict that says ``success`` false: the tool - raised, the gate denied it), with its error, ``interrupted`` for the - seal of a stopped turn, ``refused`` when ``SubAgentOutcomePlugin`` - marked the run's last answer refused, else ``completed`` (``partial``, - and followed by one warning, ``cut_off_warning``, when it marked the - answer cut). The sub-agent's answer, which ADK keeps under ``result``, - is never read for success. The result itself is shown as on Deep Agents - (``agents/runs.py::show_as_delegation``: the answer's first line, a - failed one as a failed result). Any other call is an ordinary tool call, - with no run: a name the caller has no such sub-agent for runs none (ADK - answers an unknown tool). Each ``AGENT_RUN`` is recorded in ``runs`` as - it is made, before ``on_event``. - - A delegation that finished beside a slower one in the same model step - ends later than on Deep Agents, which ends each run at its own result: - ADK hands a step's parallel function responses back in one event, after - the last one returns, so the finished run ends with the slower one's. A - turn stopped or failed before then ends it from the record - (``end_returned_run``), with its result, as that event would have. + Every event an agent wrote names its run (``WorkflowEvent.run``): the + sub-agent run the processor was made for, else the agent's own at depth + 0 (``root_run`` for the root; an agent the root transfers to is + ``RunRef(<name>, <name>, None, None, 0)``); the user's message names + none, nor does the turn's own ``ERROR``. A tool's call and result name + the call (``tool_call_id``), as on Deep Agents. The ``AGENT_RUN`` events + are the framework's (``agents/delegate.py``), not this processor's. + + A sub-agent run's processor reports no ``ERROR``: it keeps what ends the + run for its manager to end it with (``Delegations`` warns the user + once). Its last answer with text (``answer``: the last of its replies + that has any, one that also calls tools included, as Deep Agents' own + ``task`` reads a run: an empty reply after it passed over), that + answer's outcome mark + (``outcome``: ``SubAgentOutcomePlugin``'s), and why it failed + (``failure``: the overflow handler's answer, ``CONTEXT_OVERFLOW``, or a + reply that is no answer but an empty one, which is no failure: the run + ends with the answer it has). Args: model: The default model, which usage names for an agent ``models`` @@ -159,17 +141,14 @@ class ADKEventProcessor: budgets: Each agent's context numbers, by name. reply_agents: The agents that reply to the user, the root among them (``workflow/adk/build.py::reply_agents``); None for the root alone. - runs: The manager's sub-agent runs, which this processor names and - records; its own when not given. - delegates: Each agent's single-turn sub-agents, which it delegates - to through a tool named after each, by the agent's name - (``build.delegated_agents``); a collection of names alone is the - root's. kinds: Each agent's model's provider kind (``ProviderKind``'s value), by name. ledgers: The manager's usage ledgers, which this processor records each call's usage in; its own when not given. + run: The sub-agent run whose runner this processor reads; None for + the conversation's own. - The manager builds one at each initialization, from the app it built. + The manager builds one at each initialization, from the app it built, + and one for each sub-agent run. """ def __init__( @@ -180,10 +159,10 @@ def __init__( models: Mapping[str, str] | None = None, budgets: Mapping[str, ContextBudget] | None = None, reply_agents: Collection[str] | None = None, - runs: AgentRuns | None = None, - delegates: Mapping[str, Collection[str]] | Collection[str] = (), kinds: Mapping[str, str] | None = None, ledgers: UsageLedgers | None = None, + *, + run: RunRef | None = None, ) -> None: self._model = model self._on_event = on_event @@ -195,17 +174,15 @@ def __init__( self.budgets: Mapping[str, ContextBudget] = budgets or {} # The task list this turn last reported, None before any. self._reported_tasks: list | None = None - self.runs = runs if runs is not None else AgentRuns() - if isinstance(delegates, Mapping): - by_agent = {name: frozenset(own) for name, own in delegates.items()} - else: - by_agent = {root: frozenset(delegates)} if root is not None and delegates else {} - self.delegates: dict[str, frozenset[str]] = by_agent - # A sub-agent run's last answer's outcome (SubAgentOutcomePlugin's - # mark), by run id, until its delegation's result ends the run. - self._outcomes: dict[str, str] = {} self.kinds: Mapping[str, str] = kinds or {} self.ledgers = ledgers if ledgers is not None else UsageLedgers() + self.run = run + #: A sub-agent run's last answer with text ("" before one). + self.answer = "" + #: That run's last answer's outcome mark, None for none. + self.outcome: str | None = None + #: Why that run failed: ``(error, code)``, None while it has not. + self.failure: tuple[str, str] | None = None @property def model(self) -> str: @@ -224,10 +201,8 @@ def on_event(self, value: Callable[[WorkflowEvent], WorkflowEvent | None] | None self._on_event = value def start_turn(self) -> None: - """Forget the task list reported (a turn reports the first one it - sees), and the outcomes of runs a stopped turn left open.""" + """Forget the task list reported: a turn reports the first one it sees.""" self._reported_tasks = None - self._outcomes.clear() async def process_event( self, @@ -245,25 +220,10 @@ async def process_event( """ subagent = self._subagent(adk_event) run = self._run_ref(adk_event) - outcome = (getattr(adk_event, "custom_metadata", None) or {}).get(OUTCOME_KEY) - if outcome and run is not None and run.run is not None: - self._outcomes[run.run] = outcome - error_code = getattr(adk_event, "error_code", None) - if subagent is not None and error_code: - # The root's own failure leaves the run, which the manager - # reports as the turn's ERROR; this one never does. - error = WorkflowEvent.error( - f"{subagent} failed: {adk_event.error_message or error_code}", - error_code=error_code, - recoverable=True, - ) - error.metadata["agent"] = subagent - error.run = run - error = self._apply_hook(error) - if error: - yield error - elif error_code == OVERFLOW_ERROR_CODE: + if self.run is not None: + self._keep_run_end(adk_event) + elif subagent is None and error_code == OVERFLOW_ERROR_CODE: # The turn's one ERROR (the base process()'s contract), though # no exception ended it: the overflow handler answered the call. error = self._apply_hook(WorkflowEvent.turn_failed( @@ -273,12 +233,8 @@ async def process_event( if error: yield error elif subagent is None and (code := _no_answer(adk_event)) is not None: - model = self.models.get(self._agent(adk_event), self._model) - message = adk_event.error_message - # ADK's own message for an empty reply says no more than the code. - said = f": {message}" if message and code != "MODEL_RETURNED_NO_CONTENT" else "" error = self._apply_hook(WorkflowEvent.turn_failed( - message=f"{model} returned no answer{said}", error_code=code + message=self._no_answer_text(adk_event, code), error_code=code )) if error: yield error @@ -310,40 +266,53 @@ async def process_event( parts = adk_event.content.parts if adk_event.content else None for part in parts or (): - # Made before the part's own event, which a delegation's end shows. - run_event = self._delegation_run(part, run, sealed=error_code == ABORTED) workflow_event = self.process_part(part, session_id) if workflow_event: workflow_event.run = run if subagent is not None and workflow_event.type is EventType.TEXT: workflow_event.metadata.update(agent=subagent, subagent=True) - if run_event is not None and workflow_event.type is EventType.TOOL_RESULT: - show_as_delegation( - workflow_event, _result_text(part.function_response.response), run_event - ) workflow_event = self._apply_hook(workflow_event) if workflow_event: yield workflow_event - if run_event is not None: - # A run cut short is followed by its one warning. - for event in (run_event, cut_off_warning(run_event)): - event = self._apply_hook(event) if event is not None else None - if event: - yield event - - progress = self._progress(adk_event) + + progress = self._progress(adk_event) if self.run is None else None if progress is not None: progress.run = run progress = self._apply_hook(progress) if progress: yield progress - def _progress(self, adk_event: Any) -> WorkflowEvent | None: - """``TASK_PROGRESS`` for a task list ``adk_event`` wrote, when it changed. + def _keep_run_end(self, adk_event: Any) -> None: + """Keep what ``adk_event`` says of the run's end: its answer, its outcome, its failure.""" + if self._agent(adk_event) is None or getattr(adk_event, "partial", False): + return + outcome = (getattr(adk_event, "custom_metadata", None) or {}).get(OUTCOME_KEY) + if outcome: + self.outcome = outcome + error_code = getattr(adk_event, "error_code", None) + if error_code == OVERFLOW_ERROR_CODE: + self.failure = (adk_event.error_message or error_code, OVERFLOW_ERROR_CODE) + return + code = _no_answer(adk_event) + if code is not None and code != _NO_CONTENT: + self.failure = (self._no_answer_text(adk_event, code), code) + return + content = getattr(adk_event, "content", None) + parts = (content.parts if content is not None else None) or [] + text = "".join(part.text for part in parts if part.text and not part.thought) + if text.strip(): + self.answer = text.rstrip() + + def _no_answer_text(self, adk_event: Any, code: str) -> str: + """What a reply that is no answer is told as: ``<model> returned no answer[: <message>]``.""" + model = self.models.get(self._agent(adk_event), self._model) + message = adk_event.error_message + # ADK's own message for an empty reply says no more than the code. + said = f": {message}" if message and code != _NO_CONTENT else "" + return f"{model} returned no answer{said}" - A sub-agent's list is the session's too: the coordinator reads it, - and reporting it again would say nothing new. - """ + def _progress(self, adk_event: Any) -> WorkflowEvent | None: + """``TASK_PROGRESS`` for a task list ``adk_event`` wrote, when it changed.""" delta = getattr(getattr(adk_event, "actions", None), "state_delta", None) or {} tasks = delta.get("tasks") if not isinstance(tasks, list) or tasks == self._reported_tasks: @@ -363,10 +332,14 @@ def _subagent(self, adk_event: Any) -> str | None: """The sub-agent that wrote ``adk_event``, or None (an agent that replies, the user).""" agent = self._agent(adk_event) + if agent is None: + return None + if self.run is not None: + return agent replying = self.reply_agents if replying is None: replying = () if self.root is None else (self.root,) - if agent is None or not replying or agent in replying: + if not replying or agent in replying: return None return agent @@ -377,90 +350,17 @@ def _agent(adk_event: Any) -> str | None: return author if author and author != "user" else None def _run_ref(self, adk_event: Any) -> RunRef | None: - """The run that wrote ``adk_event``: its delegation branch's, else the - agent's own at depth 0; None for the user's own.""" + """The run that wrote ``adk_event``: the processor's sub-agent run, else + the agent's own at depth 0; None for the user's own.""" agent = self._agent(adk_event) if agent is None: return None - run = branch_run(self.runs, get_active_turn(), getattr(adk_event, "branch", None)) - if run is not None: - return run + if self.run is not None: + return self.run if self.root is None or agent == self.root: return root_run(agent) return RunRef(agent=agent, instance=agent, run=None, parent_run=None, depth=0) - def _run_usage(self, run: RunRef) -> dict[str, dict[str, int]]: - """What ``run`` used, by model, from its conversation's ledger.""" - return self.ledgers.ledger(get_active_turn()).run_usage(run.run or "") - - def _delegation_run( - self, part: Any, parent: RunRef | None, *, sealed: bool - ) -> WorkflowEvent | None: - """The ``AGENT_RUN`` a delegation ``part`` starts or ends, recorded; else None. - - A delegation is a call of one of ``parent``'s agent's own single-turn - sub-agents (``delegates``); any other part is none. - - Args: - part: A part of an event of ``parent``'s. - parent: The run that made the call (or got its result). - sealed: Whether the event seals a stopped turn's calls (ADK's - ``INVOCATION_ABORTED``). - """ - call = getattr(part, "function_call", None) - response = getattr(part, "function_response", None) - own = self.delegates.get(parent.agent, frozenset()) if parent is not None else frozenset() - if call is not None and call.name in own and call.id: - child = self.runs.run_for(get_active_turn(), parent, call.id, call.name) - request = (call.args or {}).get("request") - event = WorkflowEvent.agent_run( - child, RUN_STARTED, call_id=call.id, - title=run_title(request if isinstance(request, str) else ""), - ) - elif response is not None and response.name in own and response.id: - child = self.runs.run_for(get_active_turn(), parent, response.id, response.name) - event = self._ended(child, response.id, response.response, sealed=sealed) - else: - return None - self.runs.observe(event) - return event - - def end_returned_run(self, ref: RunRef, call_id: str, response: Any) -> WorkflowEvent: - """End ``ref``'s run with what its delegation returned, which no event brought; recorded. - - ADK hands a model step's parallel function responses back in one - event, after the last one returns, so a delegation that finished - beside a slower one has no result event until then. A turn stopped - or failed before it ends that run from the record with this - (``GoogleADKWorkflowManager``): as its result would have ended it, - refused or partial from its outcome mark. - - Args: - ref: The run. - call_id: Its parent's call that started it. - response: What the call returned, as ADK stores it (text under - ``result``). - """ - event = self._ended(ref, call_id, response, sealed=False) - self.runs.observe(event) - return event - - def _ended(self, child: RunRef, call_id: str, response: Any, *, sealed: bool) -> WorkflowEvent: - """The ``AGENT_RUN`` that ``response``, a delegation's result, ends ``child``'s run with. - - ``agents/runs.py::run_ended``'s decision: the framework's error - result (a dict that says it failed: the tool raised, the gate denied - it) fails it, never the sub-agent's answer, which ADK keeps under - ``result``. - """ - succeeded, error = _outcome(response) - return run_ended( - child, call_id, _result_text(response), - failed=not succeeded, error=error, - outcome=self._outcomes.pop(child.run or "", None), - usage=self._run_usage(child), sealed=sealed, - ) - def process_part(self, part: Any, session_id: str) -> WorkflowEvent | None: """Process a single part from the agent response. @@ -490,6 +390,8 @@ def process_part(self, part: Any, session_id: str) -> WorkflowEvent | None: if hasattr(part, "function_response") and part.function_response: tool_name = part.function_response.name response = part.function_response.response + if tool_name == TASK_TOOL: + response = _delegated(response) success, error = _outcome(response) logger.debug("tool_result", tool_name=tool_name, success=success) @@ -503,6 +405,9 @@ def process_part(self, part: Any, session_id: str) -> WorkflowEvent | None: if _is_mcp_error(response): # Shown as any failed result is ("Failed: <error>"). event.content = f"Failed: {error}" + found = read_envelope(response) if tool_name == TASK_TOOL else None + if found is not None: + show_as_delegation(event, found) return _with_call_id(event, getattr(part.function_response, "id", None)) if part.code_execution_result: @@ -579,12 +484,17 @@ def _with_call_id(event: WorkflowEvent, call_id: Any) -> WorkflowEvent: return event -def _result_text(response: Any) -> str: - """A delegation's result as text: ADK keeps a text result under ``result``.""" - if isinstance(response, dict): - result = response.get("result") - return result if isinstance(result, str) else json.dumps(response, default=str) - return "" if response is None else str(response) +def _delegated(response: Any) -> Any: + """A ``task`` call's result as its delegation returned it: the dict whose JSON text + ADK stores under ``result`` (``adk/task_tool.py``); anything else as it is.""" + if isinstance(response, dict) and set(response) == {"result"}: + try: + parsed = json.loads(response["result"]) + except (TypeError, ValueError): + return response + if isinstance(parsed, dict): + return parsed + return response def _no_answer(adk_event: Any) -> str | None: diff --git a/src/agentic_cli/workflow/adk/fit_guard_plugin.py b/src/agentic_cli/workflow/adk/fit_guard_plugin.py index 54b0af6d..cc31e75b 100644 --- a/src/agentic_cli/workflow/adk/fit_guard_plugin.py +++ b/src/agentic_cli/workflow/adk/fit_guard_plugin.py @@ -33,12 +33,13 @@ the system instruction, the tools and the cached contents out of it). A copy belongs to one model call: it is kept under the identity of the call's ``EventActions`` (``callback_context.actions``), which ADK makes for each -call and hands to all three of its callbacks, while two parallel calls of one -sub-agent share their invocation and agent name. It is released when the +call and hands to all three of its callbacks. It is released when the call ends (``after_model_callback``, ``on_model_error_callback``). Before google-adk 2.14 a call cancelled mid-request fires neither (2.14 runs the -error callback with the ``CancelledError``), so each run first drops the -copies any other invocation left (turns run one at a time). +error callback with the ``CancelledError``), so as each run ends +(``after_run_callback``, also for a stopped one; ``on_run_error_callback`` +for one that fails) the copies it left are dropped, its own only: two runs +of one sub-agent type share their runner, and this plugin, at once. """ from __future__ import annotations @@ -135,13 +136,22 @@ async def on_model_error_callback( self._release(callback_context) return None - async def before_run_callback(self, *, invocation_context: "InvocationContext") -> None: + async def after_run_callback(self, *, invocation_context: "InvocationContext") -> None: # What a cancelled call left: before google-adk 2.14 it fired neither release. - invocation = invocation_context.invocation_id + self._forget(invocation_context.invocation_id) + return None + + async def on_run_error_callback( + self, *, invocation_context: "InvocationContext", error: Exception + ) -> None: + self._forget(invocation_context.invocation_id) + return None + + def _forget(self, invocation: str) -> None: + """Drop the copies ``invocation`` left; another run's stay.""" self._seen = { - key: held for key, held in self._seen.items() if held.invocation == invocation + key: held for key, held in self._seen.items() if held.invocation != invocation } - return None def request_as_seen(self, callback_context: "CallbackContext") -> Seen | None: """The request of this model call as it came in, before any plugin diff --git a/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py b/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py index d12b6c79..dd5e1afe 100644 --- a/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py +++ b/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py @@ -12,13 +12,12 @@ any other was interrupted by the user; the content-less event becomes the main agent's reply ``MARKER``. -ADK's seals pair a result with a call by id alone, so a call whose id a -sub-agent's result used (a provider that numbers its call ids per agent -gives a sub-agent's first call its parent's delegation's id) is taken for -answered and left open. ``unsealed`` answers those as the turn stops, from -the record, as a seal is answered (the manager writes them before the turn -clears its record): a finished call keeps its result, one at its prompt was -not run. +ADK's seals pair a result with a call by id alone, so a call whose id +another call's result used, on another branch of the session (a native ADK +YAML app's agents), is taken for answered and left open. ``unsealed`` +answers those as the turn stops, from the record, as a seal is answered (the +manager writes them before the turn clears its record): a finished call +keeps its result, one at its prompt was not run. ``left_open`` answers, on the next turn, the calls nothing answered: a crash's, a cancel's from before this plugin, or a stop's whose answers @@ -26,10 +25,12 @@ without its result in every later request, which Claude and OpenAI refuse, and drop any other one, logging "Dropping function calls" on every request. -Each call is recorded and answered as the run's that made it, the run its -branch names (``workflow/adk/branches.py``; the root's own calls are no -run), so a sub-agent's call never stands for its parent's of the same id -(``OpenCalls``). +Each call is recorded and answered as the run's that made it, the active run +(a sub-agent run is the active one in the task its runner runs in, +``agents/delegate.py``; the root's own calls are no run), so a sub-agent's +call never stands for its parent's of the same id (``OpenCalls``). A +sub-agent run's calls are on its child session, which its own runner seals +as it stops. ADK stops at the first plugin whose ``after_tool_callback`` returns a value, so this one is registered before ``ToolResultCapPlugin``, which tells it each @@ -46,9 +47,7 @@ from google.adk.plugins.base_plugin import BasePlugin from google.genai import types -from agentic_cli.workflow.adk.branches import branch_run, delegations from agentic_cli.workflow.adk.tool_error_plugin import is_unknown_tool -from agentic_cli.workflow.agents.runs import AgentRuns from agentic_cli.workflow.interrupts import ( INTERRUPTED, INTERRUPTED_BY_USER, @@ -59,6 +58,7 @@ ) from agentic_cli.workflow.sessions import ( ToolCallRef, + get_active_run, get_active_turn, reset_active_tool_call, set_active_tool_call, @@ -70,7 +70,6 @@ from google.adk.tools.tool_context import ToolContext from agentic_cli.workflow.adk.tool_result_cap_plugin import ToolResultCapPlugin - from agentic_cli.workflow.sessions import RunRef #: ADK's ``error_code`` on the events that seal an aborted invocation #: (``google/adk/events/_abort_events.py``, private; contract-tested). @@ -104,26 +103,17 @@ class InterruptedCallsPlugin(BasePlugin): cap: The tool result cap, registered after this plugin: it tells this plugin each cut it makes, which a finished call's seal sends. - runs: The manager's runs, which name the run a seal's branch is - (the names the active run has, ``MainAgentPlugin``'s); a - registry of its own when None. """ - def __init__( - self, - open_calls: OpenCalls, - cap: "ToolResultCapPlugin | None" = None, - *, - runs: AgentRuns | None = None, - ) -> None: + def __init__(self, open_calls: OpenCalls, cap: "ToolResultCapPlugin | None" = None) -> None: super().__init__(name="interrupted_calls") self._open = open_calls self._cap = cap - self._runs = runs if runs is not None else AgentRuns() if cap is not None: cap.on_cut = self._keep_cut - # Each running call's active-tool-call token, by its branch and id: - # a sub-agent's call can have the id of its parent's delegation. + # Each running call's active-tool-call token, by its invocation and + # id: two runs of one sub-agent, each on its own invocation of one + # runner, may number their calls alike. self._active: dict[tuple[str | None, str], Any] = {} async def before_tool_callback( @@ -137,7 +127,7 @@ async def before_tool_callback( """ call_id = getattr(tool_context, "function_call_id", None) if call_id and not is_unknown_tool(tool): - self._active[(_branch(tool_context), call_id)] = set_active_tool_call( + self._active[(_invocation(tool_context), call_id)] = set_active_tool_call( ToolCallRef(call_id, tool.name) ) return None @@ -152,7 +142,7 @@ async def after_tool_callback( ) -> None: if tool_context is None: return None - self._done(_branch(tool_context), tool_context.function_call_id) + self._done(_invocation(tool_context), tool_context.function_call_id) if result is None and getattr(tool, "is_long_running", False): # ADK gives a long-running call that returned nothing no result: # its job answers it (OpenCalls.answer), never null. @@ -173,8 +163,8 @@ def _keep_cut(self, call_id: str, cut: Any) -> None: if isinstance(finished, _Finished): self._open.finished(call_id, replace(finished, cut=cut)) - def _done(self, branch: str | None, call_id: str | None) -> None: - token = self._active.pop((branch, call_id), None) if call_id else None + def _done(self, invocation: str | None, call_id: str | None) -> None: + token = self._active.pop((invocation, call_id), None) if call_id else None if token is not None: try: reset_active_tool_call(token) @@ -192,24 +182,15 @@ async def on_event_callback( role="model", parts=[types.Part(text=MARKER)], )}) actions = event.actions.model_copy(deep=True) - ref = self._branch_run(event.branch) - run = ref.run if ref is not None else None + # A seal is written by the runner that ran the call, in the task that + # iterates it: a sub-agent run's, where its run is the active one. + active = get_active_run() + run = active.run if active is not None else None parts = [await self._answered(part, actions, run) for part in content.parts] return event.model_copy(update={ "content": types.Content(role=content.role, parts=parts), "actions": actions, }) - def _branch_run(self, branch: str | None) -> "RunRef | None": - """The run ``branch`` is (None for the root's own calls). - - A seal is written outside the run whose call it answers (in the - runner's own context), so its run is its branch's, not the active - one. Asked while that run is open: ADK seals every branch of a - stopped turn before any seal reaches the event processor that ends - its run. - """ - return branch_run(self._runs, get_active_turn(), branch) - async def _answered(self, part: types.Part, actions: Any, run: str | None) -> types.Part: call = part.function_response if call is None: @@ -220,9 +201,9 @@ async def _answered(self, part: types.Part, actions: Any, run: str | None) -> ty )) -def _branch(tool_context: Any) -> str | None: - """The branch a tool call runs on (None for the root's own calls).""" - return getattr(tool_context, "branch", None) +def _invocation(tool_context: Any) -> str | None: + """The invocation a tool call runs in: one per turn, and one per sub-agent run.""" + return getattr(tool_context, "invocation_id", None) def _from_record(open_calls: OpenCalls, call_id: str | None, run: str | None, actions: Any) -> Any: @@ -300,17 +281,16 @@ def _answer_event( ) -def unsealed(events: list[Event], open_calls: OpenCalls, runs: AgentRuns) -> list[Event]: +def unsealed(events: list[Event], open_calls: OpenCalls) -> list[Event]: """The events that answer, as a turn stops, the calls ADK's seals missed. ADK seals a stopped invocation's open calls pairing a result with a call - by id alone, so a call whose id a sub-agent's result used stays open. + by id alone, so a call whose id another branch's result used stays open. Each is answered as a seal is (``InterruptedCallsPlugin``), from the - record, as the call of the run its branch names (``branch_run``: still - open, since the turn ends its runs after this): a finished call with its - result and the state it changed, one at its prompt ``NOT_RUN``, any - other ``INTERRUPTED_BY_USER``. The manager writes them before the turn - clears its record. + record, as the conversation's own call (no sub-agent run's: those are on + their child sessions): a finished call with its result and the state it + changed, one at its prompt ``NOT_RUN``, any other ``INTERRUPTED_BY_USER``. + The manager writes them before the turn clears its record. Only once ADK has sealed the stopped invocation: seals written after these answers would answer a call twice. The check is that the @@ -323,16 +303,13 @@ def unsealed(events: list[Event], open_calls: OpenCalls, runs: AgentRuns) -> lis if not events or events[-1].error_code != ABORTED: return [] stopped = [event for event in events if event.invocation_id == events[-1].invocation_id] - conversation = get_active_turn() answers: list[Event] = [] for place, calls in _unanswered(stopped).items(): - ref = branch_run(runs, conversation, place[2]) - run = ref.run if ref is not None else None actions = EventActions() answers.append(_answer_event(place, [ types.FunctionResponse( id=call.id, name=call.name, - response=_as_response(_from_record(open_calls, call.id, run, actions)), + response=_as_response(_from_record(open_calls, call.id, None, actions)), ) for call in calls ], INTERRUPTED_BY_USER, actions)) @@ -350,9 +327,10 @@ def left_open(events: list[Event], open_calls: OpenCalls) -> list[Event]: ``INTERRUPTED``): every turn clears its conversation's record as it ends (``OpenCalls.clear``), and a new process has none. Only the root's own calls (and those of an agent it transferred to) are matched to a job: a - sub-agent's run, on a delegation's branch, is numbered no more (one a - stop ended, or a crash's in a new process), so its call is answered - interrupted, never with another run's job of the same id. A stopped turn + conversation stored while sub-agents ran on delegation branches of its + own session (``<agent>@<call id>``) may hold a sub-agent's call there, + whose run is numbered no more, so its call is answered interrupted, never + with another run's job of the same id. A stopped turn answers what ADK's seals missed itself (``unsealed``), so a stop leaves a call here only when those answers could not be written. The answer is in the author, branch, scope and invocation of the event that made the @@ -377,8 +355,9 @@ def _left_open_answer(call_id: str | None, branch: str | None, by_user: bool) -> The root's own call (no delegation on its branch) gets its job's state when it submitted one (``unrecorded``, the root's: ``started_by`` None); - a sub-agent's run cannot be named any more, so its call gets no job. + a sub-agent's on a delegation's branch (``<agent>@<call id>``) cannot be + named any more, so its call gets no job. """ - if delegations(branch): + if any("@" in segment for segment in (branch or "").split(".")): return interrupted(INTERRUPTED_BY_USER if by_user else INTERRUPTED) return unrecorded(call_id, by_user=by_user) diff --git a/src/agentic_cli/workflow/adk/log_filters.py b/src/agentic_cli/workflow/adk/log_filters.py index a2d4aeed..57f6cdfc 100644 --- a/src/agentic_cli/workflow/adk/log_filters.py +++ b/src/agentic_cli/workflow/adk/log_filters.py @@ -91,6 +91,13 @@ def _overflow_plugin_failed() -> str: return OVERFLOW_PLUGIN_FAILED +# An inheriting sub-agent run's child session holds copies of its +# conversation's events, written by agents the run's tree does not have (the +# root among them): ADK warns of each such author as it picks the agent to +# run, then runs the sub-agent all the same (workflow/adk/manager.py, +# _child_session). The logger, and what its warning starts with. +_ADK_UNKNOWN_AUTHOR = ("google_adk.google.adk.agents._agent_router", "Event from an unknown agent") + # ADK logs a failure's traceback through stdlib logging where the user is # told otherwise. A summary that failed: ADK goes on with the whole history, # and the summarizer itself warns the user once a turn (it never lets its own @@ -101,8 +108,9 @@ def _overflow_plugin_failed() -> str: # failed overflow retry once more, from the plugin manager. ADK also warns on # every request of a session holding a call without a result, which it drops: # the next turn answers such a call (workflow/adk/interrupted_calls_plugin.py), -# so the warning has nothing for the user either. Each entry: the logger, what -# a record's message starts with or (``msg=``) its exact format, and the debug +# so the warning has nothing for the user either. Nor does the warning of an +# unknown author (_ADK_UNKNOWN_AUTHOR). Each entry: the logger, what a +# record's message starts with or (``msg=``) its exact format, and the debug # event it becomes. _ADK_FAILURES = ( ("google_adk.google.adk.apps.compaction", {"prefix": "Event compaction failed"}, @@ -115,6 +123,7 @@ def _overflow_plugin_failed() -> str: ("google_adk.google.adk.flows.llm_flows.tools._rearranger", {"prefix": "Dropping function calls with no matching function response"}, "adk_dropped_open_calls"), + (_ADK_UNKNOWN_AUTHOR[0], {"prefix": _ADK_UNKNOWN_AUTHOR[1]}, "adk_inherited_unknown_author"), ) @@ -169,10 +178,11 @@ def install_log_filters() -> None: context-cache logger for a cache it could not create or delete, one each on its compaction, node, runner and plugin-manager loggers for the traceback of a summary, a model call or an overflow retry that failed, - and one on its rearranger for a call without a result it drops. Only the - CLI installs them, as it runs (``BaseCLIApp.run``), so library users and - the test suite keep Python's own handling. Installing twice changes - nothing. + one on its rearranger for a call without a result it drops, and one on + its agent router for the authors of an inheriting run's copied events. + Only the CLI installs them, as it runs (``BaseCLIApp.run``), so library + users and the test suite keep Python's own handling. Installing twice + changes nothing. """ for name, kind in ( (_ADK_RUNNER_LOGGER, _AdkUncachedTransferFilter), diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index e2dfd204..8c6d5dc8 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -5,6 +5,11 @@ Domain applications define agents using AgentConfig and pass them to GoogleADKWorkflowManager. +Each agent built from a config is built on its own. The root runs on the +conversation's runner; a delegating agent has the framework's ``task`` tool +(``adk/task_tool.py``), and each sub-agent type runs on a runner of its own, +each run on a child session of the conversation's (``_run_agent``). + Deep Agents is the other backend (``workflow/deepagents/manager.py``; LangGraph, deprecated, goes in 0.8.0). Each builds on ``base_manager.BaseWorkflowManager``, which holds the lifecycle and the turn, @@ -17,6 +22,7 @@ import contextlib import functools import time +from types import MappingProxyType from typing import TYPE_CHECKING, AsyncGenerator, Any, Callable from google.genai import types @@ -35,8 +41,12 @@ from agentic_cli.workflow.base_manager import BaseWorkflowManager, Closer from agentic_cli.workflow.context import CompactResult from agentic_cli.workflow.events import WorkflowEvent, EventType -from agentic_cli.workflow.config import AgentConfig, AgentGraph, validate_agent_graph -from agentic_cli.workflow.adk import delegation +from agentic_cli.workflow.config import ( + AgentConfig, + AgentGraph, + AgentGraphError, + validate_agent_graph, +) from agentic_cli.workflow.adk.call_clock import CallClock, CallLatencyPlugin, CallSentPlugin from agentic_cli.workflow.adk.compaction import ( SUMMARY_MAX_TOKENS, @@ -51,7 +61,6 @@ from agentic_cli.workflow.adk.interrupted_calls_plugin import ( InterruptedCallsPlugin, left_open, - returned, unsealed, ) from agentic_cli.workflow.adk.model_factory import build_adk_model, generate_text @@ -60,11 +69,16 @@ from agentic_cli.workflow.adk.plugins import LLMLoggingPlugin, SentRequestLoggingPlugin from agentic_cli.workflow.adk.sessions import ( ServiceSessions, + child_app, + child_session_id, make_session_service, turn_state, ) +from agentic_cli.workflow.adk.task_tool import SHARED_KEYS, TaskTool from agentic_cli.workflow.adk.tool_result_cap_plugin import ToolResultCapPlugin -from agentic_cli.workflow.agents.runs import RUN_STARTED +from agentic_cli.workflow.agents.delegate import AgentRun, RunAnswer, RunFailed +from agentic_cli.workflow.context import OVERFLOW_ERROR_CODE +from agentic_cli.tools._core.delegation import TASK_TOOL from agentic_cli.workflow.outside_content import ( BEFORE_0_7_0, JOB_RESULT, @@ -202,6 +216,11 @@ class GoogleADKWorkflowManager(BaseWorkflowManager): #: The reply set of the build ``_build_app`` is making, or made last, for #: the parts it builds through hooks (the gate, ``_init_plugins``). _reply_agents: frozenset[str] | None = None + #: Every agent built from a config, by name, and each sub-agent type's + #: runner: what a sub-agent run runs on (``_run_agent``). Empty while there + #: is no app; class defaults, as above (read-only: each build sets its own). + _agents: "Mapping[str, LlmAgent]" = MappingProxyType({}) + _agent_runners: "Mapping[str, Runner]" = MappingProxyType({}) def __init__( self, @@ -312,14 +331,17 @@ async def generate_simple(self, prompt: str, max_tokens: int = 500) -> str: return text def _detach_backend(self) -> list[Closer]: - """The runner and the agent tree, and the LLM logging plugin. + """The runners and the agents, and the LLM logging plugin. - The runner closes the agents' toolsets (an MCP server stops with its - toolset) and plugins; the session service it only flushes, so one a - model switch keeps stays open. It closes before the session service - (the base runs the backend's closers before the store's). + The conversation's runner and each sub-agent type's: a runner closes + its agent's toolsets (an MCP server stops with its toolset) and + plugins; the session service it only flushes, so one a model switch + keeps stays open. They close before the session service (the base + runs the backend's closers before the store's). """ runner, self._runner = self._runner, None + runners, self._agent_runners = self._agent_runners, MappingProxyType({}) + self._agents = MappingProxyType({}) self._root_agent = None self._build = None self._reply_agents = None @@ -329,7 +351,13 @@ def _detach_backend(self) -> list[Closer]: if self._llm_logging_plugin: self._llm_logging_plugin.clear() self._llm_logging_plugin = None - return [("runner", functools.partial(self._aclose_owned, runner, "runner"))] + return [ + ("runner", functools.partial(self._aclose_owned, runner, "runner")), + *( + (f"runner {name}", functools.partial(self._aclose_owned, owned, f"runner {name}")) + for name, owned in runners.items() + ), + ] def _detach_store(self) -> list[Closer]: """The session service. @@ -414,8 +442,9 @@ def _wrap_long_running(self, tools: list[Callable]) -> list: ``PermissionPlugin``, which resolves the same identity. Only the root agent's tools are wrapped (``_build_agent``): ADK pauses - the whole invocation on a pending long-running call, inside a - delegation too, so a sub-agent's starter stays an ordinary call that + the whole invocation on a pending long-running call, and a sub-agent + run is an invocation of its own runner that its parent's ``task`` + call waits for, so a sub-agent's starter stays an ordinary call that returns the job's id, and its finished job is told to the root (``resume_with_job_result``). """ @@ -440,73 +469,64 @@ def _build_agent( self, config: "AgentConfig", service_map: dict, - sub_agents: list[Agent] | None = None, *, root: bool, + types: "Mapping[str, AgentConfig] | None" = None, ) -> Agent: - """Construct one ``LlmAgent`` from a config (with resolved sub-agents). + """Construct one ``LlmAgent`` from a config, on its own. Its model, generation settings and thinking come from the model initialization resolved for it, built by the model factory. - Every agent but the root is a sub-agent its parent delegates to and - gets back in the same turn (``single_turn``, no transfers; its - ``inherit_context`` decides what it sees; a placeholder description - when it has none), and ADK offers each of ``sub_agents`` to this agent - as a tool named after it; those tools are bound to the delegation - declaration as soon as this agent exists. Only the root's + No agent has ADK ``sub_agents``, so ADK offers none of them + ``transfer_to_agent``. An agent that delegates (``types``: its + sub-agents, by name) gets the framework's ``task`` tool + (``adk/task_tool.py::TaskTool``), whose calls run each sub-agent on + that sub-agent type's own runner (``_run_agent``). Only the root's long-running tools are wrapped: a pending one would pause a - delegation for good. See ``workflow/adk/delegation.py``. The root - stays in chat mode. + sub-agent's run for good. Raises: - AgentGraphError: A sub-agent is named like one of this agent's - own tools (its MCP tools, known only once they connect, - excepted). + AgentGraphError: A delegating agent's own tools include one named + ``task``, its delegation tool's name (its MCP tools, known + only once they connect, excepted). """ - children = sub_agents or [] built = build_adk_model( self._resolved_models[config.name], settings=self._settings, app_name=self.app_name ) tools = self._assemble_agent_tools(config, service_map) if root: tools = self._wrap_long_running(tools) - delegation.check_delegation_names(config, tools) - fields = {"description": config.description} + if types: + if TASK_TOOL in _tool_names(tools): + raise AgentGraphError( + f"Agent {config.name!r} delegates to sub-agents through a tool named " + f"{TASK_TOOL!r}, so its own tools cannot include one; rename that tool." + ) + tools = [*tools, TaskTool(config.name, types, lambda: self._delegations)] instruction = config.get_prompt(self._settings) - if not root: - fields.update(delegation.subagent_fields(config)) - instruction = delegation.subagent_instruction(config, instruction) - agent = LlmAgent( + return LlmAgent( name=config.name, model=built.model, # None at all for no prompt: ADK adds an instruction only when # there is one, and a provider always looks like one. instruction=_as_written(instruction) if instruction else "", tools=tools, - sub_agents=children, planner=built.planner, generate_content_config=built.generate_content_config, - **fields, + description=config.description, ) - delegation.bind_delegation_tools(agent, children) - return agent def _create_agents(self) -> Agent: - """Create the agent hierarchy from configs, in dependency order. + """Create every agent from its config, each on its own; the root. The graph is the one this initialization validated before anything was allocated (``_validate_agent_graph``), so duplicate names, dangling ``sub_agents`` references, self-references, cycles and - shapes ADK cannot represent failed there with the offending agent - named, instead of silently producing a coordinator with missing - children. Called outside an initialization, it validates the graph - itself. - - Construction then follows a topological order, so an agent is always - built after the agents it delegates to — the previous leaves-then- - coordinators split silently dropped a sub-agent that was itself a - coordinator. + shapes the framework refuses failed there with the offending agent + named. Called outside an initialization, it validates the graph + itself. Every agent is kept by name (``_agents``): each sub-agent + type gets a runner of its own (``_do_initialize``). Prompt factories are called under this manager's settings context (see ``AgentConfig.get_prompt``), so a prompt that reads settings sees the @@ -524,7 +544,7 @@ def _create_agents(self) -> Agent: if graph is None: graph = validate_agent_graph(self._agent_configs, backend=self.backend_type) - agent_map: dict[str, Agent] = {} + agents: dict[str, LlmAgent] = {} service_map = self._get_service_tool_map() from agentic_cli.config import SettingsContext @@ -533,19 +553,20 @@ def _create_agents(self) -> Agent: with SettingsContext(self._settings): for name in graph.build_order: config = graph.config_map[name] - sub_agents = [agent_map[sub] for sub in config.sub_agents] - agent_map[name] = self._build_agent( - config, service_map, sub_agents, root=name == graph.root_name + types = {sub: graph.config_map[sub] for sub in config.sub_agents} + agents[name] = self._build_agent( + config, service_map, root=name == graph.root_name, types=types ) logger.debug( "agent_created", name=name, - type="coordinator" if sub_agents else "leaf", - sub_agents=[a.name for a in sub_agents], + type="coordinator" if types else "leaf", + sub_agents=list(types), ) - root_agent = agent_map[graph.root_name] - logger.info("agents_created", root=root_agent.name, total=len(agent_map)) + self._agents = agents + root_agent = agents[graph.root_name] + logger.info("agents_created", root=root_agent.name, total=len(agents)) return root_agent def _init_plugins(self) -> list: @@ -614,16 +635,12 @@ def _plugin_chain( app's) run after every plugin, and only when none answered. So: - ``MainAgentPlugin`` first: it records the running agent, which the - summarizer reads, and makes its sub-agent run the active run. + summarizer reads. - ``CallLatencyPlugin``: each model call's answer marked with how long the call took (``workflow/adk/call_clock.py``), before any plugin could replace the answer; it returns nothing. - ``_init_plugins``: the permission gate (a denial is the call's answer), the tool-error answer, the raw log as the model answers. - - ``SubAgentOutcomePlugin``, when the tree delegates: a sub-agent's - final answer that a model refused or cut is said so (and marked) as - its parent reads it; after the raw log, which records the answer as - given, and it returns nothing, so every plugin after it still runs. - ``ForeignReasoningPlugin``: a model switch keeps the session, and no model is sent the thoughts another provider wrote (which it would refuse), before the request is measured. @@ -648,23 +665,82 @@ def _plugin_chain( - ``CallSentPlugin`` last: each call's clock starts as its request goes out, after every plugin that edits it. + A sub-agent type's runner has a chain of its own, in the same order + (``_agent_plugin_chain``). + Args: replies: The agents that reply to the user (``build.reply_agents``). cache: The app's context cache, or None. """ - from agentic_cli.workflow.adk.build import delegated_agents, own_after_tool_agents - from agentic_cli.workflow.adk.foreign_reasoning_plugin import ForeignReasoningPlugin + from agentic_cli.workflow.adk.build import own_after_tool_agents root = self._root_agent - kinds = {name: model.record.kind for name, model in self._resolved_models.items()} - clock = CallClock() - plugins: list = [ - MainAgentPlugin(self.agent_runs), CallLatencyPlugin(clock), *self._init_plugins() + return self._chain( + head=self._init_plugins(), + root=root.name, + replies=replies, + cache=cache, + skip_agents=own_after_tool_agents(root), + memory_index=self._memory_index_wanted(root.name), + ) + + def _agent_plugin_chain(self, agent: LlmAgent) -> list: + """The plugin chain of a sub-agent type's runner: the app's, made for a sub-agent. + + Its own instances, in the app's order, but for what a sub-agent is: + + - the permission gate writes no outside-content mark at a model + call (a run's mark reaches the conversation with its result, + ``adk/task_tool.py``), and the raw log is the app's own instance + (one buffer, which the manager drains, ``_report_raw_log``); + - ``SubAgentOutcomePlugin`` after the raw log: the run's final + answer that a model refused or cut is said so, and marked, as its + parent reads it; + - no memory index, and an overflow handler with no main agent: a + sub-agent's overflow, trimmed and retried once, then answers its + call with an error response (``CONTEXT_OVERFLOW``) that ends the + run failed. + + Every plugin's per-call state is kept by call or by invocation, and + each lets go of only what its own run left: two runs of one type + run on this one chain at once, and a provider may number their call + ids alike. + """ + from agentic_cli.workflow.adk.subagent_outcome_plugin import SubAgentOutcomePlugin + from agentic_cli.workflow.adk.tool_error_plugin import ToolErrorPlugin + + head: list = [ + PermissionPlugin(self._open_calls, marks=self._outside_marks), + ToolErrorPlugin(self._open_calls), ] - if delegated_agents(root): - from agentic_cli.workflow.adk.subagent_outcome_plugin import SubAgentOutcomePlugin + if self._llm_logging_plugin is not None: + head.append(self._llm_logging_plugin) + head.append(SubAgentOutcomePlugin()) + return self._chain( + head=head, + root=None, + replies=frozenset(), + cache=self._build.cache if self._build is not None else None, + skip_agents=frozenset(), + memory_index=False, + ) + + def _chain( + self, + *, + head: list, + root: str | None, + replies: frozenset[str], + cache: ContextCacheConfig | None, + skip_agents: frozenset[str], + memory_index: bool, + ) -> list: + """A plugin chain in the order ``_plugin_chain`` gives, from its ``head`` on.""" + from agentic_cli.workflow.adk.foreign_reasoning_plugin import ForeignReasoningPlugin - plugins.append(SubAgentOutcomePlugin()) + kinds = {name: model.record.kind for name, model in self._resolved_models.items()} + clock = CallClock() + plugins: list = [MainAgentPlugin(), CallLatencyPlugin(clock), *head] plugins.append(ForeignReasoningPlugin({name: kind.value for name, kind in kinds.items()})) if cache is not None: from agentic_cli.workflow.adk.context_cache_plugin import ContextCachePlugin @@ -673,17 +749,17 @@ def _plugin_chain( cap = ToolResultCapPlugin( self._settings.tool_result_max_chars, tool_output_dir(self._settings.app_name), - skip_agents=own_after_tool_agents(root), + skip_agents=skip_agents, ) - plugins.append(InterruptedCallsPlugin(self._open_calls, cap, runs=self.agent_runs)) + plugins.append(InterruptedCallsPlugin(self._open_calls, cap)) plugins.append(cap) - if self._memory_index_wanted(root.name): + if memory_index and root is not None: from agentic_cli.workflow.adk.memory_index_plugin import MemoryIndexPlugin - plugins.append(MemoryIndexPlugin(root=root.name, index_for=self._memory_index_now)) + plugins.append(MemoryIndexPlugin(root=root, index_for=self._memory_index_now)) fit_guard = FitGuardPlugin(self._budgets, kinds) plugins.append(OverflowPlugin( - root=root.name, + root=root, reply_agents=replies, budgets=self._budgets, kinds=kinds, @@ -741,8 +817,6 @@ async def _do_initialize(self) -> None: (``NoAfterTurnCompactionRunner``), and an event processor that knows which agents reply. """ - from agentic_cli.workflow.adk.build import delegated_agents - logger.info("initializing_services", app_name=self.app_name) # Create the session service (durable DatabaseSessionService by @@ -769,6 +843,23 @@ async def _do_initialize(self) -> None: events_compaction_config=build.compaction, ) self._runner = NoAfterTurnCompactionRunner(app=app, session_service=self._session_service) + # Each sub-agent type's runner, on child sessions of the same + # service: its own app (never listed as a conversation) and chain, + # the app's context cache, no summary (the fit guard trims it). + self._agent_runners = { + name: NoAfterTurnCompactionRunner( + app=App( + name=child_app(self.app_name), + root_agent=agent, + plugins=self._agent_plugin_chain(agent), + context_cache_config=build.cache, + events_compaction_config=None, + ), + session_service=self._session_service, + ) + for name, agent in self._agents.items() + if name != build.root.name + } # A call's usage names its agent's own model and context numbers (the # default model stands in for an agent without one); only the agents # that reply write the reply, another's text is a sub-agent's work. @@ -779,8 +870,6 @@ async def _do_initialize(self) -> None: models=build.models, budgets=self._budgets, reply_agents=build.reply_agents, - runs=self.agent_runs, - delegates=delegated_agents(build.root), kinds=self._agent_kinds(), ledgers=self._usage_ledgers, ) @@ -1139,11 +1228,9 @@ async def _answer_unsealed(self, ref: SessionRef) -> None: """Answer, from the record, the calls a stopped turn's seals missed; then clear it. ADK seals a stopped invocation's open calls pairing a result with a - call by id alone, so a call whose id a sub-agent's result used is + call by id alone, so a call whose id another branch's result used is left open (``interrupted_calls_plugin.unsealed``): answered here, a - finished one keeps its result and one at its prompt was not run. - Then each open run whose delegation returned ends with its result - (``_end_returned_runs``), before the record is cleared. Run + finished one keeps its result and one at its prompt was not run. Run shielded, so a second Ctrl+C neither loses the answers nor clears the record before they are read. Answers that cannot be written are given at the next turn (``left_open``), from no record. @@ -1152,10 +1239,7 @@ async def _answer_unsealed(self, ref: SessionRef) -> None: session = await self._session_service.get_session( app_name=ref.app_name, user_id=ref.user_id, session_id=ref.session_id, ) - answers = ( - unsealed(session.events, self._open_calls, self.agent_runs) - if session is not None else [] - ) + answers = unsealed(session.events, self._open_calls) if session is not None else [] for event in answers: await self._session_service.append_event(session, event) if answers: @@ -1167,28 +1251,8 @@ async def _answer_unsealed(self, ref: SessionRef) -> None: "unsealed_calls_not_answered", error_type=type(error).__name__, exc_info=error, ) finally: - self._end_returned_runs(ref) self._open_calls.clear(ref) - def _end_returned_runs(self, ref: SessionRef) -> None: - """End each open run whose delegation returned, from the record, before it is cleared. - - ADK hands a model step's parallel function responses back in one - event, after the last one returns, so a delegation that finished - beside a slower one has no result event when the turn is stopped or - fails first. Its result is in the record, under its parent's run: - its run ends as that result says (``end_returned_run``: refused or - partial from its outcome mark), and not ``interrupted`` with the - runs the turn leaves open (the base's ``_turn``). Called after - ``unsealed``, which names each branch's run while it is open. - """ - for record in self.agent_runs.records(ref): - if record.status != RUN_STARTED or not record.call_id: - continue - response = returned(self._open_calls, record.call_id, record.ref.parent_run) - if response is not None: - self._event_processor.end_returned_run(record.ref, record.call_id, response) - def _seed_outside_content(self, ref: SessionRef, session: Session) -> dict[str, Any]: """Seed the marks from the session's state; the state delta a turn writes. @@ -1343,8 +1407,7 @@ async def _run_and_stream( # id alone): it is answered here, from the record, before the # record is cleared. One a failure left open is answered at # the next turn (left_open) as interrupted: the state it - # changed, which ADK stores with its result, is gone. Either - # way a delegation that returned ends its run with its result. + # changed, which ADK stores with its result, is gone. ref = self.session_ref(session_id, user_id) if aborted.is_set(): # Should those answers not be written, left_open gives @@ -1352,7 +1415,6 @@ async def _run_and_stream( self._open_calls.cancelled(ref) await asyncio.shield(self._answer_unsealed(ref)) else: - self._end_returned_runs(ref) self._open_calls.clear(ref) # Drain any remaining LLM events after processing completes @@ -1394,6 +1456,118 @@ async def _workflow_events( async for workflow_event in self._event_processor.process_event(adk_event, session_id): yield workflow_event + async def _run_agent(self, run: AgentRun) -> RunAnswer: + """Run one sub-agent run on its type's runner, on a child session (the base's hook). + + In the run's own task (``agents/delegate.py``): the child session + (``child_app``, ``child_session_id``: the conversation's id and the + run's instance) is made with the shared state the run starts from + and, for an inheriting run, the conversation's events + (``task_tool.inherited_events``), then the runner runs the task + message on it as one invocation. Its events go to the turn's live + events as they are made, through a processor made for the run, and + so do the raw log's records of its calls. As a turn's runner is, it + is stopped with its abort signal set first, so ADK seals the calls + it leaves open, in its child session, before the cancel goes on. + + Returns: + Its last answer with text, that answer's outcome mark, the shared + keys it changed (read back from its child session's state); or, + for a reply that is no answer, the error it is. + + Raises: + RunFailed: Its request no longer fits its model's window + (the overflow handler's answer). + ValueError: Its child session's id is longer than ADK stores. + Exception: Its model call failed: the provider's error, out of + ADK's plugin wrapper (``_plugin_cause``). + """ + conversation = run.conversation + if conversation is None: + raise RuntimeError("A sub-agent run runs in a conversation's turn.") + app = child_app(self.app_name) + session_id = child_session_id(conversation.session_id, run.ref.instance) + await self._child_session(app, conversation.user_id, session_id, run) + build = self._build + processor = ADKEventProcessor( + model=self.model, + root=build.root.name, + models=build.models, + budgets=self._budgets, + reply_agents=build.reply_agents, + kinds=self._agent_kinds(), + ledgers=self._usage_ledgers, + run=run.ref, + ) + aborted = asyncio.Event() + stream = self._agent_runners[run.ref.agent].run_async( + user_id=conversation.user_id, + session_id=session_id, + new_message=types.Content(role="user", parts=[types.Part.from_text(text=run.message)]), + run_config=self._run_config(), + abort_signal=aborted, + ) + try: + merging = live_events.merged(stream, live_events.LiveEvents(), on_stop=aborted.set) + async with contextlib.aclosing(merging) as items: + async for item in items: + self._report_raw_log() + async for event in processor.process_event(item, conversation.session_id): + live_events.report(event) + except RuntimeError as error: + cause = _plugin_cause(error) + if cause is error: + raise + raise cause from None + finally: + self._report_raw_log() + if processor.failure is not None: + error, code = processor.failure + if code == OVERFLOW_ERROR_CODE: + raise RunFailed(error, code=code) + return RunAnswer(text=processor.answer, error=error) + ended = await self._session_service.get_session( + app_name=app, user_id=conversation.user_id, session_id=session_id, + config=GetSessionConfig(num_recent_events=0), + ) + state = ended.state if ended is not None else {} + return RunAnswer( + text=processor.answer, outcome=processor.outcome, state=_changed(state, run.state) + ) + + async def _child_session( + self, app: str, user_id: str, session_id: str, run: AgentRun + ) -> None: + """Make ``run``'s child session: the state it starts from, and an inheriting run's history. + + An instance's session left by an earlier process (instances are + numbered per manager, so a new one numbers ``researcher-1`` again) + is replaced: nothing reads it. + """ + service = self._session_service + stale = await service.get_session( + app_name=app, user_id=user_id, session_id=session_id, + config=GetSessionConfig(num_recent_events=0), + ) + if stale is not None: + await service.delete_session(app_name=app, user_id=user_id, session_id=session_id) + session = await service.create_session( + app_name=app, user_id=user_id, session_id=session_id, state=dict(run.state) + ) + for event in run.history or (): + await service.append_event(session, event) + + def _report_raw_log(self) -> None: + """Report what the raw LLM log holds (a sub-agent run's calls) to the turn's live events. + + One log serves every runner, so its records go out as a sub-agent + run's events do, while the conversation's runner waits on the run. + """ + if self._llm_logging_plugin is None: + return + for record in self._llm_logging_plugin.drain_events(): + live_events.report(record) + async def _conversation_exists(self, ref: SessionRef) -> bool: """Whether ``ref``'s ADK session is stored, with events or none. @@ -1656,3 +1830,39 @@ async def recent_messages( {"role": "user" if role == "user" else "assistant", "content": text} ) return out[-limit:] + + +def _tool_names(tools: list[Any]) -> set[str]: + """The names an agent's assembled tools are offered by: a function tool's + ``__name__``, an ADK tool's ``name``, a skill toolset's tools' names.""" + from google.adk.tools import BaseTool + from google.adk.tools.skill_toolset import SkillToolset + + names: set[str] = set() + for tool in tools: + if isinstance(tool, SkillToolset): + names.update(skill_tool.name for skill_tool in tool._tools) + elif isinstance(tool, BaseTool): + names.add(tool.name) + elif callable(tool): + names.add(getattr(tool, "__name__", "")) + return names + + +def _changed(state: "Mapping[str, Any]", start: "Mapping[str, Any]") -> dict[str, Any]: + """The shared keys ``state`` holds that differ from what a run started from. + + Deep Agents' ``task`` rule (``deepagents.middleware.subagents._is_unchanged``, + private, copied, as the Deep Agents manager's ``_changed`` copies it): a + key returned exactly as it was received is no change; ``is True`` takes + an ambiguous comparison (an array's) as one. + """ + changed: dict[str, Any] = {} + for key in SHARED_KEYS: + if key not in state: + continue + value = state[key] + if key in start and (value is start[key] or (value == start[key]) is True): + continue + changed[key] = value + return changed diff --git a/src/agentic_cli/workflow/adk/overflow_plugin.py b/src/agentic_cli/workflow/adk/overflow_plugin.py index 0324dbdd..a4da13dc 100644 --- a/src/agentic_cli/workflow/adk/overflow_plugin.py +++ b/src/agentic_cli/workflow/adk/overflow_plugin.py @@ -13,9 +13,10 @@ summary that fails is one warning a turn, as one before a model call is. The memory index that opens the request stays first in the retry, with the summary, and both are folded into its first user text. -- **A sub-agent** never summarizes the shared session; nor does the main - agent when the summary covers nothing the request holds. The request is - then retried with its oldest whole turns left out down to half the budget +- **A sub-agent** (on its own runner, whose chain has this plugin without a + main agent) never summarizes; nor does the main agent when the summary + covers nothing the request holds. The request is then retried with its + oldest whole turns left out down to half the budget (``fit_guard_plugin.drop_turns``). - The retry is built from the request as the fit guard saw it (``FitGuardPlugin.request_as_seen``, this call's own copy, never a parallel @@ -39,12 +40,12 @@ which ADK would store as its reply; ``ADKEventProcessor`` turns it into the turn's one ``ERROR``. Only the main agent summarizes: an agent it transferred to is retried without the oldest turns. A -sub-agent answers its coordinator with text, "I could not do this task: …", -which is how a coordinator hears from it (its reply lives in its own branch -and reaches the coordinator as the tool's result), and the user is told -once, as a recoverable ``ERROR`` reported live; that answer carries no -``error_code``, which would show the user a second warning. Any other error -of the retry propagates. +sub-agent's call is answered with an error response too, ``CONTEXT_OVERFLOW`` +and the sub-agent's warning (``context.subagent_overflow_message``): its +run's event processor keeps it as the run's failure, the run ends ``failed`` +with it, and its parent reads it in the run's envelope, as on Deep Agents; +the user is warned once, by the framework's delegation +(``agents/delegate.py``). Any other error of the retry propagates. An overflow an OpenAI Responses model reports in its answer (``status: failed``) instead of raising reaches ``after_model_callback`` as an error @@ -109,7 +110,8 @@ class OverflowPlugin(BasePlugin): """Answers a context overflow (see the module docstring). Args: - root: The main agent's name. + root: The main agent's name; None in a sub-agent type's chain, which + has no main agent. reply_agents: The agents that reply to the user besides the root (a chat-mode agent it transfers to): their overflow is the turn's clear error too. @@ -127,7 +129,7 @@ class OverflowPlugin(BasePlugin): def __init__( self, *, - root: str, + root: str | None, reply_agents: Collection[str] = (), budgets: Mapping[str, "ContextBudget"], kinds: Mapping[str, "ProviderKind"], @@ -138,7 +140,7 @@ def __init__( super().__init__(name=OVERFLOW_PLUGIN) self._root = root # The agents whose overflow is the turn's clear error. - self._replying = frozenset({root, *reply_agents}) + self._replying = frozenset({*reply_agents, *([root] if root is not None else [])}) self._budgets = dict(budgets) self._kinds = dict(kinds) self._models = dict(models) @@ -238,22 +240,15 @@ def _as_seen( return llm_request.model_copy(update=update) def _does_not_fit(self, agent: str) -> LlmResponse: - """The answer once nothing more can make the request fit.""" + """The answer once nothing more can make the request fit: an error + response, the turn's clear text for an agent that replies, the + sub-agent's warning for any other.""" model = self._models.get(agent, "the model") - if agent in self._replying: - return LlmResponse( - error_code=OVERFLOW_ERROR_CODE, error_message=overflow_message(model) - ) - warning = WorkflowEvent.error( - subagent_overflow_message(agent, model), - error_code=OVERFLOW_ERROR_CODE, - recoverable=True, + message = ( + overflow_message(model) if agent in self._replying + else subagent_overflow_message(agent, model) ) - warning.metadata["agent"] = agent - live_events.report(warning) - return LlmResponse(content=types.Content(role="model", parts=[types.Part.from_text( - text=f"I could not do this task: the request no longer fits {model}'s context window." - )])) + return LlmResponse(error_code=OVERFLOW_ERROR_CODE, error_message=message) def _with_summary(contents: list[types.Content], summary: str) -> list[types.Content]: diff --git a/src/agentic_cli/workflow/adk/permission_plugin.py b/src/agentic_cli/workflow/adk/permission_plugin.py index 623eaac5..adc42de2 100644 --- a/src/agentic_cli/workflow/adk/permission_plugin.py +++ b/src/agentic_cli/workflow/adk/permission_plugin.py @@ -13,9 +13,9 @@ class name, and never equality. own text, as Deep Agents' gate does. 1. Resolve the definition bound to this exact object. Framework-issued tools — registered callables, service-bound factory variants, and the native ADK - tool objects the framework constructs (skill tools, and the delegation tool - ADK builds for each sub-agent the framework built, ``adk/delegation.py``) — - are bound at their construction site. + tool objects the framework constructs (skill tools, and a delegating + agent's ``task``, ``adk/task_tool.py::TaskTool``) — are bound at their + construction site. 2. Failing that, unwrap ``.func`` only for ADK's own function-tool types (:data:`_TRUSTED_FUNCTION_TOOL_TYPES`), whose contract is to invoke exactly that callable, and resolve the callable by identity. @@ -68,7 +68,7 @@ class name, and never equality. # ADK auto-injects ``transfer_to_agent`` into an agent that can transfer to # another: a native ADK YAML app's (agents built from configs delegate -# instead, ``adk/delegation.py``). It's an internal routing primitive, not an +# instead, ``adk/task_tool.py``). It's an internal routing primitive, not an # external side effect, so register it with EXEMPT so the plugin lets it # through. try: @@ -233,7 +233,10 @@ class PermissionPlugin(BasePlugin): open_calls: The manager's record of its calls, marked while a call waits at its prompt: a cancel there means it was not run. marks: The manager's record of each conversation's mark. - root: The root agent's name, whose session state carries the mark. + root: The root agent's name, whose session state carries the mark; + None in a sub-agent type's chain, where no model call writes it + (a run's mark reaches the conversation's state with its result, + ``adk/task_tool.py``). reply_agents: The agents that reply to the user besides the root (a chat-mode agent it transfers to holds the conversation): their model calls write the mark into the session state too. diff --git a/src/agentic_cli/workflow/adk/plugins.py b/src/agentic_cli/workflow/adk/plugins.py index 7cd4affc..f29f7857 100644 --- a/src/agentic_cli/workflow/adk/plugins.py +++ b/src/agentic_cli/workflow/adk/plugins.py @@ -44,8 +44,9 @@ class LLMLoggingPlugin(BasePlugin): Each record names the model of the agent that made the call (``models``), else the request's own model or ``model_name``; that agent (``metadata["agent"]``); and, for a sub-agent's call, its run - (``WorkflowEvent.run``, the active run its ``MainAgentPlugin`` set, - which the log writes as ``run``), as Deep Agents' records do. A usage + (``WorkflowEvent.run``, the active run the framework's delegation set + for the run's task, ``agents/delegate.py``, which the log writes as + ``run``), as Deep Agents' records do. A usage record counts as the stream's ``LLM_USAGE`` does (``workflow/usage.py``'s ``adk_usage_event``, by the agent's model's provider kind, ``kinds``: the thinking in the output, a cache write in @@ -59,7 +60,11 @@ class LLMLoggingPlugin(BasePlugin): (``on_model_error_callback``): a plugin after this one may answer the error (the overflow handler), and that answer reaches ``after_model_callback`` like any response, timed. Each run lets go of - what another invocation left. + what it left as it ends, its own only. + + One instance serves the conversation's runner and every sub-agent + type's (``GoogleADKWorkflowManager._agent_plugin_chain``): the manager + drains its buffer as a turn's events and a sub-agent run's go out. Attributes: model_name: Default model name, for an agent ``models`` does not hold @@ -252,16 +257,21 @@ async def on_model_error_callback( The overflow handler answers a call refused as too long, and ADK hands its answer to every plugin's ``after_model_callback`` with the call's ``EventActions``, so the answer is timed and lets the clock - go. An error nobody answers leaves its clock to the next run's - ``before_run_callback``. + go. An error nobody answers leaves its clock until its run ends + (``after_run_callback``, ``on_run_error_callback``). """ return None - async def before_run_callback(self, *, invocation_context: "InvocationContext") -> None: - # What another invocation left (turns run one at a time): a call - # whose error nobody answered, and one cancelled mid-request, which - # before google-adk 2.14 fired no callback. - self.clock.keep_only(invocation_context.invocation_id) + async def after_run_callback(self, *, invocation_context: "InvocationContext") -> None: + # What the run left: a call whose error nobody answered, and one + # cancelled mid-request, which before google-adk 2.14 fired no callback. + self.clock.forget(invocation_context.invocation_id) + return None + + async def on_run_error_callback( + self, *, invocation_context: "InvocationContext", error: Exception + ) -> None: + self.clock.forget(invocation_context.invocation_id) return None # ------------------------------------------------------------------ diff --git a/src/agentic_cli/workflow/adk/sessions.py b/src/agentic_cli/workflow/adk/sessions.py index 35793b1b..bb39648b 100644 --- a/src/agentic_cli/workflow/adk/sessions.py +++ b/src/agentic_cli/workflow/adk/sessions.py @@ -24,6 +24,13 @@ ``delete_session``) and its reader's alike: ``open_sessions`` opens the service of a store from the settings, without the manager, for ``workflow/session_readers.py``. + +A sub-agent instance's transcript is a child session in the same session +service: app ``child_app(app_name)`` (``<app>--agents``), session +``child_session_id(conversation, instance)`` (``<conversation>/<instance>``), +the conversation's user. Under its own app name it never lists as a +conversation. ADK keys a session by at most ``MAX_KEY`` characters, so a +longer id is refused before anything is stored. """ from __future__ import annotations @@ -49,6 +56,31 @@ #: How many turns the user ran in it. TURNS_KEY = "agentic_cli.turns" +#: What a child session's app name adds to the conversation's app name. +CHILD_APP_SUFFIX = "--agents" +#: The longest app name or session id ADK stores (``sessions/schemas/shared.py``). +MAX_KEY = 128 + + +def child_app(app_name: str) -> str: + """The app the sub-agent instances of ``app_name``'s conversations are stored under.""" + return f"{app_name}{CHILD_APP_SUFFIX}" + + +def child_session_id(conversation: str, instance: str) -> str: + """The session that holds ``instance``'s transcript in the conversation ``conversation``. + + Raises: + ValueError: The id is longer than ADK stores (``MAX_KEY``). + """ + session_id = f"{conversation}/{instance}" + if len(session_id) > MAX_KEY: + raise ValueError( + f"The session of sub-agent {instance} would be {len(session_id)} characters long; " + f"ADK stores at most {MAX_KEY}." + ) + return session_id + def typed_prompts(events: list["Event"]) -> list[str]: """The texts the user typed, oldest first.""" diff --git a/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py b/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py index addcca53..2fe02abe 100644 --- a/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py +++ b/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py @@ -1,11 +1,11 @@ """A sub-agent's refused or cut answer, said so to its parent (``workflow/agents/outcome.py``). -ADK hands a sub-agent's last answer to its parent as the delegation's result, -whatever stopped it: a refusal reached the parent as an empty result, and an -answer cut at the output limit as a complete one. ``SubAgentOutcomePlugin`` -looks at each final answer of a sub-agent run (``get_active_run()`` is set: -``MainAgentPlugin`` makes the run active as the agent starts) and reads how it -stopped from what ADK's adapters give it: +A sub-agent run's last answer is its result, whatever stopped it: a refusal +would reach its parent as an empty result, and an answer cut at the output +limit as a complete one. ``SubAgentOutcomePlugin``, in each sub-agent type's +plugin chain, looks at each final answer of a sub-agent run +(``get_active_run()`` is set: the run's own task, ``agents/delegate.py``) and +reads how it stopped from what ADK's adapters give it: - its ``finish_reason``: Claude's ``refusal`` arrives as ``SAFETY`` and its ``max_tokens`` as ``MAX_TOKENS``, a Chat Completions ``content_filter`` as @@ -22,9 +22,9 @@ It rewrites one a model refused into the refusal notice (that text its explanation), and one cut at the output limit into its text followed by the cut-off note, its thoughts kept. It marks the answer with its outcome -(``custom_metadata[OUTCOME_KEY]``), which the event carries, so the event -processor ends the run ``refused``, or ``completed`` and ``partial`` with one -warning. +(``custom_metadata[OUTCOME_KEY]``), which the event carries, so the run's +event processor keeps it and the run ends ``refused``, or ``completed`` and +``partial`` with one warning. It changes the response in place and returns None, as ``ForeignReasoningPlugin`` does, so every plugin after it still runs; it sits diff --git a/src/agentic_cli/workflow/adk/task_tool.py b/src/agentic_cli/workflow/adk/task_tool.py new file mode 100644 index 00000000..1616f93d --- /dev/null +++ b/src/agentic_cli/workflow/adk/task_tool.py @@ -0,0 +1,133 @@ +"""ADK's ``task`` tool: the framework's delegation, as an ADK tool. + +A delegating agent built from configs gets one ``TaskTool``, whatever its +sub-agents (its sub-agents are no ADK ``sub_agents``: each runs on a runner +of its own, ``GoogleADKWorkflowManager._run_agent``). Its declaration is the +framework's (``agents/brief.py``: ``task_parameters``, ``task_description``), +as Deep Agents' ``task``'s is, and a call hands its arguments, as the model +wrote them, to the manager's ``Delegations`` (``agents/delegate.py``): it +reads the brief, runs the sub-agent and returns the result envelope. + +The call's result is the envelope as JSON text, which ADK stores as +``{"result": <text>}``: every model adapter sends that text whole (ADK's +OpenAI Responses adapter sends only a dict's ``result``, and would lose the +rest of an envelope given as a dict), as Deep Agents' ``ToolMessage`` holds +it. The text is written unescaped (``ensure_ascii=False``: an escaped +non-Latin answer is six times as long), and a long one is cut by the tool +result cap as the dict it holds (``workflow/tool_output.py``), so the parent +reads JSON still. + +The shared state is the conversation's plan, tasks and outside-content mark +(``SHARED_KEYS``): a run starts from the caller's (``tool_context.state``), +and the keys it changes are written back there, so they ride on the call's +function response into the conversation's state. An inheriting type reads +the conversation (``inherited_events``). + +The framework builds the tool, so it binds it to the ``task`` declaration +(``tools/_core/delegation.py``) as it is made: the permission gate knows it +by identity, and lets it through as the exempt declaration says. Only an +exact ``TaskTool`` is bound: a subclass may run something else, and the gate +denies it, as it denies any tool the framework did not issue. What it +relies on of ADK's ``BaseTool`` (its constructor's ``name`` and +``description``, ``_get_declaration``, ``run_async(args=, tool_context=)``) +is contract-tested. +""" + +from __future__ import annotations + +import json +from collections.abc import Callable, Mapping, Sequence +from typing import TYPE_CHECKING, Any + +from google.adk.events import Event, EventActions +from google.adk.tools import BaseTool +from google.genai import types + +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 task_description, task_parameters +from agentic_cli.workflow.agents.delegate import DelegationRequest +from agentic_cli.workflow.outside_content import OUTSIDE_CONTENT_KEY +from agentic_cli.workflow.sessions import get_active_run + +if TYPE_CHECKING: + from google.adk.tools.tool_context import ToolContext + + from agentic_cli.workflow.agents.delegate import Delegations + from agentic_cli.workflow.config import AgentConfig + +#: The state a run shares with its caller: the plan and the tasks (the state +#: tools', ``tools/adk/state_tools.py``) and the outside-content mark. +SHARED_KEYS = ("plan", "tasks", OUTSIDE_CONTENT_KEY) + + +class TaskTool(BaseTool): + """A delegating agent's ``task``, which starts a run of one of its sub-agents. + + Args: + agent: The delegating agent's name. + types: Its sub-agents, by name: what ``agent_type`` may name. + delegations: The manager's delegations, asked for at each call. + """ + + def __init__( + self, + agent: str, + types: Mapping[str, AgentConfig], + delegations: Callable[[], Delegations], + ) -> None: + super().__init__(name=TASK_TOOL, description=task_description(types, delegations().policy)) + self._agent = agent + self._parameters = task_parameters(types) + self._delegations = delegations + if type(self) is TaskTool: + bind_tool_identity(self, get_registry().get(TASK_TOOL)) + + def _get_declaration(self) -> types.FunctionDeclaration: + return types.FunctionDeclaration( + name=self.name, + description=self.description, + parameters_json_schema=self._parameters, + ) + + async def run_async(self, *, args: dict[str, Any], tool_context: "ToolContext") -> str: + state = tool_context.state + session = tool_context.session + delegated = await self._delegations().delegate(DelegationRequest( + caller=get_active_run(), + caller_agent=self._agent, + call_id=tool_context.function_call_id or "", + arguments=args, + state={key: state[key] for key in SHARED_KEYS if key in state}, + history=lambda: inherited_events(session.events), + )) + for key, value in delegated.state.items(): + state[key] = value + return json.dumps(delegated.result, ensure_ascii=False) + + +def inherited_events(events: Sequence[Event]) -> list[Event]: + """The conversation as an inheriting run reads it: copies of its root-visible events. + + Each event the conversation's own agents and user wrote (no branch) that + shows anything (content, or a summary: a compaction, which keeps its + range), with its author, invocation and time, so ADK shows the run the + conversation as it shows any other agent's: the user's turns, the + other agents' turns quoted as context, without their thoughts, a summary + in place of what it covers. The copies change no state. + """ + copied: list[Event] = [] + for event in events: + compaction = event.actions.compaction if event.actions else None + if event.branch or (event.content is None and compaction is None): + continue + copied.append(Event( + invocation_id=event.invocation_id, + author=event.author, + timestamp=event.timestamp, + content=event.content.model_copy(deep=True) if event.content is not None else None, + actions=EventActions( + compaction=compaction.model_copy(deep=True) if compaction is not None else None + ), + )) + return copied diff --git a/src/agentic_cli/workflow/agents/brief.py b/src/agentic_cli/workflow/agents/brief.py index 09151723..d86a5083 100644 --- a/src/agentic_cli/workflow/agents/brief.py +++ b/src/agentic_cli/workflow/agents/brief.py @@ -71,9 +71,8 @@ #: 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``). +#: inheriting type's task message with it, on both backends: the run reads +#: its parent's conversation before that message. 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: " diff --git a/src/agentic_cli/workflow/agents/delegate.py b/src/agentic_cli/workflow/agents/delegate.py new file mode 100644 index 00000000..139865d3 --- /dev/null +++ b/src/agentic_cli/workflow/agents/delegate.py @@ -0,0 +1,369 @@ +"""A delegation: the one place a sub-agent run starts, ends and is decided. + +A parent's ``task`` call reaches ``Delegations.delegate`` from its backend's +task tool (ADK's ``adk/task_tool.py::TaskTool``, Deep Agents' +``deepagents/task_tool.py::build_task_tool``) as a ``DelegationRequest``. +``delegate``: + +- reads the brief against the caller's own sub-agents (``brief.read_brief``): + a brief that cannot start a run is the call's error result, and nothing + else happens (no run, no record, no event); +- names the run (``AgentRuns.run_for``: its instance ``<type>-<n>`` and its run + ``<instance>#1``, under the caller's run) and reports its ``AGENT_RUN`` + ``started``: the title, the call, the brief, who started it, ``blocking``; +- runs it through the backend's hook (``BaseWorkflowManager._run_agent``) in + an asyncio task of its own, in which the run is the active run + (``get_active_run``) and no tool call is (``get_active_tool_call``): the + run's model calls, tool calls, permission checks and questions are its + own, never its caller's ``task`` call's; +- ends the run as the hook's answer says, reports the end (and a cut run's + or a failed run's one warning after it), and returns the result envelope + (``envelope.envelope``) with the shared state the run changed. + +Each ``AGENT_RUN`` is recorded (``AgentRuns.observe``) as it is made and +reported to the turn's live events, so it reaches the turn's stream while +the run works. A run ends: + +- ``failed`` when the hook raised (not a cancel) or answered an error: the + parent's envelope carries the reason (the provider's, for a failed model + call), and the user is warned once, a recoverable ``ERROR``: + ``<instance> failed: <reason>``, or the hook's own words (``RunFailed``: a + context overflow, ``context.subagent_overflow_message``); +- ``refused`` when a model refused its last answer (``agents/outcome.py``); +- ``completed`` otherwise, ``partial`` for an answer cut at its output + limit, followed by the cut's one warning (``outcome.cut_off_warning``); +- ``interrupted`` when its caller's task is cancelled (Ctrl+C stops the + turn): the cancel goes on once the run has stopped. A run's own task + cancelled while its caller goes on ends ``interrupted`` too, and its + caller reads that envelope. +""" + +from __future__ import annotations + +import asyncio +from collections.abc import Awaitable, Callable, Mapping +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Any + +from agentic_cli.constants import truncate +from agentic_cli.logging import Loggers +from agentic_cli.workflow import live_events +from agentic_cli.workflow.agents.brief import BriefError, read_brief, task_message +from agentic_cli.workflow.agents.envelope import INTERRUPTED_ERROR, envelope +from agentic_cli.workflow.agents.outcome import CUT, REFUSAL_ERROR, REFUSED, cut_off_warning +from agentic_cli.workflow.agents.runs import ( + RUN_COMPLETED, + RUN_FAILED, + RUN_INTERRUPTED, + RUN_REFUSED, + RUN_STARTED, + AgentRuns, + result_head, + run_title, +) +from agentic_cli.workflow.events import WorkflowEvent +from agentic_cli.workflow.sessions import ( + RunRef, + SessionRef, + get_active_turn, + set_active_run, + set_active_tool_call, +) + +if TYPE_CHECKING: + from agentic_cli.workflow.agents.policy import SubAgentPolicy + from agentic_cli.workflow.config import AgentConfig + from agentic_cli.workflow.usage import UsageLedgers + +logger = Loggers.workflow() + +#: How a run its parent's ``task`` call starts runs: the parent waits for it. +BLOCKING = "blocking" +#: The longest error text a failed run's log line carries. +_MAX_LOGGED_ERROR = 500 + + +def started_by(caller: RunRef | None) -> str: + """Who starts a run its parent delegated: ``agent:<the caller's instance>``. + + ``agent:root`` for the root's own calls (no run, or ``root_run``). + """ + return f"agent:{caller.instance if caller is not None else 'root'}" + + +@dataclass(frozen=True) +class DelegationRequest: + """A ``task`` call, as its backend's task tool hands it over. + + Attributes: + caller: The run that made the call (``get_active_run()`` at the + call): None, or ``root_run``, for the root. + caller_agent: The calling agent's type name. + call_id: The caller's ``task`` call. + arguments: ``task``'s arguments as the model wrote them. + state: The shared state at the call (the plan, the tasks, the + outside-content mark), which the run starts from. + history: Called once, only when the chosen type inherits its + parent's conversation: that conversation, as the backend reads it. + """ + + caller: RunRef | None + caller_agent: str + call_id: str + arguments: Mapping[str, Any] + state: Mapping[str, Any] = field(default_factory=dict) + history: Callable[[], Any] | None = None + + +@dataclass(frozen=True) +class AgentRun: + """What the backend hook is asked to run. + + Attributes: + ref: The run. + config: Its agent type. + message: The task message (``brief.task_message``): the run's first + user message. + conversation: The conversation it runs in. + state: The shared state it starts from. + history: An inheriting run's parent conversation, as the backend + reads it; None for a fresh one. + """ + + ref: RunRef + config: AgentConfig + message: str + conversation: SessionRef | None + state: Mapping[str, Any] + history: Any = None + + +@dataclass(frozen=True) +class RunAnswer: + """What the backend hook returns for a run it ran to its end. + + Attributes: + text: Its last non-empty answer (``""`` for none). + outcome: How that answer ended (``agents/outcome.py``: ``REFUSED``, + ``CUT``), None when it ended as an answer should. + error: Why it failed, when it did; None when it answered. + state: The shared state keys it changed, with their new values. + """ + + text: str = "" + outcome: str | None = None + error: str | None = None + state: Mapping[str, Any] = field(default_factory=dict) + + +@dataclass(frozen=True) +class Delegated: + """What the backend's task tool gets back for a ``task`` call. + + Attributes: + result: The envelope, or the error result of a call that started no run. + state: What the run changed of the shared state; empty when none started. + run: The run, None when no run started. + """ + + result: dict[str, Any] + state: Mapping[str, Any] + run: RunRef | None + + +RunHook = Callable[[AgentRun], Awaitable[RunAnswer]] + + +class RunFailed(Exception): + """A run's failure in its backend's words: what its parent and its user read. + + A hook raises it for a failure it has words for (a sub-agent's context + overflow, ``context.subagent_overflow_message``): its text is the + envelope's ``error`` and the user's warning, as given, and ``code`` that + warning's error code. Any other exception a hook lets out fails the run + with its text (its type's name, for none), warned of as ``<instance> + failed: <reason>`` with the type's name as its code. + """ + + def __init__(self, error: str, *, code: str) -> None: + super().__init__(error) + self.code = code + + +class Delegations: + """A manager's delegations: the one place a sub-agent run starts, ends and is decided. + + Args: + runs: The manager's runs, which name and record each run. + policy: How the manager's sub-agents run. + types: Every agent type, by name: a caller may start its own + sub-agents (``AgentConfig.sub_agents``). + hook: Runs one run (``BaseWorkflowManager._run_agent``). + ledgers: The manager's usage ledgers: a run's end carries what it + used, by model. None: an end carries no usage. + """ + + def __init__( + self, + *, + runs: AgentRuns, + policy: SubAgentPolicy, + types: Mapping[str, AgentConfig], + hook: RunHook, + ledgers: UsageLedgers | None = None, + ) -> None: + self._runs = runs + self.policy = policy + self._types = dict(types) + self._hook = hook + self._ledgers = ledgers + + def sub_agents(self, agent: str) -> dict[str, AgentConfig]: + """The types ``agent`` may start, by name, in its ``sub_agents``' order.""" + caller = self._types.get(agent) + names = caller.sub_agents if caller is not None else () + return {name: self._types[name] for name in names if name in self._types} + + async def delegate(self, request: DelegationRequest) -> Delegated: + """Run the sub-agent ``request`` asks for, to its end; its envelope. + + A brief that cannot start a run is the error result, and nothing + else happens. A cancel of the caller's task (the turn's) ends the run + ``interrupted`` once it has stopped, and goes on. + """ + try: + config, brief = read_brief(request.arguments, self.sub_agents(request.caller_agent)) + except BriefError as error: + return Delegated(result={"success": False, "error": str(error)}, state={}, run=None) + conversation = get_active_turn() + ref = self._runs.run_for(conversation, request.caller, request.call_id, config.name) + self._emit(WorkflowEvent.agent_run( + ref, RUN_STARTED, call_id=request.call_id, title=run_title(brief.title), + brief=brief.fields(), started_by=started_by(request.caller), mode=BLOCKING, + )) + inner = asyncio.create_task( + self._in_run(ref, config, brief, conversation, request), name=f"agent run {ref.run}" + ) + try: + answer = await inner + except asyncio.CancelledError: + self._end(ref, request.call_id, RUN_INTERRUPTED, error=INTERRUPTED_ERROR) + task = asyncio.current_task() + if task is not None and task.cancelling(): + raise + # The run's own task was stopped, not its caller's: the caller + # reads that it ended. + return Delegated( + result=envelope(ref, RUN_INTERRUPTED, error=INTERRUPTED_ERROR), state={}, run=ref + ) + except RunFailed as error: + return self._failed(ref, request.call_id, str(error), warning=str(error), code=error.code) + except Exception as error: # noqa: BLE001 - a sub-agent's failure is its parent's to read + reason = str(error) or type(error).__name__ + logger.debug("subagent_failed", run=ref.run, exc_info=error) + return self._failed( + ref, request.call_id, reason, + warning=f"{ref.instance} failed: {reason}", code=type(error).__name__, + ) + if answer.error is not None: + return self._failed( + ref, request.call_id, answer.error, warning=f"{ref.instance} failed: {answer.error}", + code=None, text=answer.text, state=answer.state, + ) + if answer.outcome == REFUSED: + self._end(ref, request.call_id, RUN_REFUSED, text=answer.text, error=REFUSAL_ERROR) + result = envelope(ref, RUN_REFUSED, result=answer.text, error=REFUSAL_ERROR) + else: + partial = answer.outcome == CUT + end = self._end(ref, request.call_id, RUN_COMPLETED, text=answer.text, partial=partial) + warning = cut_off_warning(end) + if warning is not None: + self._report(warning) + result = envelope(ref, RUN_COMPLETED, result=answer.text, partial=partial) + return Delegated(result=result, state=dict(answer.state), run=ref) + + async def _in_run( + self, + ref: RunRef, + config: AgentConfig, + brief: Any, + conversation: SessionRef | None, + request: DelegationRequest, + ) -> RunAnswer: + """The run, in its own task: the active run, and no tool call active. + + The task's context is a copy of its caller's, so what this sets stays + here. An inheriting type's history is read here, once. + """ + set_active_run(ref) + set_active_tool_call(None) + history = ( + request.history() + if config.inherit_context and request.history is not None else None + ) + return await self._hook(AgentRun( + ref=ref, + config=config, + message=task_message(brief, inherit=config.inherit_context), + conversation=conversation, + state=dict(request.state), + history=history, + )) + + def _failed( + self, + ref: RunRef, + call_id: str, + error: str, + *, + warning: str, + code: str | None, + text: str = "", + state: Mapping[str, Any] | None = None, + ) -> Delegated: + """End ``ref``'s run failed with ``error``, warn the user, and its envelope.""" + logger.info("subagent_failed", run=ref.run, agent=ref.agent, + error=truncate(error, _MAX_LOGGED_ERROR)) + self._end(ref, call_id, RUN_FAILED, text=text, error=error) + warned = WorkflowEvent.error(warning, error_code=code, recoverable=True) + warned.metadata["agent"] = ref.agent + warned.run = ref + self._report(warned) + return Delegated( + result=envelope(ref, RUN_FAILED, result=text, error=error), + state=dict(state or {}), run=ref, + ) + + def _end( + self, + ref: RunRef, + call_id: str, + status: str, + *, + text: str = "", + error: str | None = None, + partial: bool = False, + ) -> WorkflowEvent: + """Report and record the ``AGENT_RUN`` that ends ``ref``'s run; that event.""" + end = WorkflowEvent.agent_run( + ref, status, call_id=call_id, result=result_head(text), error=error, + partial=partial, usage=self._usage(ref), + ) + self._emit(end) + return end + + def _usage(self, ref: RunRef) -> dict[str, dict[str, int]] | None: + """What ``ref``'s run used, by model, from its conversation's ledger.""" + if self._ledgers is None: + return None + return self._ledgers.ledger(get_active_turn()).run_usage(ref.run or "") + + def _emit(self, event: WorkflowEvent) -> None: + """Record ``event`` (an ``AGENT_RUN``), then report it.""" + self._runs.observe(event) + self._report(event) + + @staticmethod + def _report(event: WorkflowEvent) -> None: + """Report ``event`` to the turn's live events (none outside a turn).""" + live_events.report(event) diff --git a/src/agentic_cli/workflow/agents/runs.py b/src/agentic_cli/workflow/agents/runs.py index e099d4b2..6d60afe3 100644 --- a/src/agentic_cli/workflow/agents/runs.py +++ b/src/agentic_cli/workflow/agents/runs.py @@ -2,19 +2,18 @@ Each run is named readably within its conversation: its instance ``<agent>-<n>`` (``researcher-2``, numbered per agent) and its run -``<instance>#<n>`` (each instance runs once: ``#1``). Both backends find a -run where its events come from (ADK's invocation branch, Deep Agents' -stream namespace) and ask ``run_for`` for its name, keyed by (conversation, -parent run, the parent's call id): the same key names the same run until it -has ended, and a new one after (a provider that numbers its call ids repeats -them every turn). +``<instance>#<n>`` (each instance runs once: ``#1``). The framework names a +run as it starts it (``agents/delegate.py::Delegations``) with ``run_for``, +keyed by (conversation, parent run, the parent's call id): the same key +names the same run until it has ended, and a new one after (a provider that +numbers its call ids repeats them every turn). The records are written from the runs' own events (``AGENT_RUN``: started, -then one end status), which the event processors hand to ``observe`` as they -make them, under the turn they are reported in. The one other writer is +then one end status), which ``Delegations`` hands to ``observe`` as it makes +them, under the turn they are reported in. The one other writer is ``interrupt_open``, for the runs a turn leaves open when it is stopped or fails, when no event can reach its consumer any more. A conversation is a -``SessionRef``, or None for a processor driven outside a manager. All of it +``SessionRef``, or None for runs started outside a manager's turn. All of it is in memory, for as long as its manager lives: a backend switch builds a new manager, and the runs recorded before it do not follow (as with its usage ledgers). @@ -22,12 +21,11 @@ from __future__ import annotations -from collections.abc import Callable +from collections.abc import Callable, Mapping from dataclasses import dataclass, field from datetime import datetime from typing import Any -from agentic_cli.workflow.agents.outcome import CUT, REFUSAL_ERROR, REFUSED from agentic_cli.workflow.events import EventType, WorkflowEvent from agentic_cli.workflow.sessions import RunRef, SessionRef, get_active_turn from agentic_cli.workflow.tool_summaries import delegation_summary @@ -43,17 +41,18 @@ {RUN_COMPLETED, RUN_FAILED, RUN_REFUSED, RUN_CANCELLED, RUN_INTERRUPTED} ) -#: The longest title a run gets: the first line of the request its parent wrote. +#: The longest title a run gets: the first line of its brief's title. TITLE_MAX = 80 #: How much of its result a run's end event, and its record, keep. RESULT_MAX = 200 -#: How a parent is told its sub-agent failed: ADK's delegation tool's words -#: (``_SingleTurnAgentTool``), which Deep Agents' delegation gives too. +#: How ADK's own delegation tool told a parent its sub-agent failed. Kept +#: for callers that read it; the framework's delegation answers with the +#: result envelope (``agents/envelope.py``), its ``error`` the reason. SUBAGENT_ERROR_PREFIX = "Error running sub-agent: " def run_title(request: str) -> str: - """A run's title: the first non-blank line of its request, cut to ``TITLE_MAX`` characters.""" + """A run's title: the first non-blank line of ``request``, cut to ``TITLE_MAX`` characters.""" line = next((line.strip() for line in request.splitlines() if line.strip()), "") return line[:TITLE_MAX] @@ -75,86 +74,30 @@ def run_label(ref: RunRef | None) -> str | None: return f"{ref.instance} ({ref.agent}, run {run_number(ref.run)})" -def run_ended( - ref: RunRef, - call_id: str | None, - answer: str, - *, - failed: bool = False, - error: str | None = None, - outcome: str | None = None, - usage: dict[str, dict[str, int]] | None = None, - sealed: bool = False, -) -> WorkflowEvent: - """The ``AGENT_RUN`` that ends ``ref``'s run, decided as on every backend. - - ``answer`` is the delegation's result as its parent read it; ``failed`` - says it is the framework's own error result (``error``: its error), and - ``outcome`` is the mark the backend's hook put on the run's last answer - (``agents/outcome.py``). The run ends: - - - ``interrupted`` for the seal of a call a stopped turn left open - (``sealed``), with its result; - - ``failed`` for ``Error running sub-agent: <reason>`` (its error the - reason), or for the framework's error result (its error, else the - answer); - - ``refused`` when the outcome is ``REFUSED``; - - else ``completed``, ``partial`` when the outcome is ``CUT``. - - The sub-agent's answer is never read for success: each backend tells - ``failed`` from its own error result alone, so an answer that looks - like a failed result completed. - """ - if sealed: - return WorkflowEvent.agent_run( - ref, RUN_INTERRUPTED, call_id=call_id, result=result_head(answer), usage=usage, - ) - if answer.startswith(SUBAGENT_ERROR_PREFIX): - return WorkflowEvent.agent_run( - ref, RUN_FAILED, call_id=call_id, result="", - error=answer.removeprefix(SUBAGENT_ERROR_PREFIX), usage=usage, - ) - if failed: - return WorkflowEvent.agent_run( - ref, RUN_FAILED, call_id=call_id, result="", error=error or answer, usage=usage, - ) - if outcome == REFUSED: - return WorkflowEvent.agent_run( - ref, RUN_REFUSED, call_id=call_id, result=result_head(answer), - error=REFUSAL_ERROR, usage=usage, - ) - return WorkflowEvent.agent_run( - ref, RUN_COMPLETED, call_id=call_id, result=result_head(answer), - partial=outcome == CUT, usage=usage, - ) - - -def show_as_delegation(result: WorkflowEvent, answer: str, ended: WorkflowEvent) -> None: - """Show a delegation's ``TOOL_RESULT`` as every backend shows it. - - ``ended`` is the ``AGENT_RUN`` the result ends the run with, and - ``answer`` what the sub-agent answered, as its parent read it. The - content becomes ``tool_summaries.delegation_summary``'s: the answer's - first line, or, for a sub-agent that failed, ``Failed: <reason>``, the - result failing too (``success`` false; its ``error`` the text the parent - read, as Deep Agents' error result has it). ``metadata["result"]`` stays - as the backend gave it. - - A result that ends its run ``interrupted`` (ADK's seal of a call a - stopped turn left open) is left as the tool result made it. No turn - shows one: ADK writes its seals as the stopped run closes, after the - turn has stopped reading its events, so only a processor handed a seal - directly meets the case. +def show_as_delegation(result: WorkflowEvent, envelope: Mapping[str, Any]) -> None: + """Show a delegation's ``TOOL_RESULT`` from its envelope, the same on every backend. + + ``envelope`` is the run's result envelope (``agents/envelope.py``), as the + parent read it. The content becomes ``tool_summaries.delegation_summary``'s: + the result's first line for a run that completed or was refused (the + refusal notice says why), else ``Failed: <error>``. The result succeeds + as the envelope does (``success``), its ``error`` the envelope's when it + does not, and ``metadata["result"]`` is the envelope. """ - status = ended.metadata.get("status") - if status == RUN_INTERRUPTED: - return - if status == RUN_FAILED: - result.content = delegation_summary(answer, error=ended.metadata.get("error") or "") - result.metadata["success"] = False - result.metadata["error"] = result.metadata.get("error") or answer - return - result.content = delegation_summary(answer) + text = envelope.get("result") + text = text if isinstance(text, str) else "" + succeeded = envelope.get("success") is True + error = envelope.get("error") + if succeeded or envelope.get("status") == RUN_REFUSED: + result.content = delegation_summary(text) + else: + result.content = delegation_summary(text, error=error if isinstance(error, str) else "") + result.metadata["success"] = succeeded + if succeeded: + result.metadata.pop("error", None) + elif isinstance(error, str): + result.metadata["error"] = error + result.metadata["result"] = dict(envelope) @dataclass @@ -164,7 +107,7 @@ class RunRecord: Attributes: ref: The run. call_id: The parent's call that started it. - title: The first line of its request. + title: Its brief's title. status: ``started`` while it runs, then its end status. started: When it started. ended: When it ended; None while it runs. @@ -172,6 +115,11 @@ class RunRecord: error: Why it ended without completing. partial: Whether its result was cut short. usage: Its token totals by model (``{"input": ..., "output": ...}``). + brief: Its brief's filled fields, the title first. + started_by: Who started it: ``agent:<instance>`` (``agent:root`` + for the root). + mode: How it runs: ``blocking`` (its parent waits for it). + cancelled_by: Who cancelled it, for a cancelled run. """ ref: RunRef @@ -184,6 +132,10 @@ class RunRecord: error: str | None = None partial: bool = False usage: dict[str, dict[str, int]] = field(default_factory=dict) + brief: dict[str, str] = field(default_factory=dict) + started_by: str | None = None + mode: str = "blocking" + cancelled_by: str | None = None def _run_id(instance: str, number: int) -> str: @@ -252,10 +204,11 @@ def run_for( def observe(self, event: WorkflowEvent) -> None: """Record what a run's ``AGENT_RUN`` event says, under the turn it is reported in. - A start makes the run's record; an end gives it its status, time, - result, error, whether it is partial and what it used (an end whose - start was not seen makes the record too). Any other event changes - nothing. + A start makes the run's record (its call, title, brief, who started + it and its mode); an end gives it its status, time, result, error, + whether it is partial, what it used and who cancelled it (an end + whose start was not seen makes the record too). Any other event + changes nothing. """ ref = event.run if event.type is not EventType.AGENT_RUN or ref is None or ref.run is None: @@ -270,6 +223,9 @@ def observe(self, event: WorkflowEvent) -> None: title=metadata.get("title") or "", status=RUN_STARTED, started=event.timestamp, + brief=dict(metadata.get("brief") or {}), + started_by=metadata.get("started_by"), + mode=metadata.get("mode") or "blocking", ) return if status not in RUN_END_STATUSES: @@ -289,6 +245,7 @@ def observe(self, event: WorkflowEvent) -> None: record.error = metadata.get("error") record.partial = bool(metadata.get("partial")) record.usage = dict(metadata.get("usage") or {}) + record.cancelled_by = metadata.get("cancelled_by") def records(self, conversation: SessionRef | None) -> list[RunRecord]: """``conversation``'s runs, in the order they started.""" diff --git a/src/agentic_cli/workflow/base_manager.py b/src/agentic_cli/workflow/base_manager.py index 04c89436..c11b79b4 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.delegate import AgentRun, Delegations, RunAnswer from agentic_cli.workflow.agents.policy import SubAgentPolicy, as_policy from agentic_cli.workflow.agents.runs import AgentRuns from agentic_cli.workflow.usage import ( @@ -578,6 +579,43 @@ def _usage_ledgers(self) -> UsageLedgers: ledgers = self.__dict__["_usage_ledgers"] = UsageLedgers() return ledgers + @property + def _delegations(self) -> Delegations: + """This manager's delegations (``workflow/agents/delegate.py``), made on first use. + + From the agent configs, the policy (``subagent_policy``) and the + backend's hook (``_run_agent``): each ``task`` call of a delegating + agent hands its brief to ``delegate``, which names, runs, ends and + records the run. + """ + delegations = self.__dict__.get("_delegations_made") + if delegations is None: + delegations = self.__dict__["_delegations_made"] = Delegations( + runs=self.agent_runs, + policy=self.subagent_policy, + types={config.name: config for config in self._agent_configs}, + hook=self._run_agent, + ledgers=self._usage_ledgers, + ) + return delegations + + async def _run_agent(self, run: AgentRun) -> RunAnswer: + """Run one sub-agent run to its end: the backend's hook (``Delegations``'s). + + Called in the run's own task, where the run is the active run and no + tool call is (``agents/delegate.py``). It runs ``run.config``'s agent + on ``run.message`` (after ``run.history`` for an inheriting one), + from the shared state ``run.state``, reports the run's events to the + turn's live events as they are made, and returns its last answer, + its outcome and the shared state it changed. A failure raises (the + provider's error, or ``RunFailed``); a cancel stops the run and + raises. + + Raises: + NotImplementedError: This backend runs no sub-agent. + """ + raise NotImplementedError(f"{type(self).__name__} runs no sub-agent") + @property def settings(self) -> "BaseSettings": """Get the settings instance.""" diff --git a/src/agentic_cli/workflow/deepagents/__init__.py b/src/agentic_cli/workflow/deepagents/__init__.py index 6bebb505..013f1572 100644 --- a/src/agentic_cli/workflow/deepagents/__init__.py +++ b/src/agentic_cli/workflow/deepagents/__init__.py @@ -1,8 +1,9 @@ """The Deep Agents orchestrator (``orchestrator = "deepagents"``). Each ``AgentConfig`` becomes one LangChain ``create_agent`` graph, and a -coordinator delegates to its sub-agents through the ``task`` tool of Deep -Agents' ``SubAgentMiddleware``. Our own middleware gates every tool call and +coordinator delegates to its sub-agents through the framework's ``task`` tool +(``task_tool.py``), each run's graph running apart from its coordinator's. +Our own middleware gates every tool call and turns a raising tool into an error result, so the framework's permission engine, tools and models are the same as on the other backends. diff --git a/src/agentic_cli/workflow/deepagents/agent_builder.py b/src/agentic_cli/workflow/deepagents/agent_builder.py index cb6bbf1e..338d114f 100644 --- a/src/agentic_cli/workflow/deepagents/agent_builder.py +++ b/src/agentic_cli/workflow/deepagents/agent_builder.py @@ -1,35 +1,26 @@ -"""The agent tree: one ``create_agent`` graph per ``AgentConfig``. - -Agents are built bottom-up, so each coordinator is built after the sub-agents -it delegates to. A coordinator gets Deep Agents' ``SubAgentMiddleware`` with -one ``CompiledSubAgent`` per sub-agent, which gives it a ``task`` tool -(``description``: the brief, ``subagent_type``: the sub-agent's name). Only -the configured sub-agents are offered: there is no automatic general-purpose -sub-agent, and none of Deep Agents' file tools. - -What a sub-agent sees follows its ``inherit_context``. A fresh one (False, -the default) is Deep Agents' isolated sub-agent: one ``HumanMessage`` holding -the brief, not the conversation. An inheriting one (True) is a fork -(``mode="fork"``): the coordinator's effective conversation (after any -summary), without the message that called ``task``, then Deep Agents' -preamble and the brief; its own summarization compacts an inherited history -too large for its window, and its stack sends none of the coordinator's -reasoning on. Either way it gets the coordinator's ``plan`` and ``tasks``, -keeps its own prompt, tools, model and middleware, runs its own tool loop, -and its last non-empty text comes back as the ``task`` call's result, with -the ``plan``/``tasks`` it changed. Deep Agents marks forks beta with a -``LangChainBetaWarning`` LangChain would print over the UI; that one warning -is filtered, and a debug log (``deepagents_fork_beta``) says which agents -fork. - -Every stack, outermost first: ``InterruptedCallsMiddleware`` (answers a -tool call a cancelled turn or a crash left without a result, before each -run, as ``workflow/interrupts.py`` says; Deep Agents' own -``PatchToolCallsMiddleware`` without the manager's record), the -coordinator's ``SubAgentMiddleware`` (so its ``task`` tool is gated like any -other), then the model side and the tool side. - -- Model side, outermost first: other providers' and other agents' reasoning +"""The agents: one ``create_agent`` graph per ``AgentConfig``, each standalone. + +Every agent is its own graph, built apart from the others: the root on the +conversation's checkpointer, every other agent with none (a sub-agent's run +ends when its delegation returns, and nothing resumes it). An agent with +sub-agents gets the framework's ``task`` tool (``task_tool.build_task_tool``) +among its tools: a call hands the brief to the manager's ``Delegations``, +which runs the sub-agent's graph apart from the caller's stream +(``DeepAgentsWorkflowManager._run_agent``) and answers with the result +envelope. Only the configured sub-agents are offered: there is no automatic +general-purpose sub-agent, and none of Deep Agents' file tools. ``graphs``, +when given, is filled with every agent's graph by name: what the manager runs +a sub-agent on. + +Every stack, outermost first: ``InterruptedCallsMiddleware`` (answers a tool +call a cancelled turn or a crash left without a result, before each run, as +``workflow/interrupts.py`` says; Deep Agents' own +``PatchToolCallsMiddleware`` without the manager's record), then the model +side and the tool side. + +- Model side, outermost first: a sub-agent's refused or cut final answer is + said so (``SubAgentOutcomeMiddleware``, every agent but the root), other + providers' and other agents' reasoning is left out of the request (``ForeignReasoningMiddleware``), Deep Agents' summarization counts exactly what will be sent (``summarization.py``), every provider's context @@ -39,7 +30,8 @@ with ``prompt_caching_enabled`` the cache marks land on the final request (``AnthropicPromptCachingMiddleware``: the system prompt, the last tool and the conversation, for 5 minutes, as on ADK). -- Tool side, outermost first: the permission gate, the tool result cap +- Tool side, outermost first: the permission gate (``task`` among the tools + it gates), the tool result cap (``ToolResultCapMiddleware``: a result over ``tool_result_max_chars`` is cut, its full output saved; an error result too), the tool-error middleware, and the active tool call (a job a tool starts is linked to its @@ -52,25 +44,16 @@ from __future__ import annotations -import warnings from collections.abc import Callable, Mapping from typing import TYPE_CHECKING -from deepagents import CompiledSubAgent, SubAgentMiddleware from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware from langchain.agents import create_agent from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware -from langchain_core._api import LangChainBetaWarning -from agentic_cli.logging import Loggers from agentic_cli.models import CacheMechanism from agentic_cli.tools._core.delegation import TASK_TOOL -from agentic_cli.tools.registry import ( - ToolDefinition, - bind_tool_identity, - get_registry, - identify_tool, -) +from agentic_cli.tools.registry import ToolDefinition, identify_tool from agentic_cli.workflow.config import AgentConfig, AgentGraphError from agentic_cli.workflow.deepagents.middleware import ( ActiveToolCallMiddleware, @@ -84,8 +67,8 @@ ToolResultCapMiddleware, ) from agentic_cli.workflow.deepagents.state import AgentCliState +from agentic_cli.workflow.deepagents.task_tool import build_task_tool from agentic_cli.workflow.context import ContextBudget -from agentic_cli.workflow.agents.runs import AgentRuns from agentic_cli.workflow.interrupts import OpenCalls from agentic_cli.workflow.outside_content import OutsideContentMarks from agentic_cli.workflow.deepagents.summarization import ( @@ -103,11 +86,7 @@ from agentic_cli.config import BaseSettings from agentic_cli.models import ResolvedModel - -logger = Loggers.workflow() - -#: What Deep Agents warns when a coordinator forks a sub-agent. -_FORK_BETA = r"The feature `forked subagents` is in beta" + from agentic_cli.workflow.agents.delegate import Delegations def build_agent_tree( @@ -127,9 +106,10 @@ def build_agent_tree( memory_index: Callable[[], str] | None = None, memory_index_cached: Callable[[], str] | None = None, memory_index_forget: Callable[[], None] | None = None, - runs: AgentRuns | None = None, + delegations: "Callable[[], Delegations] | None" = None, + graphs: "dict[str, CompiledStateGraph] | None" = None, ) -> "CompiledStateGraph": - """Build every agent, bottom-up, and return the root. + """Build every agent, each on its own, and return the root. Validates nothing: the manager runs ``validate_agent_graph`` first, so ``configs`` is a tree with one root (the agent nobody delegates to). @@ -144,13 +124,10 @@ def build_agent_tree( prompts: Each agent's system prompt, already resolved. settings: The manager's settings: the model side and the tool result cap are built from them. - checkpointer: The root's checkpointer. Sub-agents are compiled with - none (``checkpointer=False``), so they do not inherit it through - LangGraph's nested-graph rules: a sub-agent's run ends when its - ``task`` returns, nothing resumes it or reads its state, and a - fork takes its parent's conversation from the parent's state. A - checkpoint of theirs would be one nothing reads (a fork's, the - whole conversation at every step). + checkpointer: The root's checkpointer. Every other agent is compiled + with none (``checkpointer=False``): a sub-agent's run ends when + its delegation returns, and nothing resumes it or reads its + state. bound: What every agent's permission gate asks first, for a tool object the framework built and bound. Defaults to the framework registry's identity map; a manager with tool objects of its own @@ -177,14 +154,14 @@ def build_agent_tree( memory_index_forget: Drops the conversation's index snapshot: the root's summarization calls it when it writes a summary, before the request that carries the summary is sent. - runs: The manager's sub-agent runs: every agent's - ``ActiveToolCallMiddleware`` makes a ``task`` call to one of the - agent's sub-agents the run of the sub-agent it starts, and its - ``ToolCallErrorMiddleware`` names that run in the warning a - failed one gives. + delegations: The manager's delegations (``BaseWorkflowManager._delegations``): + given, an agent with sub-agents gets the ``task`` tool, which + hands each call to them. Without it no agent delegates (a tree + a unit test builds alone). + graphs: Filled, when given, with every agent's graph, by name. Raises: - AgentGraphError: A coordinator's own tools include one named + AgentGraphError: A delegating agent's own tools include one named ``task``, the name of its delegation tool. """ config_map = {config.name: config for config in configs} @@ -193,9 +170,6 @@ def build_agent_tree( def build(name: str) -> "CompiledStateGraph": config = config_map[name] - subagents = [ - _subagent(config_map[sub], build(sub)) for sub in config.sub_agents - ] model = chat_models[name] model_side = _model_side( model, resolved.get(name), settings, @@ -206,49 +180,45 @@ def build(name: str) -> "CompiledStateGraph": ) if name != root: # Outermost: it sees the answer every other model-side - # middleware let through, as the coordinator will read it. + # middleware let through, as the run's answer is read. model_side = [SubAgentOutcomeMiddleware(), *model_side] if summarizers is not None: summarizers.update( (name, middleware) for middleware in model_side if isinstance(middleware, ReportingSummarizationMiddleware) ) + own = _own_tools(config, tools.get(name, []), delegates=bool(config.sub_agents)) + if config.sub_agents and delegations is not None: + types = {sub: config_map[sub] for sub in config.sub_agents} + own = [*own, build_task_tool(name, types, delegations)] return create_agent( model=model, - tools=_own_tools(config, tools.get(name, []), delegates=bool(subagents)), + tools=own, system_prompt=prompts[name], - middleware=_middleware( - subagents, - first=( - PatchToolCallsMiddleware() if open_calls is None - else InterruptedCallsMiddleware(open_calls, root=name == root) - ), - model_side=model_side, - tool_side=_tool_side( - config, settings, bound=bound, open_calls=open_calls, marks=marks, - runs=runs, - models={ - sub: str(resolved[sub].ref) - for sub in config.sub_agents if resolved.get(sub) is not None - }, - ), - ), + middleware=[ + PatchToolCallsMiddleware() if open_calls is None + else InterruptedCallsMiddleware(open_calls, root=name == root), + *model_side, + *_tool_side(config, settings, bound=bound, open_calls=open_calls, marks=marks), + ], state_schema=AgentCliState, name=name, checkpointer=checkpointer if name == root else False, ) - return build(root) + built = {name: build(name) for name in config_map} + if graphs is not None: + graphs.update(built) + return built[root] def _own_tools( config: AgentConfig, tools: list["BaseTool"], *, delegates: bool ) -> list["BaseTool"]: - """The agent's tools; a coordinator's must leave ``task`` to delegation. + """The agent's tools; a delegating agent's must leave ``task`` to delegation. - The tool node keeps one tool per name, the agent's own after the - middleware's, so a coordinator's tool named ``task`` would silently take - delegation over. + A model is offered one tool per name, so a delegating agent's own tool + named ``task`` would take its delegation tool's place, or lose it. """ if delegates and any(tool.name == TASK_TOOL for tool in tools): raise AgentGraphError( @@ -258,19 +228,6 @@ def _own_tools( return list(tools) -def _middleware( - subagents: list[CompiledSubAgent], - *, - first: "AgentMiddleware", - model_side: list["AgentMiddleware"], - tool_side: list["AgentMiddleware"], -) -> list["AgentMiddleware"]: - stack: list[AgentMiddleware] = [first] - if subagents: - stack.append(_delegation(subagents)) - return stack + model_side + tool_side - - def _tool_side( config: AgentConfig, settings: "BaseSettings | None", @@ -278,14 +235,8 @@ def _tool_side( bound: Callable[[object], ToolDefinition | None], open_calls: OpenCalls | None = None, marks: OutsideContentMarks | None = None, - runs: AgentRuns | None = None, - models: Mapping[str, str] | None = None, ) -> list["AgentMiddleware"]: - """What runs each of the agent's tool calls, outermost first. - - ``models``: each of the agent's sub-agents' model references, which a - failed delegation's overflow warning names. - """ + """What runs each of the agent's tool calls, outermost first.""" stack: list[AgentMiddleware] = [ PermissionMiddleware(config.name, bound=bound, open_calls=open_calls, marks=marks) ] @@ -297,10 +248,7 @@ def _tool_side( settings.tool_result_max_chars, tool_output_dir(settings.app_name) ) ) - stack += [ - ToolCallErrorMiddleware(runs, sub_agents=config.sub_agents, models=models), - ActiveToolCallMiddleware(runs, sub_agents=config.sub_agents), - ] + stack += [ToolCallErrorMiddleware(), ActiveToolCallMiddleware()] return stack @@ -335,44 +283,3 @@ def _model_side( AnthropicPromptCachingMiddleware(ttl="5m", unsupported_model_behavior="ignore") ) return stack - - -def _delegation(subagents: list[CompiledSubAgent]) -> SubAgentMiddleware: - """The coordinator's ``task`` tool, bound to the framework's declaration. - - The framework built this object, so it binds it: the gate identifies it - by identity, never by its name. - """ - forks = [spec["name"] for spec in subagents if spec.get("mode") == "fork"] - if forks: - # Deep Agents warns that forks are beta whenever a coordinator has - # one, and LangChain shows its beta warnings: over the UI, once. - warnings.filterwarnings("ignore", message=_FORK_BETA, category=LangChainBetaWarning) - logger.debug("deepagents_fork_beta", agents=forks) - middleware = SubAgentMiddleware( - # Only stored: compiled sub-agents never read it. - backend=None, - subagents=subagents, - state_schema=AgentCliState, - ) - for task_tool in middleware.tools: - bind_tool_identity(task_tool, get_registry().get(TASK_TOOL)) - return middleware - - -def _subagent(config: AgentConfig, runnable: "CompiledStateGraph") -> CompiledSubAgent: - """How the coordinator's ``task`` tool offers ``config``. - - The coordinator chooses by the description, so an agent without one is - still offered, under a placeholder, and the omission is logged. An - inheriting agent (``inherit_context``) is forked: it continues the - coordinator's conversation. - """ - description = config.description.strip() - if not description: - logger.warning("deepagents_subagent_without_description", agent=config.name) - description = f"The {config.name} agent." - spec = CompiledSubAgent(name=config.name, description=description, runnable=runnable) - if config.inherit_context: - spec["mode"] = "fork" - return spec diff --git a/src/agentic_cli/workflow/deepagents/event_processor.py b/src/agentic_cli/workflow/deepagents/event_processor.py index 1f10890d..5154801f 100644 --- a/src/agentic_cli/workflow/deepagents/event_processor.py +++ b/src/agentic_cli/workflow/deepagents/event_processor.py @@ -1,55 +1,55 @@ -"""A Deep Agents turn's stream as ``WorkflowEvent``s. - -A turn streams ``astream(input, config, stream_mode=["updates", "tasks"], -subgraphs=True)``. Each item is ``(namespace, mode, payload)``; ``()`` is the -root agent, and a sub-agent's items arrive under ``("tools:<task-id>",)``, -the namespace of the coordinator's tools task that runs its ``task`` call. -The ``tasks`` mode announces that task with its tool call, whose -``subagent_type`` names the agent; deeper nesting resolves the same way, one -namespace segment at a time. +"""A Deep Agents turn's stream as ``WorkflowEvent``s, and a sub-agent run's. + +A turn streams the root agent's graph: ``astream(input, config, +stream_mode=["updates"], subgraphs=True)``, each item ``(namespace, mode, +payload)``. A sub-agent's graph never streams there: its run is the +framework's ``task`` call (``agents/delegate.py``), which runs the +sub-agent's graph apart from its caller's stream +(``DeepAgentsWorkflowManager._run_agent``), through a processor of its own, +made for that run (``run=``), whose events reach the turn's live events. +Only the root namespace's items are the agent's: a graph one of its tools +runs under the config it inherits streams in a namespace of its own, and +none of its items is an event. Each finished node output becomes events, as ADK reports them: one per -finished message, no tokens. Only the agents' own nodes speak: +finished message, no tokens. Only the agent's own nodes speak: - a ``model`` update's ``AIMessage``: ``THINKING`` (its reasoning blocks) and ``TEXT`` (its text blocks) in order, one ``TOOL_CALL`` per tool call, and ``LLM_USAGE`` on that agent's own model, with its context numbers (``context_trigger``, ``window_known``). Only the root replies to the user: - a sub-agent's ``TEXT`` is marked ``metadata["subagent"]`` (activity, not - the reply) and its usage ``purpose="subagent"``, a fork's included (its - prompt holds the conversation, but it is not the main agent's context); + a sub-agent run's ``TEXT`` is marked ``metadata["subagent"]`` (activity, not + the reply) and its usage ``purpose="subagent"``, an inheriting one's + included (its prompt holds the conversation, but it is not the main + agent's context); - a ``tools`` update's ``ToolMessage``s, including those a ``Command`` carried - (the state tools, ``task``): ``TOOL_RESULT``, a JSON dict parsed back; and - its ``tasks``, when they changed: ``TASK_PROGRESS``, in the same step. + (the state tools, ``task``): ``TOOL_RESULT``, a JSON dict parsed back, a + ``task`` call's shown from its envelope (``agents/runs.py::show_as_delegation``); + and, for the root, its ``tasks``, when they changed: ``TASK_PROGRESS``, in + the same step (a sub-agent's list is the conversation's, which its run + hands back with its result: the root reports it then). Middleware hooks' updates are not output (``PatchToolCallsMiddleware`` re-adds the whole history when it patches it), and a model call inside a tool (``generate_simple``) is no node at all, so it cannot leak into the answer. Every event carries ``metadata["agent"]`` and its run (``WorkflowEvent.run``): -the root's own at ``()``, and a sub-agent's under the namespace its ``task`` -call runs at, named by the manager's runs (``AgentRuns.run_for``) from the -call the ``tasks`` stream announced; a turn's own ``ERROR`` names none. A -``task`` call to one of the calling agent's own sub-agents is followed by the -``AGENT_RUN`` that starts its run, and its result by the one that ends it -(``failed`` for the framework's error result, with its error: the -sub-agent's answer is never read for success), the result shown as on ADK -(``agents/runs.py::show_as_delegation``), each recorded as it is made, before -``on_event``. A ``task`` call to any other type runs no sub-agent (Deep -Agents answers that it does not exist): it is an ordinary tool call, with no -run. +the root's own (``root_run``), or the sub-agent run the processor was made +for; a turn's own ``ERROR`` names none. The ``AGENT_RUN`` events are the +framework's (``Delegations``), not the stream's. What happens inside a node and is no node output (a summary call and the summary it made, and with ``raw_llm_logging`` every model call) reaches -``RunCallback`` instead, the turn's LangChain callback handler, which hands -it to the turn's ``LiveEvents`` as it happens: a summary that starts is -reported while the model node still waits on it. +``RunCallback`` instead, the LangChain callback handler of the turn's run +and of each sub-agent run, which hands it to the turn's ``LiveEvents`` as it +happens: a summary that starts is reported while the model node still waits +on it. """ from __future__ import annotations import json import time -from collections.abc import Collection, Iterable, Mapping +from collections.abc import Iterable, Mapping from dataclasses import dataclass from typing import TYPE_CHECKING, Any from uuid import UUID @@ -60,14 +60,8 @@ from agentic_cli.constants import truncate from agentic_cli.tools._core.delegation import TASK_TOOL from agentic_cli.tools._core.tasks import task_progress_data -from agentic_cli.workflow.agents.outcome import cut_off_warning -from agentic_cli.workflow.agents.runs import ( - RUN_STARTED, - AgentRuns, - run_ended, - run_title, - show_as_delegation, -) +from agentic_cli.workflow.agents.envelope import read_envelope +from agentic_cli.workflow.agents.runs import show_as_delegation from agentic_cli.workflow.context import ( OVERFLOW_ERROR_CODE, ContextBudget, @@ -75,14 +69,10 @@ overflow_message, usage_fields, ) -from agentic_cli.workflow.deepagents.middleware import ( - answer_latency, - answer_outcome, - mark_latency, -) +from agentic_cli.workflow.deepagents.middleware import answer_latency, mark_latency from agentic_cli.workflow.deepagents.summarization import CONTEXT_SUMMARIZED from agentic_cli.workflow.events import WorkflowEvent -from agentic_cli.workflow.sessions import RunRef, get_active_turn, root_run +from agentic_cli.workflow.sessions import RunRef, root_run from agentic_cli.workflow.usage import UsageLedgers, langchain_tokens, llm_usage_event if TYPE_CHECKING: @@ -107,29 +97,24 @@ #: LangChain's message types as the roles a provider knows. _ROLES = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"} -Namespace = tuple[str, ...] - - class DeepAgentsEventProcessor: - """Turns one turn's stream items into ``WorkflowEvent``s. + """Turns one agent's stream items into ``WorkflowEvent``s: the root's turn, or a sub-agent run. Args: - root: The root agent's name: the agent of namespace ``()``, and of any - namespace the stream never announced. + root: The root agent's name: the agent of every event, unless the + processor is made for a sub-agent run (``run``). agent_models: Each agent's resolved model, by name; ``LLM_USAGE`` is reported against the agent's own. session_id: Put on ``TEXT`` and ``THINKING``, as the other backends do. budgets: Each agent's context numbers, by name, which its ``LLM_USAGE`` carries; none without. - runs: The manager's sub-agent runs, which this processor names and - records; its own when not given. - sub_agents: Each agent's sub-agents, by name: a ``task`` call starts - a run only for one of the caller's own. None takes every - ``task`` call's ``subagent_type`` as the caller's. ledgers: The manager's usage ledgers: each call's usage is recorded - in its conversation's as it is made, before ``on_event``, and a - sub-agent run's end carries what the run used, by model - (``metadata["usage"]``); its own when not given. + in its conversation's as it is made, before ``on_event``; its own + when not given. + run: The sub-agent run whose graph streams here: every event is + that run's and its agent's, its text is activity + (``metadata["subagent"]``) and its usage ``purpose="subagent"``. + None: the root's turn. """ def __init__( @@ -139,71 +124,48 @@ def __init__( agent_models: Mapping[str, "ResolvedModel"], session_id: str | None = None, budgets: Mapping[str, ContextBudget] | None = None, - runs: AgentRuns | None = None, - sub_agents: Mapping[str, Collection[str]] | None = None, ledgers: UsageLedgers | None = None, + run: RunRef | None = None, ) -> None: self._root = root self._agent_models = agent_models self._session_id = session_id self._budgets: Mapping[str, ContextBudget] = budgets or {} - # Namespace -> the agent whose graph runs there. - self._agents: dict[Namespace, str] = {(): root} - # (the run that made it, call id) -> tool name: a ToolMessage a - # Command carried may have no name of its own. - self._call_names: dict[tuple[str | None, str], str] = {} + self._run = run if run is not None else root_run(root) + self._agent = self._run.agent + # Call id -> tool name: a ToolMessage a Command carried may have no + # name of its own. + self._call_names: dict[str, str] = {} self._reported_tasks: list[dict] | None = None - # The namespaces whose tasks failed, in order; a delegation that - # answered its call takes its own (and those under it) away. - self._failures: list[Namespace] = [] - # (the run that made it, call id) -> the namespace a delegation's - # sub-agent runs at, until its result. - self._spaces: dict[tuple[str | None, str], Namespace] = {} - self._runs = runs if runs is not None else AgentRuns() - # Namespace -> the run whose graph runs there; the root's at (). - self._refs: dict[Namespace, RunRef] = {(): root_run(root)} - # (the run that made it, call id) -> the run a delegation started, - # until its result: call ids are only an agent's own (a provider that - # numbers them gives a sub-agent's first call its parent's task call's). - self._delegated: dict[tuple[str | None, str], RunRef] = {} - self._sub_agents: dict[str, frozenset[str]] | None = ( - None if sub_agents is None - else {name: frozenset(own) for name, own in sub_agents.items()} - ) - # A sub-agent run's last answer's outcome (SubAgentOutcomeMiddleware's - # mark), by run id, until its task call's result ends the run. - self._outcomes: dict[str, str] = {} self._ledgers = ledgers if ledgers is not None else UsageLedgers() - def agent(self, namespace: Iterable[str]) -> str: - """The agent whose graph runs at ``namespace``.""" - return self._agents.get(tuple(namespace), self._root) - - def run(self, namespace: Iterable[str]) -> RunRef: - """The run whose graph runs at ``namespace`` (the root's, for one never announced).""" - return self._refs.get(tuple(namespace), self._refs[()]) + @property + def run(self) -> RunRef: + """The run every event this processor makes is: the root's own, or a sub-agent run.""" + return self._run def process( self, namespace: Iterable[str], mode: str, payload: Any ) -> list[WorkflowEvent]: - """The events of one stream item (none for most).""" - namespace = tuple(namespace) - if mode == "tasks": - self._track(namespace, payload) - return [] - if mode != "updates" or not isinstance(payload, dict): + """The events of one stream item (none for most). + + ``namespace`` is the item's place in the stream. Only the agent's own + graph's items (the root namespace, ``()``) are its events: a sub-agent + runs apart, on a stream of its own, so an item in a namespace of its + own is a graph one of its tools ran under the config it inherited, + whose model text is no agent's reply. + """ + if tuple(namespace) or mode != "updates" or not isinstance(payload, dict): return [] - agent = self.agent(namespace) - run = self.run(namespace) events: list[WorkflowEvent] = [] for node, update in payload.items(): for values in update if isinstance(update, list) else [update]: if not isinstance(values, dict): continue if node == "model": - events += self._model_output(agent, run, values) + events += self._model_output(values) elif node == "tools": - events += self._tools_output(agent, run, values) + events += self._tools_output(values) for event in events: # Recorded as it is made: an app's on_event cannot drop a row. self._ledgers.record(event) @@ -213,17 +175,12 @@ def turn_failed(self, error: BaseException) -> WorkflowEvent: """The one ``ERROR`` that ends a turn whose stream raised ``error``. ``WorkflowEvent.turn_failed``'s (the base ``process()``'s contract), - attributed to the agent whose task failed first, the innermost: a - sub-agent's failure that escaped its coordinator's ``task`` call fails - that call after it. One the call answered (``Error running - sub-agent: …``, ``ToolCallErrorMiddleware``) is no longer the turn's. - A context overflow (a provider's, or Deep Agents' own when a summary - still does not fit) is told in one sentence naming that agent's - model, with ``error_code`` ``CONTEXT_OVERFLOW``, as on ADK. + the agent's. A context overflow (a provider's, or Deep Agents' own + when a summary still does not fit) is told in one sentence naming the + agent's model, with ``error_code`` ``CONTEXT_OVERFLOW``, as on ADK. """ - agent = self.agent(self._failures[0]) if self._failures else self._root if is_context_overflow(error): - model = self._agent_models.get(agent) or self._agent_models.get(self._root) + model = self._agent_models.get(self._agent) or self._agent_models.get(self._root) event = WorkflowEvent.turn_failed( error, overflow_message(str(model.ref) if model is not None else "the model"), @@ -231,47 +188,16 @@ def turn_failed(self, error: BaseException) -> WorkflowEvent: ) else: event = WorkflowEvent.turn_failed(error) - return self._attributed(event, agent) - - # -- the tasks mode -------------------------------------------------------- - - def _track(self, namespace: Namespace, payload: Any) -> None: - """Learn which agent runs where, and which tasks failed.""" - if not isinstance(payload, dict): - return - if "input" in payload: # a task starts - call = _delegation_call(payload) if payload.get("name") == "tools" else None - subagent = call["args"]["subagent_type"] if call is not None else None - if subagent is not None and self._delegates_to(self.agent(namespace), subagent): - where = (*namespace, f"tools:{payload['id']}") - self._agents[where] = subagent - if call.get("id"): - caller = self.run(namespace) - self._refs[where] = self._runs.run_for( - get_active_turn(), caller, call["id"], subagent - ) - self._spaces[(caller.run, call["id"])] = where - elif payload.get("error") is not None: - self._failures.append(namespace) - - def _answered(self, message: ToolMessage, run: RunRef) -> None: - """``run``'s delegation answered its call: what failed inside it is not the turn's.""" - where = self._spaces.pop((run.run, message.tool_call_id), None) - if where is not None: - self._failures = [ - failed for failed in self._failures if failed[: len(where)] != where - ] + event.metadata["agent"] = self._agent + return event # -- node outputs ---------------------------------------------------------- - def _model_output(self, agent: str, run: RunRef, values: dict) -> list[WorkflowEvent]: + def _model_output(self, values: dict) -> list[WorkflowEvent]: events: list[WorkflowEvent] = [] for message in values.get("messages") or (): if not isinstance(message, AIMessage): continue - outcome = answer_outcome(message) - if outcome is not None and run.run is not None: - self._outcomes[run.run] = outcome for block in message.content_blocks: if block.get("type") == "reasoning" and block.get("reasoning"): events.append( @@ -279,122 +205,43 @@ def _model_output(self, agent: str, run: RunRef, values: dict) -> list[WorkflowE ) elif block.get("type") == "text" and block.get("text"): text = WorkflowEvent.text(block["text"], self._session_id) - if agent != self._root: + if not self._run.is_root: # Only the root replies to the user: a sub-agent's - # text is its work, read by its coordinator as the - # task call's result. + # text is its work, read by its parent as the + # result of its ``task`` call. text.metadata["subagent"] = True events.append(text) for call in message.tool_calls: - self._call_names[(run.run, call["id"])] = call["name"] + self._call_names[call["id"]] = call["name"] event = WorkflowEvent.tool_call(call["name"], call["args"]) event.metadata["tool_call_id"] = call["id"] events.append(event) - started = self._started(call, run) - if started is not None: - events.append(started) if message.usage_metadata: - events.append( - self._usage(agent, message.usage_metadata, answer_latency(message)) - ) - return self._all_attributed(events, agent, run) + events.append(self._usage(message.usage_metadata, answer_latency(message))) + return [self._attributed(event) for event in events] - def _tools_output(self, agent: str, run: RunRef, values: dict) -> list[WorkflowEvent]: + def _tools_output(self, values: dict) -> list[WorkflowEvent]: events: list[WorkflowEvent] = [] for message in values.get("messages") or (): if isinstance(message, ToolMessage): - self._answered(message, run) - ended = self._ended(message, run) - result = self._tool_result(message, run, delegation=ended is not None) - events.append(result) - if ended is not None: - show_as_delegation(result, message.text, ended) - events.append(ended) - # A run cut short is followed by its one warning. - warning = cut_off_warning(ended) - if warning is not None: - events.append(warning) - if "tasks" in values: + events.append(self._tool_result(message)) + if "tasks" in values and self._run.is_root: events += self._progress(values["tasks"]) - return self._all_attributed(events, agent, run) + return [self._attributed(event) for event in events] - def _all_attributed( - self, events: list[WorkflowEvent], agent: str, run: RunRef - ) -> list[WorkflowEvent]: - """``events`` as ``agent``'s, in ``run``; one that names a run (an - ``AGENT_RUN``, a cut run's warning) is its sub-agent's already.""" - return [ - event if event.run is not None else self._attributed(event, agent, run) - for event in events - ] - - def _delegates_to(self, caller: str, subagent: str) -> bool: - """Whether ``subagent`` is one of ``caller``'s own sub-agents.""" - return self._sub_agents is None or subagent in self._sub_agents.get(caller, ()) - - def _started(self, call: dict, parent: RunRef) -> WorkflowEvent | None: - """The ``AGENT_RUN`` a ``task`` call of ``parent``'s starts, recorded; else None. - - Only a call to one of ``parent``'s agent's own sub-agents starts one. - """ - args = call.get("args") or {} - subagent = args.get("subagent_type") - if call.get("name") != TASK_TOOL or not isinstance(subagent, str) or not call.get("id"): - return None - if not self._delegates_to(parent.agent, subagent): - return None - child = self._runs.run_for(get_active_turn(), parent, call["id"], subagent) - self._delegated[(parent.run, call["id"])] = child - description = args.get("description") - event = WorkflowEvent.agent_run( - child, RUN_STARTED, call_id=call["id"], - title=run_title(description if isinstance(description, str) else ""), - ) - self._runs.observe(event) - return event - - def _ended(self, message: ToolMessage, run: RunRef) -> WorkflowEvent | None: - """The ``AGENT_RUN`` the result of a ``task`` call ``run`` made ends, recorded; else None. - - ``agents/runs.py::run_ended``'s decision, as on ADK: ``failed`` for - ``Error running sub-agent: <reason>`` (its ``error`` the reason) or - the framework's other error results (an error message: its error), - ``refused`` when ``SubAgentOutcomeMiddleware`` marked the run's last - answer refused, else ``completed`` (``partial`` when it marked the - answer cut). The sub-agent's answer is never read for success - (``_delegation_result``). - """ - child = self._delegated.pop((run.run, message.tool_call_id), None) - if child is None: - return None - _, succeeded, error = _delegation_result(message) - event = run_ended( - child, message.tool_call_id, message.text, - failed=not succeeded, error=error, - outcome=self._outcomes.pop(child.run or "", None), - usage=self._ledgers.ledger(get_active_turn()).run_usage(child.run or ""), - ) - self._runs.observe(event) - return event - - def _tool_result( - self, message: ToolMessage, run: RunRef, *, delegation: bool = False - ) -> WorkflowEvent: - """``TOOL_RESULT`` for ``message``; a ``delegation``'s read as ``_delegation_result``.""" - name = ( - message.name or self._call_names.get((run.run, message.tool_call_id)) or "unknown" - ) - result, success, error = (_delegation_result if delegation else _result_of)(message) + def _tool_result(self, message: ToolMessage) -> WorkflowEvent: + """``TOOL_RESULT`` for ``message``; a delegation's shown from its envelope.""" + name = message.name or self._call_names.get(message.tool_call_id) or "unknown" + result, success, error = _result_of(message) event = WorkflowEvent.tool_result(name, result, success=success, error=error) event.metadata["tool_call_id"] = message.tool_call_id + found = read_envelope(result) if name == TASK_TOOL else None + if found is not None: + show_as_delegation(event, found) return event def _progress(self, tasks: Any) -> list[WorkflowEvent]: - """``TASK_PROGRESS`` for a changed task list. - - A sub-agent's list flows back to its coordinator with its result; - reporting it again would say nothing new. - """ + """``TASK_PROGRESS`` for a changed task list (the root's).""" if not isinstance(tasks, list) or tasks == self._reported_tasks: return [] self._reported_tasks = tasks @@ -410,24 +257,18 @@ def _progress(self, tasks: Any) -> list[WorkflowEvent]: ) ] - def _usage( - self, agent: str, usage: Mapping[str, Any], latency_ms: float | None - ) -> WorkflowEvent: - model = self._agent_models.get(agent) or self._agent_models.get(self._root) + def _usage(self, usage: Mapping[str, Any], latency_ms: float | None) -> WorkflowEvent: + model = self._agent_models.get(self._agent) or self._agent_models.get(self._root) event = usage_event(model, usage, latency_ms=latency_ms) - event.metadata.update(usage_fields(self._budgets.get(agent))) - if agent != self._root: + event.metadata.update(usage_fields(self._budgets.get(self._agent))) + if not self._run.is_root: # A sub-agent's prompt is its brief, not the conversation's context. event.metadata["purpose"] = "subagent" return event - @staticmethod - def _attributed( - event: WorkflowEvent, agent: str, run: RunRef | None = None - ) -> WorkflowEvent: - event.metadata["agent"] = agent - if run is not None: - event.run = run + def _attributed(self, event: WorkflowEvent) -> WorkflowEvent: + event.metadata["agent"] = self._agent + event.run = self._run return event @@ -478,36 +319,6 @@ def _result_of(message: ToolMessage) -> tuple[Any, bool, str | None]: return result, success, error -def _delegation_result(message: ToolMessage) -> tuple[Any, bool, str | None]: - """A delegation's result, whether it succeeded, and its error, as on ADK. - - Only the framework's own error result fails: an error message (the - gate's denial, ``ToolCallErrorMiddleware``'s ``Error running sub-agent: - …``), read as ``_result_of`` reads one. Anything else is the sub-agent's - answer, text never read for success (ADK keeps it under ``result``): an - answer that is JSON saying it failed completed. - """ - if message.status == "error": - return _result_of(message) - return message.content, True, None - - -def _delegation_call(payload: dict) -> dict | None: - """The ``task`` call a tools task runs, naming its sub-agent; else None. - - Each tool call is its own tools task (``Send``), so its input is a list - holding that one call. - """ - calls = payload.get("input") - if not isinstance(calls, list) or len(calls) != 1 or not isinstance(calls[0], dict): - return None - call = calls[0] - if call.get("name") != TASK_TOOL: - return None - subagent = (call.get("args") or {}).get("subagent_type") - return call if isinstance(subagent, str) else None - - @dataclass class _ModelCall: """One model call in flight: whose, why, on what, since when.""" @@ -522,12 +333,14 @@ def latency_ms(self) -> float: class RunCallback(AsyncCallbackHandler): - """Reports one turn's events that the stream cannot carry. + """Reports the events of a turn's run, or a sub-agent run's, that the stream cannot carry. - Attached to the turn's run config, LangChain hands it to every model call - in the run, sub-agents' and tools' included. Each event goes out through - ``live`` as it happens (the manager merges it into the turn's stream), so - it shows while the node it happened in still runs. + Attached to the run's config (the turn's root agent's, and each + sub-agent run's own: ``DeepAgentsWorkflowManager._run_agent``), LangChain + hands it to every model call in the run, its tools' included. Each event + goes out through ``live``, the turn's, as it happens (the manager merges + it into the turn's stream), so it shows while the node it happened in + still runs. - Every model call is timed, from its start to its end, and its answer marked with the milliseconds (``middleware.mark_latency``: @@ -554,7 +367,8 @@ class RunCallback(AsyncCallbackHandler): root: The root agent, for a call no agent is named on. agent_models: Each agent's resolved model, by name. llm_log: Where raw LLM traffic is written; None logs none. - live: The turn's live events, which every event goes out through. + live: The turn's live events, which every event goes out through + (and which give a failed summary's warning once a turn). budgets: Each agent's context numbers, by name, which a summary's ``LLM_USAGE`` carries; none without. ledgers: The manager's usage ledgers: a summary's usage is recorded @@ -581,8 +395,6 @@ def __init__( # Every call in flight, by run id: each is timed, and a summary's, # and every call when logging, reported as it ends. self._calls: dict[UUID, _ModelCall] = {} - # The notices given once a turn (this callback is the turn's). - self._notified: set[str] = set() async def on_chat_model_start( self, @@ -658,9 +470,8 @@ async def on_custom_event( return agent = data.get("agent") or self._root if name == SUMMARY_NOT_WRITTEN: - # Once a turn, however often its calls try again. - if SUMMARY_FAILED_CODE not in self._notified: - self._notified.add(SUMMARY_FAILED_CODE) + # Once a turn, however often its calls, and its runs', try again. + if self._live.first(SUMMARY_FAILED_CODE): text = SUMMARY_FAILED if agent == self._root else f"{agent}: {SUMMARY_FAILED}" self._emit(WorkflowEvent.error( text, error_code=SUMMARY_FAILED_CODE, recoverable=True diff --git a/src/agentic_cli/workflow/deepagents/manager.py b/src/agentic_cli/workflow/deepagents/manager.py index 9cf9a283..c5696ef6 100644 --- a/src/agentic_cli/workflow/deepagents/manager.py +++ b/src/agentic_cli/workflow/deepagents/manager.py @@ -13,7 +13,10 @@ (``tools/skills/langchain_tools.py``), with ADK's instruction appended to its prompt. With ``raw_llm_logging`` on, a turn's every model call is logged (``LLM_REQUEST``/``LLM_RESPONSE``, in the stream and in -``~/.{app_name}/logs/llm_events.jsonl``). A long-running job that finishes +``~/.{app_name}/logs/llm_events.jsonl``). A sub-agent runs when its parent's ``task`` call +delegates to it (``task_tool.build_task_tool``, the framework's +``Delegations``): its own graph, apart from its parent's stream, in the run's +own task (``_run_agent``). A long-running job that finishes resumes its conversation with a turn of its own, opened by a notification to the root agent (``resume_with_job_result``). The root agent's conversation is summarized on demand by ``compact`` (``/compact``), with its own summarization @@ -35,10 +38,12 @@ import contextlib import functools import time +import uuid from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable from deepagents.middleware.summarization import SUMMARIZATION_EVENT_KEY -from langchain_core.messages import HumanMessage +from langchain_core.messages import AIMessage, HumanMessage +from langchain_core.runnables.config import var_child_runnable_config from agentic_cli.config import BaseSettings from agentic_cli.constants import truncate @@ -59,7 +64,13 @@ validate_agent_graph, ) from agentic_cli.workflow import live_events -from agentic_cli.workflow.context import CompactResult +from agentic_cli.workflow.agents.delegate import AgentRun, RunAnswer, RunFailed +from agentic_cli.workflow.context import ( + OVERFLOW_ERROR_CODE, + CompactResult, + is_context_overflow, + subagent_overflow_message, +) from agentic_cli.workflow.deepagents.agent_builder import build_agent_tree from agentic_cli.workflow.deepagents.event_processor import ( DeepAgentsEventProcessor, @@ -67,6 +78,7 @@ usage_event, ) from agentic_cli.workflow.deepagents.mcp_tools import MCPSessions, without_clashes +from agentic_cli.workflow.deepagents.middleware import answer_outcome from agentic_cli.workflow.deepagents.sessions import ( CheckpointSessions, job_notification, @@ -79,6 +91,7 @@ summary_event, write_summary, ) +from agentic_cli.workflow.deepagents.task_tool import SHARED_KEYS from agentic_cli.workflow.deepagents.tools import to_langchain_tools from agentic_cli.workflow.events import WorkflowEvent from agentic_cli.workflow.langchain_models import build_chat_model @@ -110,9 +123,10 @@ def _with_instruction(prompt: str, instruction: str) -> str: class DeepAgentsWorkflowManager(BaseWorkflowManager): """Workflow manager on LangChain's ``create_agent`` and Deep Agents' middleware. - A coordinator delegates through Deep Agents' ``task`` tool, giving a - sub-agent only a brief; the framework's permission gate and tool-error - middleware run in every agent's stack. + A coordinator delegates through the framework's ``task`` tool, giving a + sub-agent a brief (``agents/brief.py``) and reading back its result + envelope; the framework's permission gate and tool-error middleware run + in every agent's stack. Example: configs = [ @@ -169,6 +183,8 @@ def __init__( self._sessions: CheckpointSessions | None = None self._root: CompiledStateGraph | None = None + # Every agent's graph, by name: what a sub-agent run runs on. + self._agent_graphs: dict[str, CompiledStateGraph] = {} # The root agent's summarization middleware, which compact() uses. self._root_summarization: ReportingSummarizationMiddleware | None = None @@ -258,6 +274,7 @@ async def _do_initialize(self) -> None: summarizers: dict[str, ReportingSummarizationMiddleware] = {} root = self._root_agent_name # from the graph the base validated index_wanted = self._memory_index_wanted(root) + graphs: dict[str, CompiledStateGraph] = {} self._root = build_agent_tree( self._agent_configs, chat_models={ @@ -281,8 +298,10 @@ async def _do_initialize(self) -> None: memory_index=self._memory_index_now if index_wanted else None, memory_index_cached=self._memory_index_cached if index_wanted else None, memory_index_forget=self._forget_memory_index if index_wanted else None, - runs=self.agent_runs, + delegations=lambda: self._delegations, + graphs=graphs, ) + self._agent_graphs = graphs self._root_summarization = summarizers.get(root) logger.info( @@ -392,6 +411,7 @@ def _detach_backend(self) -> list[Closer]: it even if the close is cancelled. """ self._root = None + self._agent_graphs = {} self._root_summarization = None self._pending_notices = [] sessions, self._mcp = self._mcp, MCPSessions() @@ -631,8 +651,6 @@ async def _run_turn( agent_models=self._resolved_models, session_id=ref.session_id, budgets=self._budgets, - runs=self.agent_runs, - sub_agents={config.name: config.sub_agents for config in self.agent_configs}, ledgers=self._usage_ledgers, ) live = LiveEvents() @@ -644,10 +662,12 @@ async def _run_turn( budgets=self._budgets, ledgers=self._usage_ledgers, ) + # Each item names its namespace; the processor reads only the root's + # (a graph a tool runs under the inherited config streams in its own). stream = self._root.astream( graph_input, run_config(ref, callbacks=[callback]), - stream_mode=["updates", "tasks"], + stream_mode=["updates"], subgraphs=True, ) count = 0 @@ -698,6 +718,86 @@ async def _run_turn( self._open_calls.clear(ref) logger.info("message_processed", event_count=count) + async def _run_agent(self, run: AgentRun) -> RunAnswer: + """Run one sub-agent run on its agent's graph (the base's hook, ``Delegations``'s). + + In the run's own task (``agents/delegate.py``), apart from its + caller's stream: the graph is streamed with the run's own config, + its callbacks this run's ``RunCallback``, and LangGraph's ambient + config cleared in this task (``var_child_runnable_config``), so none + of its chunks reach the caller's ``astream`` and the caller's + checkpoint namespace is not the run's. The run's events go to the + turn's live events as they are made, through a processor made for + the run. Its input is the shared state it starts from and its + messages: an inheriting run's history, then the task message. + + Returns: + Its last non-empty answer, as Deep Agents' own ``task`` read one + (Anthropic may end with an empty ``end_turn`` after its final + tool call), that answer's outcome mark + (``SubAgentOutcomeMiddleware``), and the shared keys it changed. + Its answers are the messages after its task message + (``_own_messages``): an inheriting run's history is not its own. + + Raises: + RunFailed: Its request no longer fits its model's window, still + after its summary (``subagent_overflow_message``). + Exception: Its model call failed (the provider's error). + """ + graph = self._agent_graphs[run.ref.agent] + task = HumanMessage(content=run.message, id=f"agentic-cli-task-{uuid.uuid4().hex}") + inputs: dict[str, Any] = {**run.state, "messages": [*(run.history or ()), task]} + conversation = run.conversation + processor = DeepAgentsEventProcessor( + root=self._root_agent_name, + agent_models=self._resolved_models, + session_id=conversation.session_id if conversation is not None else None, + budgets=self._budgets, + ledgers=self._usage_ledgers, + run=run.ref, + ) + callback = RunCallback( + root=self._root_agent_name, + agent_models=self._resolved_models, + llm_log=self._raw_llm_log(), + # Run outside a turn there is no one to report to. + live=live_events.current() or LiveEvents(), + budgets=self._budgets, + ledgers=self._usage_ledgers, + ) + final: dict[str, Any] = {} + detached = var_child_runnable_config.set(None) + try: + stream = graph.astream( + inputs, {"callbacks": [callback]}, stream_mode=["updates", "values"] + ) + async with contextlib.aclosing(stream) as items: + async for mode, payload in items: + if mode == "values": + final = payload + continue + for event in processor.process((), mode, payload): + live_events.report(event) + except Exception as error: + if is_context_overflow(error): + model = self._resolved_models.get(run.ref.agent) + raise RunFailed( + subagent_overflow_message( + run.ref.agent, str(model.ref) if model is not None else "the model" + ), + code=OVERFLOW_ERROR_CODE, + ) from error + raise + finally: + var_child_runnable_config.reset(detached) + own = _own_messages(final.get("messages") or [], task.id) + answers = [message for message in own if isinstance(message, AIMessage)] + return RunAnswer( + text=_last_text(answers), + outcome=answer_outcome(answers[-1]) if answers else None, + state=_changed(final, inputs), + ) + def _recording( self, ref: "SessionRef", @@ -835,3 +935,47 @@ async def recent_messages( if self._sessions is None: return [] return await self._sessions.recent(self.session_ref(session_id, user_id), limit) + + +def _own_messages(messages: list[Any], task_id: str | None) -> list[Any]: + """The messages a run wrote: those after its task message, found by its id. + + An inheriting run's messages start with its caller's conversation, whose + replies are not its answers. The task message is found by id, not by + position: ``InterruptedCallsMiddleware.before_agent`` may answer calls + left open in that conversation, inserting messages before it (the list + rewritten, each message keeping its id). Were it missing (no rewrite + drops an id), none would be the run's: an empty answer, never its + caller's. + """ + for index, message in enumerate(messages): + if task_id is not None and getattr(message, "id", None) == task_id: + return messages[index + 1:] + return [] + + +def _last_text(answers: list[AIMessage]) -> str: + """The text of the last of ``answers`` that has any, as Deep Agents' ``task`` reads it.""" + for message in reversed(answers): + text = message.text.rstrip() if message.text else "" + if text: + return text + return "" + + +def _changed(final: dict[str, Any], inputs: dict[str, Any]) -> dict[str, Any]: + """The shared keys ``final`` holds that differ from what the run started from. + + Deep Agents' ``task`` rule (``deepagents.middleware.subagents._is_unchanged``, + private, copied): a key returned exactly as it was received is no + change; ``is True`` takes an ambiguous comparison (an array's) as one. + """ + changed: dict[str, Any] = {} + for key in SHARED_KEYS: + if key not in final: + continue + value = final[key] + if key in inputs and (value is inputs[key] or (value == inputs[key]) is True): + continue + changed[key] = value + return changed diff --git a/src/agentic_cli/workflow/deepagents/middleware.py b/src/agentic_cli/workflow/deepagents/middleware.py index 527e9e87..6d7ec1c7 100644 --- a/src/agentic_cli/workflow/deepagents/middleware.py +++ b/src/agentic_cli/workflow/deepagents/middleware.py @@ -8,8 +8,7 @@ - :class:`ToolResultCapMiddleware`, inside the gate, cuts a tool result too big for the context, as ADK's ``ToolResultCapPlugin`` does. - :class:`ToolCallErrorMiddleware`, inside the cap, gives a tool that raised - the error result ADK's ``ToolErrorPlugin`` gives, and a failed delegation - the one ADK's delegation tool gives, so the turn goes on. + the error result ADK's ``ToolErrorPlugin`` gives, so the turn goes on. - :class:`ActiveToolCallMiddleware`, innermost, runs each tool as the active tool call, which links a job the tool starts to its call. - :class:`ForeignReasoningMiddleware`, on the model side, sends no model @@ -39,7 +38,7 @@ import asyncio import dataclasses import json -from collections.abc import Awaitable, Callable, Collection, Mapping +from collections.abc import Awaitable, Callable from pathlib import Path from typing import Any @@ -65,26 +64,17 @@ from langgraph.runtime import Runtime from langgraph.types import Command -from agentic_cli.constants import truncate from agentic_cli.logging import Loggers from agentic_cli.models import ProviderKind from agentic_cli.paths import resolve_path -from agentic_cli.tools._core.delegation import TASK_TOOL from agentic_cli.tools.registry import ToolDefinition, get_registry, identify_tool -from agentic_cli.workflow import live_events from agentic_cli.workflow.agents.outcome import ( REFUSED, cut_off, outcome_of, refusal_notice, ) -from agentic_cli.workflow.agents.runs import SUBAGENT_ERROR_PREFIX, AgentRuns -from agentic_cli.workflow.context import ( - OVERFLOW_ERROR_CODE, - is_context_overflow, - subagent_overflow_message, -) -from agentic_cli.workflow.events import WorkflowEvent +from agentic_cli.workflow.context import is_context_overflow from agentic_cli.workflow.interrupts import MARKER, OpenCalls from agentic_cli.workflow.langchain_models import without_foreign_reasoning from agentic_cli.workflow.outside_content import OutsideContentMarks, brings_outside_content @@ -92,18 +82,11 @@ from agentic_cli.workflow.service_registry import PERMISSION_ENGINE, get_service from agentic_cli.workflow.sessions import ( ToolCallRef, - get_active_run, get_active_turn, - reset_active_run, reset_active_tool_call, - set_active_run, set_active_tool_call, ) -from agentic_cli.workflow.tool_errors import ( - MAX_TOOL_ERROR, - tool_error_result, - unknown_tool_result, -) +from agentic_cli.workflow.tool_errors import tool_error_result, unknown_tool_result from agentic_cli.workflow.tool_output import cap_tool_result, is_saved_output logger = Loggers.workflow() @@ -315,9 +298,10 @@ class ToolResultCapMiddleware(AgentMiddleware): What it reads of a result: - - A ``ToolMessage`` whose content is a string: a JSON object (a framework - tool's dict) is cut as a dict and serialized again; other text is cut - as a string. + - A ``ToolMessage`` whose content is a string: cut as the cap cuts a + string, so a JSON object (a framework tool's dict, a delegation's + envelope) is cut as a dict and given back as JSON, as on ADK; other + text is cut as a string. - Content that is a list: its text blocks are joined into one, cut as a string, which stands where the first was, with its other keys; other blocks (images) are kept in their order, so one that sat between two @@ -399,14 +383,8 @@ def _message(self, message: ToolMessage, name: str, source: Path | None) -> Tool return message.model_copy(update={"content": capped}) def _text(self, text: str, name: str, source: Path | None) -> str: - if len(text) <= self.max_chars: - return text - result = _json_object(text) - if result is None: - return self._cap(text, name, source) - # Sent as the cap measured it, cut or not: the tool's own JSON may be - # several times longer (\uXXXX escapes, indentation). - return json.dumps(self._cap(result, name, source), ensure_ascii=False) + # The cap's own rule: a JSON object is cut as a dict, given back as JSON. + return self._cap(text, name, source) def _blocks(self, blocks: list, name: str, source: Path | None) -> list: texts = [text for text in map(_block_text, blocks) if text is not None] @@ -435,17 +413,6 @@ def _cap(self, result: Any, name: str, source: Path | None) -> Any: ) -def _json_object(text: str) -> dict | None: - """The dict ``text`` holds as JSON, or None.""" - if not text.lstrip().startswith("{"): - return None - try: - value = json.loads(text) - except ValueError: - return None - return value if isinstance(value, dict) else None - - def _block_text(block: Any) -> str | None: """A content block's text, or None when it is not a text block.""" if isinstance(block, str): @@ -460,25 +427,6 @@ def _error_message(call: ToolCall, error: Exception) -> ToolMessage: return error_tool_message(tool_error_result(call["name"], error), call) -def _is_delegation(tool: BaseTool | None) -> bool: - """Whether ``tool`` is the framework's ``task`` tool (by identity).""" - declaration = get_registry().get(TASK_TOOL) - return declaration is not None and identify_tool(tool) is declaration - - -def _own_sub_agent(call: ToolCall, sub_agents: frozenset[str] | None) -> str | None: - """The sub-agent a ``task`` call runs, when it is one of the caller's own; else None. - - Only such a call is a run: a call to any other type runs no sub-agent - (Deep Agents answers that it does not exist). ``sub_agents`` None takes - every call's ``subagent_type`` as the caller's own. - """ - subagent = (call.get("args") or {}).get("subagent_type") - if not isinstance(subagent, str): - return None - return subagent if sub_agents is None or subagent in sub_agents else None - - class ToolCallErrorMiddleware(AgentMiddleware): """A tool that raises fails its call, not the turn. @@ -486,44 +434,11 @@ class ToolCallErrorMiddleware(AgentMiddleware): the exception type and message, cut to 500 characters, logged as ``tool_raised``). Only ``Exception`` is caught: cancelling (Ctrl+C) still cancels, and LangGraph's control flow (``GraphBubbleUp``: interrupts, - parent commands) passes through. - - A failed delegation is not a tool error. The sub-agent's own stack already - turned its tools' exceptions into results, so what escapes ``task`` is the - sub-agent's model or run failing (a summary it could not write among - them). The call is answered as ADK's delegation tool answers it, - ``Error running sub-agent: <reason>`` (``status="error"``), and the user - is told at once, as ADK's event processor tells a sub-agent's failed - model call: one recoverable ``ERROR``, ``<agent> failed: <reason>``, - through the turn's live events, the sub-agent's run's (given the - manager's runs). The coordinator reads why and carries on; the turn ends - only when the root's own model or run fails. A request too long for the - sub-agent's model, still after its summary, is warned of in ADK's words, - ``<agent>: the request no longer fits <model>'s context window.``, with - ``error_code`` ``CONTEXT_OVERFLOW``. - - Args: - runs: The manager's sub-agent runs, which name the run a failed - delegation's ``ERROR`` belongs to; none without. - sub_agents: The agent's own sub-agents: only a ``task`` call to one - of them is a run, as ``ActiveToolCallMiddleware`` has it; None - takes every call's ``subagent_type`` as the agent's own. - models: Each sub-agent's model reference, as the user is told it, by - name, for an overflow's warning ("the model" for one not named). + parent commands) passes through. A delegation never raises for its + sub-agent: the framework's ``task`` answers a failed run with its + envelope (``agents/delegate.py``). """ - def __init__( - self, - runs: AgentRuns | None = None, - *, - sub_agents: Collection[str] | None = None, - models: Mapping[str, str] | None = None, - ) -> None: - super().__init__() - self._runs = runs - self._sub_agents = None if sub_agents is None else frozenset(sub_agents) - self._models = dict(models or {}) - async def awrap_tool_call( self, request: ToolCallRequest, @@ -534,56 +449,8 @@ async def awrap_tool_call( except GraphBubbleUp: raise except Exception as error: - if _is_delegation(request.tool): - return self._failed_delegation(request.tool_call, error) return _error_message(request.tool_call, error) - def _failed_delegation(self, call: ToolCall, error: Exception) -> ToolMessage: - """The ``task`` call's answer for a sub-agent that failed with ``error``; warns the user. - - The reason is the error's text, else its type's name. The ``ERROR`` - is the report: the log is for diagnosis, at info, its traceback at - debug, so nothing is said twice over the CLI's prompt. - """ - reason = str(error) or type(error).__name__ - subagent = (call.get("args") or {}).get("subagent_type") - agent = subagent if isinstance(subagent, str) else call["name"] - logger.info( - "subagent_failed", - agent=agent, - error_type=type(error).__name__, - error=truncate(reason, MAX_TOOL_ERROR), - ) - logger.debug("subagent_failed", exc_info=error) - if is_context_overflow(error): - # ADK's overflow handler's warning. What differs: ADK answers - # the sub-agent's model call with text ("I could not do this - # task: ..."), so its run completes; here the parent reads the - # error, and the run fails. - warning = WorkflowEvent.error( - subagent_overflow_message(agent, self._models.get(agent, "the model")), - error_code=OVERFLOW_ERROR_CODE, - recoverable=True, - ) - else: - warning = WorkflowEvent.error( - f"{agent} failed: {reason}", error_code=type(error).__name__, recoverable=True - ) - warning.metadata["agent"] = agent - own = _own_sub_agent(call, self._sub_agents) - if self._runs is not None and own is not None: - # The run the task call started (still open: its result is this). - warning.run = self._runs.run_for( - get_active_turn(), get_active_run(), call["id"], own - ) - live_events.report(warning) - return ToolMessage( - content=f"{SUBAGENT_ERROR_PREFIX}{reason}", - tool_call_id=call["id"], - name=call["name"], - status="error", - ) - class InterruptedCallsMiddleware(AgentMiddleware): """Every call gets one result, the ones a stopped turn left open too. @@ -599,9 +466,9 @@ class InterruptedCallsMiddleware(AgentMiddleware): On the main agent, a turn the user stopped before any reply leaves ``MARKER`` as its reply, so the next turn answers only the new message. Each call is recorded and answered as the run's that made it - (``OpenCalls``, by the active run: a sub-agent's whole stack runs inside - its coordinator's ``task`` call), so a sub-agent's call never answers its - parent's delegation of the same id. + (``OpenCalls``, by the active run: a sub-agent's run is the active one in + the task it runs in, ``agents/delegate.py``), so a sub-agent's call never + answers its parent's delegation of the same id. Args: open_calls: The manager's record of its calls. @@ -706,43 +573,20 @@ class ActiveToolCallMiddleware(AgentMiddleware): ``JobManager.submit`` reads it, so a job a long-running tool starts is linked to that call even when the tool, written for ADK, reads its call id from a ``tool_context`` that is None here. Each call runs in its own - task, so parallel calls never see each other's; a sub-agent's call runs - inside its coordinator's ``task`` call and restores it when done. - - Given the manager's runs, a ``task`` call to one of the agent's own - ``sub_agents`` is also the run of the sub-agent it starts - (``workflow.sessions.set_active_run``, named by ``AgentRuns.run_for`` - under the run it is made in): the whole sub-agent runs inside the call, - so its model calls, tool calls, permission checks and questions see it. - A ``task`` call to any other type runs no sub-agent (Deep Agents answers - that it does not exist), so it is no run. ``sub_agents`` None takes every - ``task`` call's ``subagent_type`` as the agent's own. + task, so parallel calls never see each other's. A sub-agent's run, which + a ``task`` call starts, runs in a task of its own with no tool call + active (``agents/delegate.py``): its own calls set theirs. """ - def __init__( - self, runs: AgentRuns | None = None, *, sub_agents: Collection[str] | None = None - ) -> None: - super().__init__() - self._runs = runs - self._sub_agents = None if sub_agents is None else frozenset(sub_agents) - async def awrap_tool_call( self, request: ToolCallRequest, handler: Callable[[ToolCallRequest], Awaitable[_ToolResult]], ) -> _ToolResult: - call = request.tool_call - token = set_active_tool_call(_call_ref(call)) - run_token = None - subagent = _own_sub_agent(call, self._sub_agents) - if self._runs is not None and call["name"] == TASK_TOOL and subagent is not None: - run = self._runs.run_for(get_active_turn(), get_active_run(), call["id"], subagent) - run_token = set_active_run(run) + token = set_active_tool_call(_call_ref(request.tool_call)) try: return await handler(request) finally: - if run_token is not None: - reset_active_run(run_token) reset_active_tool_call(token) diff --git a/src/agentic_cli/workflow/deepagents/task_tool.py b/src/agentic_cli/workflow/deepagents/task_tool.py new file mode 100644 index 00000000..31a72a65 --- /dev/null +++ b/src/agentic_cli/workflow/deepagents/task_tool.py @@ -0,0 +1,106 @@ +"""Deep Agents' ``task`` tool: the framework's delegation, as a LangChain tool. + +``build_task_tool`` makes a delegating agent's ``task``. Its schema and its +description are the framework's (``agents/brief.py``: ``task_parameters``, +``task_description``), as ADK's ``TaskTool``'s are, and a call hands its +arguments, as the model wrote them, to the manager's ``Delegations`` +(``agents/delegate.py``): it reads the brief, runs the sub-agent +(``DeepAgentsWorkflowManager._run_agent``, apart from this agent's stream) +and returns the result envelope. The call is answered with the envelope as +JSON (unescaped, as ADK's), one ``ToolMessage``, and the shared state the run +changed in the same ``Command``. + +The shared state is the conversation's plan, tasks and outside-content mark +(``SHARED_KEYS``): a run starts from its caller's, and what it changes comes +back, as Deep Agents' own ``task`` handed it on. An inheriting type sees its +caller's effective conversation (the root's): its messages with its summary +applied, without the message that called ``task`` (``inherited_messages``). + +The framework built the tool, so it binds it to the ``task`` declaration +(``tools/_core/delegation.py``): the permission gate knows it by identity. +""" + +from __future__ import annotations + +import json +from collections.abc import Callable, Mapping +from typing import TYPE_CHECKING, Any + +from deepagents.middleware.summarization import ( + SUMMARIZATION_EVENT_KEY, + SummarizationMiddleware, +) +from langchain_core.messages import AIMessage, AnyMessage, ToolMessage +from langchain_core.tools import StructuredTool +from langgraph.prebuilt import ToolRuntime +from langgraph.types import Command + +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 task_description, task_parameters +from agentic_cli.workflow.agents.delegate import DelegationRequest +from agentic_cli.workflow.sessions import get_active_run + +if TYPE_CHECKING: + from agentic_cli.workflow.agents.delegate import Delegations + from agentic_cli.workflow.config import AgentConfig + +#: The state a run shares with its caller (``state.AgentCliState``): it starts +#: from the caller's, and the keys it changes come back with its result. +SHARED_KEYS = ("plan", "tasks", "outside_content") + + +def build_task_tool( + agent: str, types: Mapping[str, AgentConfig], delegations: Callable[[], Delegations] +) -> StructuredTool: + """``agent``'s ``task`` tool, which starts a run of one of ``types``. + + Args: + agent: The delegating agent's name. + types: Its sub-agents, by name: what ``agent_type`` may name. + delegations: The manager's delegations, asked for at each call. + """ + + async def task(runtime: ToolRuntime, **arguments: Any) -> Command: + state = runtime.state + delegated = await delegations().delegate(DelegationRequest( + caller=get_active_run(), + caller_agent=agent, + call_id=runtime.tool_call_id, + arguments=arguments, + state={key: state[key] for key in SHARED_KEYS if key in state}, + history=lambda: inherited_messages(state), + )) + answer = ToolMessage( + json.dumps(delegated.result, ensure_ascii=False), + tool_call_id=runtime.tool_call_id, + name=TASK_TOOL, + ) + return Command(update={**delegated.state, "messages": [answer]}) + + tool = StructuredTool.from_function( + coroutine=task, + name=TASK_TOOL, + description=task_description(types, delegations().policy), + args_schema=task_parameters(types), + infer_schema=False, + ) + bind_tool_identity(tool, get_registry().get(TASK_TOOL)) + return tool + + +def inherited_messages(state: Mapping[str, Any]) -> list[AnyMessage]: + """The conversation an inheriting run reads: ``state``'s messages as its caller's model sees them. + + The caller's summary applied (Deep Agents' + ``SummarizationMiddleware._apply_event_to_messages``, private: a contract + test pins it), without the caller's last message when it is the one + that called ``task`` (an AI message with tool calls), as a Deep Agents + fork's history is. + """ + messages = list(state.get("messages") or ()) + if messages and isinstance(messages[-1], AIMessage) and messages[-1].tool_calls: + messages.pop() + return SummarizationMiddleware._apply_event_to_messages( + messages, state.get(SUMMARIZATION_EVENT_KEY) + ) diff --git a/src/agentic_cli/workflow/events.py b/src/agentic_cli/workflow/events.py index 0b199652..f4882825 100644 --- a/src/agentic_cli/workflow/events.py +++ b/src/agentic_cli/workflow/events.py @@ -201,26 +201,38 @@ def agent_run( error: str | None = None, partial: bool = False, usage: dict[str, dict[str, int]] | None = None, + brief: dict[str, str] | None = None, + started_by: str | None = None, + mode: str | None = None, + cancelled_by: str | None = None, ) -> "WorkflowEvent": """Create a sub-agent run's event: its start, or how it ended (``AGENT_RUN``). ``run`` is the sub-agent's run, and ``metadata["status"]`` says which: - ``started`` (with its ``title``), then one end status (``completed``, + ``started`` (with its ``title``, its ``brief``, who it was + ``started_by`` and its ``mode``), then one end status (``completed``, ``failed``, ``refused``, ``cancelled``, ``interrupted``: the constants of ``workflow/agents/runs.py``) with the first of its ``result``, its - ``error``, whether the result is ``partial`` and the tokens the run - used (``usage``). ``metadata["agent"]`` is the sub-agent, as on every - event an agent wrote. + ``error``, whether the result is ``partial``, the tokens the run + used (``usage``) and, for a cancelled run, who cancelled it. + ``metadata["agent"]`` is the sub-agent, as on every event an agent + wrote. Args: ref: The sub-agent's run. status: ``started`` or an end status. - title: A start's title: the first line of the request. + title: A start's title: the brief's. call_id: The parent's call that started the run. result: An end's result, its first characters. error: Why a run that did not complete ended. partial: Whether the result is cut short (a reply at its output limit). usage: An end's tokens, by model: ``{model: {"input": ..., "output": ...}}``. + brief: A start's brief: its filled fields, the title first + (``agents/brief.py::Brief.fields``). + started_by: Who started the run: ``agent:<instance>`` (``agent:root`` + for the root). + mode: How it runs: ``blocking`` (its parent waits for it). + cancelled_by: A cancelled run's canceller: ``parent``, ``user`` or ``limit``. """ metadata: dict[str, Any] = {"status": status, "agent": ref.agent, "partial": partial} if title is not None: @@ -233,6 +245,14 @@ def agent_run( metadata["error"] = error if usage is not None: metadata["usage"] = usage + if brief is not None: + metadata["brief"] = dict(brief) + if started_by is not None: + metadata["started_by"] = started_by + if mode is not None: + metadata["mode"] = mode + if cancelled_by is not None: + metadata["cancelled_by"] = cancelled_by return cls( type=EventType.AGENT_RUN, content=f"{ref.instance} {status}", diff --git a/src/agentic_cli/workflow/sessions.py b/src/agentic_cli/workflow/sessions.py index 8a53952a..c6515a33 100644 --- a/src/agentic_cli/workflow/sessions.py +++ b/src/agentic_cli/workflow/sessions.py @@ -274,9 +274,9 @@ def root_run(agent: str) -> RunRef: return RunRef(agent=agent, instance="root", run=None, parent_run=None, depth=0) -# The sub-agent run whose call is in progress in this context: set inside a -# sub-agent's run (ADK: as the agent starts, from its branch; Deep Agents: -# around its coordinator's ``task`` call), so its model calls, tool calls, +# The sub-agent run whose call is in progress in this context: set by the +# framework's delegation in the run's own task (``agents/delegate.py``, +# ``Delegations._in_run``), on both backends, so its model calls, tool calls, # permission checks and questions see it. None in the root's own calls. A # ContextVar for the same reason as the active turn: parallel runs each run # in their own context and never see one another's. diff --git a/src/agentic_cli/workflow/tool_output.py b/src/agentic_cli/workflow/tool_output.py index 27e39cf0..7f492d97 100644 --- a/src/agentic_cli/workflow/tool_output.py +++ b/src/agentic_cli/workflow/tool_output.py @@ -18,7 +18,13 @@ tool's own flag (it is truthy, as the flag would be). When strings alone cannot make it fit (many small values), the result becomes its JSON text, cut the same way, under ``result``, with ``success`` and ``error`` kept. -- A string is cut the same way, with the note appended. +- A string that holds a JSON object (a framework tool's dict as JSON text: a + delegation's envelope, a Deep Agents ``ToolMessage``'s content) is cut as + that dict and given back as its JSON text, written with + ``ensure_ascii=False`` as it is measured, so what reaches the model is + JSON still, its keys kept and the note under ``truncated``. One rule for + both backends. +- Any other string is cut the same way, with the note appended. - Anything else is wrapped as ``{"result": value}`` and cut as a dict. The saved file is meant to be read in pages of lines: a string is saved as it @@ -100,7 +106,8 @@ def cap_tool_result( Returns ``result`` itself when its serialized text fits (a string as it is, anything else as JSON). Otherwise returns a cut copy; ``result`` is - never changed. + never changed. A string holding a JSON object comes back as that + object's JSON text, cut, or whole when it fits unescaped. Args: result: What the tool returned. @@ -114,6 +121,14 @@ def cap_tool_result( text = _serialize(result) if text is None or len(text) <= max_chars: return result + held = json_object(result) if isinstance(result, str) else None + if held is not None: + # Sent as the cap measured it, cut or not: the text may be several + # times longer than its dict (\uXXXX escapes, indentation). + capped = cap_tool_result( + held, tool_name=tool_name, max_chars=max_chars, folder=folder, source=source + ) + return json.dumps(capped, ensure_ascii=False, default=str) name = f"{_safe_name(tool_name)}-{uuid.uuid4().hex[:12]}.txt" display = _display(source if source is not None else folder / name) @@ -149,6 +164,17 @@ def cap_tool_result( return {**cut, "truncated": note} +def json_object(text: str) -> dict | None: + """The dict ``text`` holds as JSON, or None (no object, or no JSON at all).""" + if not text.lstrip().startswith("{"): + return None + try: + value = json.loads(text) + except (ValueError, RecursionError): + return None + return value if isinstance(value, dict) else None + + def is_saved_output(path: Path, folder: Path) -> bool: """Whether ``path`` is an output the cap saved in ``folder``. diff --git a/tests/cli/test_agents_command.py b/tests/cli/test_agents_command.py index b98e0545..c86d57bc 100644 --- a/tests/cli/test_agents_command.py +++ b/tests/cli/test_agents_command.py @@ -3,8 +3,8 @@ ``/agents`` is a table of the runs, each followed by the runs it started, a level deeper: instance, type, status, run, title, tokens in/out, time. ``/agents <id>`` shows one instance or run: its type, parent and title, then -each run's status and time, the first lines of its result, its error and its -tokens by model. The runs are a real manager's records, filled as its event +each run's status and time, its brief's other fields, the first lines of its +result, its error and its tokens by model. The runs are a real manager's records, filled as its event processors fill them (``AgentRuns.observe`` under the conversation's turn), and the tokens its usage ledger's; nothing reaches a provider. """ @@ -72,10 +72,11 @@ def __init__(self, manager: GoogleADKWorkflowManager, conversation: SessionRef) self.conversation = conversation def start(self, agent: str, call_id: str, request: str, *, at: int, - parent: RunRef | None = None) -> RunRef: + parent: RunRef | None = None, brief: dict[str, str] | None = None) -> RunRef: ref = self.manager.agent_runs.run_for(self.conversation, parent, call_id, agent) + title = request.splitlines()[0] self._observe(WorkflowEvent.agent_run( - ref, "started", title=request.splitlines()[0], call_id=call_id + ref, "started", title=title, call_id=call_id, brief=brief, ), at) return ref @@ -225,6 +226,28 @@ async def test_a_run_by_its_id_under_the_run_that_started_it(self, manager): (" Tokens", f"{SONNET}: 800 in / 2k out · 1 call"), ] + async def test_a_runs_brief_each_field_it_filled(self, manager): + runs = Runs(manager, manager.session_ref("s1")) + ref = runs.start("researcher", "c1", "Find X", at=0, brief={ + "title": "Find X", "objective": "Find X in the docs.", + "deliverable": "One number.", "done_when": "X is [named].", + }) + runs.end(ref, "completed", at=5, result="X is 42.") + + session = await agents(manager, "researcher-1") + + (panel,) = session.add_rich.call_args.args + assert rows_of(panel.renderable) == [ + ("Type", "researcher"), + ("Parent", "root"), + ("Title", "Find X"), + ("Run #1", "completed · 5s"), + (" Objective", "Find X in the docs."), + (" Deliverable", "One number."), + (" Done when", "X is [named]."), # data, never markup + (" Result", "X is 42."), + ] + async def test_a_failed_run_says_why(self, manager): crew_ran(manager) diff --git a/tests/integration/test_context_live.py b/tests/integration/test_context_live.py index 7bb6ffca..f85e91a1 100644 --- a/tests/integration/test_context_live.py +++ b/tests/integration/test_context_live.py @@ -393,10 +393,18 @@ def _team(**extra) -> list[AgentConfig]: ] +def _envelopes_of(events, agent: str) -> list[dict]: + """The envelopes of ``agent``'s runs, as its coordinator read them (``task``'s results).""" + return [ + e.metadata["result"] for e in find_tool_results(events, "task") + if isinstance(e.metadata.get("result"), dict) + and e.metadata["result"].get("agent", "").startswith(f"{agent}-") + ] + + def _answers_of(events, agent: str, backend: str) -> list[str]: - """What ``agent`` answered its coordinator (the delegation call's results).""" - tool = agent if backend == "adk" else "task" - return [str(e.metadata.get("result")) for e in find_tool_results(events, tool)] + """What ``agent`` answered its coordinator (its runs' results), the same on ``backend``'s.""" + return [str(envelope.get("result")) for envelope in _envelopes_of(events, agent)] def _reply(events) -> str: @@ -635,7 +643,8 @@ async def test_a_sub_agents_real_overflow_is_one_warning_and_the_coordinator_ans (True, "reader") ], [e.content for e in errors] assert "no longer fits" in errors[0].content - assert "I could not do this task" in " ".join(_answers_of(events, "reader", "adk")) + (envelope,) = _envelopes_of(events, "reader") + assert (envelope["status"], envelope["error"]) == ("failed", errors[0].content) assert _reply(events).strip(), "the coordinator did not answer" diff --git a/tests/integration/test_deepagents_turns.py b/tests/integration/test_deepagents_turns.py index b1b8de8d..8e12606c 100644 --- a/tests/integration/test_deepagents_turns.py +++ b/tests/integration/test_deepagents_turns.py @@ -191,7 +191,8 @@ def calls(*uses: tuple[str, dict, str]) -> object: def delegate(subagent: str, brief: str, call_id: str) -> tuple[str, dict, str]: - return ("task", {"description": brief, "subagent_type": subagent}, call_id) + """A ``task`` call delegating ``brief`` to ``subagent``: its title and objective.""" + return ("task", {"agent_type": subagent, "title": brief, "objective": brief}, call_id) def bad_request(message: str = "The provider refused the request.") -> httpx.Response: @@ -294,7 +295,7 @@ async def test_a_sub_agent_asks_is_denied_survives_a_raise_and_answers( assert {e.metadata["agent"] for e in (allowed, denied, raised)} == {"worker"} assert [e.content for e in of(events, EventType.TEXT)] == ["Worker done.", "All done."] (delegation,) = results(events, "task") - assert (delegation.metadata["agent"], delegation.metadata["result"]) == ( + assert (delegation.metadata["agent"], delegation.metadata["result"]["result"]) == ( "lead", "Worker done." ) # The worker read every outcome as a result, the error ones flagged. @@ -327,7 +328,7 @@ def reply(input_tokens: int, block: dict) -> dict: return {**anthropic_message(block, model="claude-opus-4-7"), "stop_reason": stop, "usage": {"input_tokens": input_tokens, "output_tokens": 10}} - brief = {"description": "Look it up.", "subagent_type": "worker"} + brief = {"agent_type": "worker", "title": "Look it up", "objective": "Look it up."} claude = Claude(**{ "Lead.": [ reply(5000, {"type": "tool_use", "id": "t1", "name": "task", "input": brief}), @@ -645,12 +646,16 @@ async def test_parallel_delegation(hermetic, monkeypatch): await manager.cleanup() assert of(events, EventType.ERROR) == [] - assert sorted(e.metadata["result"] for e in results(events, "task")) == [ + # task as Claude is sent it: the brief's schema, as on ADK. + (sent,) = [t for t in claude.bodies("Lead.")[0]["tools"] if t["name"] == "task"] + assert sent["input_schema"]["required"] == ["agent_type", "title", "objective"] + assert sent["input_schema"]["properties"]["agent_type"]["enum"] == ["researcher", "writer"] + assert sorted(e.metadata["result"]["result"] for e in results(events, "task")) == [ "Draft done.", "Research done." ] assert {e.metadata["agent"] for e in results(events, "task")} == {"lead"} lead_answers = claude.bodies("Lead.")[1]["messages"][-1]["content"] - assert sorted((b["tool_use_id"], b["content"]) for b in lead_answers + assert sorted((b["tool_use_id"], json.loads(b["content"])["result"]) for b in lead_answers if b.get("type") == "tool_result") == [ ("t1", "Research done."), ("t2", "Draft done.") ] @@ -690,15 +695,19 @@ async def test_subagent_model_error_then_next_turn(hermetic, monkeypatch): (error,) = of(failed, EventType.ERROR) assert (error.metadata["agent"], error.metadata["recoverable"]) == ("worker", True) - assert error.content.startswith("worker failed: ") + assert error.content.startswith("worker-1 failed: ") assert "refused" in error.content - # The coordinator read why, as an error result, and answered in the same turn. + # The coordinator read why, in the run's envelope, and answered in the same turn. assert [e.content for e in of(failed, EventType.TEXT)] == ["Sorry, the worker failed."] read = claude.bodies("Lead.")[1]["messages"] results_sent = [b for m in read if isinstance(m["content"], list) for b in m["content"] if b.get("type") == "tool_result"] - assert [(b["tool_use_id"], b.get("is_error")) for b in results_sent] == [("t1", True)] - assert "Error running sub-agent: " in json.dumps(results_sent[0]["content"]) + assert [b["tool_use_id"] for b in results_sent] == ["t1"] + # Not flagged as the tool's error, as on ADK: the envelope says it failed. + assert not results_sent[0].get("is_error") + sent = json.loads(results_sent[0]["content"]) + assert (sent["status"], sent["success"]) == ("failed", False) + assert "The worker's request was refused." in sent["error"] # The checkpoint holds the whole turn. assert [m.type for m in state["messages"]] == ["human", "ai", "tool", "ai"] diff --git a/tests/integration/test_interrupted_calls.py b/tests/integration/test_interrupted_calls.py index 8cbb04fb..6228f801 100644 --- a/tests/integration/test_interrupted_calls.py +++ b/tests/integration/test_interrupted_calls.py @@ -482,12 +482,9 @@ async def test_a_cancel_during_the_model_call_leaves_a_note(hermetic, monkeypatc async def test_a_delegation_cut_off_in_its_sub_agent_is_answered_as_interrupted( hermetic, monkeypatch, backend ): - delegation = "researcher" if backend == "adk" else "task" - brief = {"request": "Look."} if backend == "adk" else { - "description": "Look.", "subagent_type": "researcher", - } + brief = {"agent_type": "researcher", "title": "Look", "objective": "Look."} claude = serve(monkeypatch, Claude( - Coordinate=[calls((delegation, brief, "toolu_d")), say("Back again.")], + Coordinate=[calls(("task", brief, "toolu_d")), say("Back again.")], Research=[calls(("ic_wait", {}, "toolu_w"))], ), backend) manager = manager_for(backend, [ @@ -677,15 +674,13 @@ async def saved_tasks(manager, backend: str, session_id: str = "s") -> list: @pytest.mark.parametrize("backend", BACKENDS) async def test_a_failed_delegation_keeps_its_siblings_results(hermetic, monkeypatch, backend): - """The sub-agent's model fails beside a save_tasks that returned: on Deep - Agents the turn fails (on ADK the coordinator is told and goes on). The - next turn sends save_tasks' own result, and its tasks are saved.""" + """The sub-agent's model fails beside a save_tasks that returned: the + coordinator is told and goes on, on both backends. The next turn sends + save_tasks' own result, and its tasks are saved.""" tasks = [{"description": "Brew tea", "status": "in_progress"}] - delegation = ("researcher", {"request": "Look."}) if backend == "adk" else ( - "task", {"description": "Look.", "subagent_type": "researcher"}) - coordinate = [calls(("save_tasks", {"tasks": tasks}, "toolu_t"), (*delegation, "toolu_d"))] - if backend == "adk": - coordinate.append(say("The research failed.")) + delegation = ("task", {"agent_type": "researcher", "title": "Look", "objective": "Look."}) + coordinate = [calls(("save_tasks", {"tasks": tasks}, "toolu_t"), (*delegation, "toolu_d")), + say("The research failed.")] claude = serve(monkeypatch, Claude( Coordinate=[*coordinate, say("Back again.")], Research=[bad_request("The worker's model failed.")], diff --git a/tests/integration/test_live_deepagents.py b/tests/integration/test_live_deepagents.py index 99a50ba2..8c8a603f 100644 --- a/tests/integration/test_live_deepagents.py +++ b/tests/integration/test_live_deepagents.py @@ -104,7 +104,7 @@ async def test_delegation_and_its_answer(listed, tmp_path): assert_no_errors(events) (delegation, *_) = find_tool_calls(events, "task") - assert delegation.metadata["tool_args"]["subagent_type"] == "calculator" + assert delegation.metadata["tool_args"]["agent_type"] == "calculator" assert find_tool_results(events, "task"), "the task call got no result" assert {e.metadata["agent"] for e in events} == {"coordinator", "calculator"} assert "42" in _text(events) diff --git a/tests/test_adk_event_processor.py b/tests/test_adk_event_processor.py index 5b4c5a4e..6cda1ec1 100644 --- a/tests/test_adk_event_processor.py +++ b/tests/test_adk_event_processor.py @@ -8,6 +8,7 @@ from agentic_cli.workflow.adk.event_processor import ADKEventProcessor from agentic_cli.workflow.context import ContextBudget from agentic_cli.workflow.events import EventType +from agentic_cli.workflow.sessions import RunRef class TestThinkingDetectionInline: @@ -104,21 +105,20 @@ async def test_the_users_text_is_nobodys_activity(self): assert "subagent" not in events[EventType.TEXT].metadata assert "purpose" not in events[EventType.LLM_USAGE].metadata - async def test_a_sub_agents_failure_is_a_warning_naming_it(self): - # The coordinator carries on (ADK hands it "Error running sub-agent: - # …"), so the user is told why, as a warning. + async def test_a_sub_agents_failure_is_its_runs_to_report(self): + # A sub-agent run's failure ends its run failed, and the framework's + # delegation warns the user once (agents/delegate.py): no processor + # reports it, the conversation's or the run's. failed = Event( author="researcher", invocation_id="i1", error_code="BadRequestError", error_message="Error code: 400 - max_tokens: 100000 > 64000", ) + run = RunRef(agent="researcher", instance="researcher-1", run="researcher-1#1", + parent_run=None, depth=1) - (event,) = [e async for e in ADKEventProcessor(model="m", root="coordinator") - .process_event(failed, "s1")] - - assert event.type is EventType.ERROR - assert event.content == "researcher failed: Error code: 400 - max_tokens: 100000 > 64000" - assert (event.metadata["error_code"], event.metadata["recoverable"], - event.metadata["agent"]) == ("BadRequestError", True, "researcher") + for processor in (ADKEventProcessor(model="m", root="coordinator"), + ADKEventProcessor(model="m", root="coordinator", run=run)): + assert [e async for e in processor.process_event(failed, "s1")] == [] async def test_the_roots_failure_is_left_to_the_turn(self): # Its exception leaves the run, which reports it: no second report. @@ -274,12 +274,10 @@ async def test_no_failed_calls_error_code(self): assert [e async for e in ADKEventProcessor(model="m", root="coordinator") .process_event(failed, "s1")] == [] - async def test_a_sub_agents_is_still_a_warning_naming_it(self): - (event,) = [e async for e in ADKEventProcessor(model="m", root="coordinator") - .process_event(self._overflowed("researcher"), "s1")] - - assert (event.metadata["recoverable"], event.metadata["agent"]) == (True, "researcher") - assert event.content.startswith("researcher failed: ") + async def test_a_sub_agents_is_no_turns_error(self): + # It ends its run failed (tests/workflow/adk/test_run_identity.py). + assert [e async for e in ADKEventProcessor(model="m", root="coordinator") + .process_event(self._overflowed("researcher"), "s1")] == [] # --- a tool's result ---------------------------------------------------------------- diff --git a/tests/test_adk_plugins.py b/tests/test_adk_plugins.py index 618337cd..8671a7ac 100644 --- a/tests/test_adk_plugins.py +++ b/tests/test_adk_plugins.py @@ -538,8 +538,8 @@ async def test_serialize_contents(self, plugin): def _call_context(agent: str = "researcher", invocation_id: str = "inv-1") -> SimpleNamespace: """A model call's callback context: ADK makes an ``EventActions`` for each - call and hands it to all three of the call's callbacks, while two parallel - calls of one sub-agent share their invocation and their agent's name.""" + call and hands it to all three of the call's callbacks, so a call is told + apart by it, whatever its invocation and its agent's name.""" return SimpleNamespace(invocation_id=invocation_id, agent_name=agent, actions=object()) @@ -563,8 +563,8 @@ def clock(self, monkeypatch): return times async def test_parallel_calls_of_one_agent_each_time_their_own(self, plugin, clock): - # Two delegations to one sub-agent: their requests go out at 0 s and - # 10 s, their answers come back at 20 s and 30 s. + # Two calls of one agent out at once: their requests go out at 0 s + # and 10 s, their answers come back at 20 s and 30 s. clock.extend([0.0, 10.0, 20.0, 30.0]) first, second = _call_context(), _call_context() @@ -608,9 +608,9 @@ async def test_an_answered_error_is_timed_to_its_answer(self, plugin, clock): assert latencies == [5_000.0] assert len(plugin.clock) == 0 - async def test_an_unanswered_errors_clock_goes_at_the_next_run(self, plugin): + async def test_an_unanswered_errors_clock_goes_as_its_run_ends(self, plugin): # Nothing answers the error, so no response comes: the clock waits - # for an answer until the next run lets it go. + # for an answer until its run lets it go, failing. call = _call_context(invocation_id="inv-1") await plugin.before_model_callback( callback_context=call, llm_request=_make_mock_llm_request() @@ -620,19 +620,33 @@ async def test_an_unanswered_errors_clock_goes_at_the_next_run(self, plugin): ) assert len(plugin.clock) == 1 - await plugin.before_run_callback(invocation_context=SimpleNamespace(invocation_id="inv-2")) + await plugin.on_run_error_callback( + invocation_context=SimpleNamespace(invocation_id="inv-1"), error=RuntimeError("529") + ) assert len(plugin.clock) == 0 - async def test_a_run_lets_go_of_what_another_left(self, plugin): - # Before google-adk 2.14 a call cancelled mid-request fires neither callback. + async def test_a_run_lets_go_of_what_it_left_as_it_ends(self, plugin, clock): + # Before google-adk 2.14 a call cancelled mid-request fires neither + # callback: its run's end lets it go, and another run's stays. + clock.extend([0.0, 10.0, 30.0]) left = _call_context(invocation_id="inv-1") - await plugin.before_model_callback( - callback_context=left, llm_request=_make_mock_llm_request() - ) + other = _call_context(invocation_id="inv-2") + for context in (left, other): + await plugin.before_model_callback( + callback_context=context, llm_request=_make_mock_llm_request() + ) - await plugin.before_run_callback(invocation_context=SimpleNamespace(invocation_id="inv-2")) + await plugin.after_run_callback(invocation_context=SimpleNamespace(invocation_id="inv-1")) + # inv-2's call is still out: its answer is timed, from 10 s to 30 s. + await plugin.after_model_callback( + callback_context=other, llm_response=_make_mock_llm_response(usage_metadata=_usage()) + ) + latencies = [ + r["metadata"].get("latency_ms") for r in _logged(plugin) if r["type"] == "llm_usage" + ] + assert latencies == [20_000.0] assert len(plugin.clock) == 0 async def test_a_sub_agents_records_name_it_and_its_run(self, plugin): diff --git a/tests/workflow/adk/test_call_clock.py b/tests/workflow/adk/test_call_clock.py index 8336bc51..ce8ceb6f 100644 --- a/tests/workflow/adk/test_call_clock.py +++ b/tests/workflow/adk/test_call_clock.py @@ -119,7 +119,8 @@ async def test_an_answer_already_timed_keeps_its_mark(self, plugins, ticks): assert len(clock) == 0 async def test_parallel_calls_each_time_their_own(self, plugins, ticks): - # Two delegations to one sub-agent share the invocation and the agent. + # Two calls out at once in one invocation of one agent: each is told + # apart by its own EventActions. sent, latency, _ = plugins first, second = _call(), _call() first_answer, second_answer = _answer(), _answer() @@ -133,15 +134,30 @@ async def test_parallel_calls_each_time_their_own(self, plugins, ticks): assert second_answer.custom_metadata == {LATENCY_KEY: 2_000.0} assert first_answer.custom_metadata == {LATENCY_KEY: 4_000.0} - async def test_a_run_lets_go_of_what_another_left(self, plugins, ticks): + async def test_a_run_lets_go_of_what_it_left_as_it_ends(self, plugins, ticks): + """A call cancelled mid-request fires no callback before google-adk + 2.14: its run's end lets its clock go, never another run's, which + may be out at once (two runs of one sub-agent type share a chain).""" sent, latency, clock = plugins - ticks += [10.0] - await sent.before_model_callback(callback_context=_call("inv-1"), llm_request=None) + left, other, failed = _call("inv-1"), _call("inv-2"), _call("inv-3") + ticks += [10.0, 11.0, 13.0, 20.0] + await sent.before_model_callback(callback_context=left, llm_request=None) + await sent.before_model_callback(callback_context=other, llm_request=None) - await latency.before_run_callback( - invocation_context=SimpleNamespace(invocation_id="inv-2") + await latency.after_run_callback( + invocation_context=SimpleNamespace(invocation_id="inv-1") ) + # inv-2's call is still out: its answer is timed, from 11 s to 13 s. + answer = _answer() + await latency.after_model_callback(callback_context=other, llm_response=answer) + assert answer.custom_metadata == {LATENCY_KEY: 2_000.0} + assert len(clock) == 0 + # A run that fails lets go of its own too. + await sent.before_model_callback(callback_context=failed, llm_request=None) + await latency.on_run_error_callback( + invocation_context=SimpleNamespace(invocation_id="inv-3"), error=RuntimeError("x") + ) assert len(clock) == 0 def test_an_events_mark_is_read_as_milliseconds(self): diff --git a/tests/workflow/adk/test_context_cache_plugin.py b/tests/workflow/adk/test_context_cache_plugin.py new file mode 100644 index 00000000..f666da6b --- /dev/null +++ b/tests/workflow/adk/test_context_cache_plugin.py @@ -0,0 +1,74 @@ +"""``ContextCachePlugin``: at most one Gemini cache try an agent's turn, and +what it keeps let go of as each run ends (``workflow/adk/context_cache_plugin.py``). + +A sub-agent run is an invocation of its type's runner, and two runs of one +type share that runner's chain, this plugin included: a run that ends, well +or failing, lets go of its own invocation's state and of no other's. +""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +pytest.importorskip("google.adk") + +from google.adk.agents.context_cache_config import ContextCacheConfig # noqa: E402 +from google.adk.models.cache_metadata import CacheMetadata # noqa: E402 +from google.adk.models.llm_request import LlmRequest # noqa: E402 +from google.adk.models.llm_response import LlmResponse # noqa: E402 + +from agentic_cli.workflow.adk.context_cache_plugin import ContextCachePlugin # noqa: E402 + + +def _call(invocation: str, agent: str = "researcher") -> SimpleNamespace: + return SimpleNamespace(invocation_id=invocation, agent_name=agent) + + +def _cacheable() -> LlmRequest: + """A request that could make a cache: ADK's metadata from an earlier call.""" + return LlmRequest( + cache_config=ContextCacheConfig(), + cache_metadata=CacheMetadata(fingerprint="f", contents_count=1), + ) + + +async def _spend(plugin: ContextCachePlugin, invocation: str) -> None: + """A call of ``invocation`` that could have made a cache and made none.""" + await plugin.before_model_callback(callback_context=_call(invocation), llm_request=_cacheable()) + await plugin.after_model_callback( + callback_context=_call(invocation), + llm_response=LlmResponse(cache_metadata=CacheMetadata(fingerprint="f", contents_count=1)), + ) + + +async def test_after_a_call_made_no_cache_the_turn_tries_no_more(): + plugin = ContextCachePlugin() + await _spend(plugin, "inv-1") + + again = _cacheable() + await plugin.before_model_callback(callback_context=_call("inv-1"), llm_request=again) + + assert again.cache_config is None + + +@pytest.mark.parametrize("ending", ["after_run_callback", "on_run_error_callback"]) +async def test_a_run_lets_go_of_what_it_kept_as_it_ends_and_of_nothing_else(ending): + plugin = ContextCachePlugin() + await _spend(plugin, "inv-1") + await _spend(plugin, "inv-2") + for invocation in ("inv-1", "inv-2"): + # A call still out: it could make a cache. + await plugin.before_model_callback( + callback_context=_call(invocation, "writer"), llm_request=_cacheable() + ) + + context = SimpleNamespace(invocation_id="inv-1") + if ending == "after_run_callback": + await plugin.after_run_callback(invocation_context=context) + else: + await plugin.on_run_error_callback(invocation_context=context, error=RuntimeError("529")) + + assert plugin._spent == {("inv-2", "researcher")} + assert set(plugin._could_cache) == {("inv-2", "writer")} diff --git a/tests/workflow/adk/test_delegation_result.py b/tests/workflow/adk/test_delegation_result.py deleted file mode 100644 index 6863fdb9..00000000 --- a/tests/workflow/adk/test_delegation_result.py +++ /dev/null @@ -1,85 +0,0 @@ -"""A delegation's result on ADK, shown as it is on Deep Agents. - -ADK names a sub-agent's delegation tool after the sub-agent and hands its -parent the sub-agent's answer under ``result`` (``{"result": text}``), which -the generic rendering showed as "Result: 1 items". The event processor knows -the call is a delegation (it ends the run's ``AGENT_RUN`` there), so it shows -the answer's first line (``tool_summaries.delegation_summary``), and a -sub-agent that failed as a failed result; ``metadata["result"]`` stays ADK's. -""" - -from __future__ import annotations - -import pytest - -pytest.importorskip("google.adk") - -from google.adk.events import Event # noqa: E402 -from google.genai import types # noqa: E402 - -from agentic_cli.workflow.adk.event_processor import ADKEventProcessor # noqa: E402 -from agentic_cli.workflow.adk.interrupted_calls_plugin import ABORTED # noqa: E402 -from agentic_cli.workflow.events import EventType # noqa: E402 -from agentic_cli.workflow.interrupts import INTERRUPTED_BY_USER # noqa: E402 - - -def _event(author: str, part: types.Part, *, error_code: str | None = None) -> Event: - role = "user" if part.function_response is not None else "model" - return Event( - author=author, invocation_id="i1", error_code=error_code, - content=types.Content(role=role, parts=[part]), - ) - - -def _call(name: str, call_id: str, args: dict) -> types.Part: - return types.Part(function_call=types.FunctionCall(id=call_id, name=name, args=args)) - - -def _response(name: str, call_id: str, response: dict) -> types.Part: - return types.Part( - function_response=types.FunctionResponse(id=call_id, name=name, response=response) - ) - - -async def _result_of(response: dict, *, error_code: str | None = None, name: str = "researcher"): - """The ``TOOL_RESULT`` the coordinator's call ``c1`` of ``name`` comes back with.""" - processor = ADKEventProcessor(model="m", root="coordinator", delegates={"researcher"}) - call = _event("coordinator", _call(name, "c1", {"request": "Find X."})) - [e async for e in processor.process_event(call, "s1")] - answered = _event("coordinator", _response(name, "c1", response), error_code=error_code) - events = [e async for e in processor.process_event(answered, "s1")] - return next(e for e in events if e.type is EventType.TOOL_RESULT) - - -class TestADelegationsResult: - async def test_shows_the_answers_first_line(self): - result = await _result_of({"result": "X is 42.\nThe handbook says so."}) - - assert result.content == "X is 42." - assert result.metadata["success"] is True - # What the parent read stays as ADK gave it. - assert result.metadata["result"] == {"result": "X is 42.\nThe handbook says so."} - - async def test_an_empty_answer_is_no_answer(self): - result = await _result_of({"result": ""}) - - assert result.content == "No answer" - - async def test_a_sub_agent_that_failed_is_a_failed_result(self): - result = await _result_of({"result": "Error running sub-agent: 529 overloaded"}) - - assert result.content == "Failed: 529 overloaded" - assert result.metadata["success"] is False - assert result.metadata["error"] == "Error running sub-agent: 529 overloaded" - - async def test_a_stopped_turns_seal_keeps_its_rendering(self): - result = await _result_of( - {"success": False, "error": INTERRUPTED_BY_USER}, error_code=ABORTED - ) - - assert result.content == f"Failed: {INTERRUPTED_BY_USER}" - - async def test_another_tools_result_is_rendered_as_before(self): - result = await _result_of({"result": "X is 42."}, name="lookup") - - assert result.content == "Result: 1 items" diff --git a/tests/workflow/adk/test_fit_guard.py b/tests/workflow/adk/test_fit_guard.py index 53b2512c..64ced33f 100644 --- a/tests/workflow/adk/test_fit_guard.py +++ b/tests/workflow/adk/test_fit_guard.py @@ -335,8 +335,8 @@ async def test_it_keeps_the_request_as_it_saw_it_until_the_call_ends(self): assert plugin.request_as_seen(context) is None async def test_two_calls_of_one_agent_in_one_invocation_keep_their_own(self): - """Two parallel delegations to one sub-agent share the invocation and - the agent name; each model call has its own ``EventActions``.""" + """Each model call has its own ``EventActions``, the copy's key: two + calls of one agent out at once in one invocation keep their own.""" plugin = FitGuardPlugin({"solo": budget_for([user(LONG), model("A1."), user("A?")])}, {"solo": CLAUDE}) first, second = call_context(), call_context() @@ -353,22 +353,28 @@ async def test_two_calls_of_one_agent_in_one_invocation_keep_their_own(self): llm_request=LlmRequest(), error=ValueError()) assert plugin.request_as_seen(first) is None - async def test_a_run_drops_what_another_invocation_left(self): - """A call cancelled mid-request fires neither release.""" + async def test_a_run_drops_what_it_left_as_it_ends(self): + """A call cancelled mid-request fires neither release: its run's end + drops its copy, never another run's, which may be out at once (two + runs of one sub-agent type share a chain).""" plugin = FitGuardPlugin({"solo": budget_for([user(LONG), model("A1."), user("A?")])}, {"solo": CLAUDE}) - cancelled, current = call_context(invocation="i1"), call_context(invocation="i2") - for context in (cancelled, current): + cancelled, other = call_context(invocation="i1"), call_context(invocation="i2") + for context in (cancelled, other): await plugin.before_model_callback(callback_context=context, llm_request=LlmRequest(contents=[user("Hi.")])) - answer = await plugin.before_run_callback( - invocation_context=SimpleNamespace(invocation_id="i2") + answer = await plugin.after_run_callback( + invocation_context=SimpleNamespace(invocation_id="i1") ) - assert answer is None # the run goes on + assert answer is None assert plugin.request_as_seen(cancelled) is None - assert plugin.request_as_seen(current) is not None + assert plugin.request_as_seen(other) is not None + await plugin.on_run_error_callback( + invocation_context=SimpleNamespace(invocation_id="i2"), error=RuntimeError("x") + ) + assert plugin.request_as_seen(other) is None async def test_an_agent_it_has_no_budget_for_is_left_alone(self): contents = [user(LONG), model("A1."), user(LONG), model("A2."), user("Three?")] diff --git a/tests/workflow/adk/test_interrupted_calls.py b/tests/workflow/adk/test_interrupted_calls.py index e573de58..43aed141 100644 --- a/tests/workflow/adk/test_interrupted_calls.py +++ b/tests/workflow/adk/test_interrupted_calls.py @@ -1,20 +1,20 @@ """On ADK each call is recorded, sealed and answered as the run's that made it. -ADK runs a sub-agent on the branch ``<agent>@<call id>``, and a provider that +A sub-agent run runs on its type's own runner, in a task of its own where +its run is the active one (``agents/delegate.py``), and a provider that numbers its call ids per agent gives the sub-agent's first call the id of the delegation that started it. The plugin records a call that finished -under the run in progress (``MainAgentPlugin``'s: the call's own), answers a -stopped turn's seal from the record of the seal's own branch's run, and -marks each call running by its branch and id. ADK's seals pair a result -with a call by id alone, so ``unsealed`` answers, as the turn stops, a call -they missed, from the record of its branch's run; ``left_open`` pairs a -result with a call on its own branch only, and answers a call a stopped -turn left open as the user's. +under the run in progress, answers a stopped invocation's seal from the +record of the run whose runner wrote it (the active run there), and marks +each call running by its invocation and id. ADK's seals pair a result with +a call by id alone, so ``unsealed`` answers, as the turn stops, a call of +the conversation's they missed; ``left_open`` pairs a result with a call on +its own branch only, and answers a call a stopped turn left open as the +user's. """ from __future__ import annotations -import asyncio from collections.abc import Iterator from contextlib import contextmanager from types import SimpleNamespace @@ -27,19 +27,16 @@ from google.adk.events import Event # noqa: E402 from google.genai import types # noqa: E402 -from agentic_cli.workflow.adk.branches import branch_run # noqa: E402 from agentic_cli.workflow.adk.interrupted_calls_plugin import ( # noqa: E402 ABORTED, InterruptedCallsPlugin, left_open, unsealed, ) -from agentic_cli.workflow.agents import AgentRuns # noqa: E402 from agentic_cli.tools.jobs.backends import JobState # noqa: E402 from agentic_cli.workflow.interrupts import ( # noqa: E402 INTERRUPTED, INTERRUPTED_BY_USER, - NOT_RUN, OpenCalls, interrupted, job_started, @@ -49,6 +46,7 @@ set_service_registry, ) from agentic_cli.workflow.sessions import ( # noqa: E402 + RunRef, SessionRef, ToolCallRef, get_active_tool_call, @@ -59,6 +57,9 @@ ) CONVERSATION = SessionRef("app", "u", "s") +RESEARCHER = RunRef( + agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1 +) @contextmanager @@ -75,10 +76,10 @@ def _tool(name: str) -> Any: def _context( - call_id: str, *, branch: str | None, state_delta: dict[str, Any] | None = None + call_id: str, *, invocation: str = "i1", state_delta: dict[str, Any] | None = None ) -> Any: return SimpleNamespace( - function_call_id=call_id, branch=branch, + function_call_id=call_id, invocation_id=invocation, actions=SimpleNamespace(state_delta=state_delta or {}, artifact_delta={}), ) @@ -119,28 +120,29 @@ def _answers(event: Event) -> dict[str, Any]: class TestSeals: - """ADK writes a stopped turn's seals outside the runs whose calls they - answer, so each seal is answered from the record of its own branch's run.""" + """A stopped invocation's seals are written by the runner that ran its + calls, in the task that iterates it: each is answered from the record of + the run in progress there.""" - async def test_a_seal_is_answered_from_its_own_branchs_record(self): - calls, runs = OpenCalls(), AgentRuns() - plugin = InterruptedCallsPlugin(calls, runs=runs) + async def test_a_seal_is_answered_from_its_runs_record(self): + calls = OpenCalls() + plugin = InterruptedCallsPlugin(calls) with turn_of(CONVERSATION): - # The researcher's call finishes in its run (MainAgentPlugin's). - token = set_active_run(branch_run(runs, CONVERSATION, "researcher@c1")) + # The researcher's call finishes in its run. + token = set_active_run(RESEARCHER) await plugin.after_tool_callback( tool=_tool("contract_lookup"), tool_args={}, - tool_context=_context("c1", branch="researcher@c1"), + tool_context=_context("c1", invocation="i-run"), result={"success": True, "value": 42}, ) - reset_active_run(token) - parents = await plugin.on_event_callback( - invocation_context=None, event=_seal("coordinator", None, ("researcher", "c1")), - ) its_own = await plugin.on_event_callback( invocation_context=None, - event=_seal("researcher", "researcher@c1", ("contract_lookup", "c1")), + event=_seal("researcher", None, ("contract_lookup", "c1")), + ) + reset_active_run(token) + parents = await plugin.on_event_callback( + invocation_context=None, event=_seal("coordinator", None, ("task", "c1")), ) assert _answers(parents) == {"c1": interrupted(INTERRUPTED_BY_USER)} @@ -150,14 +152,14 @@ async def test_a_seal_is_answered_from_its_own_branchs_record(self): class TestActiveToolCall: async def test_a_sub_agents_call_never_ends_its_parents_mark(self): """The researcher's call ``c1`` runs inside its coordinator's - delegation ``c1``: each ends its own mark.""" + delegation ``c1``, on an invocation of its own: each ends its own mark.""" plugin = InterruptedCallsPlugin(OpenCalls()) - parents = _context("c1", branch=None) - its_own = _context("c1", branch="researcher@c1") + parents = _context("c1", invocation="i-turn") + its_own = _context("c1", invocation="i-run") with turn_of(CONVERSATION): await plugin.before_tool_callback( - tool=_tool("researcher"), tool_args={}, tool_context=parents + tool=_tool("task"), tool_args={}, tool_context=parents ) await plugin.before_tool_callback( tool=_tool("contract_lookup"), tool_args={}, tool_context=its_own @@ -166,42 +168,43 @@ async def test_a_sub_agents_call_never_ends_its_parents_mark(self): await plugin.after_tool_callback( tool=_tool("contract_lookup"), tool_args={}, tool_context=its_own, result={} ) - assert get_active_tool_call() == ToolCallRef("c1", "researcher") + assert get_active_tool_call() == ToolCallRef("c1", "task") await plugin.after_tool_callback( - tool=_tool("researcher"), tool_args={}, tool_context=parents, result={} + tool=_tool("task"), tool_args={}, tool_context=parents, result={} ) assert get_active_tool_call() is None class TestUnsealed: - """ADK's seals pair a result with a call by id alone, so a call whose id a - sub-agent's result used is left open as the turn stops: it is answered - then, from the record of its own branch's run. Each session below ends - with ADK's seal of the stopped invocation, as a stopped turn's does.""" - - async def test_a_parents_calls_are_answered_from_its_own_record(self): - calls, runs = OpenCalls(), AgentRuns() - plugin = InterruptedCallsPlugin(calls, runs=runs) + """ADK's seals pair a result with a call by id alone, so a call whose id + another branch's result used (a native ADK YAML app's agents share the + conversation's session) is left open as the turn stops: it is answered + then, from the conversation's record. Each session below ends with ADK's + seal of the stopped invocation, as a stopped turn's does.""" + + async def test_the_conversations_calls_are_answered_from_its_record(self): + calls = OpenCalls() + plugin = InterruptedCallsPlugin(calls) events = [ - _calls("coordinator", None, ("researcher", "c1"), ("contract_whoami", "c2")), - _calls("researcher", "researcher@c1", ("contract_lookup", "c1")), - _results("researcher", "researcher@c1", ("contract_lookup", "c1", {"value": 42})), - _calls("researcher", "researcher@c1", ("contract_lookup", "c2")), - _results("researcher", "researcher@c1", ("contract_lookup", "c2", {"value": 42})), - _calls("researcher", "researcher@c1", ("contract_block", "c3")), - # ADK seals only c3: the researcher's results hide c1 and c2. - _seal("researcher", "researcher@c1", ("contract_block", "c3")), + _calls("coordinator", None, ("helper_tool", "c1"), ("contract_whoami", "c2")), + _calls("helper", "helper", ("contract_lookup", "c1")), + _results("helper", "helper", ("contract_lookup", "c1", {"value": 42})), + _calls("helper", "helper", ("contract_lookup", "c2")), + _results("helper", "helper", ("contract_lookup", "c2", {"value": 42})), + _calls("helper", "helper", ("contract_block", "c3")), + # ADK seals only c3: the helper's results hide c1 and c2. + _seal("helper", "helper", ("contract_block", "c3")), ] with turn_of(CONVERSATION): - # The coordinator's own c2 finished beside its delegation. + # The coordinator's own c2 finished. await plugin.after_tool_callback( tool=_tool("contract_whoami"), tool_args={}, - tool_context=_context("c2", branch=None, state_delta={"seen": True}), + tool_context=_context("c2", state_delta={"seen": True}), result={"success": True}, ) - (answer,) = unsealed(events, calls, runs) + (answer,) = unsealed(events, calls) assert (answer.author, answer.branch, answer.error_code) == ("coordinator", None, ABORTED) assert _answers(answer) == { @@ -210,36 +213,13 @@ async def test_a_parents_calls_are_answered_from_its_own_record(self): # Its state change is stored with its answer, as with its result. assert answer.actions.state_delta == {"seen": True} - async def test_a_sub_agents_call_is_answered_from_its_runs_record(self): - calls, runs = OpenCalls(), AgentRuns() - events = [ - _calls("coordinator", None, ("contract_whoami", "c1")), - _results("coordinator", None, ("contract_whoami", "c1", {"success": True})), - _calls("coordinator", None, ("researcher", "c2")), - _calls("researcher", "researcher@c2", ("write_file", "c1")), - # ADK seals only the delegation: the coordinator's result hides c1. - _seal("coordinator", None, ("researcher", "c2")), - ] - - with turn_of(CONVERSATION): - # The researcher's c1 waited at its prompt, in its run. - token = set_active_run(branch_run(runs, CONVERSATION, "researcher@c2")) - with pytest.raises(asyncio.CancelledError), calls.asking("c1"): - raise asyncio.CancelledError - reset_active_run(token) - answers = unsealed(events, calls, runs) - - (answer,) = answers - assert (answer.author, answer.branch) == ("researcher", "researcher@c2") - assert _answers(answer) == {"c1": interrupted(NOT_RUN)} - def test_a_stop_adk_has_not_sealed_is_left_to_the_next_turn(self): """Its seals would come after these answers, and answer a call twice: ``left_open`` answers what they leave.""" - events = [_calls("coordinator", None, ("researcher", "c1"))] + events = [_calls("coordinator", None, ("task", "c1"))] with turn_of(CONVERSATION): - assert unsealed(events, OpenCalls(), AgentRuns()) == [] + assert unsealed(events, OpenCalls()) == [] class TestLeftOpen: diff --git a/tests/workflow/adk/test_log_filters.py b/tests/workflow/adk/test_log_filters.py index 012e08b0..bb9a2105 100644 --- a/tests/workflow/adk/test_log_filters.py +++ b/tests/workflow/adk/test_log_filters.py @@ -44,6 +44,7 @@ ADK_NODE_LOGGER = "google_adk.google.adk.workflow._node_runner" ADK_PLUGIN_LOGGER = "google_adk.google.adk.plugins.plugin_manager" ADK_REARRANGER_LOGGER = "google_adk.google.adk.flows.llm_flows.tools._rearranger" +ADK_ROUTER_LOGGER = "google_adk.google.adk.agents._agent_router" class _LogRecorder: @@ -73,7 +74,7 @@ def logged(monkeypatch) -> list[dict]: ADK_LOGGERS = (ADK_RUNNER_LOGGER, ADK_CACHE_LOGGER, ADK_COMPACTION_LOGGER, ADK_NODE_LOGGER, - ADK_PLUGIN_LOGGER, ADK_REARRANGER_LOGGER) + ADK_PLUGIN_LOGGER, ADK_REARRANGER_LOGGER, ADK_ROUTER_LOGGER) @pytest.fixture(autouse=True) @@ -343,6 +344,38 @@ def test_adks_dropped_call_warning_is_logged_not_printed(logged, caplog): assert "call-1" in entry["message"] +# An inheriting sub-agent run starts on a child session holding copies of its +# conversation's events, written by agents its runner's tree does not have +# (the root among them). ADK warns of each such author as it looks for the +# agent to run, then runs the sub-agent all the same: nothing for the user. + + +def test_adks_unknown_author_warning_is_logged_not_printed(logged, caplog): + install_log_filters() + + with caplog.at_level(logging.WARNING, logger=ADK_ROUTER_LOGGER): + logging.getLogger(ADK_ROUTER_LOGGER).warning( + "Event from an unknown agent: %s, event id: %s", "coordinator", "e-1" + ) + + assert [r for r in caplog.records if r.name == ADK_ROUTER_LOGGER] == [] + (entry,) = [e for e in logged if e["event"] == "adk_inherited_unknown_author"] + assert entry["log_level"] == "debug" + assert "coordinator" in entry["message"] + + +def test_the_routers_other_records_pass(logged, caplog): + install_log_filters() + + with caplog.at_level(logging.WARNING, logger=ADK_ROUTER_LOGGER): + logging.getLogger(ADK_ROUTER_LOGGER).warning("Something else about %s", "coordinator") + + assert [r.getMessage() for r in caplog.records if r.name == ADK_ROUTER_LOGGER] == [ + "Something else about coordinator" + ] + assert logged == [] + + # --- ADK's context-cache failures ---------------------------------------------------- # # While prompt caching is on, ADK warns through stdlib logging when it cannot diff --git a/tests/workflow/adk/test_plugin_chain.py b/tests/workflow/adk/test_plugin_chain.py index 4b471b5f..8ffff9ba 100644 --- a/tests/workflow/adk/test_plugin_chain.py +++ b/tests/workflow/adk/test_plugin_chain.py @@ -15,9 +15,6 @@ answer; - ``tool_error`` answers a call that raised (and one to an unknown tool); - ``llm_logging`` records each call as the model answers it; -- ``subagent_outcome``, when the tree delegates, after the raw log (which - records an answer as the model gave it): a sub-agent's refused or cut answer - is said so, in place, so every plugin after it still runs; - ``foreign_reasoning`` drops the thoughts another provider wrote, before the request is measured; - ``context_cache`` makes one Gemini cache attempt a turn; @@ -32,7 +29,11 @@ - ``call_sent`` last: each call's clock starts as its request goes out. A native ADK YAML app gets the same chain: only the building of its agents -differs (``workflow/adk/build.py``). +differs (``workflow/adk/build.py``). Each sub-agent type's runner has a chain +of its own in the same order (``_agent_plugin_chain``): no memory index, and +``subagent_outcome`` after the raw log (which records an answer as the model +gave it), where a sub-agent's refused or cut answer is said so, in place, so +every plugin after it still runs. """ from __future__ import annotations @@ -123,16 +124,44 @@ async def test_a_plain_config_built_app(project): async def test_a_delegating_app(project): - """A tree with a sub-agent: its answers pass ``subagent_outcome``.""" + """A tree with a sub-agent: the conversation's chain is the app's; the + sub-agent type's own runner's passes its answers through ``subagent_outcome``.""" manager = GoogleADKWorkflowManager( agent_configs=[ - AgentConfig(name="lead", prompt="Lead.", sub_agents=["helper"]), - AgentConfig(name="helper", prompt="Help.", description="Helps."), + AgentConfig(name="lead", prompt="Lead.", sub_agents=["helper"], + tools=[search_memory]), + AgentConfig(name="helper", prompt="Help.", description="Helps.", + tools=[search_memory]), ], settings=_settings(extras=True), ) - assert await _chain(manager) == [ + try: + await manager.initialize_services() + chain = [plugin.name for plugin in manager._runner.app.plugins] + helpers = [plugin.name for plugin in manager._agent_runners["helper"].app.plugins] + shared = manager._llm_logging_plugin + logs = [p for p in manager._agent_runners["helper"].app.plugins if p.name == "llm_logging"] + finally: + await manager.cleanup() + + assert chain == [ + "main_agent", + "call_latency", + "permission", + "tool_error", + "llm_logging", + "foreign_reasoning", + "context_cache", + "interrupted_calls", + "tool_result_cap", + "memory_index", + "context_overflow", + "fit_guard", + "llm_logging_sent", + "call_sent", + ] + assert helpers == [ "main_agent", "call_latency", "permission", @@ -148,6 +177,8 @@ async def test_a_delegating_app(project): "llm_logging_sent", "call_sent", ] + # One raw log for every runner, whose buffer the manager drains. + assert logs == [shared] async def test_a_native_adk_yaml_app_gets_the_same_chain(project): diff --git a/tests/workflow/adk/test_run_identity.py b/tests/workflow/adk/test_run_identity.py index feaae2f8..32435961 100644 --- a/tests/workflow/adk/test_run_identity.py +++ b/tests/workflow/adk/test_run_identity.py @@ -1,15 +1,19 @@ -"""Each ADK event is its run's: the branch a sub-agent's work runs on names it. - -ADK runs a sub-agent its parent delegated to on the branch -``<agent>@<call id>``, under its parent's (``middle@c1.leaf@m1`` two levels -down); the root, and an agent the root transfers to, on none. The event -processor names each event's run from it, gives a delegation's call and -result an ``AGENT_RUN`` (started; completed, failed or interrupted), and -records it; ``MainAgentPlugin`` makes the run the active one as the agent -starts, and its parent's the active one again as it ends. ADK runs a -delegated sub-agent inside its parent's call (``run_node``, in that call's -own task), so what the agent sets as it starts is still set when it returns: -the call's after-tool callbacks are the parent's, and see the parent's run. +"""Each ADK event is its run's: the conversation's own, or the sub-agent run whose runner wrote it. + +The conversation's processor names each event of its runner the root's +(``root_run``), an agent the root transfers to at depth 0 (a native ADK YAML +app's), and the user's message no one's. A sub-agent run runs on its type's +own runner, on its child session, read by a processor made for that run +(``ADKEventProcessor(run=)``): every event is the run's, its text is +activity and its usage the sub-agent's, it reports no ``ERROR`` of its own, +and it keeps what ends the run (its last answer with text, that answer's +outcome, its failure) for the manager. The ``AGENT_RUN`` events are the +framework's (``agents/delegate.py``). A ``task`` call's result is read back +from its JSON text and shown from its envelope. + +A delegation's call is its parent's: its after-tool callbacks (every +plugin's) see the parent's run, whether the sub-agent answered or failed; +the run's own calls ran in a task of their own. """ from __future__ import annotations @@ -29,31 +33,17 @@ from google.genai import types # noqa: E402 from agentic_cli.config import BaseSettings # noqa: E402 -from agentic_cli.workflow.adk.branches import ( # noqa: E402 - branch_run, - delegations, - parent_branch_run, -) -from agentic_cli.workflow.adk.build import delegated_agents # noqa: E402 from agentic_cli.workflow.adk.compaction import MainAgentPlugin, running_agent # noqa: E402 from agentic_cli.workflow.adk.event_processor import ADKEventProcessor # noqa: E402 -from agentic_cli.workflow.adk.interrupted_calls_plugin import ( # noqa: E402 - ABORTED, - InterruptedCallsPlugin, -) +from agentic_cli.workflow.adk.interrupted_calls_plugin import InterruptedCallsPlugin # noqa: E402 from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 -from agentic_cli.workflow.agents import ( # noqa: E402 - RUN_COMPLETED, - RUN_FAILED, - RUN_INTERRUPTED, - RUN_STARTED, - AgentRuns, -) +from agentic_cli.workflow.adk.subagent_outcome_plugin import OUTCOME_KEY # noqa: E402 +from agentic_cli.workflow.agents.envelope import envelope # noqa: E402 +from agentic_cli.workflow.agents.outcome import CUT # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 +from agentic_cli.workflow.context import OVERFLOW_ERROR_CODE # noqa: E402 from agentic_cli.workflow.events import EventType # noqa: E402 -from agentic_cli.workflow.interrupts import INTERRUPTED_BY_USER # noqa: E402 from agentic_cli.workflow.sessions import RunRef, get_active_run, root_run # noqa: E402 -from agentic_cli.workflow.tool_errors import unknown_tool_result # noqa: E402 from tests.workflow.adk.fakes import FakeAPI, anthropic_message # noqa: E402 from tests.workflow.test_manager_models import route # noqa: E402 @@ -61,19 +51,19 @@ agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1 ) MIDDLE = RunRef(agent="middle", instance="middle-1", run="middle-1#1", parent_run=None, depth=1) -LEAF = RunRef(agent="leaf", instance="leaf-1", run="leaf-1#1", parent_run="middle-1#1", depth=2) -def _text(author: str, text: str = "X is 42.", *, branch: str | None = None) -> Event: +def _text(author: str, text: str = "X is 42.", **fields) -> Event: return Event( - author=author, invocation_id="i1", branch=branch, + author=author, invocation_id="i1", content=types.Content(role="model", parts=[types.Part.from_text(text=text)]), + **fields, ) -def _calls(author: str, *made: tuple[str, str, dict], branch: str | None = None) -> Event: +def _calls(author: str, *made: tuple[str, str, dict]) -> Event: return Event( - author=author, invocation_id="i1", branch=branch, + author=author, invocation_id="i1", content=types.Content(role="model", parts=[ types.Part(function_call=types.FunctionCall(id=call_id, name=name, args=args)) for name, call_id, args in made @@ -92,60 +82,19 @@ def _results(author: str, *made: tuple[str, str, dict], error_code: str | None = def _processor(**kwargs) -> ADKEventProcessor: - return ADKEventProcessor( - model="m", root="coordinator", delegates={"researcher"}, **kwargs - ) + return ADKEventProcessor(model="m", root="coordinator", **kwargs) async def _process(processor: ADKEventProcessor, event: Event) -> list: return [e async for e in processor.process_event(event, "s1")] -async def _delegated(processor: ADKEventProcessor, request: str = "Find X.") -> None: - await _process(processor, _calls("coordinator", ("researcher", "toolu_c1", {"request": request}))) - - -class TestBranches: - def test_a_branch_is_its_delegations_outermost_first(self): - assert delegations("middle@toolu_c1.leaf@toolu_m1") == [ - ("middle", "toolu_c1"), ("leaf", "toolu_m1"), - ] - - def test_no_branch_is_no_delegation(self): - assert delegations(None) == [] - assert delegations("") == [] - - def test_a_segment_without_a_call_is_no_delegation(self): - assert delegations("node.researcher@toolu_c1") == [("researcher", "toolu_c1")] - - def test_a_branch_names_its_run_under_its_parents(self): - assert branch_run(AgentRuns(), None, "middle@c1.leaf@m1") == LEAF - assert branch_run(AgentRuns(), None, None) is None - - def test_a_branchs_parent_run_made_its_delegation(self): - runs = AgentRuns() - - assert parent_branch_run(runs, None, "middle@c1.leaf@m1") == MIDDLE - assert parent_branch_run(runs, None, "middle@c1") is None - assert parent_branch_run(runs, None, None) is None - - class TestEveryEventIsItsRuns: async def test_the_roots_events_are_its_own(self): (text,) = await _process(_processor(), _text("coordinator")) assert text.run == root_run("coordinator") - async def test_a_sub_agents_events_are_its_runs(self): - (text,) = await _process(_processor(), _text("researcher", branch="researcher@toolu_c1")) - - assert text.run == RESEARCHER - - async def test_a_nested_run_is_named_under_its_parents(self): - (text,) = await _process(_processor(), _text("leaf", branch="middle@c1.leaf@m1")) - - assert text.run == LEAF - async def test_an_agent_the_root_transfers_to_runs_at_depth_0(self): processor = ADKEventProcessor( model="m", root="coordinator", reply_agents={"coordinator", "helper"} @@ -181,171 +130,145 @@ async def test_a_call_and_its_result_name_the_call(self): assert result.metadata["tool_call_id"] == "toolu_1" -class TestDelegationRuns: - async def test_a_delegation_starts_a_run_after_its_call(self): - events = await _process(_processor(), _calls( - "coordinator", ("researcher", "toolu_c1", {"request": "Find X.\nThen report."}) - )) - - assert [e.type for e in events] == [EventType.TOOL_CALL, EventType.AGENT_RUN] - call, started = events - assert call.run == root_run("coordinator") - assert started.run == RESEARCHER - assert started.content == "researcher-1 started" - assert started.metadata == { - "status": RUN_STARTED, "agent": "researcher", "partial": False, - "call_id": "toolu_c1", "title": "Find X.", - } - - async def test_its_result_ends_it(self): - processor = _processor() - await _delegated(processor) +class TestATaskCallsResult: + async def test_an_envelope_is_shown_from_its_result(self): + found = envelope(RESEARCHER, "completed", result="X is 42.\nMore.") - events = await _process(processor, _results( - "coordinator", ("researcher", "toolu_c1", {"result": "X is 42."}) + (result,) = await _process(_processor(), _results( + "coordinator", ("task", "toolu_c1", {"result": json.dumps(found)}) )) - assert [e.type for e in events] == [EventType.TOOL_RESULT, EventType.AGENT_RUN] - ended = events[1] - assert ended.run == RESEARCHER - assert (ended.metadata["status"], ended.metadata["result"]) == (RUN_COMPLETED, "X is 42.") - (record,) = processor.runs.records(None) - assert (record.status, record.title, record.result) == (RUN_COMPLETED, "Find X.", "X is 42.") + assert (result.content, result.metadata["success"]) == ("X is 42.", True) + assert result.metadata["result"] == found - async def test_a_long_result_is_cut(self): - processor = _processor() - await _delegated(processor) + async def test_a_failed_one_is_a_failed_result(self): + found = envelope(RESEARCHER, "failed", error="overloaded") - (_, ended) = await _process(processor, _results( - "coordinator", ("researcher", "toolu_c1", {"result": "z" * 500}) + (result,) = await _process(_processor(), _results( + "coordinator", ("task", "toolu_c1", {"result": json.dumps(found)}) )) - assert ended.metadata["result"] == "z" * 200 + assert result.content == "Failed: overloaded" + assert (result.metadata["success"], result.metadata["error"]) == (False, "overloaded") - async def test_a_sub_agent_that_failed_ends_its_run_failed(self): - processor = _processor() - await _delegated(processor) + async def test_a_brief_that_started_no_run_is_an_error_result(self): + refused = {"success": False, "error": "task needs agent_type: one of researcher."} - (_, ended) = await _process(processor, _results( - "coordinator", - ("researcher", "toolu_c1", {"result": "Error running sub-agent: 529 overloaded"}), + (result,) = await _process(_processor(), _results( + "coordinator", ("task", "toolu_c1", {"result": json.dumps(refused)}) )) - assert ended.metadata["status"] == RUN_FAILED - assert (ended.metadata["error"], ended.metadata["result"]) == ("529 overloaded", "") - - async def test_a_stopped_turns_seal_ends_it_interrupted(self): - processor = _processor() - await _delegated(processor) + assert result.metadata["result"] == refused + assert (result.metadata["success"], result.metadata["error"]) == ( + False, refused["error"] + ) - (_, ended) = await _process(processor, _results( - "coordinator", - ("researcher", "toolu_c1", {"success": False, "error": INTERRUPTED_BY_USER}), - error_code=ABORTED, + async def test_another_tools_result_is_read_as_it_is(self): + (result,) = await _process(_processor(), _results( + "coordinator", ("lookup", "toolu_c1", {"result": json.dumps({"success": False})}) )) - assert ended.metadata["status"] == RUN_INTERRUPTED + assert result.metadata["result"] == {"result": json.dumps({"success": False})} + assert result.metadata["success"] is True - async def test_another_tool_starts_no_run(self): - events = await _process(_processor(), _calls("coordinator", ("lookup", "toolu_1", {}))) - assert [e.type for e in events] == [EventType.TOOL_CALL] +class TestARunsProcessor: + """``run=``: every event is that run's, and what ends the run is kept.""" - async def test_an_error_result_ends_it_failed(self): - """The delegation tool raised: ``ToolErrorPlugin`` answers an error result.""" - processor = _processor() - await _delegated(processor) + async def test_every_event_is_the_runs(self): + processor = _processor(run=RESEARCHER) - (_, ended) = await _process(processor, _results( - "coordinator", - ("researcher", "toolu_c1", {"success": False, "error": "researcher failed: boom"}), - )) + events = [ + *await _process(processor, _calls("researcher", ("lookup", "toolu_1", {"q": "x"}))), + *await _process(processor, _results("researcher", ("lookup", "toolu_1", {"v": 1}))), + *await _process(processor, _text("researcher")), + ] - assert ended.metadata["status"] == RUN_FAILED - assert (ended.metadata["error"], ended.metadata["result"]) == ( - "researcher failed: boom", "", + assert [(e.type, e.run) for e in events] == [ + (EventType.TOOL_CALL, RESEARCHER), (EventType.TOOL_RESULT, RESEARCHER), + (EventType.TEXT, RESEARCHER), + ] + assert (events[-1].metadata["agent"], events[-1].metadata["subagent"]) == ( + "researcher", True ) + async def test_its_usage_is_the_sub_agents(self): + event = _text("researcher", usage_metadata=types.GenerateContentResponseUsageMetadata( + prompt_token_count=50, candidates_token_count=5, + )) -class TestOnlyTheCallersOwnSubAgents: - """A run starts only for a delegation to one of the calling agent's own - single-turn sub-agents (``delegates``, by the caller, the event's author).""" - - def test_each_agent_names_its_own_single_turn_sub_agents(self): - leaf = SimpleNamespace(name="leaf", mode="single_turn", sub_agents=[]) - helper = SimpleNamespace(name="helper", mode="chat", sub_agents=[]) - middle = SimpleNamespace(name="middle", mode="single_turn", sub_agents=[leaf]) - root = SimpleNamespace(name="coordinator", mode=None, sub_agents=[middle, helper]) - - assert delegated_agents(root) == {"coordinator": {"middle"}, "middle": {"leaf"}} - assert delegated_agents(helper) == {} + (usage, _) = await _process(_processor(run=RESEARCHER), event) - async def test_a_call_of_another_agents_sub_agent_is_a_tool_call(self): - processor = ADKEventProcessor( - model="m", root="coordinator", - delegates={"coordinator": {"middle"}, "middle": {"leaf"}}, + assert (usage.run, usage.metadata["agent"], usage.metadata["purpose"]) == ( + RESEARCHER, "researcher", "subagent" ) - called = await _process( - processor, _calls("coordinator", ("leaf", "toolu_c1", {"request": "x"})) - ) - answered = await _process(processor, _results( - "coordinator", ("leaf", "toolu_c1", unknown_tool_result("leaf", ["middle"])) + async def test_its_last_answer_with_text_is_kept(self): + processor = _processor(run=RESEARCHER) + + await _process(processor, _text("researcher", "X is 42.")) + # Anthropic may end with an empty end_turn after its final tool call. + await _process(processor, Event( + author="researcher", invocation_id="i1", error_code="MODEL_RETURNED_NO_CONTENT", )) - assert [e.type for e in called + answered] == [EventType.TOOL_CALL, EventType.TOOL_RESULT] - assert processor.runs.records(None) == [] + assert (processor.answer, processor.outcome, processor.failure) == ("X is 42.", None, None) - async def test_a_sub_agent_delegates_to_its_own(self): - processor = ADKEventProcessor( - model="m", root="coordinator", - delegates={"coordinator": {"middle"}, "middle": {"leaf"}}, - ) + async def test_an_answers_text_counts_beside_its_tool_call(self): + """As Deep Agents' own ``task`` reads a run: its last text, whatever + else the reply held.""" + processor = _processor(run=RESEARCHER) + event = _calls("researcher", ("lookup", "toolu_1", {})) + event.content.parts.insert(0, types.Part.from_text(text="X is 42. ")) - events = await _process(processor, _calls( - "middle", ("leaf", "m1", {"request": "x"}), branch="middle@c1" - )) + await _process(processor, event) - assert [(e.type, e.run) for e in events] == [ - (EventType.TOOL_CALL, MIDDLE), (EventType.AGENT_RUN, LEAF), - ] + assert processor.answer == "X is 42." - async def test_a_set_of_names_is_the_roots(self): - events = await _process(_processor(), _calls( - "middle", ("researcher", "m1", {"request": "x"}), branch="middle@c1" - )) + async def test_its_outcome_mark_is_kept(self): + processor = _processor(run=RESEARCHER) - assert [e.type for e in events] == [EventType.TOOL_CALL] + await _process(processor, _text("researcher", "X is", custom_metadata={OUTCOME_KEY: CUT})) + assert (processor.answer, processor.outcome) == ("X is", CUT) -class TestTheActiveRun: - async def test_an_agent_on_a_delegations_branch_runs_as_that_run(self): - plugin = MainAgentPlugin(AgentRuns()) + async def test_an_overflow_is_its_failure_and_no_error_is_reported(self): + processor = _processor(run=RESEARCHER) + event = Event( + author="researcher", invocation_id="i1", error_code=OVERFLOW_ERROR_CODE, + error_message="researcher: the request no longer fits m's context window.", + ) - async def start() -> RunRef | None: - await plugin.before_agent_callback( - agent=SimpleNamespace(name="leaf"), - callback_context=SimpleNamespace(branch="middle@c1.leaf@m1"), - ) - return get_active_run() + assert await _process(processor, event) == [] + assert processor.failure == ( + "researcher: the request no longer fits m's context window.", OVERFLOW_ERROR_CODE + ) - # ADK runs each agent in a task of its own: the run is that task's. - assert await asyncio.create_task(start()) == LEAF - assert get_active_run() is None + async def test_a_reply_that_is_no_answer_is_its_failure(self): + processor = _processor(run=RESEARCHER, models={"researcher": "anthropic:claude"}) + event = Event( + author="researcher", invocation_id="i1", error_code="MALFORMED_FUNCTION_CALL", + error_message="bad call", + ) - async def test_the_root_runs_as_no_run(self): - plugin = MainAgentPlugin(AgentRuns()) + assert await _process(processor, event) == [] + assert processor.failure == ( + "anthropic:claude returned no answer: bad call", "MALFORMED_FUNCTION_CALL" + ) - async def start() -> RunRef | None: - await plugin.before_agent_callback( - agent=SimpleNamespace(name="coordinator"), - callback_context=SimpleNamespace(branch=None), - ) - return get_active_run() + async def test_it_reports_no_task_progress(self): + event = _results("researcher", ("save_tasks", "toolu_1", {"success": True})) + event.actions.state_delta["tasks"] = [ + {"id": "1", "description": "Look", "status": "in_progress"} + ] + + events = await _process(_processor(run=RESEARCHER), event) - assert await asyncio.create_task(start()) is None + assert [e.type for e in events] == [EventType.TOOL_RESULT] - async def test_without_the_runs_it_records_the_agent_alone(self): + +class TestTheRunningAgent: + async def test_main_agent_plugin_records_the_agent_alone(self): async def start() -> tuple[str | None, RunRef | None]: await MainAgentPlugin().before_agent_callback( agent=SimpleNamespace(name="researcher"), callback_context=None @@ -354,31 +277,6 @@ async def start() -> tuple[str | None, RunRef | None]: assert await asyncio.create_task(start()) == ("researcher", None) - async def test_as_an_agent_ends_its_parents_run_is_active_again(self): - plugin = MainAgentPlugin(AgentRuns()) - leaf, on_leaf = SimpleNamespace(name="leaf"), SimpleNamespace(branch="middle@c1.leaf@m1") - - async def run() -> tuple[RunRef | None, RunRef | None]: - await plugin.before_agent_callback(agent=leaf, callback_context=on_leaf) - during = get_active_run() - await plugin.after_agent_callback(agent=leaf, callback_context=on_leaf) - return during, get_active_run() - - assert await asyncio.create_task(run()) == (LEAF, MIDDLE) - - async def test_as_an_agent_fails_its_parents_run_is_active_again(self): - plugin = MainAgentPlugin(AgentRuns()) - leaf, on_leaf = SimpleNamespace(name="leaf"), SimpleNamespace(branch="middle@c1.leaf@m1") - - async def run() -> RunRef | None: - await plugin.before_agent_callback(agent=leaf, callback_context=on_leaf) - await plugin.on_agent_error_callback( - agent=leaf, callback_context=on_leaf, error=RuntimeError("overloaded") - ) - return get_active_run() - - assert await asyncio.create_task(run()) == MIDDLE - # -- after a delegation, its parent's run: two turns on Claude, through FakeAPI -- @@ -389,10 +287,11 @@ def _says(text: str) -> dict: return anthropic_message({"type": "text", "text": text}) -def _delegates(agent: str, call_id: str, request: str) -> dict: - message = anthropic_message( - {"type": "tool_use", "id": call_id, "name": agent, "input": {"request": request}} - ) +def _delegates(agent: str, call_id: str, objective: str) -> dict: + message = anthropic_message({ + "type": "tool_use", "id": call_id, "name": "task", + "input": {"agent_type": agent, "title": objective, "objective": objective}, + }) message["stop_reason"] = "tool_use" return message @@ -464,7 +363,7 @@ async def test_after_a_sub_agent_answered(self, project, monkeypatch): leaf=[_says("42.")], )) - assert seen == [("leaf", MIDDLE), ("middle", None)] + assert seen == [("task", MIDDLE), ("task", None)] async def test_after_a_sub_agent_failed(self, project, monkeypatch): refused = httpx.Response(400, json={ @@ -477,4 +376,4 @@ async def test_after_a_sub_agent_failed(self, project, monkeypatch): leaf=[refused], )) - assert seen == [("leaf", MIDDLE), ("middle", None)] + assert seen == [("task", MIDDLE), ("task", None)] diff --git a/tests/workflow/adk/test_subagent_outcome_plugin.py b/tests/workflow/adk/test_subagent_outcome_plugin.py index 7a5845e9..7da1523c 100644 --- a/tests/workflow/adk/test_subagent_outcome_plugin.py +++ b/tests/workflow/adk/test_subagent_outcome_plugin.py @@ -38,7 +38,7 @@ from tests.workflow.adk.fakes import FakeAPI, anthropic_message # noqa: E402 from tests.workflow.test_adk_delegation import ( # noqa: E402,F401 Team, - calls, + delegation, manager_for, project, says, @@ -211,7 +211,7 @@ async def test_the_log_has_the_answer_as_the_model_gave_it( answer = anthropic_message(*blocks) answer.update(content=blocks, stop_reason=stop) answers = Team( - coordinator=[calls("researcher", "toolu_c1", request="Find X."), says("Done.")], + coordinator=[delegation("toolu_c1", "Find X."), says("Done.")], researcher=[answer], ) route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) @@ -233,7 +233,7 @@ async def test_the_log_has_the_answer_as_the_model_gave_it( ) (result,) = [e for e in events if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "toolu_c1"] - assert result.metadata["result"] == {"result": read} + assert result.metadata["result"]["result"] == read class TestTheADKItRestsOn: diff --git a/tests/workflow/adk/test_usage_recorded.py b/tests/workflow/adk/test_usage_recorded.py index abe05643..da2ec69b 100644 --- a/tests/workflow/adk/test_usage_recorded.py +++ b/tests/workflow/adk/test_usage_recorded.py @@ -3,9 +3,10 @@ The event processor normalizes a call's counts by its model's provider kind (the thinking counts in the output: apart from the candidates on Gemini and ADK's Claude adapter, inside them on OpenAI's), records it before -``on_event`` (an app's hook that drops events cannot drop a row), and gives -a sub-agent run's end what the run used, by model. A processor driven outside -a manager files under no conversation (None), as ``AgentRuns`` does. +``on_event`` (an app's hook that drops events cannot drop a row), and a +sub-agent run's processor records each of the run's calls under the run, +which the run's end then reads (``agents/delegate.py``). A processor driven +outside a manager files under no conversation (None), as ``AgentRuns`` does. """ from __future__ import annotations @@ -19,18 +20,16 @@ from agentic_cli.workflow.usage import UsageLedgers # noqa: E402 from tests.workflow.adk.test_run_identity import ( # noqa: E402 - _delegated, + RESEARCHER, _process, _processor, - _results, ) -def _answer(author: str, prompt: int, candidates: int, thoughts: int | None = None, - *, branch: str | None = None) -> Event: +def _answer(author: str, prompt: int, candidates: int, thoughts: int | None = None) -> Event: """A model's answer of ``author``'s that reports its usage.""" return Event( - author=author, invocation_id="i1", branch=branch, + author=author, invocation_id="i1", content=types.Content(role="model", parts=[types.Part.from_text(text="Done.")]), usage_metadata=types.GenerateContentResponseUsageMetadata( prompt_token_count=prompt, candidates_token_count=candidates, @@ -67,17 +66,17 @@ async def test_a_hook_that_drops_the_event_drops_no_row(self): assert await _process(processor, _answer("coordinator", 100, 10)) == [] assert ledgers.ledger(None).totals().calls == 1 - async def test_a_runs_end_carries_what_the_run_used(self): + async def test_a_runs_calls_are_recorded_under_it(self): ledgers = UsageLedgers() - processor = _processor(ledgers=ledgers) - await _delegated(processor) - await _process(processor, _answer("researcher", 50, 5, branch="researcher@toolu_c1")) + processor = _processor(ledgers=ledgers, run=RESEARCHER) - (_, ended) = await _process(processor, _results( - "coordinator", ("researcher", "toolu_c1", {"result": "X is 42."}) - )) + await _process(processor, _answer("researcher", 50, 5)) - assert ended.metadata["usage"] == {"m": {"input": 50, "output": 5}} + (row,) = ledgers.ledger(None).rows + assert (row.agent, row.run) == ("researcher", "researcher-1#1") + assert ledgers.ledger(None).run_usage("researcher-1#1") == { + "m": {"input": 50, "output": 5} + } class TestTheManagersProcessor: diff --git a/tests/workflow/deepagents/fakes.py b/tests/workflow/deepagents/fakes.py index e462597f..c19f6937 100644 --- a/tests/workflow/deepagents/fakes.py +++ b/tests/workflow/deepagents/fakes.py @@ -47,9 +47,11 @@ def ai( return AIMessage(content=content, tool_calls=tool_calls, usage_metadata=usage or USAGE) -def task(subagent: str, brief: str, call_id: str | None = None) -> tuple: - """A ``task`` call delegating ``brief`` to ``subagent``.""" - args = {"description": brief, "subagent_type": subagent} +def task(subagent: str, brief: str, call_id: str | None = None, **fields: str) -> tuple: + """A ``task`` call delegating ``brief`` to ``subagent``: ``brief`` the + objective, its first line the title, and the brief's other ``fields``.""" + title = next((line.strip() for line in brief.splitlines() if line.strip()), "") + args = {"agent_type": subagent, "title": title, "objective": brief, **fields} return ("task", args, call_id) if call_id else ("task", args) @@ -135,3 +137,48 @@ def __init__(self, **scripts: Sequence[AIMessage | Exception]) -> None: def __call__(self, resolved: Any, *, settings: Any, app_name: str) -> ScriptedChat: self.built.append(resolved) return self.chats[resolved.agent] + + +def tree_delegations(configs: Sequence[Any], graphs: dict[str, Any]) -> Any: + """The delegations of a tree a test builds alone (``build_agent_tree``, no manager). + + Pass the result as ``build_agent_tree(delegations=...)`` and the same dict + as ``graphs=``: each run then runs on its type's graph, built by then, + from its shared state and its messages (an inheriting run's history, + then its task message), apart from its caller's stream, as + ``DeepAgentsWorkflowManager._run_agent`` runs one; its answer is its + last text after its task message (an inheriting run's history is not its + own), and the plan and tasks it changed flow back. No ledger, no events: + a manager-level test reads those. + """ + from langchain_core.messages import HumanMessage + from langchain_core.runnables.config import var_child_runnable_config + + from agentic_cli.workflow.agents import AgentRuns, SubAgentPolicy + from agentic_cli.workflow.agents.delegate import Delegations, RunAnswer + + async def hook(run: Any) -> RunAnswer: + task = HumanMessage(content=run.message, id=f"task-{run.ref.run}") + detached = var_child_runnable_config.set(None) + try: + state = await graphs[run.ref.agent].ainvoke({ + **run.state, "messages": [*(run.history or ()), task], + }) + finally: + var_child_runnable_config.reset(detached) + ids = [m.id for m in state["messages"]] + own = state["messages"][ids.index(task.id) + 1:] if task.id in ids else [] + text = next(( + m.text for m in reversed(own) if isinstance(m, AIMessage) and m.text.strip() + ), "") + changed = { + key: state[key] for key in ("plan", "tasks") + if key in state and state[key] != run.state.get(key) + } + return RunAnswer(text=text, state=changed) + + made = Delegations( + runs=AgentRuns(), policy=SubAgentPolicy(), + types={config.name: config for config in configs}, hook=hook, + ) + return lambda: made diff --git a/tests/workflow/deepagents/test_agent_builder.py b/tests/workflow/deepagents/test_agent_builder.py index e53eacff..a465c7fe 100644 --- a/tests/workflow/deepagents/test_agent_builder.py +++ b/tests/workflow/deepagents/test_agent_builder.py @@ -1,11 +1,14 @@ -"""The agent tree (``workflow/deepagents/agent_builder.py``). +"""The agents (``workflow/deepagents/agent_builder.py``). Every ``AgentConfig`` becomes one ``create_agent`` graph on its own chat -model, built bottom-up so a coordinator is built after its sub-agents. A -coordinator delegates through Deep Agents' ``task`` tool, which lists each -sub-agent by its description and is bound to the framework's declaration. A -sub-agent sees only the brief, shares ``plan`` and ``tasks``, and answers with -its last text. Only the root has the checkpointer. Every stack has the +model, each built on its own. A coordinator delegates through the +framework's ``task`` tool (``task_tool.build_task_tool``), which lists each +sub-agent by its description, takes the brief's fields and is bound to the +framework's declaration; its calls go to the manager's delegations, which +run the sub-agent on its own graph (here ``fakes.tree_delegations``, as the +manager's hook does). A sub-agent sees only its task message, shares +``plan`` and ``tasks``, and its last text is the result its parent reads in +the envelope. Only the root has the checkpointer. Every stack has the permission gate and, inside it, the tool-error middleware. The models are scripted (``fakes.ScriptedChat``); nothing reaches a provider. @@ -20,7 +23,6 @@ pytest.importorskip("deepagents") -from deepagents import SubAgentMiddleware # noqa: E402 from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware # noqa: E402 from langchain_core.messages import AIMessage, HumanMessage, ToolMessage # noqa: E402 from langchain_core.tools import StructuredTool # noqa: E402 @@ -37,6 +39,8 @@ identify_tool, register_tool, ) +from agentic_cli.workflow.agents import brief as brief_module # noqa: E402 +from agentic_cli.workflow.agents.brief import Brief, task_message # noqa: E402 from agentic_cli.workflow.config import AgentConfig, AgentGraphError # noqa: E402 from agentic_cli.workflow.deepagents import agent_builder # noqa: E402 from agentic_cli.workflow.deepagents.agent_builder import build_agent_tree # noqa: E402 @@ -50,7 +54,12 @@ from agentic_cli.workflow.deepagents.tools import to_langchain_tools # noqa: E402 from agentic_cli.workflow.permissions import EXEMPT # noqa: E402 from agentic_cli.workflow.permissions.capabilities import Capability # noqa: E402 -from tests.workflow.deepagents.fakes import ScriptedChat, ai, task # noqa: E402 +from tests.workflow.deepagents.fakes import ( # noqa: E402 + ScriptedChat, + ai, + task, + tree_delegations, +) @register_tool(capabilities=EXEMPT) @@ -86,7 +95,8 @@ def spy(*args, **kwargs): return calls -def _tree(configs, models, tools=None, checkpointer=None): +def _tree(configs, models, tools=None, checkpointer=None, **options): + graphs: dict = {} return build_agent_tree( configs, chat_models=models, @@ -95,9 +105,23 @@ def _tree(configs, models, tools=None, checkpointer=None): prompts={config.name: f"You are {config.name}." for config in configs}, settings=None, checkpointer=checkpointer, + delegations=tree_delegations(configs, graphs), + graphs=graphs, + **options, ) +def _task_tool(created: dict, agent: str) -> StructuredTool: + """The ``task`` tool the builder gave ``agent``.""" + (found,) = [tool for tool in created[agent]["tools"] if tool.name == "task"] + return found + + +def _read(message: ToolMessage) -> dict: + """The envelope a ``task`` call's answer holds.""" + return json.loads(message.text) + + async def _turn(root, message: str = "Go.", thread: str = "t") -> dict: return await root.ainvoke( {"messages": [HumanMessage(message)]}, {"configurable": {"thread_id": thread}} @@ -136,10 +160,11 @@ async def test_a_coordinator_delegates_and_answers(self, created): ) state = await _turn(root, "What is X?") - assert list(created) == ["researcher", "coordinator"] # bottom-up + assert list(created) == ["coordinator", "researcher"] # each on its own assert [type(m) for m in state["messages"]] == [ HumanMessage, AIMessage, ToolMessage, AIMessage ] + assert _read(state["messages"][2])["result"] == "X is 42." assert state["messages"][-1].text == "X is 42, says the researcher." async def test_the_root_is_the_agent_nobody_delegates_to(self, created): @@ -220,15 +245,13 @@ def test_task_lists_each_sub_agent_by_its_description(self, created): _tree([coordinator, RESEARCHER, writer], models) - (delegation,) = [ - m for m in created["coordinator"]["middleware"] if isinstance(m, SubAgentMiddleware) - ] - (task_tool,) = delegation.tools + task_tool = _task_tool(created, "coordinator") lines = task_tool.description.splitlines() assert "- researcher: Finds facts." in lines assert "- writer: Writes drafts." in lines assert not any(line.startswith("- general-purpose") for line in lines) - assert delegation.subagent_names == {"researcher", "writer"} + assert task_tool.args["agent_type"]["enum"] == ["researcher", "writer"] + assert not any(tool.name == "task" for tool in created["writer"]["tools"]) async def test_the_coordinator_is_offered_task_and_nothing_of_deep_agents_else(self): coordinator = ScriptedChat(script=[ai("Hi.")]) @@ -243,23 +266,24 @@ async def test_the_coordinator_is_offered_task_and_nothing_of_deep_agents_else(s assert sorted(coordinator.tool_names()) == ["save_plan", "task"] schema = coordinator.tool_schema("task") - assert set(schema["parameters"]["properties"]) == {"description", "subagent_type"} + assert set(schema["parameters"]["properties"]) == { + "agent_type", "title", "objective", "deliverable", "constraints", "known", + "done_when", + } + assert schema["parameters"]["required"] == ["agent_type", "title", "objective"] def test_an_empty_description_falls_back_and_warns(self, created, monkeypatch): log = _Recorder() - monkeypatch.setattr(agent_builder, "logger", log) + monkeypatch.setattr(brief_module, "logger", log) coordinator = AgentConfig(name="coordinator", prompt="p", sub_agents=["helper"]) helper = AgentConfig(name="helper", prompt="p", description=" ") _tree([coordinator, helper], {"coordinator": ScriptedChat(), "helper": ScriptedChat()}) - (delegation,) = [ - m for m in created["coordinator"]["middleware"] if isinstance(m, SubAgentMiddleware) - ] - assert "- helper: The helper agent." in delegation.tools[0].description.splitlines() - assert ( - "warning", "deepagents_subagent_without_description", {"agent": "helper"} - ) in log.calls + assert "- helper: The helper agent." in ( + _task_tool(created, "coordinator").description.splitlines() + ) + assert ("warning", "subagent_without_description", {"agent": "helper"}) in log.calls def test_the_task_tool_is_bound_to_its_declaration(self, created): _tree( @@ -267,10 +291,29 @@ def test_the_task_tool_is_bound_to_its_declaration(self, created): {"coordinator": ScriptedChat(), "researcher": ScriptedChat()}, ) - (delegation,) = [ - m for m in created["coordinator"]["middleware"] if isinstance(m, SubAgentMiddleware) - ] - assert identify_tool(delegation.tools[0]) is get_registry().get("task") + assert identify_tool(_task_tool(created, "coordinator")) is get_registry().get("task") + + def test_without_the_delegations_no_agent_delegates(self, created): + build_agent_tree( + [COORDINATOR, RESEARCHER], + chat_models={"coordinator": ScriptedChat(), "researcher": ScriptedChat()}, + resolved={}, tools={}, prompts={"coordinator": "c", "researcher": "r"}, + settings=None, checkpointer=None, + ) + + assert created["coordinator"]["tools"] == [] + + def test_every_agents_graph_is_kept_by_name(self): + graphs: dict = {} + root = build_agent_tree( + [COORDINATOR, RESEARCHER], + chat_models={"coordinator": ScriptedChat(), "researcher": ScriptedChat()}, + resolved={}, tools={}, prompts={"coordinator": "c", "researcher": "r"}, + settings=None, checkpointer=None, graphs=graphs, + ) + + assert sorted(graphs) == ["coordinator", "researcher"] + assert graphs["coordinator"] is root def test_a_coordinator_tool_named_task_is_refused(self): def task(description: str) -> dict: # noqa: F811 - the point of the test @@ -303,10 +346,14 @@ async def test_nested_delegation(self, created): root = _tree(configs, models, checkpointer=InMemorySaver()) state = await _turn(root) - assert list(created) == ["worker", "lead", "coordinator"] - assert _tool_message(state["messages"], "c1").text == "Lead done." - assert _tool_message(models["lead"].conversation(1), "l1").text == "Worker done." - assert _shape(models["worker"].conversation(0)) == [("human", "Do it.")] + assert list(created) == ["coordinator", "lead", "worker"] + assert _read(_tool_message(state["messages"], "c1"))["result"] == "Lead done." + assert _read(_tool_message(models["lead"].conversation(1), "l1"))["result"] == ( + "Worker done." + ) + assert _shape(models["worker"].conversation(0)) == [ + ("human", task_message(Brief(title="Do it.", objective="Do it."))) + ] assert state["messages"][-1].text == "All done." @@ -336,16 +383,18 @@ async def test_only_the_brief_shared_state_and_its_last_text(self): ) state = await _turn(root, "A long conversation the researcher must not see.") - # Its input is exactly one HumanMessage: the brief. - assert _shape(researcher.conversation(0)) == [("human", "Find X. Report the number.")] + # Its input is exactly one HumanMessage: the task message. + assert _shape(researcher.conversation(0)) == [("human", task_message(Brief( + title="Find X. Report the number.", objective="Find X. Report the number." + )))] # It saw the coordinator's plan ... plan = json.loads(_tool_message(researcher.conversation(1), "r1").text) assert plan == {"success": True, "content": "- [ ] find X"} # ... and its task list flowed back to the coordinator. assert [t["description"] for t in state["tasks"]] == ["find X"] assert state["plan"] == "- [ ] find X" - # Its last non-empty text is the coordinator's tool result. - assert _tool_message(state["messages"], "c1").text == "X is 42." + # Its last non-empty text is the result in the coordinator's envelope. + assert _read(_tool_message(state["messages"], "c1"))["result"] == "X is 42." # Its intermediate messages stay out of the coordinator's conversation. assert not any("Looking." in m.text for m in state["messages"]) @@ -375,8 +424,8 @@ def worker(label: str) -> ScriptedChat: root = _tree(configs, models, tools=tools, checkpointer=InMemorySaver()) state = await _turn(root) - assert _tool_message(state["messages"], "ca").text == "a done." - assert _tool_message(state["messages"], "cb").text == "b done." + assert _read(_tool_message(state["messages"], "ca"))["result"] == "a done." + assert _read(_tool_message(state["messages"], "cb"))["result"] == "b done." assert [t["description"] for t in state["tasks"]] in (["a"], ["b"]) assert state["messages"][-1].text == "Both done." @@ -391,14 +440,13 @@ def test_the_gate_the_error_and_the_active_call_middleware_in_order(self, create _tree(configs, {config.name: ScriptedChat() for config in configs}) - delegating = [ - PatchToolCallsMiddleware, SubAgentMiddleware, - PermissionMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware, + assert [type(m) for m in created["coordinator"]["middleware"]] == [ + PatchToolCallsMiddleware, PermissionMiddleware, ToolCallErrorMiddleware, + ActiveToolCallMiddleware, ] - assert [type(m) for m in created["coordinator"]["middleware"]] == delegating # A sub-agent's model side has SubAgentOutcomeMiddleware; the root's not. assert [type(m) for m in created["lead"]["middleware"]] == [ - PatchToolCallsMiddleware, SubAgentMiddleware, SubAgentOutcomeMiddleware, + PatchToolCallsMiddleware, SubAgentOutcomeMiddleware, PermissionMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware, ] assert [type(m) for m in created["worker"]["middleware"]] == [ @@ -433,13 +481,10 @@ def bound(obj: object) -> ToolDefinition | None: coordinator = ScriptedChat(label="coordinator", script=[ ai(calls=[task("researcher", "Ask.", "c1")]), ai("Done."), ]) - root = build_agent_tree( + root = _tree( [COORDINATOR, RESEARCHER], - chat_models={"coordinator": coordinator, "researcher": researcher}, - resolved={}, + {"coordinator": coordinator, "researcher": researcher}, tools={"researcher": [remote]}, - prompts={"coordinator": "c", "researcher": "r"}, - settings=None, checkpointer=InMemorySaver(), bound=bound, ) @@ -494,4 +539,4 @@ def scratch(path: str) -> dict: "success": False, "error": "builder_flaky failed: RuntimeError: flaky broke", } - assert _tool_message(state["messages"], "c1").text == "Could not." + assert _read(_tool_message(state["messages"], "c1"))["result"] == "Could not." diff --git a/tests/workflow/deepagents/test_compact.py b/tests/workflow/deepagents/test_compact.py index 951a8b9a..97bafec9 100644 --- a/tests/workflow/deepagents/test_compact.py +++ b/tests/workflow/deepagents/test_compact.py @@ -903,6 +903,8 @@ def test_a_failed_summary_s_range_is_found_as_deep_agents_finds_it(self): assert list(inspect.signature(cutoff).parameters) == ["self", "messages"] def test_an_event_is_applied_as_the_summary_and_the_messages_after_its_cut(self): + """An inheriting run reads its parent's conversation through it too + (``task_tool.inherited_messages``): a change fails here first.""" apply = SummarizationMiddleware._apply_event_to_messages messages = [HumanMessage("One?", id="h1"), AIMessage("A1", id="a1"), HumanMessage("Two?", id="h2"), AIMessage("A2", id="a2")] diff --git a/tests/workflow/deepagents/test_context.py b/tests/workflow/deepagents/test_context.py index 7c7b1dcf..dfd0ffab 100644 --- a/tests/workflow/deepagents/test_context.py +++ b/tests/workflow/deepagents/test_context.py @@ -39,7 +39,6 @@ pytest.importorskip("deepagents") -from deepagents import SubAgentMiddleware # noqa: E402 from deepagents.backends.protocol import BackendProtocol # noqa: E402 from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware # noqa: E402 from deepagents.middleware.summarization import SummarizationMiddleware # noqa: E402 @@ -60,6 +59,7 @@ resolve_model, ) from agentic_cli.tools.registry import register_tool # noqa: E402 +from agentic_cli.workflow.agents.brief import Brief, task_message # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 from agentic_cli.workflow.context import ( # noqa: E402 OVERFLOW_ERROR_CODE, @@ -385,7 +385,7 @@ def test_every_stack_in_order(self, created, tmp_path, monkeypatch): lead = created["lead"]["middleware"] assert [type(m) for m in lead] == [ - PatchToolCallsMiddleware, SubAgentMiddleware, ForeignReasoningMiddleware, + PatchToolCallsMiddleware, ForeignReasoningMiddleware, ReportingSummarizationMiddleware, ContextOverflowMiddleware, AnthropicPromptCachingMiddleware, PermissionMiddleware, ToolResultCapMiddleware, ToolCallErrorMiddleware, @@ -393,14 +393,14 @@ def test_every_stack_in_order(self, created, tmp_path, monkeypatch): ] # The cap is inside the gate (a denial is short) and outside the error # middleware (an error result is capped too), on the settings. - assert (lead[7].max_chars, lead[7].folder) == ( + assert (lead[6].max_chars, lead[6].folder) == ( 30_000, tmp_path / ".agentic_cli" / "tool-output" ) assert issubclass(ReportingSummarizationMiddleware, SummarizationMiddleware) # Each agent leaves other providers' and other agents' reasoning out. - assert (lead[2].kind, lead[2].agent) == (ProviderKind.ANTHROPIC, "lead") - assert lead[3].agent == "lead" - assert (lead[5].ttl, lead[5].unsupported_model_behavior) == ("5m", "ignore") + assert (lead[1].kind, lead[1].agent) == (ProviderKind.ANTHROPIC, "lead") + assert lead[2].agent == "lead" + assert (lead[4].ttl, lead[4].unsupported_model_behavior) == ("5m", "ignore") # A sub-agent's model side starts with SubAgentOutcomeMiddleware. assert [type(m) for m in created["helper"]["middleware"]] == [ PatchToolCallsMiddleware, SubAgentOutcomeMiddleware, ForeignReasoningMiddleware, @@ -427,7 +427,7 @@ def test_the_root_gets_the_memory_index_middleware(self, created, tmp_path, monk memory_index_cached=lambda: "", ) lead = [type(m) for m in created["lead"]["middleware"]] - assert lead[2:7] == [ + assert lead[1:6] == [ ForeignReasoningMiddleware, ReportingSummarizationMiddleware, ContextOverflowMiddleware, MemoryIndexMiddleware, AnthropicPromptCachingMiddleware, ] @@ -442,7 +442,7 @@ def test_every_agent_summarizes_on_its_own_models_budget(self, created): _build(TEAM, {"lead": claude, "helper": unknown}, settings) - lead = created["lead"]["middleware"][3]._lc_helper + lead = created["lead"]["middleware"][2]._lc_helper # A sub-agent's model side starts with SubAgentOutcomeMiddleware. helper = created["helper"]["middleware"][3]._lc_helper assert (lead.trigger, lead.keep) == thresholds_of(claude, settings) @@ -792,10 +792,10 @@ async def test_at_the_default_limit_that_result_is_cut_and_the_turn_answers( assert len(tool_message["content"]) <= 50_000 async def test_a_summary_stays_with_the_agent_that_wrote_it(self, small, monkeypatch): - """The coordinator's summary never reaches a sub-agent's brief, and - the sub-agent's own summary never reaches the coordinator.""" + """The coordinator's summary never reaches a sub-agent's task message, + and the sub-agent's own summary never reaches the coordinator.""" lead = [chat_completion(f"Answer {n}.") for n in range(1, 7)] + [ - _call("task", {"description": "Brief.", "subagent_type": "worker"}, "t1"), + _call("task", {"agent_type": "worker", "title": "Brief", "objective": "Brief."}, "t1"), chat_completion("Done."), ] # The worker's second report puts it over its trigger: it summarizes. @@ -820,10 +820,11 @@ async def test_a_summary_stays_with_the_agent_that_wrote_it(self, small, monkeyp assert [e.metadata["agent"] for t in earlier for e in t if e.type is EventType.CONTEXT_TRIMMED] == ["lead"] own = summarized["_summarization_event"] - # ...yet the worker's brief is the brief alone, + # ...yet the worker's request is its task message alone, first, *_, last = server.requests("Work.") - assert first == [{"role": "system", "content": "Work."}, - {"role": "user", "content": "Brief."}] + assert first == [{"role": "system", "content": "Work."}, {"role": "user", "content": ( + task_message(Brief(title="Brief", objective="Brief.")) + )}] # and the worker's summary, of its brief and first report, stays its own. assert last[1]["content"].endswith("A summary of 3 messages.") assert state["_summarization_event"]["cutoff_index"] == own["cutoff_index"] diff --git a/tests/workflow/deepagents/test_delegation_result.py b/tests/workflow/deepagents/test_delegation_result.py deleted file mode 100644 index b692860d..00000000 --- a/tests/workflow/deepagents/test_delegation_result.py +++ /dev/null @@ -1,70 +0,0 @@ -"""A delegation's result on Deep Agents, shown as it is on ADK. - -Deep Agents' ``task`` returns the sub-agent's whole answer as text, which -the generic rendering showed up to 200 characters, lines and all. The event -processor knows the call is a delegation (it ends the run's ``AGENT_RUN`` -there), so it shows the answer's first line -(``tool_summaries.delegation_summary``), and a sub-agent that failed as a -failed result; ``metadata["result"]`` stays the text the parent read. -""" - -from __future__ import annotations - -import pytest - -pytest.importorskip("deepagents") - -from langchain_core.messages import AIMessage, ToolMessage # noqa: E402 - -from agentic_cli.workflow.events import EventType # noqa: E402 -from tests.workflow.deepagents.test_event_processor import ( # noqa: E402 - _call, - _model_update, - _processor, - _tools_update, -) - - -def _result_of(message: ToolMessage, *, name: str = "task"): - """The ``TOOL_RESULT`` the coordinator's call ``c1`` of ``name`` comes back with.""" - processor = _processor() - args = {"description": "Find X.", "subagent_type": "researcher"} if name == "task" else {} - processor.process((), "updates", _model_update(AIMessage("", tool_calls=[ - _call(name, args, "c1"), - ]))) - events = processor.process((), "updates", _tools_update(message)) - return next(e for e in events if e.type is EventType.TOOL_RESULT) - - -class TestADelegationsResult: - def test_shows_the_answers_first_line(self): - result = _result_of(ToolMessage( - "X is 42.\nThe handbook says so.", tool_call_id="c1", name="task" - )) - - assert result.content == "X is 42." - assert result.metadata["success"] is True - # What the parent read stays as Deep Agents gave it. - assert result.metadata["result"] == "X is 42.\nThe handbook says so." - - def test_an_empty_answer_is_no_answer(self): - result = _result_of(ToolMessage("", tool_call_id="c1", name="task")) - - assert result.content == "No answer" - - def test_a_sub_agent_that_failed_is_a_failed_result(self): - result = _result_of(ToolMessage( - "Error running sub-agent: 529 overloaded", - tool_call_id="c1", name="task", status="error", - )) - - assert result.content == "Failed: 529 overloaded" - assert result.metadata["success"] is False - assert result.metadata["error"] == "Error running sub-agent: 529 overloaded" - - def test_another_tools_result_is_rendered_as_before(self): - result = _result_of( - ToolMessage("X is 42.\nMore.", tool_call_id="c1", name="lookup"), name="lookup" - ) - - assert result.content == "X is 42.\nMore." diff --git a/tests/workflow/deepagents/test_event_processor.py b/tests/workflow/deepagents/test_event_processor.py index 149cbb7d..74b2302d 100644 --- a/tests/workflow/deepagents/test_event_processor.py +++ b/tests/workflow/deepagents/test_event_processor.py @@ -1,15 +1,14 @@ """The event stream (``workflow/deepagents/event_processor.py``). -A turn streams ``astream(..., stream_mode=["updates", "tasks"], -subgraphs=True)``: ``(namespace, mode, payload)`` items, ``()`` being the -root. ``DeepAgentsEventProcessor`` turns each finished node output into -``WorkflowEvent``s, one row of the spec's mapping per test class, and -attributes every event to its agent through the ``tasks`` mode, which maps a -sub-agent's ``tools:<task-id>`` namespace to the ``task`` call that started -it. +A turn streams the root agent's graph, ``astream(..., stream_mode=["updates"], +subgraphs=True)``: ``(namespace, mode, payload)`` items. A sub-agent's graph +streams apart, in its run's own task, through a processor made for that run +(``run=``). ``DeepAgentsEventProcessor`` turns each finished node output into +``WorkflowEvent``s, one row of the spec's mapping per test class, each the +processor's agent's and run's: the root's own, or the sub-agent run's. Most tests feed the processor payloads shaped as the stream sends them; the -last runs a real agent tree on scripted models and feeds it the real stream. +last runs a real manager on scripted models and reads its turn's events. """ from __future__ import annotations @@ -32,28 +31,28 @@ ToolMessage, ) from langchain_core.outputs import ChatGeneration, LLMResult # noqa: E402 -from langgraph.checkpoint.memory import InMemorySaver # noqa: E402 from langgraph.graph.message import REMOVE_ALL_MESSAGES # noqa: E402 from agentic_cli.models import ModelCatalog, RoleMap, resolve_model # noqa: E402 +from agentic_cli.tools.registry import register_tool # noqa: E402 from agentic_cli.tools._core.tasks import task_progress_data # noqa: E402 -from agentic_cli.tools.langgraph.state_tools import save_plan, save_tasks # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 from agentic_cli.workflow.context import ( # noqa: E402 OVERFLOW_ERROR_CODE, ContextBudget, overflow_message, ) -from agentic_cli.workflow.deepagents.agent_builder import build_agent_tree # noqa: E402 from agentic_cli.workflow.deepagents.event_processor import ( # noqa: E402 DeepAgentsEventProcessor, RunCallback, ) -from agentic_cli.workflow.deepagents.tools import to_langchain_tools # noqa: E402 +from agentic_cli.workflow.agents.envelope import envelope # noqa: E402 from agentic_cli.workflow.events import EventType, WorkflowEvent # noqa: E402 +from agentic_cli.workflow.permissions import EXEMPT # noqa: E402 from agentic_cli.workflow.live_events import LiveEvents, merged # noqa: E402 +from agentic_cli.workflow.sessions import RunRef # noqa: E402 from tests.models.fakes import providers # noqa: E402 -from tests.workflow.deepagents.fakes import ScriptedChat, ai, task # noqa: E402 +from tests.workflow.deepagents.fakes import ScriptedModels, ai, task # noqa: E402 _PROVIDERS = providers(anthropic="a-test-key", google="g-test-key", openai="o-test-key") @@ -87,29 +86,24 @@ def _model(agent: str, spec: str): } CONTEXT_KEYS = ("agent", "context_trigger", "window_known") -SUB = "tools:4f2c" # a sub-agent's namespace segment: its task's id -NESTED = "tools:9a1e" +RESEARCHER = RunRef( + agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1 +) def _processor(**kwargs) -> DeepAgentsEventProcessor: return DeepAgentsEventProcessor(root="coordinator", agent_models=MODELS, **kwargs) -def _task_started(task_id: str, call: dict, name: str = "tools") -> dict: - """A ``tasks``-mode start payload: one tool call sent to the tools node.""" - return {"id": task_id, "name": name, "input": [call], "triggers": ("__pregel_push",)} +def _run_processor(**kwargs) -> DeepAgentsEventProcessor: + """A processor made for the researcher's run, as ``_run_agent`` makes one.""" + return _processor(run=RESEARCHER, **kwargs) def _call(name: str, args: dict, call_id: str) -> dict: return {"name": name, "args": args, "id": call_id, "type": "tool_call"} -def _delegated(processor, namespace: tuple, segment: str, subagent: str) -> None: - """Tell the processor that ``segment`` under ``namespace`` runs ``subagent``.""" - call = _call("task", {"description": "brief", "subagent_type": subagent}, "c-" + segment) - processor.process(namespace, "tasks", _task_started(segment.removeprefix("tools:"), call)) - - def _model_update(*messages) -> dict: return {"model": {"messages": list(messages)}} @@ -156,13 +150,11 @@ def test_the_roots_text_is_the_reply(self): def test_a_sub_agents_text_is_its_activity(self): # Only the root replies to the user; a sub-agent's text is its work, # and its answer reaches the coordinator as the task call's result. - processor = _processor() - _delegated(processor, (), SUB, "researcher") - - events = processor.process((SUB,), "updates", _model_update(AIMessage("It is 42."))) + events = _run_processor().process((), "updates", _model_update(AIMessage("It is 42."))) (event,) = [e for e in events if e.type is EventType.TEXT] assert (event.metadata["agent"], event.metadata["subagent"]) == ("researcher", True) + assert event.run == RESEARCHER class TestThinking: @@ -220,9 +212,8 @@ def test_one_event_per_call(self): assert all(e.metadata["agent"] == "coordinator" for e in calls) def test_delegation_is_a_task_call(self): - message = AIMessage("", tool_calls=[ - _call("task", {"description": "Find X.", "subagent_type": "researcher"}, "c1"), - ]) + brief = {"agent_type": "researcher", "title": "Find X", "objective": "Find X."} + message = AIMessage("", tool_calls=[_call("task", brief, "c1")]) (event,) = [ e for e in _processor().process((), "updates", _model_update(message)) @@ -230,9 +221,7 @@ def test_delegation_is_a_task_call(self): ] assert event.metadata["tool_name"] == "task" - assert event.metadata["tool_args"] == { - "description": "Find X.", "subagent_type": "researcher" - } + assert event.metadata["tool_args"] == brief def test_a_denied_call_is_a_call_then_a_failed_result(self): processor = _processor() @@ -293,15 +282,14 @@ def test_status_error_is_a_failure(self): def test_a_result_without_a_name_takes_its_calls(self): processor = _processor() processor.process((), "updates", _model_update( - AIMessage("", tool_calls=[_call("task", {"description": "d", "subagent_type": "researcher"}, "c1")]) + AIMessage("", tool_calls=[_call("lookup", {"q": "x"}, "c1")]) )) - event, ended = processor.process( + (event,) = processor.process( (), "updates", _tools_update(ToolMessage("Done.", tool_call_id="c1")) ) - assert event.metadata["tool_name"] == "task" - assert ended.type is EventType.AGENT_RUN + assert event.metadata["tool_name"] == "lookup" def test_a_state_tools_command_is_its_tool_message(self): """``save_plan`` returns a ``Command``; the update carries its state @@ -317,15 +305,36 @@ def test_a_state_tools_command_is_its_tool_message(self): assert event.metadata["result"] == {"success": True, "message": "Plan saved"} assert "Command" not in event.content - def test_a_task_command_is_the_sub_agents_answer(self): + def test_a_task_command_is_the_runs_envelope(self): tasks = [{"id": "t1", "description": "find X", "status": "completed"}] + found = envelope(RESEARCHER, "completed", result="X is 42.\nIt says so.") events = _processor().process((), "updates", _tools_update( - ToolMessage("X is 42.", tool_call_id="c1", name="task"), tasks=tasks + ToolMessage(json.dumps(found), tool_call_id="c1", name="task"), tasks=tasks )) assert _types(events) == [EventType.TOOL_RESULT, EventType.TASK_PROGRESS] - assert events[0].metadata["result"] == "X is 42." + assert events[0].metadata["result"] == found + assert (events[0].content, events[0].metadata["success"]) == ("X is 42.", True) + + def test_a_failed_runs_envelope_is_a_failed_result(self): + found = envelope(RESEARCHER, "failed", error="overloaded") + + (event,) = _processor().process((), "updates", _tools_update( + ToolMessage(json.dumps(found), tool_call_id="c1", name="task") + )) + + assert event.content == "Failed: overloaded" + assert (event.metadata["success"], event.metadata["error"]) == (False, "overloaded") + + def test_an_empty_answer_is_shown_as_no_answer(self): + found = envelope(RESEARCHER, "completed", result="") + + (event,) = _processor().process((), "updates", _tools_update( + ToolMessage(json.dumps(found), tool_call_id="c1", name="task") + )) + + assert (event.content, event.metadata["success"]) == ("No answer", True) def test_a_tool_internal_model_call_is_not_text(self): """``generate_simple`` inside a tool is not a graph node: the stream @@ -358,20 +367,24 @@ def test_a_tasks_update_reports_progress_in_the_same_step(self): assert event.metadata["current_task_description"] == "write it up" assert event.metadata["agent"] == "coordinator" - def test_the_same_list_again_reports_nothing_new(self): - """A sub-agent's list flows back with its result: one report, not two.""" + def test_a_sub_agents_list_is_reported_once_as_it_comes_back(self): + """A sub-agent's list is the conversation's, which its run hands back + with its result: the root's processor reports it then, once.""" processor = _processor() - _delegated(processor, (), SUB, "researcher") message = ToolMessage(json.dumps({"success": True}), tool_call_id="r1", name="save_tasks") - first = processor.process((SUB,), "updates", _tools_update(message, tasks=self.TASKS)) + in_the_run = _run_processor().process((), "updates", _tools_update(message, tasks=self.TASKS)) back = processor.process((), "updates", _tools_update( ToolMessage("Done.", tool_call_id="c1", name="task"), tasks=self.TASKS )) + again = processor.process((), "updates", _tools_update( + ToolMessage("Done.", tool_call_id="c2", name="task"), tasks=self.TASKS + )) - assert _types(first) == [EventType.TOOL_RESULT, EventType.TASK_PROGRESS] - assert first[1].metadata["agent"] == "researcher" - assert _types(back) == [EventType.TOOL_RESULT] + assert _types(in_the_run) == [EventType.TOOL_RESULT] + assert _types(back) == [EventType.TOOL_RESULT, EventType.TASK_PROGRESS] + assert back[1].metadata["agent"] == "coordinator" + assert _types(again) == [EventType.TOOL_RESULT] def test_an_empty_list_reports_nothing(self): message = ToolMessage(json.dumps({"success": True}), tool_call_id="c1", name="save_tasks") @@ -436,14 +449,12 @@ def test_cache_writes_broken_down_by_ttl_are_counted(self): ) def test_a_sub_agents_usage_is_on_its_own_model(self): - processor = _processor() - _delegated(processor, (), SUB, "researcher") message = AIMessage( "Found.", usage_metadata={"input_tokens": 5, "output_tokens": 2, "total_tokens": 7} ) (usage,) = [ - e for e in processor.process((SUB,), "updates", _model_update(message)) + e for e in _run_processor().process((), "updates", _model_update(message)) if e.type is EventType.LLM_USAGE ] @@ -452,15 +463,13 @@ def test_a_sub_agents_usage_is_on_its_own_model(self): assert "cached_tokens" not in usage.metadata def test_a_sub_agents_usage_is_not_the_conversations_context(self): - processor = _processor() - _delegated(processor, (), SUB, "researcher") message = AIMessage( "Found.", usage_metadata={"input_tokens": 5, "output_tokens": 2, "total_tokens": 7} ) - (sub,) = [e for e in processor.process((SUB,), "updates", _model_update(message)) + (sub,) = [e for e in _run_processor().process((), "updates", _model_update(message)) if e.type is EventType.LLM_USAGE] - (root,) = [e for e in processor.process((), "updates", _model_update(message)) + (root,) = [e for e in _processor().process((), "updates", _model_update(message)) if e.type is EventType.LLM_USAGE] assert sub.metadata["purpose"] == "subagent" @@ -472,16 +481,14 @@ def test_a_message_without_usage_reports_none(self): assert EventType.LLM_USAGE not in _types(events) def test_each_agents_usage_carries_its_own_context_trigger(self): - processor = _processor(budgets=BUDGETS) - _delegated(processor, (), SUB, "researcher") message = AIMessage( "Found.", usage_metadata={"input_tokens": 5, "output_tokens": 2, "total_tokens": 7} ) - (sub,) = [e for e in processor.process((SUB,), "updates", _model_update(message)) - if e.type is EventType.LLM_USAGE] - (root,) = [e for e in processor.process((), "updates", _model_update(message)) - if e.type is EventType.LLM_USAGE] + (sub,) = [e for e in _run_processor(budgets=BUDGETS).process( + (), "updates", _model_update(message)) if e.type is EventType.LLM_USAGE] + (root,) = [e for e in _processor(budgets=BUDGETS).process( + (), "updates", _model_update(message)) if e.type is EventType.LLM_USAGE] assert {key: root.metadata.get(key) for key in CONTEXT_KEYS} == { "agent": "coordinator", "context_trigger": 154_536, "window_known": True, @@ -492,49 +499,31 @@ def test_each_agents_usage_carries_its_own_context_trigger(self): class TestError: - def test_a_failed_turn_is_one_error_from_the_agent_that_failed(self): - """A sub-agent's failure that escaped its ``task`` call. In a turn the - framework builds none does (``ToolCallErrorMiddleware`` answers the - call; only a cancel or LangGraph's control flow escapes it): this - branch of the processor is defensive.""" - processor = _processor() - _delegated(processor, (), SUB, "researcher") + def test_a_failed_turn_is_one_error_the_agents(self): error = RuntimeError("Error code: 400 - bad request") - # The sub-agent's model task fails first, then the coordinator's tools task. - processor.process((SUB,), "tasks", {"id": "m1", "name": "model", "error": error, - "interrupts": [], "result": None}) - processor.process((), "tasks", {"id": SUB.removeprefix("tools:"), "name": "tools", - "error": error, "interrupts": [], "result": None}) - event = processor.turn_failed(error) + event = _processor().turn_failed(error) assert event.type is EventType.ERROR assert event.content == "Error code: 400 - bad request" assert event.metadata["error_code"] == "RuntimeError" assert event.metadata["recoverable"] is False - assert event.metadata["agent"] == "researcher" + assert event.metadata["agent"] == "coordinator" - def test_without_a_failed_task_it_is_the_roots(self): + def test_without_a_message_it_is_named_by_its_type(self): event = _processor().turn_failed(TimeoutError()) assert event.content == "TimeoutError" assert event.metadata["agent"] == "coordinator" - def test_an_overflow_names_the_failing_agents_model(self): - """Deep Agents' own error when a summary still does not fit, escaping - a sub-agent's ``task`` call: in a turn the framework builds, - ``ToolCallErrorMiddleware`` answers that call instead (a defensive - branch; the root's own overflow is the next test's).""" - processor = _processor() - _delegated(processor, (), SUB, "researcher") + def test_an_overflow_names_the_agents_own_model(self): + """Deep Agents' own error when a summary still does not fit.""" error = ContextOverflowError( "Context remains above the input budget after compaction; reduce input, " "tools, or configured output tokens." ) - processor.process((SUB,), "tasks", {"id": "m1", "name": "model", "error": error, - "interrupts": [], "result": None}) - event = processor.turn_failed(error) + event = _run_processor().turn_failed(error) assert event.type is EventType.ERROR assert event.content == overflow_message("google:gemini-2.5-flash") @@ -559,107 +548,26 @@ def test_a_providers_overflow_at_the_root(self): assert event.metadata["error_code"] == OVERFLOW_ERROR_CODE assert event.metadata["agent"] == "coordinator" - def test_a_failure_its_task_call_answered_is_not_the_turns(self): - """A sub-agent whose model failed answers its ``task`` call with the - error, and its coordinator goes on: a later failure is the coordinator's.""" - processor = _processor() - _delegated(processor, (), SUB, "researcher") - processor.process((SUB,), "tasks", {"id": "m1", "name": "model", - "error": RuntimeError("overloaded"), - "interrupts": [], "result": None}) - processor.process((), "updates", _tools_update(ToolMessage( - "Error running sub-agent: overloaded", tool_call_id="c-" + SUB, name="task", - status="error", - ))) - - event = processor.turn_failed(TimeoutError()) - - assert event.metadata["agent"] == "coordinator" - - def test_a_nested_failure_answered_leaves_its_parents_own(self): - """The leaf fails and its task call is answered; then its parent fails, - unanswered: the turn's failure is the parent's.""" - processor = _processor() - _delegated(processor, (), SUB, "researcher") - _delegated(processor, (SUB,), NESTED, "leaf") - error = RuntimeError("overloaded") - processor.process((SUB, NESTED), "tasks", {"id": "m2", "name": "model", "error": error, - "interrupts": [], "result": None}) - processor.process((SUB,), "updates", _tools_update(ToolMessage( - "Error running sub-agent: overloaded", tool_call_id="c-" + NESTED, name="task", - status="error", - ))) - processor.process((SUB,), "tasks", {"id": "m1", "name": "model", "error": error, - "interrupts": [], "result": None}) - - event = processor.turn_failed(error) - - assert event.metadata["agent"] == "researcher" - - def test_a_sub_agents_own_call_of_the_same_id_answers_no_delegation(self): - """Call ids are only an agent's own (a provider that numbers them - gives a sub-agent's first call its parent's ``task`` call's): the - sub-agent's own result is not its delegation's, which still answers - the failure inside it when its own result comes.""" - processor = _processor() - _delegated(processor, (), SUB, "researcher") - processor.process((SUB,), "updates", _tools_update(ToolMessage( - '{"success": true}', tool_call_id="c-" + SUB, name="contract_lookup", - ))) - processor.process((SUB,), "tasks", {"id": "m1", "name": "model", - "error": RuntimeError("overloaded"), - "interrupts": [], "result": None}) - processor.process((), "updates", _tools_update(ToolMessage( - "Error running sub-agent: overloaded", tool_call_id="c-" + SUB, name="task", - status="error", - ))) - - event = processor.turn_failed(TimeoutError()) - - assert event.metadata["agent"] == "coordinator" - class TestAttribution: - def test_a_sub_agents_events_are_its_own(self): - processor = _processor() - _delegated(processor, (), SUB, "researcher") - - events = processor.process( - (SUB,), "updates", _model_update(AIMessage("", tool_calls=[_call("grep", {}, "r1")])) + def test_a_sub_agents_events_are_its_runs(self): + events = _run_processor().process( + (), "updates", _model_update(AIMessage("", tool_calls=[_call("grep", {}, "r1")])) ) - assert {e.metadata["agent"] for e in events} == {"researcher"} + assert {(e.metadata["agent"], e.run) for e in events} == {("researcher", RESEARCHER)} - def test_nested_namespaces_resolve_through_the_chain(self): + def test_an_item_of_a_nested_graph_is_none_of_its_events(self): + """Only its own graph's items (the root namespace) are its events: a + graph a tool runs under the config it inherits streams in a + namespace of its own, and its model's text is no agent's reply.""" processor = _processor() - _delegated(processor, (), SUB, "researcher") - _delegated(processor, (SUB,), NESTED, "worker") - message = AIMessage( - "Done.", usage_metadata={"input_tokens": 1, "output_tokens": 1, "total_tokens": 2} - ) - - events = processor.process((SUB, NESTED), "updates", _model_update(message)) - - assert {e.metadata["agent"] for e in events} == {"worker"} - assert next(e for e in events if e.type is EventType.LLM_USAGE).metadata["model"] == ( - "openai:gpt-5" - ) - - def test_an_unknown_namespace_falls_back_to_the_root(self): - events = _processor().process(("tools:unseen",), "updates", _model_update(AIMessage("Hi."))) - - assert {e.metadata["agent"] for e in events} == {"coordinator"} - - def test_a_tools_task_that_is_not_delegation_maps_nothing(self): - """Only ``task`` delegates, whatever another tool's arguments say.""" - processor = _processor() - lookalike = _call("assign", {"subagent_type": "researcher"}, "c1") - processor.process((), "tasks", _task_started("ab12", lookalike)) - - events = processor.process(("tools:ab12",), "updates", _model_update(AIMessage("Hi."))) - - assert {e.metadata["agent"] for e in events} == {"coordinator"} + assert processor.process( + ("tools:unseen",), "updates", _model_update(AIMessage("Hi.")) + ) == [] + (said,) = processor.process((), "updates", _model_update(AIMessage("Hi."))) + assert (said.type, said.metadata["agent"]) == (EventType.TEXT, "coordinator") def test_other_nodes_emit_nothing(self): """A middleware hook's update (here, a patched history) is not output.""" @@ -671,6 +579,7 @@ def test_other_nodes_emit_nothing(self): assert processor.process((), "updates", {"PatchToolCallsMiddleware.before_agent": patched}) == [] assert processor.process((), "updates", {"PatchToolCallsMiddleware.before_agent": None}) == [] assert processor.process((), "custom", {"anything": 1}) == [] + assert processor.process((), "tasks", {"id": "t1", "name": "tools"}) == [] async def _reported(live: LiveEvents, act) -> list[WorkflowEvent]: @@ -769,48 +678,85 @@ async def act(): "tokens_before": 18_000, "tokens_after": 3_100} -class TestARealStream: - """A real tree on scripted models: the stream's own shapes, end to end.""" +@register_tool(capabilities=EXEMPT, description="Run a graph of its own (a processor test tool).") +async def processor_probe_nested_graph() -> dict: + """Run a LangGraph graph whose "model" node answers, under the config the + tool inherits: its updates reach the turn's stream as a subgraph's.""" + from langgraph.graph import START, MessagesState, StateGraph + + graph = StateGraph(MessagesState) + graph.add_node("model", lambda state: {"messages": [AIMessage("The nested graph's text.")]}) + graph.add_edge(START, "model") + await graph.compile().ainvoke({"messages": [HumanMessage("Go.")]}) + return {"success": True} - async def test_a_delegating_turn(self): - configs = [ - AgentConfig(name="coordinator", prompt="p", sub_agents=["researcher"]), - AgentConfig(name="researcher", prompt="p", description="Finds facts."), + +class TestARealTurn: + """A real manager on scripted models: the turn's events end to end, the + sub-agent's run among them, as its own stream reports them.""" + + async def test_a_graph_a_tool_runs_is_none_of_the_turns_text(self, tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("HOME", str(tmp_path)) + monkeypatch.setenv("ANTHROPIC_API_KEY", "a-test-key") + from agentic_cli.config import BaseSettings + from agentic_cli.workflow.deepagents import manager as manager_module + + models = ScriptedModels( + solo=[ai(calls=[("processor_probe_nested_graph", {}, "c1")]), ai("Done.")] + ) + monkeypatch.setattr(manager_module, "build_chat_model", models) + manager = manager_module.DeepAgentsWorkflowManager( + agent_configs=[AgentConfig(name="solo", prompt="p", + tools=[processor_probe_nested_graph], + model="anthropic:claude-sonnet-4-5")], + settings=BaseSettings(session_store="memory", default_model="anthropic:claude-sonnet-4-5"), + ) + try: + events = [e async for e in manager.process("Go.", "u", session_id="s1")] + finally: + await manager.cleanup() + + assert [e.content for e in events if e.type is EventType.TEXT] == ["Done."] + assert [e.metadata.get("tool_name") for e in events + if e.type in (EventType.TOOL_CALL, EventType.TOOL_RESULT)] == [ + "processor_probe_nested_graph", "processor_probe_nested_graph", ] - models = { - "coordinator": ScriptedChat(label="coordinator", script=[ + + async def test_a_delegating_turn(self, tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("HOME", str(tmp_path)) + monkeypatch.setenv("ANTHROPIC_API_KEY", "a-test-key") + from agentic_cli.config import BaseSettings + from agentic_cli.workflow.deepagents import manager as manager_module + + models = ScriptedModels( + coordinator=[ ai(calls=[("save_plan", {"content": "- [ ] find X"}, "c0")]), ai("Delegating.", calls=[task("researcher", "Find X.", "c1")]), ai("X is 42."), - ]), - "researcher": ScriptedChat(label="researcher", script=[ + ], + researcher=[ ai(calls=[("save_tasks", {"tasks": [ {"description": "find X", "status": "in_progress"} ]}, "r1")], reasoning="Plan first."), ai("It is 42."), - ]), - } - root = build_agent_tree( - configs, - chat_models=models, - resolved=MODELS, - tools={ - "coordinator": to_langchain_tools([save_plan]), - "researcher": to_langchain_tools([save_tasks]), - }, - prompts={"coordinator": "Coordinate.", "researcher": "Research."}, - settings=None, - checkpointer=InMemorySaver(), + ], + ) + monkeypatch.setattr(manager_module, "build_chat_model", models) + manager = manager_module.DeepAgentsWorkflowManager( + agent_configs=[ + AgentConfig(name="coordinator", prompt="p", sub_agents=["researcher"], + model="anthropic:claude-sonnet-4-5"), + AgentConfig(name="researcher", prompt="p", description="Finds facts.", + model="anthropic:claude-haiku-4-5"), + ], + settings=BaseSettings(session_store="memory", default_model="anthropic:claude-sonnet-4-5"), ) - processor = _processor(session_id="s1") - events: list[WorkflowEvent] = [] - async for namespace, mode, payload in root.astream( - {"messages": [HumanMessage("What is X?")]}, - {"configurable": {"thread_id": "t"}}, - stream_mode=["updates", "tasks"], - subgraphs=True, - ): - events += processor.process(namespace, mode, payload) + try: + events = [e async for e in manager.process("What is X?", "u", session_id="s1")] + finally: + await manager.cleanup() seen = [ (e.type.value, e.metadata["agent"], e.metadata.get("tool_name") or e.content) @@ -829,10 +775,10 @@ async def test_a_delegating_turn(self): ("thinking", "researcher", "Plan first."), ("tool_call", "researcher", "save_tasks"), ("tool_result", "researcher", "save_tasks"), - ("task_progress", "researcher", progress["display"]), ("text", "researcher", "It is 42."), - ("tool_result", "coordinator", "task"), ("agent_run", "researcher", "researcher-1 completed"), + ("tool_result", "coordinator", "task"), + ("task_progress", "coordinator", progress["display"]), ("text", "coordinator", "X is 42."), ] assert [(e.metadata["agent"], e.metadata.get("subagent")) for e in events @@ -844,13 +790,13 @@ async def test_a_delegating_turn(self): assert usage == [ ("coordinator", "anthropic:claude-sonnet-4-5"), ("coordinator", "anthropic:claude-sonnet-4-5"), - ("researcher", "google:gemini-2.5-flash"), - ("researcher", "google:gemini-2.5-flash"), + ("researcher", "anthropic:claude-haiku-4-5"), + ("researcher", "anthropic:claude-haiku-4-5"), ("coordinator", "anthropic:claude-sonnet-4-5"), ] task_result = next( e for e in events if e.type is EventType.TOOL_RESULT and e.metadata["tool_name"] == "task" ) - assert task_result.metadata["result"] == "It is 42." + assert task_result.metadata["result"]["result"] == "It is 42." assert all("Command(" not in e.content for e in events) diff --git a/tests/workflow/deepagents/test_fork.py b/tests/workflow/deepagents/test_fork.py index ae701992..f836309a 100644 --- a/tests/workflow/deepagents/test_fork.py +++ b/tests/workflow/deepagents/test_fork.py @@ -1,13 +1,11 @@ -"""A sub-agent's context on Deep Agents: a fresh brief, or a fork of the conversation. - -A sub-agent with ``inherit_context`` False (the default) is Deep Agents' -isolated ``CompiledSubAgent``: its first request holds the brief alone. One -with ``inherit_context=True`` is a fork (``mode="fork"``): it gets the coordinator's effective -conversation (after any summary), without the message that called ``task``, -then Deep Agents' preamble and the brief. It keeps its own prompt, tools and -model. Deep Agents marks forks beta with a ``LangChainBetaWarning`` that -LangChain would print over the UI; that one warning is filtered and logged at -debug instead. A fork never sends the coordinator's reasoning on (signed +"""A sub-agent's context on Deep Agents: its task message alone, or the conversation first. + +A sub-agent with ``inherit_context`` False (the default) is sent its task +message alone (``agents/brief.py::task_message``). One with +``inherit_context=True`` gets the coordinator's effective conversation (after +any summary), without the message that called ``task``, then its task +message, which ends with ``INHERITED_CONTEXT_NOTE``. It keeps its own prompt, +tools and model. It never sends the coordinator's reasoning on (signed reasoning from one model may be refused by another), while its own goes back to it in its tool loop; the coordinator's state keeps all of it. @@ -24,18 +22,15 @@ pytest.importorskip("deepagents") -from deepagents import CompiledSubAgent, SubAgentMiddleware # noqa: E402 -from langchain.agents import create_agent # noqa: E402 from langchain.agents.middleware import ModelRequest # noqa: E402 -from langchain_core._api import LangChainBetaWarning # noqa: E402 from langchain_core.messages import AIMessage, HumanMessage # noqa: E402 from agentic_cli.cli.usage_tracker import UsageTracker, format_tokens # noqa: E402 from agentic_cli.config import BaseSettings # noqa: E402 from agentic_cli.models import ProviderKind # noqa: E402 +from agentic_cli.workflow.agents.brief import INHERITED_CONTEXT_NOTE, Brief, task_message # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 from agentic_cli.workflow.context import context_budget # noqa: E402 -from agentic_cli.workflow.deepagents import agent_builder # noqa: E402 from agentic_cli.workflow.deepagents import manager as manager_module # noqa: E402 from agentic_cli.workflow.deepagents.manager import DeepAgentsWorkflowManager # noqa: E402 from agentic_cli.workflow.deepagents.middleware import ForeignReasoningMiddleware # noqa: E402 @@ -45,21 +40,11 @@ BRIEF = "Find X. Report the number." TURNS = ["My name is Ada and the secret code is 7.", "Have the researcher find X."] -#: How Deep Agents opens a fork's task message. -PREAMBLE = "[The messages above are a prior conversation you are continuing as the subagent" -class _Recorder: - """Stands in for a module's structlog logger.""" - - def __init__(self) -> None: - self.calls: list[tuple[str, str, dict]] = [] - - def __getattr__(self, level: str): - def log(event: str, **fields) -> None: - self.calls.append((level, event, fields)) - - return log +def task_of(inherit: bool = False) -> str: + """The researcher's task message for ``BRIEF``.""" + return task_message(Brief(title=BRIEF, objective=BRIEF), inherit=inherit) @pytest.fixture @@ -135,19 +120,19 @@ async def test_an_inheriting_one_continues_the_conversation(self, hermetic, monk # The coordinator's conversation, without the message that delegated ... assert sent[:3] == [("human", TURNS[0]), ("ai", "Noted, Ada."), ("human", TURNS[1])] assert not any("Delegating." in text for _, text in sent) - # ... then Deep Agents' preamble and the brief. - (kind, last), = sent[3:] - assert kind == "human" and last.startswith(PREAMBLE) and last.endswith(BRIEF) + # ... then its task message, which ends with the note. + assert sent[3:] == [("human", task_of(inherit=True))] + assert sent[3][1].endswith(INHERITED_CONTEXT_NOTE) # Its own prompt, not the coordinator's. assert researcher.system_prompt(0).startswith("You research.") assert [e.content for e in events[1] if e.type is EventType.TEXT][-1] == ( "The researcher says X is 42." ) - async def test_a_fresh_one_sees_only_the_brief(self, hermetic, monkeypatch): + async def test_a_fresh_one_sees_only_its_task_message(self, hermetic, monkeypatch): models, _ = await two_turns(monkeypatch, team(False), delegating()) - assert shape(models.chats["researcher"].conversation(0)) == [("human", BRIEF)] + assert shape(models.chats["researcher"].conversation(0)) == [("human", task_of())] class TestUsagePerAgent: @@ -224,43 +209,6 @@ def sized(prompt_tokens: int) -> dict: ] -class TestTheBetaWarning: - def test_deep_agents_warns_of_a_fork(self): - # What the builder quiets: if Deep Agents stops warning, or words it - # otherwise, this fails and the filter is to be revisited. - runnable = create_agent(model=ScriptedChat(), tools=[], name="researcher") - fork = CompiledSubAgent( - name="researcher", description="Finds facts.", runnable=runnable, mode="fork" - ) - with pytest.warns(LangChainBetaWarning, match="The feature `forked subagents` is in beta"): - SubAgentMiddleware(backend=None, subagents=[fork]) - - async def test_building_a_fork_logs_it_instead(self, hermetic, monkeypatch, recwarn): - recorder = _Recorder() - monkeypatch.setattr(agent_builder, "logger", recorder) - scripted(monkeypatch, **delegating()) - manager = manager_for(team(True)) - try: - await manager.initialize_services() - finally: - await manager.cleanup() - - assert [w for w in recwarn if issubclass(w.category, LangChainBetaWarning)] == [] - assert ("debug", "deepagents_fork_beta", {"agents": ["researcher"]}) in recorder.calls - - async def test_no_fork_logs_nothing(self, hermetic, monkeypatch): - recorder = _Recorder() - monkeypatch.setattr(agent_builder, "logger", recorder) - scripted(monkeypatch, **delegating()) - manager = manager_for(team(False)) - try: - await manager.initialize_services() - finally: - await manager.cleanup() - - assert [event for _, event, _ in recorder.calls if event == "deepagents_fork_beta"] == [] - - # --- reasoning ------------------------------------------------------------------------- diff --git a/tests/workflow/deepagents/test_manager.py b/tests/workflow/deepagents/test_manager.py index 533baf57..8e71ec74 100644 --- a/tests/workflow/deepagents/test_manager.py +++ b/tests/workflow/deepagents/test_manager.py @@ -25,6 +25,7 @@ from agentic_cli.config import BaseSettings, get_settings # noqa: E402 from agentic_cli.tools.registry import register_tool # noqa: E402 from agentic_cli.workflow import factory # noqa: E402 +from agentic_cli.workflow.agents.brief import Brief, task_message # noqa: E402 from agentic_cli.workflow.config import AgentConfig, AgentGraphError # noqa: E402 from agentic_cli.workflow.deepagents import manager as manager_module # noqa: E402 from agentic_cli.workflow.deepagents.manager import DeepAgentsWorkflowManager # noqa: E402 @@ -164,7 +165,9 @@ async def test_each_agent_runs_on_its_own_resolved_model(self, ctx, monkeypatch, "writer": "google:gemini-2.5-pro", } assert dict(manager.agent_models) == {r.agent: r for r in models.built} - assert models.chats["writer"].conversation(0)[0].text == "Write it." + assert models.chats["writer"].conversation(0)[0].text == task_message( + Brief(title="Write it.", objective="Write it.") + ) assert [e.metadata["model"] for e in of(events, EventType.LLM_USAGE)] == [ "google:gemini-2.5-flash", "google:gemini-2.5-pro", "google:gemini-2.5-flash" ] diff --git a/tests/workflow/deepagents/test_permission_middleware.py b/tests/workflow/deepagents/test_permission_middleware.py index f80cd7d3..a213fd45 100644 --- a/tests/workflow/deepagents/test_permission_middleware.py +++ b/tests/workflow/deepagents/test_permission_middleware.py @@ -30,7 +30,6 @@ pytest.importorskip("deepagents") from langchain.agents.middleware import ToolCallRequest # noqa: E402 -from langchain_core.exceptions import ContextOverflowError # noqa: E402 from langchain_core.messages import ToolMessage # noqa: E402 from langchain_core.tools import BaseTool, StructuredTool # noqa: E402 from langgraph.errors import GraphInterrupt # noqa: E402 @@ -44,17 +43,12 @@ get_registry, register_tool, ) -from agentic_cli.workflow import live_events # noqa: E402 -from agentic_cli.workflow.agents import AgentRuns # noqa: E402 from agentic_cli.workflow.base_manager import BaseWorkflowManager # noqa: E402 from agentic_cli.workflow.deepagents.middleware import ( # noqa: E402 PermissionMiddleware, ToolCallErrorMiddleware, ) -from agentic_cli.workflow.context import OVERFLOW_ERROR_CODE # noqa: E402 from agentic_cli.workflow.deepagents.tools import to_langchain_tools # noqa: E402 -from agentic_cli.workflow.events import EventType, WorkflowEvent # noqa: E402 -from agentic_cli.workflow.live_events import LiveEvents, merged # noqa: E402 from agentic_cli.workflow.permissions import EXEMPT, PermissionEngine # noqa: E402 from agentic_cli.workflow.permissions.capabilities import Capability # noqa: E402 from agentic_cli.workflow.permissions.prompt import ( # noqa: E402 @@ -635,7 +629,8 @@ def _delegation(subagent: str = "researcher") -> ToolCallRequest: tool = _Native(name="task") bind_tool_identity(tool, get_registry().get("task")) return ToolCallRequest( - tool_call={"name": "task", "args": {"description": "Find X.", "subagent_type": subagent}, + tool_call={"name": "task", + "args": {"agent_type": subagent, "title": "Find X", "objective": "Find X."}, "id": "call-9", "type": "tool_call"}, tool=tool, state={}, @@ -643,117 +638,18 @@ def _delegation(subagent: str = "researcher") -> ToolCallRequest: ) -async def _warned(act) -> list[WorkflowEvent]: - """What ``act`` (an async callable) reports through a turn's live events.""" - live = LiveEvents() +class TestADelegation: + """The framework's ``task`` never raises for its sub-agent: a failed run + is answered with its envelope (``agents/delegate.py``). What escapes it + anyway is a tool error, as any tool's; cancelling still cancels.""" - async def source(): - with live_events.reporting(live): - await act() - if False: # pragma: no cover - a source that yields nothing itself - yield + async def test_an_exception_out_of_it_is_a_tool_error(self): + error = RuntimeError("delegation broke") - return [item async for item in merged(source(), live)] + message = await ToolCallErrorMiddleware().awrap_tool_call(_delegation(), _raising(error)) - -class TestAFailedDelegation: - """What escapes ``task`` is the sub-agent's model or run failing (its own - tools' errors were already results): the call is answered as ADK's - delegation tool answers it, the user is warned, and the turn goes on.""" - - async def test_its_result_is_adks_error_text(self): - message = await ToolCallErrorMiddleware().awrap_tool_call( - _delegation(), _raising(RuntimeError("provider said 400")) - ) - - assert isinstance(message, ToolMessage) - assert (message.content, message.status, message.name, message.tool_call_id) == ( - "Error running sub-agent: provider said 400", "error", "task", "call-9", - ) - - async def test_an_error_without_text_is_named_by_its_type(self): - message = await ToolCallErrorMiddleware().awrap_tool_call( - _delegation(), _raising(TimeoutError()) - ) - - assert message.content == "Error running sub-agent: TimeoutError" - - async def test_the_user_is_warned_once_as_the_sub_agents_run(self): - runs = AgentRuns() - started = runs.run_for(None, None, "call-9", "researcher") - - async def act(): - await ToolCallErrorMiddleware(runs).awrap_tool_call( - _delegation(), _raising(RuntimeError("provider said 400")) - ) - - (warning,) = await _warned(act) - - assert warning.type is EventType.ERROR - assert warning.content == "researcher failed: provider said 400" - assert (warning.metadata["recoverable"], warning.metadata["agent"], - warning.metadata["error_code"]) == (True, "researcher", "RuntimeError") - assert warning.run == started - - async def test_a_call_to_a_type_not_its_own_numbers_no_instance(self): - """Only a ``task`` call to one of the agent's own sub-agents is a run - (``ActiveToolCallMiddleware``'s rule): another's failure numbers no - instance of that type. (Its warning is still given; in a turn it - names the caller's run, as any live event that names none does.)""" - runs = AgentRuns() - - async def act(): - await ToolCallErrorMiddleware(runs, sub_agents=("writer",)).awrap_tool_call( - _delegation("researcher"), _raising(RuntimeError("provider said 400")) - ) - - (warning,) = await _warned(act) - - assert warning.content == "researcher failed: provider said 400" - assert runs.run_for(None, None, "call-10", "researcher").instance == "researcher-1" - - @pytest.mark.parametrize("models, model", [ - ({"researcher": "anthropic:claude-sonnet-4-6"}, "anthropic:claude-sonnet-4-6"), - ({}, "the model"), - ]) - async def test_an_overflow_is_said_as_on_adk(self, models, model): - """A request too long for the sub-agent's model, after its summary: - the warning ADK's overflow handler gives, its code ``CONTEXT_OVERFLOW``; - the parent reads the error, as for any other failure.""" - runs = AgentRuns() - started = runs.run_for(None, None, "call-9", "researcher") - error = ContextOverflowError("Model input still does not fit after recovery.") - answered: list[ToolMessage] = [] - - async def act(): - answered.append(await ToolCallErrorMiddleware(runs, models=models).awrap_tool_call( - _delegation(), _raising(error) - )) - - (warning,) = await _warned(act) - - assert warning.content == ( - f"researcher: the request no longer fits {model}'s context window." - ) - assert warning.metadata == { - "recoverable": True, "error_code": OVERFLOW_ERROR_CODE, "agent": "researcher", - } - assert warning.run == started - assert answered[0].content == ( - "Error running sub-agent: Model input still does not fit after recovery." - ) - - async def test_it_is_logged_below_a_warning(self): - """The ``ERROR`` is the report: nothing is said twice over the CLI's prompt.""" - with capture_logs() as logs: - await ToolCallErrorMiddleware().awrap_tool_call( - _delegation(), _raising(RuntimeError("provider said 400")) - ) - - assert {log["log_level"] for log in logs if log["event"] == "subagent_failed"} == { - "info", "debug", - } - assert not [log for log in logs if log["log_level"] in ("warning", "error")] + assert _content(message) == tool_error_result("task", error) + assert (message.status, message.tool_call_id) == ("error", "call-9") async def test_cancelling_still_cancels(self): with pytest.raises(asyncio.CancelledError): diff --git a/tests/workflow/deepagents/test_raw_logging.py b/tests/workflow/deepagents/test_raw_logging.py index 3496a914..dd444776 100644 --- a/tests/workflow/deepagents/test_raw_logging.py +++ b/tests/workflow/deepagents/test_raw_logging.py @@ -26,6 +26,7 @@ from agentic_cli.config import BaseSettings # noqa: E402 from agentic_cli.tools.registry import register_tool # noqa: E402 +from agentic_cli.workflow.agents.brief import Brief, task_message # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 from agentic_cli.workflow.deepagents.manager import DeepAgentsWorkflowManager # noqa: E402 from agentic_cli.workflow.events import EventType # noqa: E402 @@ -135,7 +136,8 @@ def _delegating_server(monkeypatch, turns: int = 1) -> Endpoint: """The server for ``turns`` delegating turns, each on a fresh manager.""" server = Endpoint(**{ "Lead.": [ - _call("task", {"description": "Report.", "subagent_type": "worker"}, "t1"), + _call("task", {"agent_type": "worker", "title": "Report", "objective": "Report."}, + "t1"), chat_completion("Done."), ] * turns, # The second report puts the worker over its trigger: it summarizes. @@ -235,7 +237,9 @@ async def test_a_record_holds_what_was_sent_and_what_came_back(self, home, monke request, response = logged[2], logged[3] # the worker's first call assert request.metadata["model"] == "small" assert request.metadata["system_instruction"] == "Work." - assert request.metadata["messages"] == [{"role": "user", "content": "Report."}] + assert request.metadata["messages"] == [ + {"role": "user", "content": task_message(Brief(title="Report", objective="Report."))} + ] assert request.metadata["tools"] == ["rl_digest", "rl_report"] assert request.metadata["config"]["model_name"] == "small" assert "tools" not in request.metadata["config"] diff --git a/tests/workflow/deepagents/test_run_identity.py b/tests/workflow/deepagents/test_run_identity.py index c0b13ec7..12fa6ced 100644 --- a/tests/workflow/deepagents/test_run_identity.py +++ b/tests/workflow/deepagents/test_run_identity.py @@ -1,18 +1,17 @@ -"""Each Deep Agents event is its run's: the namespace a sub-agent's work streams under names it. - -A sub-agent runs inside its coordinator's ``task`` call, a tools task whose -namespace segment ``tools:<task id>`` its events stream under; the ``tasks`` -stream announces that task with the call. The event processor names each -event's run from its namespace, follows a ``task`` call and its result with -the ``AGENT_RUN`` that starts and ends the run, and records it; -``ActiveToolCallMiddleware`` makes the run the active one around the -``task`` call, which the whole sub-agent runs inside. +"""Each Deep Agents event is its run's: the root's own, or the sub-agent run whose graph streamed it. + +A sub-agent run runs its agent's graph apart from its parent's stream, in +the run's own task (``agents/delegate.py``, ``DeepAgentsWorkflowManager._run_agent``), +through a processor made for that run: every event it makes is that run's. +The root's stream carries the root's own events alone. The ``AGENT_RUN`` +events are the framework's. ``ActiveToolCallMiddleware`` makes each tool +call the active one around its tool, the ``task`` call included; the run it +starts is the active run in the run's own task, with no tool call active. """ from __future__ import annotations import asyncio -import json from types import SimpleNamespace import pytest @@ -20,294 +19,66 @@ pytest.importorskip("deepagents") from langchain.agents.middleware import ToolCallRequest # noqa: E402 -from langchain_core.messages import AIMessage, ToolMessage # noqa: E402 +from langchain_core.messages import AIMessage # noqa: E402 -from agentic_cli.workflow.agents import ( # noqa: E402 - RUN_COMPLETED, - RUN_FAILED, - RUN_STARTED, - AgentRuns, -) -from agentic_cli.workflow.deepagents.event_processor import DeepAgentsEventProcessor # noqa: E402 from agentic_cli.workflow.deepagents.middleware import ActiveToolCallMiddleware # noqa: E402 -from agentic_cli.workflow.events import EventType # noqa: E402 from agentic_cli.workflow.sessions import ( # noqa: E402 - RunRef, + ToolCallRef, get_active_run, + get_active_tool_call, reset_active_run, root_run, set_active_run, ) from tests.workflow.deepagents.test_event_processor import ( # noqa: E402 - MODELS, - NESTED, - SUB, + RESEARCHER, _call, - _delegated, _model_update, - _task_started, - _tools_update, - _types, -) - -RESEARCHER = RunRef( - agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1 + _processor, + _run_processor, ) -def _processor(**kwargs) -> DeepAgentsEventProcessor: - return DeepAgentsEventProcessor(root="coordinator", agent_models=MODELS, **kwargs) - - -def _delegating(call_id: str = "c1", brief: str = "Find X.\nThen report.") -> dict: - return _model_update(AIMessage("", tool_calls=[ - _call("task", {"description": brief, "subagent_type": "researcher"}, call_id), - ])) - - class TestEveryEventIsItsRuns: def test_the_roots_events_are_its_own(self): (event,) = _processor().process((), "updates", _model_update(AIMessage("Hello."))) assert event.run == root_run("coordinator") - def test_a_sub_agents_events_are_its_runs(self): - processor = _processor() - _delegated(processor, (), SUB, "researcher") - - (event,) = processor.process((SUB,), "updates", _model_update(AIMessage("It is 42."))) - - assert event.run == RESEARCHER - - def test_a_nested_run_is_its_parents_child(self): - processor = _processor() - _delegated(processor, (), SUB, "middle") - _delegated(processor, (SUB,), NESTED, "leaf") - - (event,) = processor.process((SUB, NESTED), "updates", _model_update(AIMessage("42."))) - - assert event.run == RunRef( - agent="leaf", instance="leaf-1", run="leaf-1#1", parent_run="middle-1#1", depth=2 - ) - - def test_the_tasks_stream_finds_the_run_the_call_started(self): - processor = _processor() - _, started = processor.process((), "updates", _delegating(call_id="c-" + SUB)) - _delegated(processor, (), SUB, "researcher") # announces the call "c-tools:4f2c" - - (event,) = processor.process((SUB,), "updates", _model_update(AIMessage("It is 42."))) - - assert event.run == started.run == RESEARCHER - - def test_a_failed_turns_error_is_the_managers(self): - assert _processor().turn_failed(RuntimeError("boom")).run is None - - -class TestDelegationRuns: - def test_a_task_call_starts_a_run_after_it(self): - events = _processor().process((), "updates", _delegating()) - - assert _types(events) == [EventType.TOOL_CALL, EventType.AGENT_RUN] - call, started = events - assert call.run == root_run("coordinator") - assert started.run == RESEARCHER - assert started.metadata == { - "status": RUN_STARTED, "agent": "researcher", "partial": False, - "call_id": "c1", "title": "Find X.", - } - - def test_its_result_ends_it(self): - runs = AgentRuns() - processor = _processor(runs=runs) - processor.process((), "updates", _delegating()) - - events = processor.process((), "updates", _tools_update( - ToolMessage("X is 42.", tool_call_id="c1", name="task") - )) - - assert _types(events) == [EventType.TOOL_RESULT, EventType.AGENT_RUN] - result, ended = events - assert result.run == root_run("coordinator") - assert ended.run == RESEARCHER - assert (ended.metadata["status"], ended.metadata["result"]) == (RUN_COMPLETED, "X is 42.") - (record,) = runs.records(None) - assert (record.status, record.title, record.result) == (RUN_COMPLETED, "Find X.", "X is 42.") - - def test_an_error_result_ends_it_failed(self): - processor = _processor() - processor.process((), "updates", _delegating()) - - _, ended = processor.process((), "updates", _tools_update(ToolMessage( - "Error running sub-agent: overloaded", tool_call_id="c1", name="task", status="error" - ))) - - assert ended.metadata["status"] == RUN_FAILED - assert (ended.metadata["error"], ended.metadata["result"]) == ("overloaded", "") - - def test_the_frameworks_error_result_ends_it_failed_with_its_error(self): - """The gate's or the error middleware's result: an error message - whose JSON holds the error.""" - processor = _processor() - processor.process((), "updates", _delegating()) - - _, ended = processor.process((), "updates", _tools_update(ToolMessage( - json.dumps({"success": False, "error": "researcher failed: boom"}), - tool_call_id="c1", name="task", status="error", - ))) - - assert ended.metadata["status"] == RUN_FAILED - assert (ended.metadata["error"], ended.metadata["result"]) == ( - "researcher failed: boom", "", - ) - - def test_an_answer_that_says_it_failed_completes_it(self): - """The sub-agent's answer is text, never read for success.""" - answer = json.dumps({"success": False, "error": "no X here"}) - processor = _processor() - processor.process((), "updates", _delegating()) - - result, ended = processor.process((), "updates", _tools_update(ToolMessage( - answer, tool_call_id="c1", name="task", - ))) - - assert (ended.metadata["status"], ended.metadata["result"]) == (RUN_COMPLETED, answer) - assert (result.metadata["result"], result.metadata["success"]) == (answer, True) - - def test_a_long_result_is_cut(self): - processor = _processor() - processor.process((), "updates", _delegating()) - - _, ended = processor.process((), "updates", _tools_update( - ToolMessage("z" * 500, tool_call_id="c1", name="task") + def test_a_sub_agent_runs_events_are_that_runs(self): + events = _run_processor().process((), "updates", _model_update( + AIMessage("Looking.", tool_calls=[_call("grep", {"pattern": "x"}, "r1")]) )) - assert ended.metadata["result"] == "z" * 200 - - def test_another_tool_starts_no_run(self): - events = _processor().process((), "updates", _model_update( - AIMessage("", tool_calls=[_call("grep", {"pattern": "x"}, "c1")]) - )) - - assert _types(events) == [EventType.TOOL_CALL] - - def test_a_sub_agents_call_with_its_parents_call_id_is_its_own(self): - """Call ids are only an agent's own: a provider that numbers them - (``call_0``, ...) gives a sub-agent's first call its parent's task - call's id. The sub-agent's result neither ends its own run nor lends - its name to its parent's result.""" - processor = _processor() - brief = {"description": "Find X.", "subagent_type": "researcher"} - processor.process((), "updates", _model_update( - AIMessage("", tool_calls=[_call("task", brief, "call_0")]) - )) - processor.process((), "tasks", _task_started("4f2c", _call("task", brief, "call_0"))) - processor.process((SUB,), "updates", _model_update( - AIMessage("", tool_calls=[_call("lookup", {"q": "X"}, "call_0")]) - )) - - inner = processor.process((SUB,), "updates", _tools_update( - ToolMessage('{"success": true, "value": 42}', tool_call_id="call_0") - )) - outer = processor.process((), "updates", _tools_update( - ToolMessage("X is 42.", tool_call_id="call_0") - )) - - assert [(e.type, e.metadata.get("tool_name"), e.run) for e in inner] == [ - (EventType.TOOL_RESULT, "lookup", RESEARCHER), + assert [(e.type.value, e.run) for e in events] == [ + ("text", RESEARCHER), ("tool_call", RESEARCHER), ] - assert [(e.type, e.metadata.get("tool_name")) for e in outer] == [ - (EventType.TOOL_RESULT, "task"), (EventType.AGENT_RUN, None), - ] - assert (outer[1].run, outer[1].metadata["result"]) == (RESEARCHER, "X is 42.") - - -class TestOnlyTheCallersOwnSubAgents: - """A run starts only for a ``task`` call to one of the calling agent's own - sub-agents (``sub_agents``); Deep Agents answers any other type that it - does not exist, and no sub-agent runs.""" - TREE = {"coordinator": ("middle",), "middle": ("leaf",)} - - def test_a_task_call_to_another_agents_sub_agent_is_a_tool_call(self): - runs = AgentRuns() - processor = _processor(runs=runs, sub_agents=self.TREE) - brief = {"description": "Look X up.", "subagent_type": "leaf"} - - called = processor.process((), "updates", _model_update( - AIMessage("", tool_calls=[_call("task", brief, "c1")]) - )) - processor.process((), "tasks", _task_started("4f2c", _call("task", brief, "c1"))) - answered = processor.process((), "updates", _tools_update(ToolMessage( - "We cannot invoke subagent leaf because it does not exist, the only allowed " - "types are `middle`", tool_call_id="c1", name="task", - ))) - - assert _types(called + answered) == [EventType.TOOL_CALL, EventType.TOOL_RESULT] - assert runs.records(None) == [] - assert runs.run_for(None, None, "c9", "leaf").run == "leaf-1#1" - - def test_a_sub_agent_delegates_to_its_own(self): - processor = _processor(sub_agents=self.TREE) - _delegated(processor, (), SUB, "middle") - - events = processor.process((SUB,), "updates", _model_update(AIMessage("", tool_calls=[ - _call("task", {"description": "Look X up.", "subagent_type": "leaf"}, "m1"), - ]))) - - assert _types(events) == [EventType.TOOL_CALL, EventType.AGENT_RUN] - assert events[1].run == RunRef( - agent="leaf", instance="leaf-1", run="leaf-1#1", parent_run="middle-1#1", depth=2 - ) + def test_a_failed_turns_error_is_the_managers(self): + assert _processor().turn_failed(RuntimeError("boom")).run is None def _request(name: str = "task", args: dict | None = None, call_id: str = "c1") -> ToolCallRequest: - if args is None: - args = {"description": "Find X.", "subagent_type": "researcher"} return ToolCallRequest( - tool_call={"name": name, "args": args, "id": call_id, "type": "tool_call"}, - tool=None, - state={}, - runtime=SimpleNamespace(tools=[]), + tool_call=_call(name, args or {"agent_type": "researcher"}, call_id), + tool=None, state={}, runtime=SimpleNamespace(tools=[]), ) -class TestTheActiveRun: - async def test_a_task_call_runs_as_its_sub_agents_run(self): +class TestTheActiveToolCall: + async def test_each_call_is_the_active_one_around_its_tool(self): seen = [] async def handler(request): - seen.append(get_active_run()) + seen.append((get_active_tool_call(), get_active_run())) return "done" - await ActiveToolCallMiddleware(AgentRuns()).awrap_tool_call(_request(), handler) - - assert seen == [RESEARCHER] - assert get_active_run() is None - - async def test_a_task_call_inside_a_run_starts_its_child(self): - runs = AgentRuns() - middle = runs.run_for(None, None, "c0", "middle") - seen = [] - - async def handler(request): - seen.append(get_active_run()) - return "done" - - token = set_active_run(middle) - try: - await ActiveToolCallMiddleware(runs).awrap_tool_call( - _request(args={"description": "d", "subagent_type": "leaf"}, call_id="m1"), handler - ) - after = get_active_run() - finally: - reset_active_run(token) + await ActiveToolCallMiddleware().awrap_tool_call(_request(), handler) - assert seen == [RunRef( - agent="leaf", instance="leaf-1", run="leaf-1#1", parent_run="middle-1#1", depth=2 - )] - assert after == middle + assert seen == [(ToolCallRef("c1", "task"), None)] + assert get_active_tool_call() is None - async def test_another_tools_call_keeps_the_run_it_is_in(self): + async def test_a_call_keeps_the_run_it_is_in(self): seen = [] async def handler(request): @@ -316,7 +87,7 @@ async def handler(request): token = set_active_run(RESEARCHER) try: - await ActiveToolCallMiddleware(AgentRuns()).awrap_tool_call( + await ActiveToolCallMiddleware().awrap_tool_call( _request(name="grep", args={"pattern": "x"}), handler ) finally: @@ -324,50 +95,11 @@ async def handler(request): assert seen == [RESEARCHER] - async def test_without_the_runs_no_run_is_set(self): - seen = [] - - async def handler(request): - seen.append(get_active_run()) - return "done" - - await ActiveToolCallMiddleware().awrap_tool_call(_request(), handler) - - assert seen == [None] - async def test_a_raising_call_resets_it_too(self): async def handler(request): raise asyncio.CancelledError with pytest.raises(asyncio.CancelledError): - await ActiveToolCallMiddleware(AgentRuns()).awrap_tool_call(_request(), handler) - - assert get_active_run() is None - - async def test_a_task_call_to_another_agents_sub_agent_runs_as_no_run(self): - runs = AgentRuns() - seen = [] - - async def handler(request): - seen.append(get_active_run()) - return "We cannot invoke subagent leaf because it does not exist" - - await ActiveToolCallMiddleware(runs, sub_agents=("middle",)).awrap_tool_call( - _request(args={"description": "d", "subagent_type": "leaf"}), handler - ) - - assert seen == [None] - assert runs.run_for(None, None, "c9", "leaf").run == "leaf-1#1" - - async def test_a_task_call_to_its_own_sub_agent_runs_as_its_run(self): - seen = [] + await ActiveToolCallMiddleware().awrap_tool_call(_request(), handler) - async def handler(request): - seen.append(get_active_run()) - return "done" - - await ActiveToolCallMiddleware(AgentRuns(), sub_agents=("researcher",)).awrap_tool_call( - _request(), handler - ) - - assert seen == [RESEARCHER] + assert get_active_tool_call() is None diff --git a/tests/workflow/deepagents/test_subagent_outcome_middleware.py b/tests/workflow/deepagents/test_subagent_outcome_middleware.py index caf9def9..d47d3990 100644 --- a/tests/workflow/deepagents/test_subagent_outcome_middleware.py +++ b/tests/workflow/deepagents/test_subagent_outcome_middleware.py @@ -296,4 +296,4 @@ async def test_the_log_has_the_answer_as_the_model_gave_it( assert logged.metadata["finish_reason"] == stop (result,) = [e for e in events if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "c1"] - assert result.metadata["result"] == read + assert result.metadata["result"]["result"] == read diff --git a/tests/workflow/deepagents/test_tool_result_cap.py b/tests/workflow/deepagents/test_tool_result_cap.py index 45f30cbd..f4df3c63 100644 --- a/tests/workflow/deepagents/test_tool_result_cap.py +++ b/tests/workflow/deepagents/test_tool_result_cap.py @@ -155,11 +155,12 @@ async def test_a_sub_agents_long_answer_is_cut(self, ctx, monkeypatch, cleanup): events = await turn(manager) message = models.chats["lead"].conversation(1)[-1] - body, _, note = message.content.rpartition("\n\n") - assert CUT.search(body) - assert SAVED_NOTE.match(note)["name"].startswith("task-") - # Deep Agents strips the sub-agent's answer. - assert saved_path(note).read_text() == REPORT.rstrip() + sent = json.loads(message.content) # the run's envelope, cut as a dict + assert (sent["status"], sent["agent"]) == ("completed", "helper-1") + assert CUT.search(sent["result"]) + assert SAVED_NOTE.match(sent["truncated"])["name"].startswith("task-") + # The run's last text, as Deep Agents' own task read it: stripped. + assert REPORT.rstrip() in saved_path(sent["truncated"]).read_text() assert texts(events)[-1] == "Done." async def test_an_error_result_passes(self, ctx, monkeypatch, cleanup): diff --git a/tests/workflow/deepagents/test_usage_recorded.py b/tests/workflow/deepagents/test_usage_recorded.py index 8fe78052..224fd87f 100644 --- a/tests/workflow/deepagents/test_usage_recorded.py +++ b/tests/workflow/deepagents/test_usage_recorded.py @@ -1,10 +1,11 @@ """Deep Agents records each call's usage in its conversation's ledger as it reports it. The event processor records an agent's step as it makes its ``LLM_USAGE``, -before ``on_event`` (an app's hook that drops events cannot drop a row), and -a sub-agent run's end carries what the run used, by model; the run callback -records a summary's. A processor driven outside a manager files under no -conversation (None), as ``AgentRuns`` does. +before ``on_event`` (an app's hook that drops events cannot drop a row), a +sub-agent run's processor records each of the run's calls under the run, +which the run's end then reads (``agents/delegate.py``), and the run +callback records a summary's. A processor driven outside a manager files +under no conversation (None), as ``AgentRuns`` does. """ from __future__ import annotations @@ -15,7 +16,7 @@ pytest.importorskip("deepagents") -from langchain_core.messages import AIMessage, HumanMessage, ToolMessage # noqa: E402 +from langchain_core.messages import AIMessage, HumanMessage # noqa: E402 from langchain_core.outputs import ChatGeneration, LLMResult # noqa: E402 from agentic_cli.workflow.deepagents.event_processor import RunCallback # noqa: E402 @@ -23,13 +24,10 @@ from agentic_cli.workflow.usage import UsageLedgers # noqa: E402 from tests.workflow.deepagents.test_event_processor import ( # noqa: E402 MODELS, - SUB, - _call, - _delegated, _model_update, _processor, _reported, - _tools_update, + _run_processor, ) @@ -53,20 +51,16 @@ def test_an_agents_step_is_recorded(self): "coordinator", None, None, 100, 10, 60 ) - def test_a_runs_end_carries_what_the_run_used(self): + def test_a_runs_calls_are_recorded_under_it(self): ledgers = UsageLedgers() - processor = _processor(ledgers=ledgers) - processor.process((), "updates", _model_update(AIMessage("", tool_calls=[ - _call("task", {"description": "Find X.", "subagent_type": "researcher"}, "c-" + SUB), - ]))) - _delegated(processor, (), SUB, "researcher") - processor.process((SUB,), "updates", _model_update(_answer("X is 42.", 50, 5))) - - _, ended = processor.process((), "updates", _tools_update( - ToolMessage("X is 42.", tool_call_id="c-" + SUB, name="task") - )) - assert ended.metadata["usage"] == {"google:gemini-2.5-flash": {"input": 50, "output": 5}} + _run_processor(ledgers=ledgers).process( + (), "updates", _model_update(_answer("X is 42.", 50, 5)) + ) + + assert ledgers.ledger(None).run_usage("researcher-1#1") == { + "google:gemini-2.5-flash": {"input": 50, "output": 5} + } assert ledgers.ledger(None).totals(run="researcher-1#1").calls == 1 diff --git a/tests/workflow/test_adk_agent_construction.py b/tests/workflow/test_adk_agent_construction.py index 8f815af9..f20ad0e2 100644 --- a/tests/workflow/test_adk_agent_construction.py +++ b/tests/workflow/test_adk_agent_construction.py @@ -48,14 +48,24 @@ async def test_explicit_description_is_preserved(): async def test_coordinator_with_sub_agents_builds(): - """A coordinator + leaf pair (README example) constructs end to end.""" - root = await _root_agent([ - AgentConfig(name="coordinator", prompt="Route.", sub_agents=["worker"]), - AgentConfig(name="worker", prompt="Work."), - ]) + """A coordinator + leaf pair (README example) constructs end to end: each + agent on its own, the coordinator delegating through ``task``.""" + from agentic_cli.workflow.adk.task_tool import TaskTool + + with MockContext(google_api_key="test-key", session_store="memory") as ctx: + mgr = GoogleADKWorkflowManager(agent_configs=[ + AgentConfig(name="coordinator", prompt="Route.", sub_agents=["worker"]), + AgentConfig(name="worker", prompt="Work."), + ], settings=ctx.settings) + await mgr.initialize_services() + try: + root, agents = mgr._root_agent, dict(mgr._agents) + finally: + await mgr.cleanup() assert root.name == "coordinator" - assert [a.name for a in root.sub_agents] == ["worker"] + assert sorted(agents) == ["coordinator", "worker"] + assert [type(t) for t in root.tools if isinstance(t, TaskTool)] == [TaskTool] assert root.description == "" diff --git a/tests/workflow/test_adk_compaction.py b/tests/workflow/test_adk_compaction.py index 4ad48bb4..a53a7041 100644 --- a/tests/workflow/test_adk_compaction.py +++ b/tests/workflow/test_adk_compaction.py @@ -51,6 +51,7 @@ running_agent, ) from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 +from agentic_cli.workflow.agents.brief import Brief, task_message # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 from agentic_cli.workflow.context import ( # noqa: E402 CompactResult, @@ -95,6 +96,17 @@ def calls(name: str, call_id: str, prompt_tokens: int = UNDER, **args) -> dict: return message +def delegate(prompt_tokens: int = UNDER) -> dict: + """The coordinator's ``task`` call ``toolu_c1``: the researcher is to find X.""" + return calls("task", "toolu_c1", prompt_tokens, agent_type="researcher", title="Find X", + objective="Find X.") + + +def task_of(inherit: bool = False) -> str: + """The researcher's task message for ``delegate()``'s call.""" + return task_message(Brief(title="Find X", objective="Find X."), inherit=inherit) + + def is_summary(body: dict) -> bool: first = body["messages"][0]["content"] text = first if isinstance(first, str) else first[0].get("text", "") @@ -558,8 +570,7 @@ async def spy(self, *, events): monkeypatch.setattr(AgentCliSummarizer, "maybe_summarize_events", spy) answers = serve(monkeypatch, Claude( - coordinator=[says("Noted."), says("Noted again."), - calls("researcher", "toolu_c1", request="Find X."), says("X is 42.")], + coordinator=[says("Noted."), says("Noted again."), delegate(), says("X is 42.")], # Both of the researcher's prompts pass its trigger. researcher=[calls("get_plan", "toolu_r1", OVER), says("X is 42.", OVER)], )) @@ -573,25 +584,26 @@ async def spy(self, *, events): finally: await manager.cleanup() - # ADK asked: for the researcher, whose last prompt passed the trigger. - assert "researcher" in consulted + # The researcher runs on its own runner, whose app summarizes + # nothing: ADK never asks for it, whose prompts passed its trigger. + assert "researcher" not in consulted assert "summary" not in answers.asked assert answers.asked == ["coordinator"] * 3 + ["researcher", "researcher", "coordinator"] # no loop assert summaries_in(session) == [] first, second = answers.bodies("researcher") - assert lines(first)[-1] == "user: Find X." # its brief + assert lines(first)[-1] == f"user: {task_of(inherit_context)}" # its task message assert lines(second) == [*lines(first), "assistant: called get_plan#toolu_r1", "user: result#toolu_r1"] assert texts(events)[-1] == "X is 42." @pytest.mark.parametrize("inherit_context", [False, True]) async def test_a_delegation_after_a_summary(self, project, monkeypatch, inherit_context): - """A fresh sub-agent is sent its brief alone; an inheriting one the - conversation as it now is, the summary first.""" + """A fresh sub-agent is sent its task message alone; an inheriting one + the conversation as it now is, the summary first.""" answers = serve(monkeypatch, Claude( - coordinator=[says("Noted."), says("Noted again.", OVER), - calls("researcher", "toolu_c1", request="Find X."), says("X is 42.")], + coordinator=[says("Noted."), says("Noted again.", OVER), delegate(), + says("X is 42.")], researcher=[says("X is 42.")], )) manager = GoogleADKWorkflowManager(agent_configs=team(inherit_context), settings=settings()) @@ -609,15 +621,16 @@ async def test_a_delegation_after_a_summary(self, project, monkeypatch, inherit_ (research,) = answers.bodies("researcher") sent = lines(research) if not inherit_context: - assert sent == ["user: Find X."] + assert sent == [f"user: {task_of()}"] else: assert sent[0] == f"user: {SUMMARY_PREFIX}\n\n{SUMMARY}" - assert sent[-1] == "user: Find X." + assert sent[-1] == f"user: {task_of(inherit=True)}" assert texts(events)[-1] == "X is 42." async def test_the_main_agent_still_summarizes_after_a_delegation(self, project, monkeypatch): - """A sub-agent runs in a task of its own: what it records as the running - agent never reaches its coordinator's next model call.""" + """A sub-agent runs in a task of its own, on a runner of its own: what + it records as the running agent never reaches its coordinator's next + model call.""" consulted: list[str | None] = [] real = AgentCliSummarizer.maybe_summarize_events @@ -628,8 +641,7 @@ async def spy(self, *, events): monkeypatch.setattr(AgentCliSummarizer, "maybe_summarize_events", spy) # The coordinator's delegating call passes its trigger. answers = serve(monkeypatch, Claude( - coordinator=[says("Noted."), says("Noted again."), - calls("researcher", "toolu_c1", OVER, request="Find X."), + coordinator=[says("Noted."), says("Noted again."), delegate(OVER), says("X is 42.")], researcher=[says("X is 42.")], )) @@ -647,7 +659,7 @@ async def spy(self, *, events): assert len(summaries_in(session)) == 1 final = lines(answers.bodies("coordinator")[-1]) assert final[0] == f"user: {SUMMARY_PREFIX}\n\n{SUMMARY}" - assert final[-2:] == ["assistant: called researcher#toolu_c1", "user: result#toolu_c1"] + assert final[-2:] == ["assistant: called task#toolu_c1", "user: result#toolu_c1"] class TestCancelledTurns: diff --git a/tests/workflow/test_adk_delegation.py b/tests/workflow/test_adk_delegation.py index 102ebd03..cba0e59f 100644 --- a/tests/workflow/test_adk_delegation.py +++ b/tests/workflow/test_adk_delegation.py @@ -1,46 +1,47 @@ -"""ADK delegates to a sub-agent and gets its answer back, in the same turn. - -An agent built from an ``AgentConfig`` that is not the root runs in ADK's -``single_turn`` mode, with transfers to its parent and peers off. Its parent -is offered it as a tool named after it (``<agent>(request=...)``, ADK's -private ``_SingleTurnAgentTool``), calls it, and reads its answer as the -tool's result, ``{"result": <its last text>}``; the root then answers the -user, and the next turn starts at the root again. No agent built from a -config is offered ``transfer_to_agent``. A sub-agent with ``inherit_context`` -False (the default) sees only the request; one with ``inherit_context=True`` -also sees its parent's conversation, which ADK gives a ``single_turn`` agent -only when ``include_contents`` is passed explicitly. - -ADK builds the delegation tool in the parent's constructor, and it calls no -``func`` the permission plugin could verify, so the manager binds each one to -the exempt delegation declaration (``tools/_core/delegation.py``) right after -the parent is built: only the exact ``_SingleTurnAgentTool`` ADK made for a -child the framework built. Anything else that looks like one is denied. The -sub-agent's own tool calls go through the same gate. - -A sub-agent's long-running tool is an ordinary call there: ADK pauses the -whole invocation on a pending long-running call, delegation included, so -only the root's are wrapped. A job a sub-agent started is told to the root -when it finishes, in the notice Deep Agents sends. A sub-agent without a -description is offered as "The <name> agent.", as on Deep Agents. +"""ADK delegates to a sub-agent and gets its result back, in the same turn. + +Every agent built from an ``AgentConfig`` is built on its own: no ADK +``sub_agents``, so none is offered ``transfer_to_agent``. A delegating agent +is offered one tool, the framework's ``task`` (``adk/task_tool.py``): its +call carries a brief (``agent_type``, ``title``, ``objective``, ...), the +sub-agent runs on a runner of its own, on a child session of the +conversation's (``<app>--agents``, ``<conversation>/<instance>``), its first +message the task message (``agents/brief.py::task_message``), and the call's +result is the run's envelope, as JSON text (``agents/envelope.py``). The root +then answers the user, and the next turn starts at the root again. A +sub-agent with ``inherit_context`` False (the default) sees only its task +message; one with ``inherit_context=True`` sees the conversation first, and +its task message ends with ``INHERITED_CONTEXT_NOTE``. + +The framework builds the ``task`` tool, so it binds it to the exempt +delegation declaration (``tools/_core/delegation.py``) as it is made: an +application's tool of that name, or a look-alike, is denied. A delegating +agent's own tool named ``task`` fails the build. The sub-agent's own tool +calls go through the same gate. + +A sub-agent's long-running tool is an ordinary call there: only the root's +are wrapped. A job a sub-agent started is told to the root when it +finishes, in the notice Deep Agents sends. A sub-agent without a description +is offered as "The <name> agent.", as on Deep Agents. A native ADK YAML app (``adk_config_path``) is built by ADK and keeps transferring (``tests/workflow/test_adk_transfer_tool.py``). -Turns run the real manager on ``FakeAPI`` (Claude); the private ADK pieces -this rests on have contract tests at the end. +Turns run the real manager on ``FakeAPI`` (Claude); what the ``task`` tool +relies on of ADK's ``BaseTool`` has contract tests at the end. """ from __future__ import annotations import dataclasses +import inspect import json +import logging import textwrap from pathlib import Path from types import SimpleNamespace import anthropic -import httpx import pytest pytest.importorskip("google.adk") @@ -53,7 +54,7 @@ from google.adk.models.anthropic_llm import AnthropicLlm # noqa: E402 from google.adk.sessions import InMemorySessionService # noqa: E402 from google.adk.tools import BaseTool, LongRunningFunctionTool # noqa: E402 -from google.adk.tools.agent_tool import AgentTool, _SingleTurnAgentTool # noqa: E402 +from google.adk.tools.agent_tool import AgentTool # noqa: E402 from google.adk.tools.skill_toolset import SkillToolset # noqa: E402 from google.genai import types # noqa: E402 @@ -73,9 +74,17 @@ register_tool, ) from agentic_cli.tools.skills import SkillStore # noqa: E402 -from agentic_cli.workflow.adk import delegation # noqa: E402 from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 from agentic_cli.workflow.adk.permission_plugin import _UNVERIFIED, PermissionPlugin # noqa: E402 +from agentic_cli.workflow.adk.sessions import child_app # noqa: E402 +from agentic_cli.workflow.adk.task_tool import TaskTool # noqa: E402 +from agentic_cli.workflow.agents import brief as brief_module # noqa: E402 +from agentic_cli.workflow.agents.brief import ( # noqa: E402 + INHERITED_CONTEXT_NOTE, + Brief, + task_message, +) +from agentic_cli.workflow.agents.envelope import read_envelope # noqa: E402 from agentic_cli.workflow.config import AgentConfig, AgentGraphError # noqa: E402 from agentic_cli.workflow.context import context_budget # noqa: E402 from agentic_cli.workflow.events import EventType # noqa: E402 @@ -100,6 +109,22 @@ def calls(name: str, call_id: str, **args) -> dict: return message +def delegation(call_id: str, objective: str = BRIEF, *, agent: str = "researcher", + title: str = "Find X", **fields) -> dict: + """A ``task`` call delegating ``objective`` to ``agent``.""" + return calls(TASK_TOOL, call_id, agent_type=agent, title=title, objective=objective, **fields) + + +def message_of(objective: str = BRIEF, *, title: str = "Find X", inherit: bool = False) -> str: + """The task message a delegation of ``objective`` starts its run with.""" + return task_message(Brief(title=title, objective=objective), inherit=inherit) + + +def result_of(line: str) -> dict: + """The envelope a ``lines`` result line holds: ``user: result "<JSON>"``.""" + return json.loads(json.loads(line.removeprefix("user: result "))) + + #: The call id each start of the probe job was given. STARTED: list[str] = [] @@ -229,7 +254,7 @@ def delegating() -> Team: return Team( coordinator=[ says("Noted, Ada."), - calls("researcher", "toolu_c1", request=BRIEF), + delegation("toolu_c1"), says("The researcher says X is 42."), says("The coordinator answers turn 3."), ], @@ -247,14 +272,16 @@ async def three_turns(monkeypatch, configs: list[AgentConfig], answers: Team) -> class TestDelegation: - async def test_the_root_is_offered_the_sub_agent_and_no_transfer(self, project, monkeypatch): + async def test_the_root_is_offered_task_and_no_transfer(self, project, monkeypatch): answers = delegating() await three_turns(monkeypatch, team(), answers) for body in answers.bodies("coordinator"): - assert tool_names(body) == ["researcher"] + assert tool_names(body) == [TASK_TOOL] (declaration,) = answers.bodies("coordinator")[0]["tools"] - assert declaration["input_schema"]["required"] == ["request"] + schema = declaration["input_schema"] + assert schema["required"] == ["agent_type", "title", "objective"] + assert schema["properties"]["agent_type"]["enum"] == ["researcher"] async def test_a_sub_agent_is_offered_no_transfer(self, project, monkeypatch): answers = delegating() @@ -279,17 +306,22 @@ async def test_the_sub_agent_answers_its_parent_in_the_same_turn(self, project, await manager.cleanup() assert answers.agents == ["coordinator", "coordinator", "researcher", "coordinator"] - assert lines(answers.bodies("coordinator")[2])[-2:] == [ - f"assistant: called researcher({json.dumps({'request': BRIEF})})", - 'user: result "X is 42."', - ] + called, result = lines(answers.bodies("coordinator")[2])[-2:] + assert called == "assistant: called task({})".format(json.dumps( + {"agent_type": "researcher", "title": "Find X", "objective": BRIEF} + )) + assert result_of(result) == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": "completed", "partial": False, "result": "X is 42.", "error": None, + } (response,) = [ part.function_response for event in session.events for part in (event.content.parts if event.content else []) if part.function_response ] - assert (response.name, response.response) == ("researcher", {"result": "X is 42."}) + assert response.name == TASK_TOOL + assert json.loads(response.response["result"])["result"] == "X is 42." assert texts(events)[-1] == "The researcher says X is 42." async def test_the_next_turn_starts_at_the_root(self, project, monkeypatch): @@ -300,19 +332,19 @@ async def test_the_next_turn_starts_at_the_root(self, project, monkeypatch): assert texts(events[2]) == ["The coordinator answers turn 3."] assert len(answers.bodies("researcher")) == 1 - async def test_a_fresh_sub_agent_sees_only_the_request(self, project, monkeypatch): + async def test_a_fresh_sub_agent_sees_only_its_task_message(self, project, monkeypatch): answers = delegating() await three_turns(monkeypatch, team(inherit_context=False), answers) (body,) = answers.bodies("researcher") - assert lines(body) == [f"user: {BRIEF}"] + assert lines(body) == [f"user: {message_of()}"] async def test_the_default_is_fresh(self, project, monkeypatch): answers = delegating() await three_turns(monkeypatch, team(), answers) (body,) = answers.bodies("researcher") - assert lines(body) == [f"user: {BRIEF}"] + assert lines(body) == [f"user: {message_of()}"] async def test_an_inheriting_sub_agent_sees_the_conversation(self, project, monkeypatch): answers = delegating() @@ -323,34 +355,54 @@ async def test_an_inheriting_sub_agent_sees_the_conversation(self, project, monk assert sent[0] == f"user: {TURNS[0]}" assert f"user: {TURNS[1]}" in sent assert any("Noted, Ada." in line for line in sent) # the coordinator's reply, quoted - assert sent[-1] == f"user: {BRIEF}" + assert sent[-1] == f"user: {message_of(inherit=True)}" assert "assistant" not in {line.partition(":")[0] for line in sent} - async def test_an_inheriting_sub_agent_is_told_whose_conversation_it_reads( + async def test_an_inheriting_sub_agents_task_message_says_whose_conversation_it_reads( self, project, monkeypatch ): # The user's turns reach it as plain user messages, so without the # note it may take them as its own instructions and answer as the - # coordinator. + # coordinator. The note ends the task message; the prompt is its own. answers = delegating() await three_turns(monkeypatch, team(inherit_context=True), answers) (body,) = answers.bodies("researcher") - assert system_text(body) == f"{PROMPTS['researcher']}\n\n{delegation.INHERITED_CONTEXT_NOTE}" + assert lines(body)[-1].endswith(INHERITED_CONTEXT_NOTE) + assert system_text(body).startswith(PROMPTS["researcher"]) + assert INHERITED_CONTEXT_NOTE not in system_text(body) for body in answers.bodies("coordinator"): - assert delegation.INHERITED_CONTEXT_NOTE not in system_text(body) + assert INHERITED_CONTEXT_NOTE not in system_text(body) + + async def test_adk_warns_of_the_inherited_events_authors_as_the_cli_filter_expects( + self, project, monkeypatch, caplog + ): + # The copied events' authors are not in the run's tree, so ADK warns + # of each as it picks the agent to run: the CLI logs those warnings + # at debug (adk/log_filters.py), by this logger and this text. + from agentic_cli.workflow.adk.log_filters import _ADK_UNKNOWN_AUTHOR + + logger_name, prefix = _ADK_UNKNOWN_AUTHOR + # ADK's own warning, as it comes: without the filter a test that ran + # the CLI (BaseCLIApp.run) may have left on that logger. + monkeypatch.setattr(logging.getLogger(logger_name), "filters", []) + with caplog.at_level(logging.WARNING, logger=logger_name): + await three_turns(monkeypatch, team(inherit_context=True), delegating()) + + warned = [r.getMessage() for r in caplog.records if r.name == logger_name] + assert warned and all(message.startswith(prefix) for message in warned) async def test_a_fresh_sub_agent_is_given_no_note(self, project, monkeypatch): answers = delegating() await three_turns(monkeypatch, team(inherit_context=False), answers) (body,) = answers.bodies("researcher") - assert system_text(body) == PROMPTS["researcher"] + assert system_text(body).startswith(PROMPTS["researcher"]) + assert INHERITED_CONTEXT_NOTE not in json.dumps(body) async def test_the_sub_agents_own_tool_calls_are_gated(self, project, monkeypatch): answers = Team( - coordinator=[calls("researcher", "toolu_c1", request="Write a note."), - says("It could not.")], + coordinator=[delegation("toolu_c1", "Write a note."), says("It could not.")], researcher=[calls("write_file", "toolu_r1", path="note.txt", content="hi"), says("Writing was denied.")], ) @@ -375,8 +427,9 @@ async def approver(request): async def test_a_middle_coordinator_delegates_in_turn(self, project, monkeypatch): answers = Team( - coordinator=[calls("middle", "toolu_c1", request="Plan X."), says("Planned: 42.")], - middle=[calls("leaf", "toolu_m1", request="Look X up."), says("X is 42, says the leaf.")], + coordinator=[delegation("toolu_c1", "Plan X.", agent="middle"), says("Planned: 42.")], + middle=[delegation("toolu_m1", "Look X up.", agent="leaf"), + says("X is 42, says the leaf.")], leaf=[says("42.")], ) route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) @@ -394,20 +447,22 @@ async def test_a_middle_coordinator_delegates_in_turn(self, project, monkeypatch await manager.cleanup() assert answers.agents == ["coordinator", "middle", "leaf", "middle", "coordinator"] - assert tool_names(answers.bodies("middle")[0]) == ["leaf"] - # Two levels down, each sub-agent is sent its own request alone. - assert lines(answers.bodies("middle")[0]) == ["user: Plan X."] - assert lines(answers.bodies("leaf")[0]) == ["user: Look X up."] - assert lines(answers.bodies("middle")[1])[-1] == 'user: result "42."' - assert lines(answers.bodies("coordinator")[1])[-1] == ( - 'user: result "X is 42, says the leaf."' + assert tool_names(answers.bodies("middle")[0]) == [TASK_TOOL] + # Two levels down, each sub-agent is sent its own task message alone. + assert lines(answers.bodies("middle")[0]) == [f"user: {message_of('Plan X.')}"] + assert lines(answers.bodies("leaf")[0]) == [f"user: {message_of('Look X up.')}"] + assert result_of(lines(answers.bodies("middle")[1])[-1])["result"] == "42." + assert result_of(lines(answers.bodies("coordinator")[1])[-1])["result"] == ( + "X is 42, says the leaf." ) assert texts(events)[-1] == "Planned: 42." async def test_two_delegations_in_one_response(self, project, monkeypatch): both = anthropic_message( - {"type": "tool_use", "id": "toolu_a", "name": "researcher", "input": {"request": "X?"}}, - {"type": "tool_use", "id": "toolu_b", "name": "researcher", "input": {"request": "Z?"}}, + {"type": "tool_use", "id": "toolu_a", "name": TASK_TOOL, + "input": {"agent_type": "researcher", "title": "X", "objective": "X?"}}, + {"type": "tool_use", "id": "toolu_b", "name": TASK_TOOL, + "input": {"agent_type": "researcher", "title": "Z", "objective": "Z?"}}, ) both["stop_reason"] = "tool_use" answers = Team(coordinator=[both, says("Both.")], @@ -419,16 +474,19 @@ async def test_two_delegations_in_one_response(self, project, monkeypatch): finally: await manager.cleanup() - # Each run sees only its own request; both results come back together. - assert sorted(lines(b)[-1] for b in answers.bodies("researcher")) == ["user: X?", "user: Z?"] - assert sorted(lines(answers.bodies("coordinator")[1])[-2:]) == [ - 'user: result "X is 42."', 'user: result "Z is 7."', + # Each run sees only its own task message; both results come back. + assert sorted(lines(b)[-1] for b in answers.bodies("researcher")) == [ + f"user: {message_of('X?', title='X')}", f"user: {message_of('Z?', title='Z')}", + ] + read = [result_of(line) for line in lines(answers.bodies("coordinator")[1])[-2:]] + assert sorted((r["agent"], r["result"]) for r in read) == [ + ("researcher-1", "X is 42."), ("researcher-2", "Z is 7."), ] assert texts(events)[-1] == "Both." async def test_a_sub_agents_long_answer_is_capped(self, project, monkeypatch): answers = Team( - coordinator=[calls("researcher", "toolu_c1", request=BRIEF), says("Done.")], + coordinator=[delegation("toolu_c1"), says("Done.")], researcher=[says("word " * 30_000)], ) route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) @@ -440,8 +498,20 @@ async def test_a_sub_agents_long_answer_is_capped(self, project, monkeypatch): result = lines(answers.bodies("coordinator")[1])[-1] assert len(result) < 60_000 - assert "Cut: " in result and "tool-output/researcher-" in result - (saved,) = (project / ".agentic_cli" / "tool-output").glob("researcher-*.txt") + # The envelope is cut as a dict: its JSON still reads, the note in it. + (held,) = [ + block["content"] + for message in answers.bodies("coordinator")[1]["messages"] + if isinstance(message["content"], list) + for block in message["content"] if block["type"] == "tool_result" + ] + if isinstance(held, list): + held = "".join(part.get("text", "") for part in held) + read = read_envelope(held) + assert read is not None, held[:300] + assert (read["status"], read["agent"], read["success"]) == ("completed", "researcher-1", True) + assert read["truncated"].startswith("Cut: ") and "tool-output/task-" in read["truncated"] + (saved,) = (project / ".agentic_cli" / "tool-output").glob("task-*.txt") assert saved.read_text().count("word") == 30_000 # all of it, in lines to page async def test_an_inheriting_sub_agent_is_sent_none_of_the_coordinators_thinking( @@ -454,7 +524,7 @@ async def test_an_inheriting_sub_agent_is_sent_none_of_the_coordinators_thinking {"type": "thinking", "thinking": thought, "signature": "sig-c1"}, {"type": "text", "text": "Noted, Ada."}, ), - calls("researcher", "toolu_c1", request=BRIEF), + delegation("toolu_c1"), says("The researcher says X is 42."), ], researcher=[says("X is 42.")], @@ -469,6 +539,26 @@ async def test_an_inheriting_sub_agent_is_sent_none_of_the_coordinators_thinking assert thought not in json.dumps(body) assert "sig-c1" not in json.dumps(body) + async def test_each_run_is_kept_in_a_child_session(self, project, monkeypatch): + """The run's transcript: its own app's session, under the conversation's id.""" + answers = delegating() + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) + manager = manager_for(team()) + try: + await turn(manager, TURNS[0]) + await turn(manager, TURNS[1]) + service = manager._session_service + child = await service.get_session( + app_name=child_app(manager.app_name), user_id="u", session_id="s/researcher-1" + ) + listed = await manager.list_sessions(user_id="u") + finally: + await manager.cleanup() + + assert [e.author for e in child.events] == ["user", "researcher"] + assert child.events[0].content.parts[0].text == message_of() + assert [row.session_id for row in listed] == ["s"] + async def test_a_native_adk_app_keeps_transferring(self, project, tmp_path): (tmp_path / "helper.yaml").write_text(textwrap.dedent(""" agent_class: LlmAgent @@ -493,7 +583,8 @@ async def test_a_native_adk_app_keeps_transferring(self, project, tmp_path): try: root = manager._root_agent assert root.sub_agents[0].mode == "chat" - assert not any(isinstance(tool, AgentTool) for tool in root.tools) + assert not any(isinstance(tool, (AgentTool, TaskTool)) for tool in root.tools) + assert manager._agent_runners == {} finally: await manager.cleanup() @@ -553,31 +644,6 @@ async def test_a_sub_agents_text_and_usage_are_marked(self, project, monkeypatch assert [e.metadata.get("purpose") for e in delegated if e.type is EventType.LLM_USAGE] == [None, "subagent", None] - async def test_a_sub_agents_failure_is_a_warning_and_the_turn_goes_on( - self, project, monkeypatch - ): - refused = httpx.Response(400, json={"type": "error", "error": { - "type": "invalid_request_error", "message": "max_tokens: 100000 > 64000"}}) - answers = Team( - coordinator=[calls("researcher", "toolu_c1", request=BRIEF), - says("The researcher could not do it.")], - researcher=[refused], - ) - route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) - manager = manager_for(team()) - try: - events = await turn(manager, "Find X.") - finally: - await manager.cleanup() - - (error,) = [e for e in events if e.type is EventType.ERROR] - assert error.content.startswith("researcher failed: ") - assert "max_tokens: 100000 > 64000" in error.content - assert (error.metadata["recoverable"], error.metadata["agent"]) == (True, "researcher") - # The coordinator is asked again, and answers the user. - assert answers.agents == ["coordinator", "researcher", "coordinator"] - assert texts(events)[-1] == "The researcher could not do it." - async def test_fact_extraction_reads_only_the_user_and_the_main_agent( self, project, monkeypatch ): @@ -698,7 +764,7 @@ async def test_the_status_bar_shows_only_the_main_agents_context( self, project, monkeypatch, inherit_context ): route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(Team( - coordinator=[sized(calls("researcher", "toolu_c1", request=BRIEF), 4_000), + coordinator=[sized(delegation("toolu_c1"), 4_000), sized(says("The researcher says X is 42."), 4_200)], # A prompt far larger than the coordinator's, as an inheriting # sub-agent's may be: it is still not the main agent's context. @@ -732,7 +798,7 @@ async def test_with_the_raw_llm_log_a_sub_agent_never_moves_ctx( A second, unattributed copy made a sub-agent's prompt the context and counted every call twice.""" route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(Team( - coordinator=[sized(calls("researcher", "toolu_c1", request=BRIEF), 4_000), + coordinator=[sized(delegation("toolu_c1"), 4_000), sized(says("The researcher says X is 42."), 4_200)], researcher=[sized(says("X is 42."), 150_000)], ))) @@ -768,7 +834,7 @@ async def test_with_the_raw_llm_log_a_sub_agent_never_moves_ctx( async def test_the_raw_log_names_each_calls_own_model(self, project, monkeypatch): coordinator, researcher = team() route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(Team( - coordinator=[calls("researcher", "toolu_c1", request=BRIEF), says("X is 42.")], + coordinator=[delegation("toolu_c1"), says("X is 42.")], researcher=[says("X is 42.")], ))) manager = GoogleADKWorkflowManager( @@ -832,32 +898,42 @@ def sized(message: dict, prompt_tokens: int) -> dict: async def built(configs: list[AgentConfig]) -> LlmAgent: """The root agent a manager over ``configs`` builds.""" + return (await built_all(configs))[0] + + +async def built_all(configs: list[AgentConfig]) -> tuple[LlmAgent, GoogleADKWorkflowManager]: + """The root agent a manager over ``configs`` builds, and the manager (cleaned up).""" manager = manager_for(configs) await manager.initialize_services() try: - return manager._root_agent + return manager._root_agent, manager finally: await manager.cleanup() class TestTheAgents: - async def test_a_sub_agent_is_a_single_turn_agent_that_cannot_transfer(self, project): - root = await built(team()) - (researcher,) = root.sub_agents - - assert root.mode in (None, "chat") - assert researcher.mode == "single_turn" - assert researcher.disallow_transfer_to_parent is True - assert researcher.disallow_transfer_to_peers is True - - async def test_a_fresh_one_leaves_include_contents_to_adk(self, project): - (researcher,) = (await built(team())).sub_agents - assert "include_contents" not in researcher.model_fields_set + async def test_every_agent_is_built_on_its_own(self, project): + manager = manager_for(team()) + await manager.initialize_services() + try: + root, agents = manager._root_agent, dict(manager._agents) + runners = dict(manager._agent_runners) + finally: + await manager.cleanup() - async def test_an_inheriting_one_passes_it_explicitly(self, project): - (researcher,) = (await built(team(inherit_context=True))).sub_agents - assert "include_contents" in researcher.model_fields_set - assert researcher.include_contents == "default" + researcher = agents["researcher"] + assert root is agents["coordinator"] + assert (root.sub_agents, researcher.sub_agents) == ([], []) + assert researcher.mode in (None, "chat") + (task,) = [tool for tool in root.tools if isinstance(tool, TaskTool)] + assert identify_tool(task) is get_registry().get(TASK_TOOL) + assert not any(isinstance(tool, TaskTool) for tool in researcher.tools) + # The sub-agent type's own runner: its own app, never summarized. + (runner,) = runners.values() + assert list(runners) == ["researcher"] + assert runner.app.name == child_app(manager.app_name) + assert runner.app.root_agent is researcher + assert runner.app.events_compaction_config is None async def test_a_middle_coordinator_delegates_too(self, project): configs = [ @@ -865,25 +941,34 @@ async def test_a_middle_coordinator_delegates_too(self, project): AgentConfig(name="middle", prompt="p", sub_agents=["leaf"], description="Mid."), AgentConfig(name="leaf", prompt="p", description="Leaf."), ] - root = await built(configs) - (middle,) = root.sub_agents - (leaf,) = middle.sub_agents + manager = manager_for(configs) + await manager.initialize_services() + try: + agents = dict(manager._agents) + runners = sorted(manager._agent_runners) + finally: + await manager.cleanup() - assert (middle.mode, leaf.mode) == ("single_turn", "single_turn") - for parent, child in ((root, middle), (middle, leaf)): - (tool,) = [t for t in parent.tools if isinstance(t, AgentTool)] - assert type(tool) is _SingleTurnAgentTool and tool.agent is child - assert identify_tool(tool) is get_registry().get(TASK_TOOL) + assert runners == ["leaf", "middle"] + for parent in ("coordinator", "middle"): + (task,) = [t for t in agents[parent].tools if isinstance(t, TaskTool)] + assert identify_tool(task) is get_registry().get(TASK_TOOL) + assert not any(isinstance(t, TaskTool) for t in agents["leaf"].tools) class TestWhatTheAgentsAreOffered: async def test_only_the_roots_long_running_tools_are_wrapped(self, project): - root = await built(team( + configs = team( researcher_tools=[delegation_probe_start_job], tools=[delegation_probe_start_job] - )) - (researcher,) = root.sub_agents + ) + manager = manager_for(configs) + await manager.initialize_services() + try: + root, researcher = manager._root_agent, manager._agents["researcher"] + finally: + await manager.cleanup() - assert [type(t) for t in root.tools if not isinstance(t, AgentTool)] == [ + assert [type(t) for t in root.tools if not isinstance(t, TaskTool)] == [ LongRunningFunctionTool ] assert researcher.tools == [delegation_probe_start_job] @@ -892,7 +977,7 @@ async def test_a_sub_agent_without_a_description_is_still_described( self, project, monkeypatch ): recorder = _Recorder() - monkeypatch.setattr(delegation, "logger", recorder) + monkeypatch.setattr(brief_module, "logger", recorder) answers = Team(coordinator=[says("ok")]) route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) configs = team() @@ -904,61 +989,43 @@ async def test_a_sub_agent_without_a_description_is_still_described( await manager.cleanup() (tool,) = answers.bodies("coordinator")[0]["tools"] - assert tool["description"] == "The researcher agent." # as on Deep Agents - assert ("warning", "adk_subagent_without_description", {"agent": "researcher"}) in ( + assert "- researcher: The researcher agent." in tool["description"] # as on Deep Agents + assert ("warning", "subagent_without_description", {"agent": "researcher"}) in ( recorder.calls ) async def test_a_described_one_keeps_its_description(self, project, monkeypatch): recorder = _Recorder() - monkeypatch.setattr(delegation, "logger", recorder) - (researcher,) = (await built(team())).sub_agents + monkeypatch.setattr(brief_module, "logger", recorder) + root = await built(team()) - assert researcher.description == "Finds facts." + (task,) = [tool for tool in root.tools if isinstance(tool, TaskTool)] + assert "- researcher: Finds facts." in task.description assert recorder.calls == [] +def task(objective: str) -> dict: + """An application's function named ``task``: not the framework's.""" + return {"success": True} + + class TestTheNameClash: - """ADK names the delegation tool after the sub-agent, and the tool appended - last takes the name: a parent's own tool of that name would be shadowed.""" + """A delegating agent is offered the framework's ``task``: a tool of its + own by that name would be offered beside it, under the same name.""" - async def test_a_sub_agent_named_like_its_parents_tool(self, project): - configs = team(tools=["read_file"]) - configs[1] = AgentConfig(name="read_file", prompt="p", description="Reads.") - configs[0].sub_agents = ["read_file"] + async def test_a_delegating_agents_own_task_tool_fails_the_build(self, project): + configs = team(tools=[task]) with pytest.raises(AgentGraphError) as exc: await built(configs) message = str(exc.value) - assert "'coordinator'" in message and "'read_file'" in message - - async def test_a_state_tool_counts(self, project): - configs = [ - AgentConfig(name="coordinator", prompt="p", sub_agents=["save_plan"]), - AgentConfig(name="save_plan", prompt="p", description="Plans."), - ] - with pytest.raises(AgentGraphError, match="'save_plan'"): - await built(configs) + assert "'coordinator'" in message and "'task'" in message - async def test_a_skill_tool_counts(self, project, tmp_path): - skill = _make_skill(tmp_path / "skills") - configs = [ - AgentConfig(name="coordinator", prompt="p", sub_agents=["load_skill"], - skills=[str(skill)]), - AgentConfig(name="load_skill", prompt="p", description="Loads."), - ] - with pytest.raises(AgentGraphError, match="'load_skill'"): - await built(configs) + async def test_an_agent_that_does_not_delegate_may_have_one(self, project): + configs = [AgentConfig(name="solo", prompt="p", tools=[task])] - async def test_another_agents_tool_does_not(self, project): - # Only the parent's own tools share its tool list with the delegation tool. - configs = [ - AgentConfig(name="coordinator", prompt="p", sub_agents=["read_file", "writer"]), - AgentConfig(name="read_file", prompt="p", description="Reads."), - AgentConfig(name="writer", prompt="p", description="Writes.", tools=["read_file"]), - ] root = await built(configs) - assert [t.name for t in root.tools if isinstance(t, AgentTool)] == ["read_file", "writer"] + assert not any(isinstance(tool, TaskTool) for tool in root.tools) # --- permission identity --------------------------------------------------------------- @@ -966,7 +1033,7 @@ async def test_another_agents_tool_does_not(self, project): async def _gate(tool) -> dict | None: return await PermissionPlugin().before_tool_callback( - tool=tool, tool_args={"request": "Do it."}, tool_context=None + tool=tool, tool_args={"agent_type": "researcher"}, tool_context=None ) @@ -975,66 +1042,42 @@ def _denied(result: dict | None) -> bool: class TestPermissionIdentity: - """Only the exact delegation tools ADK built for the framework's children pass.""" + """Only the ``task`` tool the framework built passes.""" - async def test_the_delegation_tool_the_framework_built_passes(self, project): + async def test_the_task_tool_the_framework_built_passes(self, project): root = await built(team()) - (tool,) = [t for t in root.tools if isinstance(t, AgentTool)] + (tool,) = [t for t in root.tools if isinstance(t, TaskTool)] assert identify_tool(tool) is get_registry().get(TASK_TOOL) assert await _gate(tool) is None - async def test_an_apps_agent_tool_is_denied(self, project): - (researcher,) = (await built(team())).sub_agents - tool = AgentTool(researcher) - - assert PermissionPlugin._resolve_definition(tool) is _UNVERIFIED - assert _denied(await _gate(tool)) - async def test_a_look_alike_with_the_same_name_is_denied(self, project): - class Researcher(BaseTool): + class Task(BaseTool): async def run_async(self, *, args, tool_context): # pragma: no cover return "anything" await built(team()) - assert _denied(await _gate(Researcher(name="researcher", description="Finds facts."))) - - async def test_a_subclass_around_the_frameworks_child_is_denied(self, project): - class Delegate(_SingleTurnAgentTool): - pass - - (researcher,) = (await built(team())).sub_agents - assert _denied(await _gate(Delegate(researcher))) - - async def test_another_one_around_the_frameworks_child_is_denied(self, project): - # The exact class and the framework's own child, but not the object - # ADK built in the parent's constructor: identity is the object's. - (researcher,) = (await built(team())).sub_agents - assert _denied(await _gate(_SingleTurnAgentTool(researcher))) - - async def test_one_around_an_agent_the_framework_did_not_build_is_denied(self): - stranger = LlmAgent(name="researcher", mode="single_turn", description="Finds facts.") - assert _denied(await _gate(_SingleTurnAgentTool(stranger))) - - def test_binding_takes_only_the_tools_adk_built_for_the_children(self): - from agentic_cli.workflow.adk.delegation import bind_delegation_tools - - child = LlmAgent(name="child", mode="single_turn", description="Child.") - stranger = LlmAgent(name="stranger", mode="single_turn", description="Not ours.") + tool = Task(name=TASK_TOOL, description="Delegates.") + assert PermissionPlugin._resolve_definition(tool) is _UNVERIFIED + assert _denied(await _gate(tool)) - class Delegate(_SingleTurnAgentTool): + async def test_a_subclass_is_denied(self, project): + class Delegate(TaskTool): pass - supplied = [_SingleTurnAgentTool(stranger), AgentTool(child), Delegate(child)] - parent = LlmAgent(name="parent", tools=list(supplied), sub_agents=[child]) - - bind_delegation_tools(parent, [child]) + manager = manager_for(team()) + await manager.initialize_services() + try: + tool = Delegate("coordinator", {"researcher": team()[1]}, lambda: manager._delegations) + finally: + await manager.cleanup() + # A subclass may run anything: only an exact TaskTool is bound. + assert identify_tool(tool) is None + assert _denied(await _gate(tool)) - task = get_registry().get(TASK_TOOL) - (made,) = [t for t in parent.tools if not any(t is s for s in supplied)] - assert type(made) is _SingleTurnAgentTool and made.agent is child - assert identify_tool(made) is task - assert [identify_tool(t) for t in supplied] == [None, None, None] + async def test_an_apps_agent_tool_is_denied(self, project): + stranger = LlmAgent(name="researcher", description="Finds facts.") + assert _denied(await _gate(AgentTool(stranger))) # --- jobs ----------------------------------------------------------------------------- @@ -1062,7 +1105,7 @@ class TestJobs: @staticmethod def _sub_agents_job() -> Team: return Team( - coordinator=[calls("researcher", "toolu_c1", request="Start the build."), + coordinator=[delegation("toolu_c1", "Start the build."), says("The researcher started job j1."), says("The build finished: built ok.")], researcher=[calls("delegation_probe_start_job", "toolu_r1", command="make"), @@ -1083,7 +1126,9 @@ async def test_a_sub_agents_job_starter_returns_in_the_turn(self, project, monke # The sub-agent's starter returned at once, with the job's id. started = lines(answers.bodies("researcher")[1])[-1].removeprefix("user: result ") assert json.loads(json.loads(started))["job_id"] == "j1" - assert lines(answers.bodies("coordinator")[1])[-1] == 'user: result "Started job j1."' + assert result_of(lines(answers.bodies("coordinator")[1])[-1])["result"] == ( + "Started job j1." + ) assert texts(events)[-1] == "The researcher started job j1." async def test_its_finished_job_is_told_to_the_main_agent(self, project, monkeypatch): @@ -1192,17 +1237,30 @@ async def _run(root: LlmAgent, texts_in: list[str]) -> None: pass -class TestTheADKItRestsOn: - def test_a_pending_long_running_call_escapes_the_delegation_tool(self): - # ADK pauses a delegation on a pending long-running call by raising - # NodeInterruptedError out of run_node; _SingleTurnAgentTool catches - # Exception only, so the pause takes the whole invocation with it. - # Hence a sub-agent's long-running tools are not wrapped. - from google.adk.workflow._errors import NodeInterruptedError +class _Probe(BaseTool): + """A ``BaseTool`` as ``TaskTool`` is one: its declaration from a JSON schema, + its run from ``run_async(args=, tool_context=)``.""" + + def __init__(self) -> None: + super().__init__(name="probe", description="Probe a thing.") + self.ran: list[tuple[dict, str | None, dict]] = [] + + def _get_declaration(self) -> types.FunctionDeclaration: + return types.FunctionDeclaration( + name=self.name, description=self.description, + parameters_json_schema={ + "type": "object", "properties": {"q": {"type": "string"}}, "required": ["q"], + }, + ) - assert issubclass(NodeInterruptedError, BaseException) - assert not issubclass(NodeInterruptedError, Exception) + async def run_async(self, *, args, tool_context): + tool_context.state["plan"] = "probed" + self.ran.append((dict(args), tool_context.function_call_id, + {"events": len(tool_context.session.events)})) + return json.dumps({"success": True}) + +class TestTheADKItRestsOn: async def test_a_skill_toolsets_tools_are_its_static_list(self, tmp_path): # The name-clash check reads SkillToolset._tools: it is what ADK offers. skills = SkillStore().resolve([str(_make_skill(tmp_path))]) @@ -1216,58 +1274,40 @@ async def test_a_skill_toolsets_tools_are_its_static_list(self, tmp_path): t.name for t in toolset._tools } - def test_the_delegation_tool_class(self): - child = LlmAgent(name="researcher", mode="single_turn", description="Finds facts.") - tool = _SingleTurnAgentTool(child) - - assert issubclass(_SingleTurnAgentTool, AgentTool) - assert tool.agent is child - assert tool.name == "researcher" - - def test_a_parent_gets_one_tool_for_a_single_turn_child(self): - child = LlmAgent( - name="researcher", mode="single_turn", description="Finds facts.", - disallow_transfer_to_parent=True, disallow_transfer_to_peers=True, - ) - parent = LlmAgent(name="coordinator", sub_agents=[child]) - - (tool,) = parent.tools - assert type(tool) is _SingleTurnAgentTool - assert tool.agent is child and tool.name == "researcher" - - @pytest.mark.parametrize( - "include, sees_the_conversation", - [ - pytest.param(None, False, id="left-unset"), - pytest.param("default", True, id="default-passed"), - ], - ) - async def test_a_single_turn_child_sees_the_conversation_only_when_asked_explicitly( - self, include, sees_the_conversation - ): - answers = Team( - coordinator=[says("Noted, Ada."), calls("researcher", "toolu_c1", request=BRIEF), - says("Done.")], - researcher=[says("X is 42.")], - ) - api = FakeAPI(answers) - extra = {} if include is None else {"include_contents": include} - child = LlmAgent( - name="researcher", model=claude(api), instruction=PROMPTS["researcher"], - description="Finds facts.", mode="single_turn", - disallow_transfer_to_parent=True, disallow_transfer_to_peers=True, **extra, - ) - parent = LlmAgent( - name="coordinator", model=claude(api), instruction=PROMPTS["coordinator"], - sub_agents=[child], - ) + def test_a_base_tool_is_made_from_its_name_and_description(self): + parameters = inspect.signature(BaseTool.__init__).parameters + assert {"name", "description"} <= set(parameters) + assert set(inspect.signature(BaseTool.run_async).parameters) == { + "self", "args", "tool_context", + } - await _run(parent, TURNS[:2]) + async def test_a_tool_is_declared_and_run_as_task_is(self): + """ADK offers a tool by its ``_get_declaration`` (a JSON schema, sent + as given), calls ``run_async`` with the model's arguments and a tool + context (its call id, its state, its session), stores a text result + as ``{"result": <text>}``, and writes its state changes with the + result.""" + api = FakeAPI(Team( + coordinator=[calls("probe", "toolu_p1", q="X"), says("Done.")], + )) + probe = _Probe() + root = LlmAgent(name="coordinator", model=claude(api), + instruction=PROMPTS["coordinator"], tools=[probe]) + service = InMemorySessionService() + runner = Runner(app=App(name="contract", root_agent=root), session_service=service) + session = await service.create_session(app_name="contract", user_id="u") + async for _ in runner.run_async( + user_id="u", session_id=session.id, new_message=_user("Probe X.") + ): + pass + stored = await service.get_session(app_name="contract", user_id="u", session_id=session.id) - assert answers.agents == ["coordinator", "coordinator", "researcher", "coordinator"] - assert tool_names(answers.bodies("coordinator")[1]) == ["researcher"] - (body,) = answers.bodies("researcher") - assert tool_names(body) == [] - sent = lines(body) - assert sent[-1] == f"user: {BRIEF}" - assert (f"user: {TURNS[0]}" in sent) is sees_the_conversation + (declared,) = api.bodies[0]["tools"] + assert (declared["name"], declared["input_schema"]["required"]) == ("probe", ["q"]) + assert probe.ran == [({"q": "X"}, "toolu_p1", {"events": 2})] + (response,) = [ + part.function_response for event in stored.events + for part in (event.content.parts if event.content else []) if part.function_response + ] + assert response.response == {"result": json.dumps({"success": True})} + assert stored.state["plan"] == "probed" diff --git a/tests/workflow/test_adk_fit_guard.py b/tests/workflow/test_adk_fit_guard.py index 821a0e43..3efe0f01 100644 --- a/tests/workflow/test_adk_fit_guard.py +++ b/tests/workflow/test_adk_fit_guard.py @@ -190,8 +190,9 @@ def says(text: str, prompt_tokens: int = 100) -> dict: return message delegate = says("") - delegate["content"] = [{"type": "tool_use", "id": "toolu_c1", "name": "researcher", - "input": {"request": "Find X."}}] + delegate["content"] = [{"type": "tool_use", "id": "toolu_c1", "name": "task", + "input": {"agent_type": "researcher", "title": "Find X.", + "objective": "Find X."}}] delegate["stop_reason"] = "tool_use" coordinator = [says("Noted."), says("Noted again."), delegate, says("X is 42.")] claude = FakeAPI(lambda request: coordinator.pop(0)) @@ -225,7 +226,7 @@ def says(text: str, prompt_tokens: int = 100) -> dict: assert sent[0].startswith(FIT_NOTE) assert not any(text.startswith("One:") for text in sent) assert any("Two:" in text for text in sent) - assert sent[-1].startswith("Find X.") + assert sent[-1].startswith("# Task: Find X.") (trimmed,) = trims(events) assert trimmed.metadata["agent"] == "researcher" # The coordinator's own requests went whole, and nothing was summarized. diff --git a/tests/workflow/test_adk_overflow.py b/tests/workflow/test_adk_overflow.py index 5177d0fa..d63ee04c 100644 --- a/tests/workflow/test_adk_overflow.py +++ b/tests/workflow/test_adk_overflow.py @@ -32,7 +32,6 @@ pytest.importorskip("google.adk") from google.adk import Runner # noqa: E402 -from google.adk import __version__ as _adk_version # noqa: E402 from google.adk.agents import LlmAgent # noqa: E402 from google.adk.apps import App # noqa: E402 from google.adk.models.base_llm import BaseLlm # noqa: E402 @@ -51,6 +50,7 @@ OVERFLOW_ERROR_CODE, SUMMARY_FAILED, overflow_message, + subagent_overflow_message, ) from agentic_cli.workflow.events import EventType # noqa: E402 from agentic_cli.workflow.summary_prompt import SUMMARY_PREFIX # noqa: E402 @@ -639,10 +639,15 @@ def team(inherit_context: bool) -> list[AgentConfig]: ] +def task_call(call_id: str, objective: str) -> dict: + """A ``task`` call's block, delegating ``objective`` to the researcher.""" + return {"type": "tool_use", "id": call_id, "name": "task", + "input": {"agent_type": "researcher", "title": objective, "objective": objective}} + + def delegate() -> dict: message = claude_says("") - message["content"] = [{"type": "tool_use", "id": "toolu_c1", "name": "researcher", - "input": {"request": "Find X."}}] + message["content"] = [task_call("toolu_c1", "Find X.")] message["stop_reason"] = "tool_use" return message @@ -666,7 +671,7 @@ class TestAnAgentThatReplies: """An agent the root transfers to (a native ADK YAML app's chat-mode agent) holds the conversation and answers the user: a conversation it no longer fits ends the turn with the clear error, as the main agent's does, never - with a sub-agent's "I could not do this task" as its reply.""" + with a sub-agent's warning, which ends only that sub-agent's run.""" @staticmethod def plugin() -> "OverflowPlugin": @@ -703,14 +708,14 @@ async def test_its_overflow_is_the_turns_clear_error(self): assert helper.error_code == OVERFLOW_ERROR_CODE assert helper.error_message == overflow_message("anthropic:claude-sonnet-4-6") - assert worker.error_code is None - assert worker.content.parts[0].text.startswith("I could not do this task") + assert worker.error_code == OVERFLOW_ERROR_CODE + assert worker.error_message == subagent_overflow_message( + "worker", "anthropic:claude-sonnet-4-6" + ) class TestASubAgentsOverflow: - async def test_it_answers_that_it_could_not_and_the_user_is_warned_once( - self, project, monkeypatch - ): + async def test_its_run_fails_and_the_user_is_warned_once(self, project, monkeypatch): _, status, body = SHAPES["claude-400"] monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key") api = Team(coordinator=[delegate(), claude_says("The researcher could not.")], @@ -727,15 +732,16 @@ async def test_it_answers_that_it_could_not_and_the_user_is_warned_once( await manager.cleanup() model = "anthropic:claude-sonnet-4-6" - # Its brief alone is the request: nothing to leave out, no retry. + warned = f"researcher: the request no longer fits {model}'s context window." + # Its task message alone is the request: nothing to leave out, no retry. assert api.asked == ["You coordinate.", "You research.", "You coordinate."] (error,) = errors(events) - assert error.content == f"researcher: the request no longer fits {model}'s context window." + assert error.content == warned assert error.metadata == {"recoverable": True, "error_code": OVERFLOW_ERROR_CODE, "agent": "researcher"} result = json.loads(api.requests[2].content)["messages"][-1]["content"][0] - assert f"I could not do this task: the request no longer fits {model}'s context window." \ - in json.dumps(result) + read = json.loads(result["content"]) + assert (read["status"], read["error"], read["success"]) == ("failed", warned, False) assert texts(events)[-1] == "The researcher could not." async def test_an_inheriting_one_is_retried_without_the_oldest_turns( @@ -1014,18 +1020,14 @@ async def test_a_parallel_delegations_retry_carries_its_own_task(project, monkey _, status, refusal = SHAPES["claude-400"] monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key") coordinator = [claude_says("Noted."), claude_says(""), claude_says("Both done.")] - coordinator[1]["content"] = [ - {"type": "tool_use", "id": "toolu_c1", "name": "researcher", - "input": {"request": "Task A."}}, - {"type": "tool_use", "id": "toolu_c2", "name": "researcher", - "input": {"request": "Task B."}}, - ] + coordinator[1]["content"] = [task_call("toolu_c1", "Task A."), task_call("toolu_c2", "Task B.")] coordinator[1]["stop_reason"] = "tool_use" b_started, retried = asyncio.Event(), asyncio.Event() retries: list[str] = [] async def researcher(body: dict): - task = _last_text(body) + # Its task message: "# Task: Task A." ... and the note. + task = _last_text(body).removeprefix("# Task: ").partition("\n")[0] if FIT_NOTE in json.dumps(body["messages"]): # a retry retries.append(task) retried.set() @@ -1056,7 +1058,7 @@ def claude(request): finally: await manager.cleanup() - # Both requests quote both calls; a call's own task is its brief, last. + # Both requests quote both calls; a call's own task is its task message, last. assert retries == ["Task A."] final = json.loads(api.requests[-1].content)["messages"][-1]["content"] results = {block["tool_use_id"]: json.dumps(block["content"]) for block in final @@ -1066,9 +1068,6 @@ def claude(request): assert texts(events)[-1] == "Both done." -_ADK_VERSION = tuple(int(part) for part in _adk_version.split(".")[:2]) - - async def test_a_cancelled_call_leaves_no_copy_past_the_next_turn(project, monkeypatch): from agentic_cli.workflow.adk.fit_guard_plugin import FitGuardPlugin @@ -1097,7 +1096,7 @@ async def held(reply): assert texts(events) == ["Again."] # From google-adk 2.14 a cancelled model call runs on_model_error_callback - # with the CancelledError, which releases the copy at once; before it, the - # copy stays until the next turn starts. - assert left_by_the_cancel == (0 if _ADK_VERSION >= (2, 14) else 1) + # with the CancelledError, which releases the copy at once; before it, + # the stopped run's end does (after_run_callback, as its abort closes it). + assert left_by_the_cancel == 0 assert after_the_next_turn == 0 diff --git a/tests/workflow/test_adk_session_rows.py b/tests/workflow/test_adk_session_rows.py index d8fa6a9a..e5f58d55 100644 --- a/tests/workflow/test_adk_session_rows.py +++ b/tests/workflow/test_adk_session_rows.py @@ -8,6 +8,11 @@ nothing is written back: its place in the list stays. A job's resume adds no turn, nor does a delegated request or a summary: nobody typed them. +A sub-agent instance's transcript is a child session of the conversation's +own store, under an app of its own (``child_app``), so it never lists as a +conversation: its id is the conversation's and the instance's +(``child_session_id``), at most the 128 characters ADK stores. + The other hooks a resume reads: ``recent_messages`` is the user's and the main agent's text, without its thinking, and deleting a conversation that is not stored says so (False). @@ -33,8 +38,12 @@ from agentic_cli.tools.jobs.resume import JOB_NOTICE_HEADER # noqa: E402 from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 from agentic_cli.workflow.adk.sessions import ( # noqa: E402 + CHILD_APP_SUFFIX, + MAX_KEY, TITLE_KEY, TURNS_KEY, + child_app, + child_session_id, typed_prompts, ) from agentic_cli.workflow.sessions import SessionInfo # noqa: E402 @@ -353,3 +362,20 @@ async def test_deleting_a_conversation_that_is_not_stored_says_so(self, project, await manager.cleanup() assert (missing, deleted, listed) == (False, True, []) + + +class TestChildSessions: + def test_a_child_session_is_under_the_apps_own_child_app(self): + assert (CHILD_APP_SUFFIX, child_app("research_demo")) == ( + "--agents", "research_demo--agents" + ) + + def test_its_id_names_the_conversation_and_the_instance(self): + assert child_session_id("s1", "researcher-2") == "s1/researcher-2" + + def test_an_id_past_what_adk_stores_is_refused(self): + conversation = "c" * (MAX_KEY - len("/researcher-1")) + assert len(child_session_id(conversation, "researcher-1")) == MAX_KEY + + with pytest.raises(ValueError, match="ADK stores at most 128"): + child_session_id(conversation + "c", "researcher-1") diff --git a/tests/workflow/test_agent_brief.py b/tests/workflow/test_agent_brief.py index 66ea90fd..0dae82e8 100644 --- a/tests/workflow/test_agent_brief.py +++ b/tests/workflow/test_agent_brief.py @@ -118,12 +118,6 @@ def test_a_fresh_types_message_has_no_note(self): 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 " diff --git a/tests/workflow/test_agent_delegate.py b/tests/workflow/test_agent_delegate.py new file mode 100644 index 00000000..01334987 --- /dev/null +++ b/tests/workflow/test_agent_delegate.py @@ -0,0 +1,447 @@ +"""``Delegations``: the one place a sub-agent run starts, ends and is decided. + +Driven with a fake hook and no backend: the brief is read against the +caller's own sub-agents, the run is named and its ``AGENT_RUN`` events are +recorded and reported to the turn's live events, the hook runs in a task of +its own (the run active there, no tool call), and the run ends as the hook's +answer says, with its envelope. +""" + +from __future__ import annotations + +import asyncio +from collections.abc import Awaitable, Callable +from typing import Any + +import pytest + +from agentic_cli.workflow import live_events +from agentic_cli.workflow.agents import ( + RUN_COMPLETED, + RUN_FAILED, + RUN_INTERRUPTED, + RUN_REFUSED, + RUN_STARTED, + AgentRuns, + SubAgentPolicy, +) +from agentic_cli.workflow.agents.brief import INHERITED_CONTEXT_NOTE, Brief, task_message +from agentic_cli.workflow.agents.delegate import ( + AgentRun, + DelegationRequest, + Delegations, + RunAnswer, + RunFailed, + started_by, +) +from agentic_cli.workflow.agents.envelope import INTERRUPTED_ERROR +from agentic_cli.workflow.agents.outcome import CUT, REFUSAL_ERROR, REFUSED +from agentic_cli.workflow.config import AgentConfig +from agentic_cli.workflow.events import EventType, WorkflowEvent +from agentic_cli.workflow.live_events import LiveEvents, merged +from agentic_cli.workflow.sessions import ( + RunRef, + SessionRef, + ToolCallRef, + get_active_run, + get_active_tool_call, + reset_active_tool_call, + reset_active_turn, + set_active_tool_call, + set_active_turn, +) +from agentic_cli.workflow.usage import UsageLedgers, UsageTotals, llm_usage_event +from tests.loop_guard import no_blocking_calls + +CONVERSATION = SessionRef("app", "u", "s") +RESEARCHER = RunRef( + agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1 +) +TYPES = { + "coordinator": AgentConfig(name="coordinator", prompt="p", sub_agents=["researcher", "middle", + "reader"]), + "researcher": AgentConfig(name="researcher", prompt="p", description="Finds."), + "middle": AgentConfig(name="middle", prompt="p", description="Plans.", sub_agents=["leaf"]), + "leaf": AgentConfig(name="leaf", prompt="p", description="Looks up."), + "reader": AgentConfig(name="reader", prompt="p", description="Reads.", inherit_context=True), +} +BRIEF = {"agent_type": "researcher", "title": "Find X", "objective": "Find X."} + +Hook = Callable[[AgentRun], Awaitable[RunAnswer]] + + +def answering(text: str = "X is 42.", **fields: Any) -> tuple[Hook, list[AgentRun]]: + """A hook that answers ``text``; the runs it was asked to run.""" + asked: list[AgentRun] = [] + + async def hook(run: AgentRun) -> RunAnswer: + asked.append(run) + return RunAnswer(text=text, **fields) + + return hook, asked + + +def delegations(hook: Hook, **options: Any) -> Delegations: + return Delegations( + runs=options.pop("runs", AgentRuns()), policy=SubAgentPolicy(), types=TYPES, hook=hook, + **options, + ) + + +def request(arguments: dict | None = None, **fields: Any) -> DelegationRequest: + return DelegationRequest( + caller=fields.pop("caller", None), caller_agent=fields.pop("caller_agent", "coordinator"), + call_id=fields.pop("call_id", "c1"), arguments=BRIEF if arguments is None else arguments, + **fields, + ) + + +async def delegated(made: Delegations, asked: DelegationRequest) -> tuple[Any, list[WorkflowEvent]]: + """``made.delegate(asked)`` in a turn of ``CONVERSATION``: its result, and what it reported.""" + live = LiveEvents() + out: dict[str, Any] = {} + + async def source(): + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(live): + out["result"] = await made.delegate(asked) + finally: + reset_active_turn(token) + if False: # pragma: no cover - a source that yields nothing itself + yield + + events = [item async for item in merged(source(), live)] + return out["result"], events + + +def statuses(events: list[WorkflowEvent]) -> list[tuple[str, str]]: + return [ + (e.type.value, e.metadata.get("status") or e.content) for e in events + ] + + +class TestABriefThatCannotStartARun: + async def test_is_the_error_result_and_nothing_else(self): + hook, asked = answering() + runs = AgentRuns() + + result, events = await delegated( + delegations(hook, runs=runs), request({"agent_type": "researcher", "title": "Find X"}) + ) + + assert result.result == { + "success": False, "error": "The brief for 'researcher' is missing: objective.", + } + assert (result.state, result.run, events, asked) == ({}, None, [], []) + assert runs.records(CONVERSATION) == [] + # No instance was numbered: the next run is researcher-1. + assert runs.run_for(CONVERSATION, None, "c9", "researcher").instance == "researcher-1" + + async def test_a_type_that_is_not_the_callers_own_is_unknown(self): + hook, asked = answering() + + result, _ = await delegated(delegations(hook), request( + {"agent_type": "leaf", "title": "Look", "objective": "Look X up."} + )) + + assert result.result["error"] == ( + "Unknown agent_type 'leaf': the agents you can delegate to are " + "researcher, middle, reader." + ) + assert asked == [] + + +class TestACompletedRun: + async def test_starts_runs_and_ends_with_its_envelope(self): + hook, asked = answering(state={"tasks": [{"description": "find X"}]}) + runs = AgentRuns() + + result, events = await delegated(delegations(hook, runs=runs), request( + state={"plan": "- [ ] find X"}, + )) + + assert result.result == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": False, "result": "X is 42.", "error": None, + } + assert (result.run, result.state) == (RESEARCHER, {"tasks": [{"description": "find X"}]}) + (run,) = asked + assert (run.ref, run.config.name, run.conversation) == ( + RESEARCHER, "researcher", CONVERSATION + ) + assert run.message == task_message(Brief(title="Find X", objective="Find X.")) + assert (run.state, run.history) == ({"plan": "- [ ] find X"}, None) + started, ended = events + assert started.metadata == { + "status": RUN_STARTED, "agent": "researcher", "partial": False, "call_id": "c1", + "title": "Find X", "brief": {"title": "Find X", "objective": "Find X."}, + "started_by": "agent:root", "mode": "blocking", + } + assert (ended.metadata["status"], ended.metadata["result"], ended.run) == ( + RUN_COMPLETED, "X is 42.", RESEARCHER + ) + (record,) = runs.records(CONVERSATION) + assert (record.status, record.title, record.brief, record.started_by, record.mode) == ( + RUN_COMPLETED, "Find X", {"title": "Find X", "objective": "Find X."}, + "agent:root", "blocking", + ) + + async def test_an_empty_answer_completes_with_an_empty_result(self): + hook, _ = answering("") + + result, events = await delegated(delegations(hook), request()) + + assert (result.result["status"], result.result["result"]) == (RUN_COMPLETED, "") + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_COMPLETED)] + + async def test_a_cut_answer_completes_partial_and_is_warned_of_once_after_its_end(self): + hook, _ = answering("X is\n\n[cut off at the output limit]", outcome=CUT) + + result, events = await delegated(delegations(hook), request()) + + assert (result.result["status"], result.result["partial"], result.result["success"]) == ( + RUN_COMPLETED, True, True + ) + started, ended, warning = events + assert ended.metadata["partial"] is True + assert (warning.type, warning.content, warning.run) == ( + EventType.ERROR, "researcher-1's answer was cut off at the output limit", RESEARCHER + ) + + async def test_its_end_carries_what_it_used(self): + ledgers = UsageLedgers() + + async def hook(run: AgentRun) -> RunAnswer: + # Recorded where the run's calls are: in its task, the run active. + ledgers.record(llm_usage_event( + "anthropic:claude", UsageTotals(input=50, output=5, calls=1) + )) + return RunAnswer(text="X is 42.") + + _, events = await delegated(delegations(hook, ledgers=ledgers), request()) + + assert events[-1].metadata["usage"] == {"anthropic:claude": {"input": 50, "output": 5}} + + +class TestARefusedRun: + async def test_ends_refused_and_its_parent_reads_the_notice(self): + hook, _ = answering("The subagent stopped because a model refused the request.", + outcome=REFUSED) + + result, events = await delegated(delegations(hook), request()) + + assert result.result == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_REFUSED, "partial": False, + "result": "The subagent stopped because a model refused the request.", + "error": REFUSAL_ERROR, + } + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_REFUSED)] + + +class TestAFailedRun: + async def test_a_hook_that_raises_fails_it_and_warns_once(self): + async def hook(run: AgentRun) -> RunAnswer: + raise RuntimeError("Error code: 400 - overloaded") + + result, events = await delegated(delegations(hook), request()) + + assert result.result == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_FAILED, "partial": False, "result": "", + "error": "Error code: 400 - overloaded", + } + started, ended, warning = events + assert (ended.metadata["status"], ended.metadata["error"]) == ( + RUN_FAILED, "Error code: 400 - overloaded" + ) + assert warning.content == "researcher-1 failed: Error code: 400 - overloaded" + assert (warning.metadata["recoverable"], warning.metadata["error_code"], + warning.metadata["agent"], warning.run) == ( + True, "RuntimeError", "researcher", RESEARCHER + ) + + async def test_an_error_without_text_is_named_by_its_type(self): + async def hook(run: AgentRun) -> RunAnswer: + raise TimeoutError() + + result, events = await delegated(delegations(hook), request()) + + assert result.result["error"] == "TimeoutError" + assert events[-1].content == "researcher-1 failed: TimeoutError" + + async def test_a_hook_that_answers_an_error_fails_it_with_its_text(self): + hook, _ = answering("Half an answer.", error="m returned no answer") + + result, events = await delegated(delegations(hook), request()) + + assert (result.result["status"], result.result["result"], result.result["error"]) == ( + RUN_FAILED, "Half an answer.", "m returned no answer" + ) + assert events[-1].content == "researcher-1 failed: m returned no answer" + + async def test_its_own_words_are_said_as_given(self): + said = "researcher: the request no longer fits m's context window." + + async def hook(run: AgentRun) -> RunAnswer: + raise RunFailed(said, code="CONTEXT_OVERFLOW") + + result, events = await delegated(delegations(hook), request()) + + assert result.result["error"] == said + warning = events[-1] + assert (warning.content, warning.metadata["error_code"]) == (said, "CONTEXT_OVERFLOW") + + +class TestTheRunsOwnTask: + async def test_the_run_is_active_there_and_no_tool_call_is(self): + seen: list[tuple[RunRef | None, ToolCallRef | None]] = [] + + async def hook(run: AgentRun) -> RunAnswer: + seen.append((get_active_run(), get_active_tool_call())) + return RunAnswer(text="Done.") + + token = set_active_tool_call(ToolCallRef("c1", "task")) + try: + await delegated(delegations(hook), request()) + after = (get_active_run(), get_active_tool_call()) + finally: + reset_active_tool_call(token) + + assert seen == [(RESEARCHER, None)] + # The caller's own context is as it was. + assert after == (None, ToolCallRef("c1", "task")) + + async def test_a_nested_run_is_its_callers_child(self): + hook, asked = answering() + middle = RunRef(agent="middle", instance="middle-1", run="middle-1#1", + parent_run=None, depth=1) + + _, events = await delegated(delegations(hook), request( + {"agent_type": "leaf", "title": "Look", "objective": "Look X up."}, + caller=middle, caller_agent="middle", call_id="m1", + )) + + assert asked[0].ref == RunRef(agent="leaf", instance="leaf-1", run="leaf-1#1", + parent_run="middle-1#1", depth=2) + assert events[0].metadata["started_by"] == "agent:middle-1" + assert started_by(None) == "agent:root" + + async def test_parallel_runs_each_end_when_their_own_hook_returns(self): + slow_may_end = asyncio.Event() + + async def hook(run: AgentRun) -> RunAnswer: + if run.ref.instance == "researcher-2": + await slow_may_end.wait() + return RunAnswer(text=run.ref.instance) + + made = delegations(hook) + live = LiveEvents() + ended: list[str] = [] + + async def source(): + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(live): + fast = asyncio.create_task(made.delegate(request(call_id="c1"))) + slow = asyncio.create_task(made.delegate(request(call_id="c2"))) + await fast + slow_may_end.set() + await slow + finally: + reset_active_turn(token) + if False: # pragma: no cover + yield + + async for event in merged(source(), live): + if event.metadata.get("status") == RUN_COMPLETED: + ended.append(event.run.instance) + if event.run.instance == "researcher-1": + assert not slow_may_end.is_set() # the slow one still runs + + assert ended == ["researcher-1", "researcher-2"] + + +class TestAnInheritingType: + async def test_its_history_is_read_once_and_its_message_ends_with_the_note(self): + hook, asked = answering() + read: list[int] = [] + + def history() -> list[str]: + read.append(1) + return ["the conversation"] + + await delegated(delegations(hook), request( + {"agent_type": "reader", "title": "Read", "objective": "Read it."}, history=history, + )) + + (run,) = asked + assert (run.history, read) == (["the conversation"], [1]) + assert run.message.endswith(INHERITED_CONTEXT_NOTE) + + async def test_a_fresh_type_never_reads_it(self): + hook, asked = answering() + + def history() -> list[str]: + raise AssertionError("a fresh run read the conversation") + + await delegated(delegations(hook), request(history=history)) + + assert asked[0].history is None + + +class TestACancel: + async def test_of_the_callers_task_ends_the_run_interrupted_and_goes_on(self): + started, stopped = asyncio.Event(), asyncio.Event() + + async def hook(run: AgentRun) -> RunAnswer: + started.set() + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + stopped.set() + raise + return RunAnswer() # pragma: no cover + + runs = AgentRuns() + made = delegations(hook, runs=runs) + live = LiveEvents() + + async def caller(): + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(live): + await made.delegate(request()) + finally: + reset_active_turn(token) + + task = asyncio.create_task(caller()) + await asyncio.wait_for(started.wait(), 5) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + + assert stopped.is_set() # the run stopped before the cancel went on + (record,) = runs.records(CONVERSATION) + assert (record.status, record.error) == (RUN_INTERRUPTED, INTERRUPTED_ERROR) + + async def test_of_the_runs_own_task_alone_is_read_by_its_caller(self): + async def hook(run: AgentRun) -> RunAnswer: + raise asyncio.CancelledError # its task stopped, its caller not + + result, events = await delegated(delegations(hook), request()) + + assert (result.result["status"], result.result["error"], result.result["success"]) == ( + RUN_INTERRUPTED, INTERRUPTED_ERROR, False + ) + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_INTERRUPTED)] + + +async def test_a_delegation_blocks_no_event_loop(): + hook, _ = answering() + + with no_blocking_calls(): + result, _ = await delegated(delegations(hook), request()) + + assert result.result["status"] == RUN_COMPLETED diff --git a/tests/workflow/test_agent_graph.py b/tests/workflow/test_agent_graph.py index 7dd5088c..629e8d23 100644 --- a/tests/workflow/test_agent_graph.py +++ b/tests/workflow/test_agent_graph.py @@ -100,16 +100,32 @@ def _nested_configs(self, order: str) -> list[AgentConfig]: @pytest.mark.parametrize("order", ["top-first", "leaf-first"]) async def test_two_level_hierarchy_is_built_completely(self, order: str): + from agentic_cli.workflow.adk.task_tool import TaskTool + + def delegates_to(agent) -> list[str]: + """The types an agent's ``task`` offers, by name ([] without one).""" + return [ + name for tool in agent.tools if isinstance(tool, TaskTool) + for name in tool._get_declaration().parameters_json_schema[ + "properties"]["agent_type"]["enum"] + ] + with MockContext(google_api_key="test-key", session_store="memory") as ctx: mgr = GoogleADKWorkflowManager( agent_configs=self._nested_configs(order), settings=ctx.settings ) - root = await _built(mgr) + await mgr.initialize_services() + try: + root, agents = mgr._root_agent, dict(mgr._agents) + finally: + await mgr.cleanup() assert root.name == "top" - assert [a.name for a in root.sub_agents] == ["mid"] + assert sorted(agents) == ["leaf", "mid", "top"] + assert delegates_to(agents["top"]) == ["mid"] # The nested coordinator must keep its own child. - assert [a.name for a in root.sub_agents[0].sub_agents] == ["leaf"] + assert delegates_to(agents["mid"]) == ["leaf"] + assert delegates_to(agents["leaf"]) == [] class TestPromptSettingsScope: diff --git a/tests/workflow/test_manager_models.py b/tests/workflow/test_manager_models.py index 1107fa88..8857db61 100644 --- a/tests/workflow/test_manager_models.py +++ b/tests/workflow/test_manager_models.py @@ -146,11 +146,11 @@ async def test_a_0_6_settings_file_still_starts(providers, home, monkeypatch): assert manager.catalog.is_authoritative("google") assert manager.catalog.is_authoritative("anthropic") # Each agent runs on its own provider's model class. - root = manager._root_agent + root, writer = manager._root_agent, manager._agents["writer"] assert type(root.model) is Gemini assert root.model.model == "gemini-2.5-flash" - assert type(root.sub_agents[0].model) is AnthropicLlm - assert root.sub_agents[0].model.model == "claude-sonnet-4-5" + assert type(writer.model) is AnthropicLlm + assert writer.model.model == "claude-sonnet-4-5" finally: await manager.cleanup() @@ -248,7 +248,7 @@ async def test_an_agent_naming_a_role(self, providers, monkeypatch): await manager.initialize_services() try: assert str(manager._resolved_models["writer"].ref) == "google:gemini-2.5-flash-lite" - assert manager._root_agent.sub_agents[0].model.model == "gemini-2.5-flash-lite" + assert manager._agents["writer"].model.model == "gemini-2.5-flash-lite" finally: await manager.cleanup() @@ -527,8 +527,7 @@ async def test_a_model_switch_to_another_provider_rebuilds_the_model( await manager.reinitialize(model="anthropic:claude-sonnet-4-5", preserve_sessions=True) assert manager.model == "anthropic:claude-sonnet-4-5" - root = manager._root_agent - for agent in (root, root.sub_agents[0]): + for agent in (manager._root_agent, manager._agents["writer"]): assert type(agent.model) is AnthropicLlm assert agent.model.model == "claude-sonnet-4-5" assert manager._session_service is service @@ -557,7 +556,7 @@ async def test_a_mixed_tree_runs_each_agent_on_its_own_provider(self, providers, await manager.initialize_services() try: root = manager._root_agent - researcher, drafter = root.sub_agents + researcher, drafter = manager._agents["researcher"], manager._agents["drafter"] assert type(root.model) is AnthropicLlm assert type(researcher.model) is Gemini assert type(drafter.model) is OpenAICompatibleLlm @@ -582,7 +581,7 @@ async def test_each_agent_s_settings_reach_its_own_config(self, providers, monke await manager.initialize_services() try: - root, writer = manager._root_agent, manager._root_agent.sub_agents[0] + root, writer = manager._root_agent, manager._agents["writer"] assert writer.generate_content_config.temperature == 0.2 assert writer.generate_content_config.max_output_tokens == 1000 assert writer.planner.thinking_config.thinking_budget == 4096 @@ -712,7 +711,7 @@ async def test_adk_builds_every_provider(self, providers, monkeypatch): await manager.initialize_services() try: - writer = manager._root_agent.sub_agents[0] + writer = manager._agents["writer"] assert type(writer.model) is OpenAIResponsesLlm assert writer.model.model == "gpt-5.5" finally: @@ -742,7 +741,7 @@ async def test_a_native_thinking_level_runs_on_adk(self, providers, monkeypatch) await manager.initialize_services() try: - writer = manager._root_agent.sub_agents[0] + writer = manager._agents["writer"] assert writer.generate_content_config.effort == "xhigh" assert writer.planner.thinking_config.thinking_budget == -1 # adaptive finally: diff --git a/tests/workflow/test_resource_ownership.py b/tests/workflow/test_resource_ownership.py index 19d9cdb5..924b3be2 100644 --- a/tests/workflow/test_resource_ownership.py +++ b/tests/workflow/test_resource_ownership.py @@ -124,7 +124,24 @@ async def close(self) -> None: class TestRunnerClose: """The runner is closed on every release: dropped unclosed, each agent's - MCP toolset stayed open (``tests/workflow/test_adk_mcp_lifecycle.py``).""" + MCP toolset stayed open (``tests/workflow/test_adk_mcp_lifecycle.py``). + So is each sub-agent type's runner, before the session service.""" + + async def test_each_sub_agent_types_runner_is_closed_too(self): + order: list[str] = [] + + class Service: + async def close(self) -> None: + order.append("session_service") + + mgr = _manager(Service()) + mgr._runner = _Runner(order) + mgr._agent_runners = {"researcher": _Runner(order)} + + await mgr.cleanup() + + assert order == ["runner", "runner", "session_service"] + assert dict(mgr._agent_runners) == {} async def test_cleanup_closes_it_before_the_session_service(self): order: list[str] = [] diff --git a/tests/workflow/test_run_answer_rules.py b/tests/workflow/test_run_answer_rules.py new file mode 100644 index 00000000..0bf91a05 --- /dev/null +++ b/tests/workflow/test_run_answer_rules.py @@ -0,0 +1,108 @@ +"""The rules each backend's ``_run_agent`` reads a sub-agent run's answer by. + +Both managers hand a run's shared-state changes back by one rule, Deep +Agents' own ``task``'s (``deepagents.middleware.subagents._is_unchanged``): +a key returned exactly as it was received, or equal to it, is no change, and +an ambiguous comparison (an array's) counts as a change. Deep Agents also +reads a run's answer only from the messages after its task message, the +last of them with text. + +The contract suite runs whole turns; these pin the rules themselves, which +the builder tests' fake hook only re-implements. +""" + +from __future__ import annotations + +import numpy as np +import pytest + + +def _adk_changed(): + pytest.importorskip("google.adk") + from agentic_cli.workflow.adk.manager import _changed + + return _changed + + +def _deepagents_changed(): + pytest.importorskip("deepagents") + from agentic_cli.workflow.deepagents.manager import _changed + + return _changed + + +@pytest.fixture(params=["adk", "deepagents"]) +def changed(request): + """The backend's ``_changed(state at the end, state at the start)``.""" + return _adk_changed() if request.param == "adk" else _deepagents_changed() + + +class TestTheChangedKeys: + def test_an_unchanged_key_is_never_handed_back(self, changed): + tasks = [{"description": "find X", "status": "pending"}] + start = {"plan": "- [ ] find X", "tasks": tasks} + + # The same objects, and equal copies. + assert changed({"plan": start["plan"], "tasks": tasks}, start) == {} + assert changed({"plan": "- [ ] find X", "tasks": [dict(tasks[0])]}, start) == {} + + def test_a_changed_key_and_a_new_one_are(self, changed): + start = {"plan": "- [ ] find X"} + end = {"plan": "- [x] find X", "tasks": [{"description": "find X"}]} + + assert changed(end, start) == end + + def test_a_key_that_is_not_shared_is_never_handed_back(self, changed): + assert changed({"messages": ["hi"], "files": {"a": 1}}, {}) == {} + + def test_an_ambiguous_comparison_is_a_change(self, changed): + # An array's == is an array, neither True nor False. + start = {"tasks": np.array([1, 2])} + end = {"tasks": np.array([1, 2])} + + (key,) = changed(end, start) + assert key == "tasks" + # The same object is no change, whatever its == says. + assert changed(start, start) == {} + + +class TestDeepAgentsAnswer: + @pytest.fixture(autouse=True) + def _deepagents(self): + pytest.importorskip("deepagents") + + def test_the_last_text_is_the_last_message_with_any(self): + from langchain_core.messages import AIMessage + + from agentic_cli.workflow.deepagents.manager import _last_text + + answers = [AIMessage("First."), AIMessage("X is 42. \n", tool_calls=[ + {"name": "contract_lookup", "args": {}, "id": "r1"}, + ]), AIMessage(""), AIMessage([])] + + assert _last_text(answers) == "X is 42." + assert _last_text([AIMessage(""), AIMessage(" ")]) == "" + assert _last_text([]) == "" + + def test_its_own_messages_are_those_after_its_task_message(self): + from langchain_core.messages import AIMessage, HumanMessage, ToolMessage + + from agentic_cli.workflow.deepagents.manager import _own_messages + + history = [HumanMessage("My name is Ada.", id="h1"), AIMessage("Noted, Ada.", id="a1"), + ToolMessage("answered", tool_call_id="x", id="t1")] + task = HumanMessage("# Task: Find the code", id="task-1") + own = [AIMessage("", id="a2")] + + assert _own_messages([*history, task, *own], "task-1") == own + assert _own_messages([*history, task], "task-1") == [] + + def test_without_its_task_message_none_is_its_own(self): + from langchain_core.messages import AIMessage, HumanMessage + + from agentic_cli.workflow.deepagents.manager import _own_messages + + messages = [HumanMessage("Hi.", id="h1"), AIMessage("The caller's reply.", id="a1")] + + assert _own_messages(messages, "task-1") == [] + assert _own_messages(messages, None) == [] diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 0a13814e..9b9f1f99 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -4,11 +4,12 @@ Deep Agents (``ScriptedChat``) and expects the same events, run records and results: the two backends behave alike. A scenario's model answers are written once, in backend-neutral steps (``says``; ``calls`` with ``delegate`` -and ``use``), which the harness turns into each backend's: on ADK a -delegation is a call of the tool named after the sub-agent (``request``), on -Deep Agents a ``task`` call (``description``, ``subagent_type``). Each -agent's prompt is ``You are <name>.``, by which ADK's fake API tells the -agents apart. +and ``use``), which the harness turns into each backend's. A delegation is a +``task`` call on both (``task_arguments``: ``agent_type``, the brief's +``title`` and ``objective``, and any other field of the brief), answered +with the run's envelope as JSON (``agents/envelope.py``; ``envelope_read`` +reads it back). Each agent's prompt is ``You are <name>.``, by which ADK's +fake API tells the agents apart. Offline: no provider is reached and no catalog lists (``tests/conftest.py``). """ @@ -40,7 +41,9 @@ RUN_REFUSED, RUN_STARTED, RunRecord, + SubAgentPolicy, ) +from agentic_cli.workflow.agents.envelope import read_envelope from agentic_cli.workflow.config import AgentConfig from agentic_cli.workflow.events import ( EventType, @@ -57,6 +60,7 @@ SessionRef, get_active_run, get_active_tool_call, + get_active_turn, reset_active_turn, root_run, set_active_turn, @@ -75,6 +79,7 @@ UsageTotals, side_call, ) +from tests.loop_guard import no_blocking_calls from tests.workflow.adk.fakes import FakeAPI, anthropic_message from tests.workflow.compacting import compact_now from tests.workflow.test_manager_models import route @@ -98,7 +103,11 @@ @dataclass(frozen=True) class Call: - """One call a model answer makes: a delegation to ``agent``, or a call of ``tool``.""" + """One call a model answer makes: a delegation to ``agent``, or a call of ``tool``. + + A delegation's ``args`` are its brief's fields besides the objective + (``brief``): ``title`` and any other, as ``task`` names them. + """ call_id: str agent: str | None = None @@ -107,9 +116,26 @@ class Call: args: dict[str, Any] = field(default_factory=dict) -def delegate(agent: str, brief: str, call_id: str) -> Call: - """A delegation of ``brief`` to the sub-agent ``agent``.""" - return Call(call_id=call_id, agent=agent, brief=brief) +def delegate(agent: str, brief: str, call_id: str, **fields: Any) -> Call: + """A ``task`` call that delegates to ``agent``: ``brief`` its objective, its + title ``brief``'s first line unless ``fields`` name one, and ``fields`` + the brief's other fields (or any argument, as a model may write it).""" + return Call(call_id=call_id, agent=agent, brief=brief, args=dict(fields)) + + +def task_arguments(call: Call) -> dict[str, Any]: + """A delegation's ``task`` arguments, as both backends' models write them.""" + title = next((line.strip() for line in call.brief.splitlines() if line.strip()), "") + arguments: dict[str, Any] = {"agent_type": call.agent, "title": title, "objective": call.brief} + arguments.update(call.args) + return arguments + + +def envelope_read(text: str) -> dict[str, Any]: + """The envelope a parent read for a delegation, from the result's text.""" + found = json.loads(text) + assert isinstance(found, dict) and "status" in found, text + return found def use(tool: str, call_id: str, **args: Any) -> Call: @@ -163,14 +189,15 @@ def agent( tools: tuple[Any, ...] = (), **fields: Any, ) -> AgentConfig: - """An agent of a scenario's team, without state tools (its requests hold only its own).""" + """An agent of a scenario's team, without state tools unless ``fields`` ask + for them (its requests hold only its own).""" return AgentConfig( name=name, prompt=prompt_of(name), sub_agents=list(sub_agents), tools=list(tools), description=fields.pop("description", f"The {name}."), - include_state_tools=False, + include_state_tools=fields.pop("include_state_tools", False), **fields, ) @@ -189,8 +216,8 @@ def _claude_answer(step: Step) -> dict[str, Any] | httpx.Response: blocks.append({"type": "text", "text": step.text}) for call in step.calls: if call.agent is not None: - blocks.append({"type": "tool_use", "id": call.call_id, "name": call.agent, - "input": {"request": call.brief}}) + blocks.append({"type": "tool_use", "id": call.call_id, "name": "task", + "input": task_arguments(call)}) else: blocks.append({"type": "tool_use", "id": call.call_id, "name": call.tool, "input": dict(call.args)}) @@ -205,7 +232,7 @@ def _claude_answer(step: Step) -> dict[str, Any] | httpx.Response: def _scripted_answer(step: Step) -> Any: """``step`` as a ``ScriptedChat`` answers, for Deep Agents: its stop reason in ``response_metadata``, where ChatAnthropic reports Claude's.""" - from tests.workflow.deepagents.fakes import ai, task + from tests.workflow.deepagents.fakes import ai if step.fails is not None: # What the Anthropic client raises for that 400. @@ -216,7 +243,7 @@ def _scripted_answer(step: Step) -> Any: ) made = [ - task(call.agent, call.brief, call.call_id) if call.agent is not None + ("task", task_arguments(call), call.call_id) if call.agent is not None else (call.tool, dict(call.args), call.call_id) for call in step.calls ] @@ -325,6 +352,9 @@ class Crew: _answers: Callable[[str, str], Awaitable[list[str]]] | None = None _last_message: Callable[[str, int], str] | None = None _bodies: Callable[[str], list[str]] | None = None + _tool_names: Callable[[str, int], list[str]] | None = None + _message_count: Callable[[str, int], int] | None = None + _state: Callable[[], Awaitable[dict[str, Any]]] | None = None async def turn(self, text: str = "Go.") -> list[WorkflowEvent]: """One turn of the conversation, run to its end; its events.""" @@ -381,12 +411,29 @@ def bodies(self, agent: str) -> list[str]: assert self._bodies is not None return self._bodies(agent) + def tool_names(self, agent: str, call: int = 0) -> list[str]: + """The tools ``agent``'s model request ``call`` offered, by name, in order.""" + assert self._tool_names is not None + return self._tool_names(agent, call) + + def message_count(self, agent: str, call: int = 0) -> int: + """How many messages ``agent``'s model request ``call`` held, its system prompt aside.""" + assert self._message_count is not None + return self._message_count(agent, call) + + async def state(self) -> dict[str, Any]: + """The conversation's shared state as the root holds it: its plan and tasks.""" + assert self._state is not None + return await self._state() + async def answers(self, agent: str, call_id: str) -> list[str]: """The answers ``agent``'s call ``call_id`` has after a stopped turn, one per answer, as text: a call answered twice is there twice. - ADK keeps every agent's conversation, so these are the answers its - session holds. Deep Agents keeps only the root's (a sub-agent is + ADK keeps every agent's conversation, the root's in the + conversation's session and each sub-agent run's in its child session + (``adk/sessions.py::child_app``), so these are the answers those + sessions hold. Deep Agents keeps only the root's (a sub-agent is compiled without a checkpointer), so a call's answer there is the one its stack gives it from the record (``OpenCalls``, under the run of ``agent``); read it before the next turn ends, which clears it. @@ -408,12 +455,18 @@ def _settings() -> BaseSettings: return BaseSettings(session_store="memory", default_model="claude-sonnet-4-6") -def _adk_crew(team: list[AgentConfig], scripts: dict[str, list[Step]], monkeypatch) -> Crew: +def _adk_crew( + team: list[AgentConfig], scripts: dict[str, list[Step]], monkeypatch, + subagents: SubAgentPolicy | None = None, +) -> Crew: from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager + from agentic_cli.workflow.adk.sessions import child_app claude = _ClaudeTeam(scripts) route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(claude)) - manager = GoogleADKWorkflowManager(agent_configs=team, settings=_settings()) + manager = GoogleADKWorkflowManager( + agent_configs=team, settings=_settings(), subagents=subagents + ) def results_read(name: str, call: int) -> dict[str, str]: return _claude_results([body for sent, body in claude.sent if sent == name][call]) @@ -425,12 +478,17 @@ def result_ids(name: str, call: int) -> list[str]: return _claude_result_ids([body for sent, body in claude.sent if sent == name][call]) async def answers(name: str, call_id: str) -> list[str]: - session = await manager._session_service.get_session( - app_name=manager.session_ref(SESSION, USER).app_name, - user_id=USER, session_id=SESSION, - ) + service = manager._session_service + app = manager.session_ref(SESSION, USER).app_name + sessions = [await service.get_session(app_name=app, user_id=USER, session_id=SESSION)] + listed = await service.list_sessions(app_name=child_app(app), user_id=USER) + for child in listed.sessions: + sessions.append(await service.get_session( + app_name=child_app(app), user_id=USER, session_id=child.id, + )) return [ json.dumps(response.response) + for session in sessions if session is not None for event in session.events if event.author == name for response in event.get_function_responses() if response.id == call_id ] @@ -445,13 +503,30 @@ def last_message(name: str, call: int) -> str: def bodies(name: str) -> list[str]: return [json.dumps(body) for sent, body in claude.sent if sent == name] + def tool_names(name: str, call: int) -> list[str]: + body = [body for sent, body in claude.sent if sent == name][call] + return [tool["name"] for tool in body.get("tools", [])] + + def message_count(name: str, call: int) -> int: + return len([body for sent, body in claude.sent if sent == name][call]["messages"]) + + async def state() -> dict[str, Any]: + session = await manager._session_service.get_session( + app_name=manager.session_ref(SESSION, USER).app_name, + user_id=USER, session_id=SESSION, + ) + return {key: session.state[key] for key in ("plan", "tasks") if key in session.state} + return Crew( "adk", manager, manager.session_ref(SESSION, USER), results_read, requests, result_ids, - answers, last_message, bodies, + answers, last_message, bodies, tool_names, message_count, state, ) -def _deepagents_crew(team: list[AgentConfig], scripts: dict[str, list[Step]], monkeypatch) -> Crew: +def _deepagents_crew( + team: list[AgentConfig], scripts: dict[str, list[Step]], monkeypatch, + subagents: SubAgentPolicy | None = None, +) -> Crew: from langchain_core.messages import ToolMessage from agentic_cli.workflow.deepagents import manager as deepagents_manager @@ -470,7 +545,9 @@ def _deepagents_crew(team: list[AgentConfig], scripts: dict[str, list[Step]], mo label=chat.label, script=chat.script, summaries=summaries ) monkeypatch.setattr(deepagents_manager, "build_chat_model", models) - manager = deepagents_manager.DeepAgentsWorkflowManager(agent_configs=team, settings=_settings()) + manager = deepagents_manager.DeepAgentsWorkflowManager( + agent_configs=team, settings=_settings(), subagents=subagents + ) def results_read(name: str, call: int) -> dict[str, str]: return { @@ -511,9 +588,23 @@ def bodies(name: str) -> list[str]: for request in models.chats[name].requests ] + def tool_names(name: str, call: int) -> list[str]: + return models.chats[name].tool_names(call) + + def message_count(name: str, call: int) -> int: + return len(models.chats[name].conversation(call)) + + async def state() -> dict[str, Any]: + from agentic_cli.workflow.deepagents.sessions import run_config + + values = (await manager._root.aget_state( + run_config(manager.session_ref(SESSION, USER)) + )).values + return {key: values[key] for key in ("plan", "tasks") if key in values} + return Crew( "deepagents", manager, manager.session_ref(SESSION, USER), results_read, requests, - result_ids, answers, last_message, bodies, + result_ids, answers, last_message, bodies, tool_names, message_count, state, ) @@ -540,7 +631,8 @@ def runs_of(events: list[WorkflowEvent], status: str | None = None) -> list[Work #: What each ``contract_whoami`` call saw: the active run, and its own call id. SEEN: list[tuple[RunRef | None, str | None]] = [] -#: ``BLOCKING["started"]`` is set when a ``contract_block`` call starts (made per test). +#: ``BLOCKING["started"]`` is set when a ``contract_block`` call starts (made per +#: test); ``BLOCKING["stopped"]`` is made by each call and set as it stops. BLOCKING: dict[str, asyncio.Event] = {} @@ -567,9 +659,13 @@ async def contract_summarize(text: str = "") -> dict: @register_tool(capabilities=EXEMPT, description="Wait until stopped (a contract-test tool).") async def contract_block() -> dict: - """Wait, as a slow tool does, until the turn is stopped.""" + """Wait, as a slow tool does, until the turn is stopped; say so as it stops.""" + stopped = BLOCKING["stopped"] = asyncio.Event() BLOCKING["started"].set() - await asyncio.Event().wait() + try: + await asyncio.Event().wait() + finally: + stopped.set() return {"success": True} @@ -662,19 +758,23 @@ def project(tmp_path, monkeypatch) -> Path: @pytest.fixture async def make_crew(backend, project, monkeypatch): - """``make_crew(team, **scripts)``: ``team``'s manager on ``backend``, each - agent answering from its script (an agent without one has none); every - manager made is cleaned up after the test.""" + """``make_crew(team, *, subagents=None, **scripts)``: ``team``'s manager on + ``backend``, with the sub-agent policy ``subagents``, each agent answering + from its script (an agent without one has none); every manager made is + cleaned up after the test.""" SEEN.clear() BLOCKING["started"] = asyncio.Event() made: list[Crew] = [] - def make(team: list[AgentConfig], **scripts: list[Step]) -> Crew: + def make( + team: list[AgentConfig], *, subagents: SubAgentPolicy | None = None, + **scripts: list[Step], + ) -> Crew: complete = {config.name: list(scripts.get(config.name, ())) for config in team} complete[SIDE_CALLS] = list(scripts.get(SIDE_CALLS, ())) complete[SUMMARIES] = list(scripts.get(SUMMARIES, ())) build = _adk_crew if backend == "adk" else _deepagents_crew - crew = build(team, complete, monkeypatch) + crew = build(team, complete, monkeypatch, subagents) made.append(crew) return crew @@ -719,6 +819,8 @@ async def test_a_delegation_is_a_run_from_its_call_to_its_result(self, make_crew assert started.metadata == { "status": RUN_STARTED, "agent": "researcher", "partial": False, "call_id": "c1", "title": "Find X.", + "brief": {"title": "Find X.", "objective": "Find X.\nUse what you know."}, + "started_by": "agent:root", "mode": "blocking", } assert (ended.metadata["status"], ended.metadata["call_id"], ended.metadata["result"]) == ( RUN_COMPLETED, "c1", "X is 42.", @@ -727,12 +829,20 @@ async def test_a_delegation_is_a_run_from_its_call_to_its_result(self, make_crew if e.type is EventType.TOOL_CALL and e.metadata.get("tool_call_id") == "c1") result = next(i for i, e in enumerate(events) if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "c1") - assert events.index(started) == call + 1 - assert events.index(ended) == result + 1 + # The run starts after its call (and the step's usage), before any + # event of its own, and ends as it ends: before its parent's result, + # which comes when the parent's step is done. + own = [i for i, e in enumerate(events) if e.run == RESEARCHER and e not in (started, ended)] + assert call < events.index(started) < own[0] + assert own[-1] < events.index(ended) < result (record,) = crew.records() assert (record.ref, record.call_id, record.title, record.status, record.result) == ( RESEARCHER, "c1", "Find X.", RUN_COMPLETED, "X is 42.", ) + assert (record.brief, record.started_by, record.mode) == ( + {"title": "Find X.", "objective": "Find X.\nUse what you know."}, + "agent:root", "blocking", + ) assert record.ended is not None and record.ended >= record.started async def test_every_event_an_agent_wrote_names_its_run(self, make_crew): @@ -884,6 +994,8 @@ async def test_a_stopped_turn_leaves_its_open_run_interrupted(self, make_crew): # lock, and the fixture's cleanup would wait for it forever. await crew.stop(turn) + # The run's tool in flight stopped before the stop returned. + assert BLOCKING["stopped"].is_set() (record,) = crew.records() assert (record.ref, record.status) == (RESEARCHER, RUN_INTERRUPTED) assert record.ended is not None @@ -912,8 +1024,8 @@ async def test_a_delegation_ends_at_its_own_result(self, make_crew): assert results[0].metadata["tool_name"] == "contract_lookup" (ended,) = runs_of(events, RUN_COMPLETED) assert (ended.run, ended.metadata["result"]) == (RESEARCHER, "X is 42.") - assert events.index(ended) == events.index(results[1]) + 1 - assert crew.results_read("coordinator")["c1"] == "X is 42." + assert events.index(results[0]) < events.index(ended) < events.index(results[1]) + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == "X is 42." async def test_after_ctrl_c_a_delegation_is_answered_as_interrupted(self, make_crew): crew = make_crew( @@ -1063,7 +1175,7 @@ async def test_after_ctrl_c_a_finished_delegation_keeps_its_result(self, make_cr ] assert sorted(crew.result_ids("coordinator")) == ["c1", "c2"] answered = crew.results_read("coordinator") - assert answered["c1"] == "X is 42." + assert envelope_read(answered["c1"])["result"] == "X is 42." assert INTERRUPTED_BY_USER in answered["c2"] @@ -1090,7 +1202,11 @@ async def test_a_refusal_reaches_the_parent_as_the_notice_and_the_run_is_refused events = await crew.turn() - assert crew.results_read("coordinator")["c1"] == REFUSAL + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_REFUSED, "partial": False, "result": REFUSAL, + "error": "a model refused the request", + } (ended,) = runs_of(events, RUN_REFUSED) assert ended.run == RESEARCHER assert (ended.metadata["result"], ended.metadata["error"], ended.metadata["partial"]) == ( @@ -1111,7 +1227,10 @@ async def test_a_cut_answer_is_kept_marked_partial_and_warned_once(self, make_cr events = await crew.turn() - assert crew.results_read("coordinator")["c1"] == CUT_OFF + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": True, "result": CUT_OFF, "error": None, + } (ended,) = runs_of(events, RUN_COMPLETED) assert (ended.run, ended.metadata["result"], ended.metadata["partial"]) == ( RESEARCHER, CUT_OFF, True, @@ -1140,7 +1259,10 @@ async def test_parallel_runs_each_end_by_their_own_last_answer(self, make_crew): events = await crew.turn() - read = crew.results_read("coordinator") + read = { + call: envelope_read(text)["result"] + for call, text in crew.results_read("coordinator").items() + } assert sorted(read[call] for call in ("c1", "c2")) == sorted([REFUSAL, "B is 7."]) ended = { e.metadata["call_id"]: (e.metadata["status"], e.metadata["result"]) @@ -1161,7 +1283,7 @@ async def test_an_answer_that_ended_well_is_not_touched(self, make_crew): events = await crew.turn() - assert crew.results_read("coordinator")["c1"] == "X is 42." + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == "X is 42." (ended,) = runs_of(events, RUN_COMPLETED) assert ended.metadata["partial"] is False assert [e for e in events if e.type is EventType.ERROR] == [] @@ -1200,21 +1322,18 @@ async def test_the_parent_reads_why_and_the_turn_goes_on(self, make_crew): events = await crew.turn() (warning,) = [e for e in events if e.type is EventType.ERROR] - assert warning.content.startswith("researcher failed: ") + assert warning.content.startswith("researcher-1 failed: ") assert "max_tokens: 100000 > 64000" in warning.content assert (warning.metadata["recoverable"], warning.metadata["agent"], warning.run) == ( True, "researcher", RESEARCHER, ) - read = crew.results_read("coordinator")["c1"] - assert read.startswith("Error running sub-agent: ") + # The parent reads the provider's reason, on both backends. + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["success"], read["status"], read["result"]) == (False, RUN_FAILED, "") + assert "max_tokens: 100000 > 64000" in read["error"] (ended,) = runs_of(events, RUN_FAILED) assert (ended.run, ended.metadata["result"]) == (RESEARCHER, "") - assert ended.metadata["error"] == read.removeprefix("Error running sub-agent: ") - if crew.backend == "deepagents": - # A named difference: ADK's private delegation tool words its - # reason "Dynamic node researcher failed" (the provider's reason - # reaches the user in the warning above). - assert "max_tokens: 100000 > 64000" in read + assert ended.metadata["error"] == read["error"] assert [r.status for r in crew.records()] == [RUN_FAILED] assert [e.content for e in events if e.type is EventType.TEXT and e.run == COORDINATOR] == [ @@ -1261,17 +1380,13 @@ async def test_an_overflow_is_warned_of_alike(self, make_crew): warning.metadata["agent"], warning.run) == ( True, "CONTEXT_OVERFLOW", "researcher", RESEARCHER, ) - read = crew.results_read("coordinator")["c1"] + # The run fails with the overflow's words, on both backends. + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["status"], read["error"]) == (RUN_FAILED, warning.content) (ended,) = [e for e in runs_of(events) if e.metadata["status"] != RUN_STARTED] - if crew.backend == "adk": - # A named difference: ADK's overflow handler answers the - # sub-agent's model call with text, so its run completes; on - # Deep Agents the parent reads the error, and the run fails. - assert read.startswith("I could not do this task: the request no longer fits ") - assert ended.metadata["status"] == RUN_COMPLETED - else: - assert read.startswith("Error running sub-agent: ") - assert ended.metadata["status"] == RUN_FAILED + assert (ended.metadata["status"], ended.metadata["error"]) == ( + RUN_FAILED, warning.content + ) assert [e.content for e in events if e.type is EventType.TEXT and e.run == COORDINATOR] == [ "The researcher could not do it." @@ -1301,16 +1416,21 @@ async def test_a_nested_failure_is_the_leafs_and_its_parent_answers(self, make_c leaf = RunRef(agent="leaf", instance="leaf-1", run="leaf-1#1", parent_run="middle-1#1", depth=2) (warning,) = [e for e in events if e.type is EventType.ERROR] - assert warning.content.startswith("leaf failed: ") + assert warning.content.startswith("leaf-1 failed: ") assert "overloaded" in warning.content assert (warning.metadata["recoverable"], warning.metadata["agent"], warning.run) == ( True, "leaf", leaf, ) - assert crew.results_read("middle")["m1"].startswith("Error running sub-agent: ") + # The middle reads why its leaf failed: the provider's reason. + read = envelope_read(crew.results_read("middle")["m1"]) + assert read["status"] == RUN_FAILED + assert "overloaded" in read["error"] assert [(e.run, e.metadata["status"]) for e in runs_of(events)] == [ (middle, RUN_STARTED), (leaf, RUN_STARTED), (leaf, RUN_FAILED), (middle, RUN_COMPLETED), ] - assert crew.results_read("coordinator")["c1"] == "The leaf could not look X up." + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == ( + "The leaf could not look X up." + ) assert [e.content for e in events if e.type is EventType.TEXT and e.run == COORDINATOR] == [ "Planned without the leaf." @@ -1352,10 +1472,11 @@ async def test_a_refused_delegation_shows_the_notices_first_line(self, make_crew e for e in events if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "c1" ] - # The notice is one line, longer than a summary: it is cut. + # The notice is one line, longer than a summary: it is cut. A refused + # run did not complete: its result fails, as its envelope says. assert "\n" not in REFUSAL and len(REFUSAL) > TOOL_SUMMARY_MAX_LENGTH - assert (result.content, result.metadata["success"]) == ( - REFUSAL[:TOOL_SUMMARY_MAX_LENGTH] + "...", True, + assert (result.content, result.metadata["success"], result.metadata["error"]) == ( + REFUSAL[:TOOL_SUMMARY_MAX_LENGTH] + "...", False, "a model refused the request", ) async def test_a_cut_delegation_shows_the_kept_texts_first_line(self, make_crew): @@ -1371,7 +1492,7 @@ async def test_a_cut_delegation_shows_the_kept_texts_first_line(self, make_crew) e for e in events if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "c1" ] - assert crew.results_read("coordinator")["c1"] == CUT_OFF + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == CUT_OFF assert (result.content, result.metadata["success"]) == ("X is", True) async def test_a_failed_delegation_shows_why(self, make_crew): @@ -1387,17 +1508,11 @@ async def test_a_failed_delegation_shows_why(self, make_crew): e for e in events if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "c1" ] - read = crew.results_read("coordinator")["c1"] - reason = read.removeprefix("Error running sub-agent: ") + reason = envelope_read(crew.results_read("coordinator")["c1"])["error"] first = truncate(reason.strip().splitlines()[0], TOOL_SUMMARY_MAX_LENGTH) assert result.content == f"Failed: {first}" - assert (result.metadata["success"], result.metadata["error"]) == (False, read) - if crew.backend == "adk": - # A named difference: ADK's private delegation tool words the - # parent's reason itself. - assert result.content == "Failed: Dynamic node researcher failed" - else: - assert "overloaded" in reason + assert (result.metadata["success"], result.metadata["error"]) == (False, reason) + assert "overloaded" in reason # the provider's own reason, on both backends async def test_an_answer_that_looks_like_a_failed_result_is_an_answer(self, make_crew): """A sub-agent's answer is text, never read for success: JSON that @@ -1416,7 +1531,7 @@ async def test_an_answer_that_looks_like_a_failed_result_is_an_answer(self, make if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "c1" ] (ended,) = runs_of(events, RUN_COMPLETED) - assert crew.results_read("coordinator")["c1"] == answer + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == answer assert (ended.run, ended.metadata["result"]) == (RESEARCHER, answer) assert "error" not in ended.metadata assert (result.content, result.metadata["success"]) == (answer, True) @@ -1873,3 +1988,346 @@ async def allow_one(request: UserInputRequest) -> str: } assert "Permission denied: no rule + user denied" in read["r2"] assert "Permission denied" not in read["r1"] + + +# -- the framework's task: the brief in, the envelope out, the same on both backends ------ + + +@register_tool(capabilities=EXEMPT, description="Echo a value (a contract-test tool).") +def contract_echo(q: str = "") -> dict: + """Echo ``q`` back, marked: what a run reads of its own call.""" + return {"success": True, "echo": f"echo-{q}"} + + +#: ``contract_echo_together``'s calls: ``TOGETHER["open"]`` in flight now, +#: ``TOGETHER["most"]`` the most at once (made per test). +TOGETHER: dict[str, int] = {} + + +@register_tool(capabilities=EXEMPT, description="Echo once two calls are in (a contract-test tool).") +async def contract_echo_together(q: str = "") -> dict: + """Echo ``q`` back, marked, once two calls are in flight at once: a + barrier, so two runs' calls are open together before either answers.""" + TOGETHER["open"] += 1 + TOGETHER["most"] = max(TOGETHER["most"], TOGETHER["open"]) + try: + await until(lambda: TOGETHER["most"] >= 2, within=10) + finally: + TOGETHER["open"] -= 1 + return {"success": True, "echo": f"echo-{q}"} + + +@register_tool(capabilities=EXEMPT, description="Wait for a run to end (a contract-test tool).") +async def contract_await_a_finished_run() -> dict: + """Wait until a run of this conversation has completed, as a slow tool would.""" + runs = get_service(WORKFLOW).agent_runs + conversation = get_active_turn() + for _ in range(500): + if any(record.status == RUN_COMPLETED for record in runs.records(conversation)): + return {"success": True} + await asyncio.sleep(0.01) + return {"success": False, "error": "no run completed"} + + +class TestTheTaskTool: + async def test_the_delegation_tool_is_task_on_both(self, make_crew): + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[says("X is 42.")], + ) + + await crew.turn() + + assert crew.tool_names("coordinator") == ["contract_whoami", "task"] + assert "task" not in crew.tool_names("researcher") + + async def test_a_sub_agents_first_request_is_its_task_message(self, make_crew): + crew = make_crew( + team(), + coordinator=[calls(delegate( + "researcher", "Find X.", "c1", title="Find X", deliverable="One number.", + constraints="Use the handbook.", known="It is not 41.", done_when="X is named.", + )), says("Done.")], + researcher=[says("X is 42.")], + ) + + events = await crew.turn() + + assert crew.message_count("researcher", 0) == 1 + assert crew.last_message("researcher", 0) == ( + "# Task: Find X\n\n## Objective\nFind X.\n\n## Deliverable\nOne number.\n\n" + "## Constraints\nUse the handbook.\n\n## What is already known\nIt is not 41.\n\n" + "## Done when\nX is named." + ) + (started,) = runs_of(events, RUN_STARTED) + assert started.metadata["brief"] == { + "title": "Find X", "objective": "Find X.", "deliverable": "One number.", + "constraints": "Use the handbook.", "known": "It is not 41.", + "done_when": "X is named.", + } + + async def test_a_brief_that_misses_a_required_field_starts_no_run(self, make_crew): + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", brief_required=("objective", "deliverable"))], + coordinator=[calls(delegate("researcher", "Find X.", "c1")), + says("I will brief it again.")], + researcher=[says("[never asked]")], + ) + + events = await crew.turn() + + assert json.loads(crew.results_read("coordinator")["c1"]) == { + "success": False, "error": "The brief for 'researcher' is missing: deliverable.", + } + assert runs_of(events) == [] + assert crew.records() == [] + assert crew.requests("researcher") == 0 + (result,) = [e for e in events if e.type is EventType.TOOL_RESULT] + assert result.metadata["success"] is False + + async def test_the_envelope_of_a_completed_run(self, make_crew): + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[says("X is 42.")], + ) + + events = await crew.turn() + + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": False, "result": "X is 42.", "error": None, + } + (result,) = [e for e in events if e.type is EventType.TOOL_RESULT] + assert result.metadata["result"] == envelope_read(crew.results_read("coordinator")["c1"]) + + +class TestEachRunEndsAtItsOwnEnd: + async def test_of_two_parallel_delegations_the_fast_ones_run_ends_first(self, make_crew): + """The slow run waits until the fast one has ended: its end comes + while the slow one still works, not with its sibling's.""" + crew = make_crew( + [ + agent("coordinator", sub_agents=("researcher", "waiter")), + agent("researcher"), + agent("waiter", tools=(contract_await_a_finished_run,)), + ], + coordinator=[calls(delegate("researcher", "Fast.", "c1"), + delegate("waiter", "Slow.", "c2")), + says("Both.")], + researcher=[says("Fast done.")], + waiter=[calls(use("contract_await_a_finished_run", "w1")), says("Slow done.")], + ) + + events = await crew.turn() + + ends = [(e.run.instance, events.index(e)) for e in runs_of(events, RUN_COMPLETED)] + assert [instance for instance, _ in ends] == ["researcher-1", "waiter-1"] + (waited,) = [i for i, e in enumerate(events) + if e.type is EventType.TOOL_RESULT and e.metadata["tool_call_id"] == "w1"] + assert ends[0][1] < waited < ends[1][1] + assert json.loads(crew.results_read("waiter", 1)["w1"]) == {"success": True} + + +class TestSharedState: + async def test_the_plan_reaches_a_run_and_its_tasks_come_back(self, make_crew): + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",), include_state_tools=True), + agent("researcher", include_state_tools=True)], + coordinator=[calls(use("save_plan", "c0", content="- [ ] find X")), + calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("get_plan", "r1")), + calls(use("save_tasks", "r2", tasks=[ + {"description": "find X", "status": "completed"}, + ])), + says("X is 42.")], + ) + + await crew.turn() + + assert "find X" in crew.results_read("researcher", 1)["r1"] + state = await crew.state() + assert state["plan"] == "- [ ] find X" + assert [task["description"] for task in state["tasks"]] == ["find X"] + + +class TestAnInheritingRun: + async def test_it_reads_the_conversation_and_its_task_message_ends_with_the_note( + self, make_crew + ): + from agentic_cli.workflow.agents.brief import INHERITED_CONTEXT_NOTE, Brief, task_message + + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", inherit_context=True)], + coordinator=[says("Noted, Ada."), + calls(delegate("researcher", "Find the code.", "c1")), says("Done.")], + researcher=[says("The code is 7.")], + ) + + await crew.turn("My name is Ada and the code is 7.") + await crew.turn("Have the researcher find the code.") + + (first,) = crew.bodies("researcher") + assert "My name is Ada and the code is 7." in first + assert "Noted, Ada." in first + last = crew.last_message("researcher", 0) + assert last == task_message( + Brief(title="Find the code.", objective="Find the code."), inherit=True + ) + assert last.endswith(INHERITED_CONTEXT_NOTE) + + async def test_one_that_writes_no_text_answers_nothing_of_its_parents(self, make_crew): + """Its result is what it wrote: none of the conversation it read, + the parent's earlier reply included, is its answer.""" + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", inherit_context=True)], + coordinator=[says("Noted, Ada. The code is 7."), + calls(delegate("researcher", "Find the code.", "c1")), says("Done.")], + researcher=[says("")], + ) + + await crew.turn("My name is Ada and the code is 7.") + events = await crew.turn("Have the researcher find the code.") + + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["status"], read["result"]) == (RUN_COMPLETED, "") + (result,) = [e for e in events if e.type is EventType.TOOL_RESULT + and e.metadata.get("tool_call_id") == "c1"] + assert result.content == "No answer" + assert [r.result for r in crew.records()] == [""] + + +class TestRunsOfOneTypeWithTheSameCallIds: + """Two instances of one type at once, on a provider that numbers its call + ids alike in both (``call_0``): each run reads its own call's result, + never the other's.""" + + async def test_each_run_keeps_its_own_results(self, make_crew): + TOGETHER.update(open=0, most=0) + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", tools=(contract_echo_together,))], + coordinator=[calls(delegate("researcher", "Find A.", "c1"), + delegate("researcher", "Find B.", "c2")), + says("Both.")], + researcher=[calls(use("contract_echo_together", "call_0", q="A")), + calls(use("contract_echo_together", "call_0", q="B")), + says("One done."), says("The other done.")], + ) + + events = await crew.turn() + + # Both calls named call_0 were open at once (the barrier held each + # until the other came in), yet each run read its own result. + assert TOGETHER["most"] == 2 + + echoed = [ + {value for value in ("echo-A", "echo-B") if value in body} + for body in crew.bodies("researcher") + ] + assert sorted(map(sorted, filter(None, echoed))) == [["echo-A"], ["echo-B"]] + assert sorted(r.status for r in crew.records()) == [RUN_COMPLETED, RUN_COMPLETED] + read = crew.results_read("coordinator") + assert sorted(envelope_read(read[call])["run"] for call in ("c1", "c2")) == [ + "researcher-1#1", "researcher-2#1", + ] + assert [e for e in events if e.type is EventType.ERROR] == [] + + +class TestAnEmptyLastAnswer: + """A run's result is its last non-empty text on both backends (Anthropic + may end with an empty ``end_turn`` after a final tool call), and a run + with no text at all completes with an empty result, shown as + ``No answer``.""" + + async def test_a_trailing_empty_answer_leaves_the_last_text(self, make_crew): + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1"), text="X is 42."), says("")], + ) + + events = await crew.turn() + + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == "X is 42." + (ended,) = runs_of(events, RUN_COMPLETED) + assert ended.metadata["result"] == "X is 42." + + async def test_no_text_at_all_is_an_empty_result_shown_as_no_answer(self, make_crew): + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[says("")], + ) + + events = await crew.turn() + + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["status"], read["success"], read["result"]) == (RUN_COMPLETED, True, "") + (result,) = [e for e in events if e.type is EventType.TOOL_RESULT + and e.metadata.get("tool_call_id") == "c1"] + assert (result.content, result.metadata["success"]) == ("No answer", True) + assert [r.status for r in crew.records()] == [RUN_COMPLETED] + + +class TestALongResult: + """A run's envelope passes the tool result cap as a dict on both backends: + the parent reads JSON still, the cut and the note in it.""" + + async def test_an_envelope_over_the_cap_is_still_the_envelope(self, make_crew): + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[says("X is 42. " * 500)], + ) + crew.manager.settings.tool_result_max_chars = 2_000 + + events = await crew.turn() + + sent = crew.results_read("coordinator")["c1"] + read = read_envelope(sent) + assert read is not None, sent[:300] + assert len(sent) <= 2_000 + assert (read["success"], read["agent"], read["status"]) == ( + True, "researcher-1", RUN_COMPLETED, + ) + assert read["result"].startswith("X is 42.") and "characters cut]" in read["result"] + assert read["truncated"].startswith("Cut: ") and "tool-output/task-" in read["truncated"] + (result,) = [e for e in events if e.type is EventType.TOOL_RESULT + and e.metadata.get("tool_call_id") == "c1"] + assert result.metadata["result"] == read + assert result.metadata["success"] is True + assert result.content.startswith("X is 42.") + + async def test_its_text_is_sent_as_written(self, make_crew): + """Not as JSON escapes, which make a non-Latin answer six times as long.""" + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[says("答案是四十二。")], + ) + + await crew.turn() + + sent = crew.results_read("coordinator")["c1"] + assert "答案是四十二。" in sent + assert envelope_read(sent)["result"] == "答案是四十二。" + + +class TestOffTheLoop: + async def test_a_delegation_blocks_no_event_loop(self, make_crew): + """A delegation, on both backends, runs once under the loop guard.""" + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X")), says("X is 42.")], + ) + + with no_blocking_calls(): + events = await crew.turn() + + assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_COMPLETED] diff --git a/tests/workflow/test_tool_output.py b/tests/workflow/test_tool_output.py index 02e1e8df..55fb6fca 100644 --- a/tests/workflow/test_tool_output.py +++ b/tests/workflow/test_tool_output.py @@ -119,11 +119,12 @@ class TestAResultThatFits: [ {"success": True, "content": "x" * 100}, "plain text", + '{"success": true, "result": "a JSON object"}', ["a", "b"], None, 42, ], - ids=["dict", "str", "list", "none", "int"], + ids=["dict", "str", "json-str", "list", "none", "int"], ) def test_is_returned_as_is(self, folder, result): assert cap(result, folder) is result @@ -300,6 +301,41 @@ def test_a_list_is_wrapped_and_cut_as_a_dict(self, folder): assert capped["result"][1] == "short" assert size(capped) <= LIMIT + def test_a_string_holding_a_json_object_is_cut_as_that_dict_and_stays_json(self, folder): + # A delegation's envelope, as ADK's task tool returns it: its keys + # stay, its long field is cut, the note goes under "truncated". + envelope = {"success": True, "agent": "researcher-1", "status": "completed", + "result": lines(5_000), "error": None} + + capped = cap(json.dumps(envelope), folder, tool_name="task") + + assert isinstance(capped, str) and len(capped) <= LIMIT + read = json.loads(capped) + assert list(read) == [*envelope, "truncated"] + assert (read["success"], read["status"], read["error"]) == (True, "completed", None) + head, _, tail = pieces(read["result"]) + assert envelope["result"].startswith(head) and envelope["result"].endswith(tail) + assert SAVED_NOTE.match(read["truncated"])["name"].startswith("task-") + + def test_such_a_string_is_measured_and_sent_unescaped(self, folder): + # Escaped, each of these characters takes six: unescaped it fits. + envelope = {"status": "completed", "result": "字" * (LIMIT // 2)} + text = json.dumps(envelope) + assert len(text) > LIMIT + + capped = cap(text, folder) + + assert capped == json.dumps(envelope, ensure_ascii=False) + assert not folder.exists() + + def test_a_string_that_holds_no_json_object_is_cut_as_text(self, folder): + text = json.dumps(["x" * 60_000]) # JSON, but no object + + capped = cap(text, folder) + + body, _, note = capped.rpartition("\n\n") + assert MARKER.search(body) and SAVED_NOTE.match(note) + class TestTheSavedOutput: def test_it_is_private_in_a_private_folder_git_ignores(self, folder):