Skip to content

docs(website): align guides with current ARGI APIs and document merged capabilities #372

Open

Description

@yuluo-yx

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

  1. added
    documentationImprovements or additions to documentation
    help wantedExtra attention is needed
    area/docs文档:项目文档、教程与使用指南
    on Nov 15, 2026
  2. logicwu0 commented on Nov 17, 2026

    @logicwu0
    Contributor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/docs文档:项目文档、教程与使用指南documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions