Repository navigation
Description
Repository scope
This issue is tracked in ARGI because Issues are disabled in argi-website. Implementation belongs in argi-website; submit documentation PRs there and link them back to this issue. No Core runtime changes are requested.
Problem
The website does not yet describe several merged ARGI capabilities, and parts of the onboarding guidance still target pre-migration packages and artifacts. Users following the current documentation can select obsolete dependencies, copy incompatible imports, or miss important failure and cancellation semantics.
Audit baseline and evidence
Audited on 2026-11-15:
- Website main: 7974c3b4, last updated on 2026-10-19.
- Core main: ef67b8e08.
- Some guides explicitly pin Core commit 5ec935b (2026-10-18). Preserve that historical context or clearly replace it; do not silently present the old baseline as current.
- docs/versions.md still names argi-graph-core; the current artifact is argi-workflow-graph-core.
- 52 of the 66 Markdown files under docs/ and i18n/ contain the old io.github.agentic.ai.graph.* namespace.
- docs/frameworks/agent-framework/workflow.md still describes the whole framework as Spring AI based, without the independent Agent/Workflow and optional-adapter boundaries.
- docs/frameworks/agent-framework/runtime-contracts.md excludes AgentResult delivery and tool-context patch validation from its pinned baseline, but provides no current replacement guide.
- scripts/verify-argi-contract.mjs passes while explicitly requiring the obsolete ReactAgent and StateGraph package names. Its success is not evidence of source compatibility.
Work items
1. Repair onboarding and compatibility guidance
- Select and record a current Core source baseline and its compatible Extensions baseline; distinguish source availability from Maven Central publication.
- Update Maven coordinates, module ownership, Java imports, homepage examples and quick starts. Explain independent ReActAgent, WorkflowAgent and graph-based ReactAgent entry points.
- Document Core versus Extensions persistence ownership and the required BOMs/dependencies.
- Provide migration guidance for changed artifacts/packages/APIs. Preserve explicitly versioned historical guides where useful.
- Correct scheduling ownership/shutdown documentation, including registration rejection after shutdown.
2. Document merged user-facing capabilities
Each guide needs a minimal usable example, required dependencies, activation/defaults, result and failure behavior, limitations, and a source/version reference.
| Capability | Core references | Required coverage |
|---|---|---|
| Independent Workflow | #359, #360 | Definition/build/run, input/output schema boundaries, validation errors, suspend/resume, subflow cycles and depth limits |
| Structured result delivery and repair usage | #366 | callResult/streamResult, AgentResult statuses, repairUsage, unknown totals and failed repair |
| Streaming message identity | #358 | Shared per-turn IDs for deltas/snapshots and consumer replacement behavior |
| Model retries | #356 | RetryPolicy, failure categories, total attempt count, deadline reserve and cancellation |
| Streaming fallback | #368 | First-event switch boundary, cancellation, and ordering with retry |
| Context window budgets | #352 | System/history/tool-schema/output-reserve accounting and budget failure |
| Strict tool state | #265, #334 | strictToolState, nested isolation, patch admission and deterministic merges |
| Lifecycle extension contracts | #351 | Stages, identities and extension types; distinguish contracts from engine wiring |
| Model-turn recording | #337 | Recording/recovery boundaries, missing-response policy and storage responsibilities |
| Persisted run-state gauges | #361 | Stock versus counters, freshness/stale behavior and multi-replica aggregation |
| Scheduling registration lifecycle | #340, #369 | Owning manager, stop/unregister behavior and registration/shutdown exclusion |
3. Make documentation checks detect API drift
- Replace stale literal checks with checks against the declared source baseline.
- Compile representative onboarding and feature examples against the selected artifacts/source revision.
- Run deterministic offline examples for the documented success and failure paths.
- Validate navigation, links, supported locale builds and existing site lint/type checks.
- Keep an explicit checklist mapping each capability above to its guide, example and validation evidence.
Acceptance criteria
- Current onboarding no longer recommends obsolete coordinates or imports; historical examples are clearly versioned.
- Every capability above has linked documentation and a verified example, or an explicit, justified boundary explaining why only a contract is available.
- Existing Chinese and English counterparts remain semantically consistent; untranslated coverage is identified rather than implied.
- Validation results identify exact revisions, commands, outcomes and any unverified real-provider scenarios.
- Do not document unmerged proposals as available functionality. Recheck PR status before writing.
- No runtime implementation changes, provider credentials or fabricated live-service validation are required.
Claiming and delivery
Open for contributors. Please comment with the phase/capability you want to own and the planned scope before starting, so maintainers can coordinate assignments. Small, linked PRs are welcome; use this issue to track the remaining work. Please do not claim a capability is complete until its documentation and example validation are both included.
Activity
logicwu0 commentedon Nov 17, 2026
I would like to take the streaming message identity documentation item (#358). Scope: a focused Chinese/English guide for the independent ReAct streaming API, explaining per-turn delta/snapshot identity, snapshot replacement, and invocation-local ID boundaries; a deterministic offline example compiled against a pinned current Core revision; navigation and validation notes. No Core runtime changes. I will verify the actual APIs and merged behavior before documenting them, and distinguish source availability from published artifacts. Other capabilities and the broader onboarding migration remain outside this contribution.