-
feat(adk): add durable background task execution (#1169)
frostbyte_neo 发布于
2026-08-10 07:44:06 +00:00 - feat(adk): add durable background task execution
Persist task intent, ordered updates, leases, checkpoints, results, and notifications so long-running work can survive parent turns and worker recovery. Migrate sub-agent, control middleware, filesystem compatibility, and DeepAgent wiring onto the unified manager lifecycle.
Change-Id: I20c02689b92960073c249ce4e9ce60d5a7826fc4
- fix(adk): complete durable task conformance
Align the provisional task schema and control boundaries with the canonical Phase 1 contract. Preserve recovery policy when drains cannot produce a safe checkpoint and add adversarial coverage for fencing, deadlines, artifacts, notifications, and multi-turn resume.
Change-Id: I0ebe829a152433724b04c1799f743a3b1a518dc3
- test(adk): synchronize durable store test clock
Change-Id: I82490cb87acd519d72e07fd7d93195efd3be8550
- refactor(adk): simplify background task manager api
Remove task-level payload versions, task updates, and worker vocabulary from the background task core. Keep lifecycle status, checkpoints, pending resume commands, and terminal results as separate persisted facts so Store owns fencing and snapshot invariants.
Change-Id: Ib1bbfd3f35391568c9ebc8331638b71277d67c5d
- refactor(adk): finalize background task manager api
Change-Id: I7aefb95bf274f7c1a30275551cd32e6f27a449c8
- fix(adk): address background task lint issues
Change-Id: Ib265257b9a2df081a124e6189bda199b193bf454
- fix(adk): resolve deep background lint
Change-Id: Ic00e1df55559e851879a4cfaba47f51daae8308d
- fix(adk): stabilize explicit background stream notice
Change-Id: I5e81291eac3d8f55d4ca958401c2d8e7426fe4be
- fix(adk): preserve foreground stream errors
Change-Id: Ic219b2745f35dc3dd1b8028f6ee38f1ed1a33ad8
- test(adk): avoid background state race
Change-Id: If79c86b55676f75aebe3ff69d0579f181b84a876
- feat(adk): unify durable background task execution
Align local and durable subagent execution, async shell coordination, runner environment propagation, task control semantics, and output transcript handling so background work has one consistent lifecycle contract.
Change-Id: I1cc0a012cd18c5fc965ad2d5aba6638355018eab
- fix(adk): restore go 1.18 subagent tests
Change-Id: I20fd633d48466ba318ca449dd78885342bebe98d
- fix(adk): preserve background task compatibility
Keep process-local cancellation terminal and retain the established model-facing prompts and output framing while representing durable cancellation intent accurately. Deep-copy notification routing metadata so caller-owned maps cannot mutate pending inbox state.
Change-Id: I499c9816414acbcfef067f8b6a4062248a30379a
- fix(adk): reconstruct durable subagent run options
Resolve deployment-owned run options from the serialized subagent registration on every attempt so retries and worker reassignment do not depend on the launching process. Keep parent-event projection in ADK-internal context and reject invocation-scoped options that cannot be reconstructed durably.
Change-Id: I4b76545e321349933db1a4ec7fc6a2db1f481b51
- refactor(adk): separate background task execution concerns
Keep Manager focused on Store-backed lifecycle and worker coordination while moving process-local closures and foreground projection behind dedicated owners. Persist attempt-fenced output records so Local and Durable execution share an ordered replay contract without exposing process-local observer APIs.
Change-Id: I09def447ecac917198012a9812f6af270d6c506e
- refactor(adk): simplify durable subagent resume
Align durable subagent reconstruction with Eino checkpoint semantics. Persist only the logical query and agent name, derive task-scoped identities, and remove the separate next-turn and empty-resume policies.
Change-Id: I72c138cc176be568f83f62294941a8fc005be105
- refactor(adk): use sessions for durable subagent progress
Make the child SessionEventStore the single durable transcript authority instead of duplicating events into task output files and feeds. Share transcript formatting across local and durable execution, project durable progress through task_output, and clarify the in-memory Store name.
Change-Id: I9dff0505d591d939ca23293a7c5155bc6d35f321
- refactor(adk): narrow background task manager surface
Keep Manager as the aggregate runtime while replacing raw Store and executor registry access with narrow composition APIs. Move projection detachment into foreground context so executor runtime only carries execution concerns, while preserving the dedicated timeout bridge.
Change-Id: I20d498aad67e6f8a8de857387c0c3eb7a1d8b2d2
- refactor(adk): internalize foreground timeout control
Scope timeout requests to the execution context so downstream applications cannot address active attempts through Manager. Preserve deterministic timeout failure and synchronous acknowledgement while keeping cancellation and shutdown controls separately owned.
Change-Id: Id87a1dc3eccd03f74a1549720ea49c71597a82fa
- fix(adk): harden durable background task lifecycle
Fix lifecycle races, stable pagination, deterministic notifications, and lossless resume data found during comprehensive review. Add adversarial coverage and make Go 1.18 CI tests deterministic.
Change-Id: Ib86f396c4babfd279f7e81ed1cdc1ca7c191a2ff
- fix(adk): preserve early stream failures
Prioritize an already-signaled stream readiness result when execution terminates immediately, so callers receive the constructed stream and its source error instead of a startup-state error.
Change-Id: I72527827db6ce43494437fba7905782f86848888
- docs(adk): remove background task design draft
Change-Id: Ifa552a6ef3b600fae491d3cd423f22211e2da024
- feat(adk): add durable background tool execution
Extend the durable task lifecycle to explicitly capable tools and recoverable shells while preserving one task ID space, crash-safe registration, Worker handoff, replay-safe progress, and existing process-local behavior.
Change-Id: I904050fa95c7ce8c58fad627a979b281091e7c12
- fix(adk): harden durable background tool execution
Resolve comprehensive review findings around Worker error visibility, checkpoint retention, terminal update draining, projection detachment, shared Manager validation, and coverage of recovery and failure boundaries.
Change-Id: Ifb386993ae9899be3b7a206ae51ba96cd20349d2
- refactor(adk): simplify recoverable tool contracts
Treat checkpoints as optional hints handled by Recover and keep managed updates focused on bounded textual progress rather than advertising unused MIME semantics.
Change-Id: I69737fdadfc7614eeebf3fc8ccc4b713b2113c59
- refactor(adk): simplify task progress events
Replace sequence-based output records with EventID-keyed task events, centralize generated identities in the execution runtime, and preserve replay-safe materialization semantics.
Change-Id: I7e1d21601e4d61e1824feda681ea8e1196cf111d
- fix(adk): preserve generated task event ids
Project resolved runtime-generated EventIDs to live plain updates, harden adversarial coverage for task-event replay semantics, and refresh the comprehensive PR review report.
Change-Id: I9aa5ab0512566c5b17e4881b3cad54dfb00d50b1
- refactor(adk): internalize checkpoint validation
Checkpoint compatibility and restart safety are executor-specific. Pass persisted checkpoints through unchanged so executors can reject incompatible recovery state without Manager silently discarding it.
Change-Id: If89c84786d7768e4de314a617781018d6bb4d7d2
- refactor(adk): make subagent dependencies explicit
Durable sub-agent execution previously discovered mandatory stores and session configuration through context values, which prevented generic workers from executing those tasks. Bind those services to the concrete executor and keep Runner context limited to request-scoped session identity.
Change-Id: I0a01901cde2543b0e3e1d24ec67a79945161c128
- feat(adk): persist background task control reasons
Cancellation intent can outlive a worker, so its optional reason must be stored with the task and replayed to replacement attempts. Drain reasons remain advisory, timeout reasons are always deterministic, and the unreleased State aliases are removed while the API is still alpha.
Change-Id: I65dfda15d2a3dc3d9a57e54d2fa0c1055f65a055
- refactor(adk): clarify background task errors
The background-task API is still alpha, so replace ambiguous sentinel names directly rather than carrying aliases. The new names identify execution-result invariants, planned-drain checkpoint failure, executor envelope compatibility, and EventID conflicts precisely.
Change-Id: I17a5bf314b60a1dadb224ef1f3886847d4af53ca
- refactor(adk): improve background task api
Change-Id: I5b91d4a3a5957a67af1fd1002347aaa6eb81bae1
- refactor(adk): split task lifecycle and event stores
Keep authoritative lifecycle transitions separate from append-only progress persistence so providers can implement and evolve the two capabilities independently.
Change-Id: Ie69a018c72c259f0320f6fe47fcea68ce85620dd
- refactor(adk): clarify execution runtime semantics
Keep persistence envelopes behind the attempt-scoped runtime and expose progress emission and transcript failure concepts directly to executors.
Change-Id: I02d039f47f68f16a34df3233ba1b84bc617b9131
- refactor(adk): improve background task api
Change-Id: I93c50867fac6a44b3249c5db0d764387fb4f0f1e
- docs(adk): clarify session notification delivery
Notification delivery no longer has generic consumers or sinks, so describe the dispatcher and session inbox as the concrete ownership boundaries.
Change-Id: Icc40a2206627d556ee789ecd5e79a8a2da4d7dc7
- refactor(adk): remove managed tool checkpoints
Recoverable managed tools reconstruct external operations by task identity and attempt, so worker handoff should yield directly without imposing a checkpoint capability or failure mode.
Change-Id: Ie44b709751fcf8aa3e581913843cac78b43862d3
- refactor(adk): move recovery conformance to tooltest
Recovery conformance is a reusable backend test contract, not part of managed task execution. A dedicated tooltest package keeps the capability available without expanding the production-facing tool API.
Change-Id: I42b37a77c34879b023212af6af1f9dc5531856c3
- feat(adk): add paginated task event replay
Task event consumers need exhaustive replay as well as bounded recent reads. Snapshot-stable opaque cursors provide both without exposing storage sequence fields or admitting concurrent appends into an in-progress traversal.
Change-Id: If85fa487ec16415195b137809a0335a0454d95fc
- refactor(adk): tighten background task api contracts
Remove speculative worker and fallback surfaces, separate local and recoverable filesystem modes, and make executor-specific progress capabilities explicit. Strengthen public variant validation, identifier rules, notification scoping, and exported API documentation before the alpha API stabilizes.
Change-Id: I25ca5e6607b4c1ca7bde761a5264dff572fa3d6d
- refactor(adk): rename managed tool response event
Name the public NDJSON envelope after its model-facing response role so it is not confused with task persistence or executor stream state. Preserve the existing wire discriminator values.
Change-Id: I203c45c691bc37e06fe4bffef690d33b19be1917
- refactor(adk): resolve background task api audit
Fail invalid persistence wiring at construction, make lifecycle timestamps provider-owned, simplify session activation, and freeze operational dependencies behind validated constructors. Add reusable conformance suites so external providers can verify lifecycle, event, notification, and inbox contracts before deployment.
Change-Id: I2c861a0a69f9f2907e934da9076e799fd7778708
- refactor(adk): consolidate session notification delivery
Keep task notifications generic while moving session inbox, dispatch, and wake-up concerns into sessionnotify. Replace the core activation interface and request type with one session activation callback owned by the session dispatcher.
Change-Id: I49374626f4f542c86fd02df8f419bd7fed79fb9b
- refactor(adk): remove speculative session notification adapter
Keep the durable boundary at NotificationOutbox and leave session ownership, inbox persistence, scheduling, and wake-up behavior to host applications. Make outbox records self-contained for routing with immutable session and task identifiers.
Change-Id: I3c51601bf5e87ce8a08769247562d82b052dbd5e
- refactor(adk): hide subagent session store
Expose bounded durable progress as an executor-owned semantic operation instead of leaking the underlying child-session store. Keep transcript presentation configurable while preserving storage authority inside the executor.
Change-Id: Ib3a384ec1f17d62e641f95ddf4e9c8cade324475
- refactor(adk): inline subagent progress formatter
Change-Id: I5370fa93c2d8b9130ed92f857389ecd38739cb28
- feat(adk): emit task creation session events
Publish each parent-owned task ID into the active Runner timeline immediately after authoritative task creation. Route the extension event through TypedSendEvent so Runner preserves session single-writer ordering, and surface recoverable send failures without pretending task and session stores share a transaction.
Change-Id: I459503291301f9f34b8fc3c6add1b08d252f4e36
- fix(adk): make task creation events recoverable
Atomically enqueue a task_created notification with every parent-owned task and use a deterministic TaskCreated session event ID. This gives hosts a durable reconciliation source if the creating process exits before Runner persists the immediate timeline event.
Change-Id: I6109fb5832c7dd225c74509b03071fab1d250222
- feat(adk): add attempt-bound subagent session stores
Change-Id: Idaa818b8522eb86959f942248d0638ef5a302649
- feat(adk): support managed tool input interrupts
Prepare managed-tool input synchronously in the parent Runner before allocating or persisting a durable task. This lets tool authors use standard StatefulInterrupt and targeted resume without coupling Runner checkpoints to durable task recovery.
Change-Id: I545df3af22c31026367c9c6b00a73c0edab1e3b9
- feat(adk): return rich managed tool results
Use the enhanced tool interfaces so managed tools can return structured multimodal output while retaining the durable task control envelope as the first text part.
Change-Id: I65c0ee6ffa160f72cf789e01d9719c6684e0111f
- feat(adk): support durable task input resume
Preserve resume commands across recoverable attempt loss so sub-agents and managed tools can replay input safely. Add resumable managed-tool contracts, typed input requests, validation, and multi-round recovery coverage.
Change-Id: I332fff3a0cd6aabdc2385afdd82ea002f8a8f36d
- feat(adk): persist durable subagent sessions
Decouple child session identity from task identity so later durable sub-agent tasks can inherit committed history. Keep task progress scoped, bind reusable sessions to their parent and agent, and yield concurrent session attempts instead of failing them.
Change-Id: I5969958cfdd56319e1b3b984f63f64c636365bab
- docs(adk): update background task API audit
Change-Id: I033f4bac42ca5bf223eeeadcfafb3e99f3443198
- refactor(adk): validate input during managed resume
Remove the separate validation hook so managed tools validate and apply resume input in one operation. A typed rejection error preserves the existing waiting request without turning malformed input into terminal failure.
Change-Id: Iadfb22e90493992461b9f6ff373afcb803abfec7
- fix(adk): harden durable background task contracts
Align lifecycle pagination with its query-bound cursor contract and preserve durable subagent identity across progress and terminal paths. Add adversarial coverage for recovery, replay, stream races, and validation boundaries discovered during comprehensive review.
Change-Id: I18cf6eff3973b55f7689ed54b1adf6d8f5119f2d
- feat(adk): extend durable background task APIs
Expose direct managed-tool submission and attempt-scoped parent notifications so applications can integrate durable tools without constructing private payloads or supplying task authority.
Change-Id: I5f87e923a6807e35cd72e1649d392b20188e4893
- fix(adk): isolate custom notification identities
Make application notification IDs structurally disjoint from lifecycle records and retain adversarial and provider-conformance coverage for the durable notification contract.
Change-Id: Ic58853292c55a7ef0dec3749696b95f753a30108
- chore(adk): remove audit file
Change-Id: I24d275fb5243e499e3339a4accdd25b5a10f7212
- feat(adk): support typed durable subagent input
Durable subagents need the same multimodal input surface as foreground agents while keeping serialization and recovery semantics framework-owned.
Change-Id: I51b4ec778ff65fbc526f1cd3f377e590ddc6df83
- fix(adk): address typed subagent review findings
Keep durable input serialization private to the subagent payload and harden its validation and adversarial coverage.
Change-Id: I3d1adad2981811a93a8f66aee899cd0b1a6603b3
- feat(adk): persist managed tool recovery metadata
Managed tools need an Eino-owned durable handoff from task identity to opaque business run identity across worker recovery and input resume.
Change-Id: I376cf83d802b065dc8f70b51d74ca60f3f8ac73d
- fix(adk): preserve checkpoint store compatibility
Keep running checkpoint persistence behind an optional Store capability and reject unsupported recovery before external side effects.
Change-Id: If4d0287a31afd7e33b8594957dc523c920d3d811
- refactor(adk): unify managed tool checkpoint lifecycle
Make initial and waiting-input recovery state explicit tool checkpoints committed at their natural lifecycle boundaries.
Change-Id: I3d309199c595e17e10ef9e6b552b0e5f61342609
- test(adk): harden managed tool start contract
Make one-shot start commits and plain-tool checkpoint constraints explicit and protect invalid StartResult variants with attack tests.
Change-Id: Ibb1ca7f25c80885652186a5cd9c85aff3cd7b065
- fix(adk): restore go 1.18 ci compatibility
Replace a newer fmt helper and resolve lint regressions so benchmark, lint, and compatibility jobs can compile the durable task changes on the repository's minimum Go version.
Change-Id: I534157c4c7544e9d9f6cc76ba1ce1a3cf764f8a9
- fix(ci): support go 1.18 lint config
Change-Id: I41255aee7eee1d916d520a4cd1d8c8fa560e1f49
- fix(adk): mark resumed sessions running
Interrupted turns transition to idle while awaiting input. Emit a new running lifecycle event after a resume request is restored so lifecycle consumers observe resumed execution without changing the logical turn ID.
Change-Id: Icbb1a573dd64fe6ede0070c7eadb891e0f24fe46
- test(adk): harden resumed session lifecycle coverage
Cover corrupt checkpoint restoration and the generic agentic resume path so future changes cannot emit a false running transition or regress lifecycle ordering across message types.
Change-Id: I32ffb41e0c496801116492d50d1b863a35684cde
- fix(adk): harden background task cancellation and shutdown (#1179)
Co-authored-by: N3ko xuzhaonan@bytedance.com
下载附件