fix(adk): fail the task when the model stops at max_tokens instead of completing with a cut answer

[fiunchinho]

Fixes #2895

What

When the turn's last model response ends with genai.FinishReasonMaxTokens, the A2A task now ends in TASK_STATE_FAILED with a status message naming what happened:

model output limit reached (max_tokens=8192): the answer is incomplete

The number comes from the response's usage: a model that stopped at the limit was billed for exactly that many output tokens. When usage does not carry it, the sentence is sent without a number rather than with a guess. The artifacts already streamed are untouched, so the caller keeps the partial answer and reads the failure beside it.

The remote agent tool (Go and Python) now reports a failed task to the parent agent the same way: the status message is the error, and the artifacts the task kept are the result. Before, the tool read the artifacts first for a failed task too, so a parent would have seen the cut answer as the error text and never the reason.

Why

A model that stops at its output limit returns an answer cut mid-sentence, and the A2A task reported it as completed. The finish reason was already on the model.LLMResponse — anthropicStopReasonToGenai maps stop_reason: max_tokens onto genai.FinishReasonMaxTokens, and the OpenAI chat, OpenAI Responses and Ollama adapters map their own "length" reasons onto the same value — but nothing downstream acted on it, so it was dropped at the executor boundary.

Nothing after that point could tell a cut answer from a whole one: not a chat front end showing the reply, and not a parent agent calling this one through the remote A2A agent tool, which will happily summarise or act on half an answer. The issue has the details of a turn where this happened (an Anthropic ModelConfig without maxTokens, so the adapter default of 8192, and a thinking model that spent most of the budget before it began writing).

The check keys on the provider-neutral genai.FinishReasonMaxTokens, not on any provider's own type, so every adapter is covered.

Design

• Failed with a message, not completed with a metadata flag. A2A completed is a statement about the work; for a cut answer it is a false one. A flag in metadata is something every client would have to learn to read, and the clients that most need the signal — agents calling agents — are the least likely to read it.
• The streamed artifacts stay. Nothing is withdrawn, so a person still sees what the model managed to write, with the failure next to it.
• No automatic continuation. Re-prompting the model to continue is a policy decision (cost, loops, tool state) that can be layered on top of this signal later. This change only stops a cut answer from being reported as a whole one.
• AfterExecuteCallback rewrites the terminal status. ExecutorConfig.AfterEventCallback sees the ADK *session.Event carrying the finish reason and records how the turn's last model response ended; ExecutorConfig.AfterExecuteCallback sees the terminal TaskStatusUpdateEvent before it is yielded and turns completed into failed. The status message part carries adka2a.ToA2AMetaKey("is_error_message"), the same metadata ADK sets on the failures it reports itself, so clients render it the way they already render an agent failure. Both callbacks are configured once per executor and shared by concurrent executions, so the per-turn state travels in the request context.
• A status that is not completed is left alone, so a failure ADK already reports (a function call broken by the same truncation, say) or an input-required pause is neither overwritten nor reported twice.
• Returning an error from AfterEventCallback was tried first and rejected. ADK v2.3.0 does turn it into a TaskStateFailed status and keeps the artifacts (Executor.process → makeTaskFailedEvent → writeFinalTaskStatus), but it prefixes the message with processor failed:, which reads as an internal fault rather than a model limit, and it aborts the run at that event instead of letting the turn end. Rewriting the terminal status keeps the message exact and the event order unchanged.
• Only completed model responses count. Streaming chunks and the events tools produce carry no finish reason, so a partial chunk never moves the watch, and the last completed model response of the turn decides: a turn that hit the limit on one model call and then answered normally still completes.
• The remote agent tool reads the status message of a failed task first. processResult in go/adk/pkg/tools/remote_a2a_tool.go and its Python twin in _remote_a2a_tool.py preferred the artifacts for every terminal state, which is right for a completed task and wrong for a failed one that kept its output: the parent got the cut answer as the error and never the reason. A failed task now yields error from the status message and result from the artifacts, so the parent reads both. A failed task without a status message still reads its text from the artifacts, and one with neither still names the agent, as before. The Python tool returned a bare string for a failure, which ADK hands to the model as a plain result; it now returns the same error/result/subagent_session_id dict as the Go tool, the shape its HITL failure branch already used.

Tests and commands

New tests in go/adk/pkg/a2a/output_limit_test.go, each driving a fake agent through NewKAgentExecutor in the style of the existing executor tests:

• TestKAgentExecutorFailsTheTaskWhenTheModelStopsAtTheOutputLimit — a partial chunk and a final response with FinishReasonMaxTokens and usage: the task fails, the message names output limit and max_tokens=8192, and the streamed artifact still holds the partial answer. The fixture also sets ThoughtsTokenCount, which is a breakdown of the billed output and must not be added to it (the OpenAI Responses adapter fills both fields).
• TestKAgentExecutorOmitsTheLimitWhenUsageDoesNotNameIt — the same without usage: the task fails and the message carries no number.
• TestKAgentExecutorCompletesTheTaskWhenTheLastResponseStopsNormally — a partial chunk carrying the limit followed by a FinishReasonStop response: the task still completes with no status message.

For the remote agent tool, TestProcessResult_FailedTaskReportsTheReasonBesideThePartialAnswer in go/adk/pkg/tools/remote_a2a_tool_test.go and three cases in python/packages/kagent-adk/tests/unittests/test_remote_a2a_tool.py cover a failure with a status message and artifacts, with a message alone, with artifacts alone, and with neither.

From go/:

go build ./...                          # ok
go vet ./adk/pkg/a2a/... ./adk/pkg/tools/...   # ok
go test -race ./adk/pkg/a2a/... ./adk/pkg/tools/...   # ok
gofmt -l adk/pkg/                       # clean
golangci-lint run ./adk/pkg/a2a/... ./adk/pkg/tools/...   # 0 issues

From python/: uv run pytest packages/kagent-adk/tests/unittests/test_remote_a2a_tool.py (32 passed), ruff format --diff and ruff check clean.

With the rewrite disabled, the first two executor tests fail with terminal state = "TASK_STATE_COMPLETED" — the reported behaviour.

Known gap

A response truncated before it emitted any content part — a turn whose whole budget went to thinking — produces no artifact event, so AfterEventCallback never fires for it and the watch does not see it. That turn arrives empty rather than cut. Covering it would need a runner plugin (OnEventCallback), which seemed more machinery than this fix warrants; happy to add it if you would rather have the complete coverage.

[moezdil]

#2890 also rewrites this callback, conflicts on merge

[fiunchinho]

Thanks. #2890 has merged, so I merged main into this branch (c14d593): the observe call sits at the top of the AfterEventCallback that now ends in transformStructuredOutput, the new AfterExecuteCallback is unchanged, and the test follows the new NewKAgentExecutor error return. The two paths do not overlap: a structured-output turn that stops at max_tokens already fails inside transformStructuredOutput, and failTruncatedAnswer leaves a non-completed terminal status alone, so there is no double report. build, vet, the package tests (incl. TestKAgentExecutorFailsCompletedStructuredOutputWithoutResult) and make lint pass on the merged branch.

[github-actions]

This pull request has been marked as stale because of no activity in the last 15 days. It will be closed in the next 5 days unless it is tagged "no stalebot" or other activity occurs.

[moezdil]

remote tool reads artifacts first, does parent see this?

[fiunchinho]

you are right, it did not. I pushed a new commit, a failed task now yields the status message as error and the artifacts as result, so the parent reads both.