Agently 4.1.3.8 Release Notes

Languages: English · 中文

Agently 4.1.3.8 finalizes the task-execution strategy optimization work on the AgentExecution-backed AgentTask path. The public owner remains AgentExecution; task strategy selection is decided by the AgentExecution / AgentTask policy layer, while TaskBoard stays an execution substrate and ACP stays a capability that can be planned directly or selected by recovery policy.

This release does not introduce a separate public AgentTask lifecycle and does not turn task-shape analysis into a hard router.

Recommended Shape

The default task execution mode is auto. In auto, AgentTask asks the model for natural-language task-shape analysis plus a thin non-binding execution hint, then policy resolves the effective execution shape to flat or taskboard. Explicit user selection wins:

result = (
    agent
    .goal(
        "Prepare a migration risk report.",
        success_criteria=[
            "Cover compatibility, rollout, and rollback risks.",
            "Include evidence for each recommendation.",
        ],
    )
    .effort("medium")
    .strategy("taskboard")
    .output({
        "summary": (str, "short final summary", True),
        "risks": [(str, "one material risk")],
    })
    .get_result()
)

data = result.get_data()
meta = result.get_meta()
effective_shape = meta.get("effective_execution_strategy")

Nested AgentExecution instances inherit the parent strategy context unless a user explicitly overrides the child execution.

Core Changes

Area	What changed	Recommended usage	Compatibility / risk
Execution strategy	execution_strategy defaults to auto; policy resolves flat or taskboard. `.strategy("flat"	"taskboard")` is active again for explicit execution-shape selection.	Leave simple tasks on auto; use .strategy(...) when the host knows the desired shape.
Strategy verification	Flat and TaskBoard both use consumer-driven sufficiency for intermediate work units. In Flat, non-empty remaining_work defaults to the next iteration consuming the facts instead of triggering an immediate verifier; ready_for_final_verification=false can make the same intent explicit, while explicit true hands the result to terminal, blocking, or risk verification. TaskBoard downstream cards decide whether dependency evidence is enough for their objective. Failed terminal verification now exposes compact repair_context to the next Flat work unit and Workspace artifact draft request. A planning-stage liveness stall is recorded as diagnostic-only when the candidate is a trusted file-backed Workspace artifact, independent readback and grounding guards are clear, all criterion checks are satisfied, and the executed actions did not fail. Structural verifier guards also rewrite conflicting completion/progress/replan fields so the next planner is not handed an internally contradictory record.	Treat independent verifier requests as terminal, fan-in/control, trusted-boundary, contradiction, or high-risk review points. Let the next consumer use repair_context as the active correction contract without reintroducing cold provenance into hot prompts.	This removes redundant after-action verifier calls without removing final acceptance, terminal repair feedback, trusted Workspace/source/readback guards, or blocking behavior for real execution/action failures.
TaskBoard path	TaskBoard no longer classifies complexity. It only runs after strategy policy selects it and preserves save/load/resume, handler diagnostics, card evidence contracts, and consumer-driven continuation. Auto may reuse a validated initial board from task-shape analysis, fall back to Flat for small linear boards, and promote a completed terminal candidate directly to verification instead of issuing a redundant final synthesis request. Planning card ids are optional model hints; the framework canonicalizes, deduplicates, or generates stable card ids and remaps dependencies before validation. TaskBoard scheduling defaults to event-driven frontier mode, where completed cards immediately unlock ready successors; historical tick-batch behavior remains available through explicit taskboard_scheduler="batch" for diagnostics and regression comparison.	Treat TaskBoard as a substrate for branched or multi-perspective work after policy selection. Let downstream cards decide whether upstream evidence is enough for their own objective. Use explicit .strategy("taskboard") when the host wants TaskBoard even for small boards. For file-backed deliverables, return Workspace artifact pointers or acceptance anchors instead of copying the file body into final synthesis fields.	TaskBoard is a board/dependency/patch coordinator, not a separate execution carrier. Cost reductions remove redundant model calls only; promoted results still pass ledger guards, Workspace readback evidence, and terminal verification. Ambiguous planning id hints fail closed instead of being guessed.
TaskBoard harness projection	TaskBoard checkpoints now include a bounded acceptance-index projection and handoff projection for long-running resume and inspection. Control/finalization prompts can see compact focus context, and final gates can consume explicit task-scoped dirty or unresolved state facts from Actions, ExecutionResources, or Workspace diagnostics.	Use these projections to understand what remains active, blocked, deferred, or verifier-satisfied without reading raw traces. Preflight requirements must be expressed through mounted capabilities or existing Workspace refs.	The projections are orientation only: they do not enter EvidenceEnvelope.evidence_items, do not create another public lifecycle or strategy, do not run git/browser/shell checks by default, and do not replace terminal verifier judgment.
Effort reflection density	`effort("low"	"medium"	"high")` now maps to reflection density. Low keeps final reflection plus planner-marked important points; medium reflects at major nodes or card/tick boundaries; high reflects at each framework-observable action, ACP call, card, bounded step, and final point.
Workspace artifact readback	AgentTask-delivered artifacts are accepted only after trusted Workspace readback records path, bytes, sha256, bounded preview, and file_refs in cold evidence; artifact delivery then records workspace_artifact.acceptance_locator evidence from the actual Workspace file using headings, byte offsets, line ranges, fingerprints, artifact manifests, TaskBoard card criteria, and model-returned acceptance-point intent. Model-hot verifier input sees path/ref handles, bounded content or preview, truncation status, locator views, and bounded targeted_readbacks for long artifacts when locator or fallback anchors need scoped inspection. Integrity metadata stays programmatically traceable. capability_evidence.artifacts.readback uses path handles, not path#sha ids.	Use artifact_markdown or artifact_manifest.sections for deliverables and let Workspace produce the evidence chain. If a complete Markdown body is returned inside structured evidence, it is materialized only when explicitly labeled as artifact/body/deliverable/Markdown or tied to the manifest path; ordinary source content/snippets remain evidence. Structured outputs may include optional acceptance_points with expected headings or anchors, but line and offset facts are determined by Workspace readback, not trusted from the model.	Write-success/readback-failure cases report agent_task.workspace_artifact.readback_failed or agent_task.workspace_artifact.readback_insufficient, not generic budget or iteration failure. Successful write/readback hands stale artifact-write remaining_work to terminal verification instead of forcing a write-only replan. Locator evidence only tells the verifier where to read; semantic acceptance remains verifier-owned.
TaskBoard cold readback	TaskBoard readback cards can inspect Action artifact refs and trusted Workspace file/content refs through bounded cold readbacks. Framework-generated readback cards scope evidence to direct dependencies plus upstream evidence cards, and continuation cards no longer recursively synthesize another readback chain for the same unresolved evidence gap. Structured target_refs are split by kind: external HTTP/HTTPS refs become Action evidence work, while Workspace/content paths and retained-note refs become direct bounded Workspace readback cards.	Use readback cards for scoped cold evidence inspection; if the evidence is still insufficient, propose different executable work instead of another identical readback.	This preserves no-default-hard-cap behavior while preventing readback-only loops and avoiding model-owned rewrites of Workspace readback facts.
Scoped Workspace retrieval	Flat and TaskBoard work units can carry scoped_retrieval.query_groups; the shared BlockCarrier lowers those groups to pre-step Blocks workspace_operation.search facts. The operation name remains compatible, but execution now uses the Workspace-owned workspace.retrieve(...) strategy for record/file candidates, optional vector/hybrid mode, structure-gated rerank, refill, and budget packaging before injecting a body-light model-hot evidence_ledger index plus compatibility scoped_retrieval_results into the bounded agent_step or card. Query groups can choose workspace_index, workspace_files, or workspace_index_and_files; record collections belong in filters.collection, exact record kinds may use filters.kind, file scopes use top-level path/pattern without applying that file path as a record filter, and explicit retrieval tuning may pass tags, method, rerank, selection, top_n, or max_candidates. Broad-pool rerank sees a bounded candidate-summary window before final selected-snippet packaging, so dropped candidates do not starve later relevant records or file snippets. Selected structured record payloads are projected into compact model-hot text with projection and original_ref metadata while the raw Workspace record remains the source of truth for readback. EvidenceEnvelope.evidence_items records retrieval/search success, empty result, failure, locator, snippet, and readback facts with stable ids, status, and body_state; evidence_snippet facts expose whether bounded context was truncated.	Retrieve scoped Workspace/file evidence before broad reads when that reduces prompt input, then let the downstream model judge whether snippets are useful or more readback is needed. Bind factual output through evidence_use ids when structured output is available. TaskBoard blocked/insufficient scoped-retrieval cards without an explicit next action synthesize an expanded evidence card and continuation card instead of relying on a terminal verifier to repair intermediate evidence.	Retrieval hits are not local semantic acceptance, quality gates, or completion evidence. Failed/empty evidence supports unavailable/missing-data claims only; ref_only supports only discovery until readback exists. Flat and TaskBoard retrieval keep the hot/cold evidence split; full effect claims still require real-run evidence.
Coding Workspace actions and safe shell	agent.enable_coding_agent_actions(...) exposes Workspace-owned read_file, glob_files, grep_files, edit_file, apply_patch, and stale-guarded write_file actions for coding-agent style local work. agent.enable_shell(...) now defaults to a small safe command profile when commands is omitted, includes explicit model-visible guidance to prefer Workspace file actions for file IO, and returns bounded stdout/stderr previews while persisting oversized streams under artifacts/shell/.	Use Workspace file actions for reading, searching, editing, patching, and full-file writes; use shell for tests, builds, git status/diff/log inspection, and read-only diagnostics. Use expected_sha256 or prior read state for guarded writes and expected_files for patch intent checks.	Shell output truncation is not destructive; full oversized streams remain file artifacts. Non-allowlisted commands and missing Workspace boundaries fail closed with structured diagnostics. apply_patch(...) applies unified diffs and remains inside the Workspace file root.
EvidenceEnvelope grounding ledger	EvidenceEnvelope.evidence_items is now the canonical internal grounding ledger for Flat synthesis, TaskBoard card/final synthesis, verifier prompts, deterministic host guards, and artifact acceptance locators. Legacy evidence buckets, scoped_retrieval_results, TaskBoard source_refs, and verifier locator views are compatibility projections from the ledger, not separate authorities. Model-hot ledger views include short cite_as handles, and deterministic guard reconciliation canonicalizes cite_as, producer-declared structural aliases, path, unique basename, record id, URL, artifact id, action id, action call id, and provenance aliases back to ledger ids. Verifier requests no longer perform private Workspace artifact readback inside _request_verification; readback must appear as an evidence item before synthesis and verification can both see it.	Use evidence_use claim bindings in structured outputs when a result depends on specific source facts, unavailable data, or ref pointers. Prefer visible cite_as or canonical ids; path/URL/action-ref aliases are producer-owned compatibility affordances, not guard-maintained business action names. Do not treat failed/empty items as positive support, do not claim file/repository/source content from ref_only, and request readback before full-source claims. Treat workspace_artifact.acceptance_locator as a readback pointer for an acceptance point, not as content proof by itself.	Deterministic guards reject ambiguous aliases, unresolved ids, and structurally impossible support before model verification. Semantic grounding remains verifier-owned; the host guard does not parse or rewrite prose claims. Binding-only repair is targeted to evidence_use, not whole-result regeneration, and unresolved bindings block with exact diagnostics.
ACP capability	ACP is an Action plus ExecutionResource(kind="acp"). It can be selected directly by planner/user intent or by recovery after retry exhaustion.	Call .use_acp(...) only when ACP should be available; otherwise no ACP dependency is loaded. acp_list_agents includes common adapter-name hints such as codex, claude code / cc, openclaw, hermes / hermes agent, and gemini.	ACP does not bypass AgentExecution or AgentTask policy, and adapter hints are not runnable-agent evidence.
Optional dependency loading	MCP and ACP use utils.LazyImport and do not load optional packages unless .use_mcp(...) or .use_acp(...) is explicitly used.	Keep ordinary agents dependency-light; enable optional runtimes at the capability boundary.	Missing optional dependencies fail through LazyImport diagnostics only when the optional path is used.
Skills termination diagnostics	Direct Skills execution emits skills.execution.aborted when cooperative host cancellation or framework execution failure reaches the Skills runtime. Built-in react and staged strategies emit skills.execution.budget_exhausted when step-budget policy stops or truncates work.	Consume direct Skills stream_handler items when a host UI, DevTools bridge, or service runner needs to explain why a Skills run stopped.	These events are diagnostics only. Wall-clock and no-progress limits remain host policy unless cancellation propagates into Skills execution.
Strong-format process output	Intermediate strong-format model requests use Agently .output(..., format=...) with the appropriate parser. If a declared non-JSON parser fails, the framework can fall back to JSON and accepts it only when the parsed value is dict-shaped with diagnostics. Selected internal AgentTask process requests may include short pre/post fields such as intent, decision_basis, self_check, short_summary, verification_summary, criterion_checks, repair_summary, and progress_message only when a downstream consumer exists.	Use .output(...) for process contracts, not keyword or local scorecard parsing. Keep process fields short and bounded; they are stored as process_summary, not as EvidenceEnvelope evidence or completion proof.	Fallback is a parse recovery path, not a semantic shortcut. No public runtime mode or Agent.output() API is added.
Delta text stream	get_async_generator(type="delta") remains the public text-increment stream. Complex AgentTask / AgentExecution runs project template progress, structured progress_message, action observations, snapshots, heartbeat status, phase status, retry markers, and terminal task result into paragraph text while instant keeps the structured payloads. Non-progress process fields remain in instant/records and are not projected as public text delta.	Use delta for user-facing streaming text and instant/structured execution items for UI state, diagnostics, or DevTools-style replay. Durable artifact writers should consume structured $status when available; if they intentionally consume plain text, they must treat <$retry>...</$retry> as a replay boundary at the consumption side instead of forcing freeform bodies through .output() just to obtain instant fields.	Existing text increments still stream as strings; process-event projection is additive and action/progress paragraphs are observation text, not completion or verification proof unless backed by action/readback/verifier facts.
Observation compatibility	AgentExecution projects flat and TaskBoard process stream items to agent_execution.stream RuntimeEvents; task/TaskBoard/ACP/reflection payloads stay generic and fail-open. agent_task.action.*, model.status, and model_request_telemetry remain observation-only; terminal model.status can carry estimated input/output character lengths without exposing raw request payloads.	Use agently-devtools >=0.1.10,<0.2.0; DevTools displays AgentTask action observations and model-request usage per request plus selected-branch descendant aggregates, with unavailable provider token counts shown as NaN and estimated input/output lengths as diagnostics.	DevTools can ingest, store, query, and replay AgentExecution, flat, TaskBoard, action, and usage observation facts without owning task strategy, budget, retry, quality, or completion semantics.
Public typing	The package now ships agently/py.typed and adds typing to common public facade methods.	IDEs, including Pylance and pyright-compatible tooling, can inspect installed Agently types directly. Release review must check both source typing and installed-package metadata.	Remaining broad internal surfaces stay documented compatibility escape hatches.

Compatibility

• Package version: 4.1.3.8.
• Release manifest: compatibility/releases/4.1.3.8.json.
• Recommended agently-devtools: >=0.1.10,<0.2.0.
• Development-line planning remains in compatibility/in-development.json until the next release line moves on.

Deferred Scope

4.1.3.8 does not complete multi-task scheduling, background autonomous scheduling, production distributed task recovery, production Redis/Postgres or object-storage Workspace providers, or TriggerFlow-backed AdaptiveLoop / BootstrapLoop packaging for AgentTask.