Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 27 additions & 11 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -584,9 +584,12 @@ the start of the entry's title.
shows what it has used so far) and time. `/agents <id>` 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. During a turn each line of the events box names
the sub-agent run at work (`researcher-2 › Calling: web_fetch`), as its
tool results in the transcript do; the main agent's lines are unchanged.
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`),
as its tool results in the transcript do; the main agent's lines are
unchanged.
- **Token usage by run and agent, on both backends.** Every model call the
framework makes is one `LLM_USAGE`, side calls included (`generate_simple`:
web_fetch's and the knowledge base's summaries, `purpose` `tool`; the memory
Expand Down Expand Up @@ -627,11 +630,21 @@ the start of the entry's title.
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`, `failed` or
`interrupted`, with the first 200 characters of its result), and each
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
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`. `get_active_run()` (exported
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
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
tools, permission checks and questions see it. A consumer that does not
Expand Down Expand Up @@ -1216,9 +1229,11 @@ the start of the entry's title.
model, and `ForeignReasoningMiddleware` leaves out the reasoning of AI
messages another agent wrote, so a fork is never sent its coordinator's.
`validate_agent_graph` raises `AgentGraphError` for `inherit_context=True`
on the root or on an agent with sub-agents of its own (in 0.7.0: Deep
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), and for a value that is not True or False.
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.
- **`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`
Expand Down Expand Up @@ -2816,9 +2831,10 @@ step; each entry says what to use instead.
the stream (`WorkflowEvent.run`) and in `llm_events.jsonl` (`run`: agent,
instance, run, parent run, depth), on both backends.
- **A sub-agent's refused or cut answer is said so, on both backends.** A
sub-agent whose model refused reached its parent as an empty result with
no warning (ADK; Deep Agents before 0.7.34), and an answer cut at the
output limit passed as complete. Now the parent reads Deep Agents
sub-agent whose model refused reached its parent with no warning: as an
empty result on ADK, and on Deep Agents before 0.7.34 as the sub-agent's
last non-empty text (empty when it had written none); and an answer cut at
the output limit passed as complete. Now the parent reads Deep Agents
0.7.34's notice ("The subagent stopped because a model refused the
request. … rephrase it or continue without it.") whichever deepagents is
installed, and the run ends `refused`; a cut answer keeps its text (and
Expand Down
17 changes: 9 additions & 8 deletions CLAUDE.md

Large diffs are not rendered by default.

5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1279,8 +1279,9 @@ references, self-references, delegation cycles, a sub-agent shared by two
parents, and **more than one root** raise `AgentGraphError` naming the
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 or on an agent with sub-agents of its own,
and an `inherit_context` that is not True or False, raise it too, and on ADK,
`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
matter. Then every agent's model is resolved, with the default model, before
Expand Down
28 changes: 21 additions & 7 deletions src/agentic_cli/cli/agents_command.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@

The runs are the manager's records (``BaseWorkflowManager.agent_runs``,
``workflow/agents/runs.py``) and the tokens its usage ledger's
(``usage_of``), so a run still going shows what it has used so far. They
are this process's runs, one run per instance.
(``usage_of``), so a run still going shows what it has used so far. Both
live in memory with the manager: a conversation resumed from an earlier run
of the app, or after a backend switch (a new manager), lists none. Each
instance runs once.
"""

from __future__ import annotations
Expand All @@ -28,13 +30,20 @@
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.runs import run_number

if TYPE_CHECKING:
from agentic_cli.workflow.agents import RunRecord
from agentic_cli.workflow.usage import UsageLedger, UsageTotals

#: How many lines of a run's result ``/agents <id>`` shows.
RESULT_LINES = 3
#: What ``/agents`` says for a conversation with no run recorded.
NO_RUNS = (
"No sub-agent runs in this conversation yet. Runs are kept while the app "
"runs, by its backend: a conversation resumed from an earlier run of the "
"app, or after a backend switch, lists none."
)


def _now() -> datetime:
Expand All @@ -60,21 +69,26 @@ async def execute(self, args: str, app: Any) -> None:
if workflow is None:
return
conversation = workflow.session_ref(getattr(app, "session_id", None))
records = workflow.agent_runs.records(conversation)
runs = workflow.agent_runs
records = runs.records(conversation)
ledger = workflow.usage_of(conversation)
parts = self.parse_args(args).positional.split()
if parts:
wanted = parts[0]
mine = [r for r in records if wanted in (r.ref.instance, r.ref.run)]
if not mine:
found = runs.record(conversation, wanted)
if found is None:
app.session.add_warning(
f"No sub-agent {wanted} in this conversation. Type /agents for the list."
)
return
# A run's id shows that run; an instance's, each of its runs.
mine = [found] if found.ref.run == wanted else [
r for r in records if r.ref.instance == found.ref.instance
]
app.session.add_rich(_one(mine, ledger))
return
if not records:
app.session.add_message("system", "No sub-agent runs in this conversation yet.")
app.session.add_message("system", NO_RUNS)
return
app.session.add_rich(_table(records, ledger))

Expand Down Expand Up @@ -173,7 +187,7 @@ def _status(record: "RunRecord") -> str:

def _run_number(record: "RunRecord") -> str:
"""The run's number within its instance: ``#1`` of ``researcher-2#1``."""
return "#" + (record.ref.run or "").rpartition("#")[2]
return "#" + run_number(record.ref.run or "")


def _tokens(totals: "UsageTotals") -> str:
Expand Down
122 changes: 67 additions & 55 deletions src/agentic_cli/workflow/adk/event_processor.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,11 @@
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,
REFUSAL_ERROR,
REFUSED,
cut_off_warning,
)
from agentic_cli.workflow.agents.outcome import cut_off_warning
from agentic_cli.workflow.agents.runs import (
RUN_COMPLETED,
RUN_FAILED,
RUN_INTERRUPTED,
RUN_REFUSED,
RUN_STARTED,
SUBAGENT_ERROR_PREFIX,
AgentRuns,
result_head,
run_ended,
run_title,
show_as_delegation,
)
Expand Down Expand Up @@ -78,8 +68,12 @@ class ADKEventProcessor:
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. With neither a root nor reply agents,
nothing is marked.
<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.

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
Expand Down Expand Up @@ -132,18 +126,28 @@ class ADKEventProcessor:
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: ``failed`` for
ADK's answer for a sub-agent that failed (``Error running sub-agent:
…``) or an error result (``success`` false: the tool raised), 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 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``.
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.

Args:
model: The default model, which usage names for an agent ``models``
Expand Down Expand Up @@ -415,40 +419,48 @@ def _delegation_run(
)
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)
text = _result_text(response.response)
usage = self._run_usage(child)
outcome = self._outcomes.pop(child.run or "", None)
succeeded, error = _outcome(response.response)
if sealed:
event = WorkflowEvent.agent_run(
child, RUN_INTERRUPTED, call_id=response.id, result=result_head(text),
usage=usage,
)
elif text.startswith(SUBAGENT_ERROR_PREFIX):
event = WorkflowEvent.agent_run(
child, RUN_FAILED, call_id=response.id, result="",
error=text.removeprefix(SUBAGENT_ERROR_PREFIX), usage=usage,
)
elif not succeeded:
event = WorkflowEvent.agent_run(
child, RUN_FAILED, call_id=response.id, result="", error=error or text,
usage=usage,
)
elif outcome == REFUSED:
event = WorkflowEvent.agent_run(
child, RUN_REFUSED, call_id=response.id, result=result_head(text),
error=REFUSAL_ERROR, usage=usage,
)
else:
event = WorkflowEvent.agent_run(
child, RUN_COMPLETED, call_id=response.id, result=result_head(text),
partial=outcome == CUT, usage=usage,
)
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.

Expand Down
37 changes: 28 additions & 9 deletions src/agentic_cli/workflow/adk/interrupted_calls_plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,12 @@ class _Finished:
artifact_delta: dict[str, Any]
cut: Any = None

@property
def read(self) -> Any:
"""What the model reads of the result: the cap's cut, else the result
(never cut again, which would save its full output a second time)."""
return self.result if self.cut is None else self.cut


class InterruptedCallsPlugin(BasePlugin):
"""Answer the calls a cancelled turn leaves open (``workflow/interrupts.py``).
Expand Down Expand Up @@ -222,18 +228,27 @@ def _branch(tool_context: Any) -> str | None:
def _from_record(open_calls: OpenCalls, call_id: str | None, run: str | None, actions: Any) -> Any:
"""A stopped turn's call answered from the record, as ``run``'s.

A finished call keeps what the model would have read: the cap's cut, or
the result as it was (never cut again, which would save its full output
a second time); the state it changed goes into ``actions``, stored with
the answer as with its result. Any other is answered as
``OpenCalls.answer`` says.
A finished call keeps what the model would have read (``_Finished.read``);
the state it changed goes into ``actions``, stored with the answer as
with its result. Any other is answered as ``OpenCalls.answer`` says.
"""
answer = open_calls.answer(call_id, by_user=True, run=run)
if not isinstance(answer, _Finished):
return answer
actions.state_delta.update(answer.state_delta)
actions.artifact_delta.update(answer.artifact_delta)
return answer.result if answer.cut is None else answer.cut
return answer.read


def returned(open_calls: OpenCalls, call_id: str | None, run: str | None) -> dict[str, Any] | None:
"""What the call ``call_id`` of ``run`` returned, from the record; None if it did not finish.

As ADK stores the result (text under ``result``), and as the model reads
it (the cap's cut): what the manager ends a delegation's run with when
no event brought its result (``ADKEventProcessor.end_returned_run``).
"""
finished = open_calls.recorded(call_id, run=run)
return _as_response(finished.read) if isinstance(finished, _Finished) else None


def _as_response(result: Any) -> dict[str, Any]:
Expand Down Expand Up @@ -297,9 +312,13 @@ def unsealed(events: list[Event], open_calls: OpenCalls, runs: AgentRuns) -> lis
other ``INTERRUPTED_BY_USER``. The manager writes them before the turn
clears its record.

Only once ADK has sealed the stopped invocation (its seals are the
session's last events): seals written after these answers would answer
a call twice. ``left_open`` answers, at the next turn, what is left.
Only once ADK has sealed the stopped invocation: seals written after
these answers would answer a call twice. The check is that the
session's last event is a seal, which is also so between two of ADK's
seal appends; a read made there is caught by the durable store's stale
check (an append to a session changed since it was read fails, and
``left_open`` answers the call at the next turn), not by this check.
``left_open`` answers, at the next turn, what is left.
"""
if not events or events[-1].error_code != ABORTED:
return []
Expand Down
Loading
Loading