diff --git a/docs/frameworks/agent-framework/stream-message-identity.md b/docs/frameworks/agent-framework/stream-message-identity.md new file mode 100644 index 00000000..ec58086e --- /dev/null +++ b/docs/frameworks/agent-framework/stream-message-identity.md @@ -0,0 +1,100 @@ +--- +title: 流式消息 ID 与消息视图 +description: 独立 ReActAgent 的增量追加、快照替换和调用内消息标识。 +--- + +# 流式消息 ID 与消息视图 + +## 基线与依赖 + +本文针对独立的 `io.github.agentic.ai.agent.react.ReActAgent`,不是 graph-based +`ReactAgent` 或 Graph 流式 API。基线为 Core +[ef67b8e08](https://github.com/agentic-ai-java/argi/tree/ef67b8e083746899da43c0a056b76b71db9e92ab), +2026-11-17 核对,包含已合并的 [#358](https://github.com/agentic-ai-java/argi/pull/358)。 +源码版本为 `2.1.0-RC2-SNAPSHOT`,不代表该提交已发布到 Maven Central; +相同 SNAPSHOT 字符串也不保证相同源码。本页不替换固定旧基线的 +[runtime contracts](./runtime-contracts.md)。 + +示例依赖 `io.github.agentic-ai-java:argi-agent-core:2.1.0-RC2-SNAPSHOT`, +传递引入中立 ChatClient、Agent 和 Runtime 契约。无需 Spring Boot、Graph、 +Extensions BOM、模型适配器或 API key。先从固定提交构建安装依赖。 + +显式使用 `ReActAgent.builder(client).streamModel(true).build()` 开启模型流式调用, +再通过 `agent.stream(request, context)` 订阅 `Flow.Publisher`。 +本文只覆盖显式启用路径,不把普通 `call` 当作流式调用。 + +## 消费规则 + +| 事件 | 消费动作 | +| --- | --- | +| `AgentEvent.MessageDelta` | 按 `messageId()` 追加 `text()`。 | +| `AgentEvent.Message` | 按同一 ID 替换为 `message().text()`,不能再次追加。 | +| `AgentEvent.Finished` | 保存 `outcome()`;消息快照不是整个运行成功的证明。 | +| `onError` | 标记运行失败;没有快照的增量仍是未完成文本。 | + +例如增量 `He`、`llo` 后收到完整快照 `Hello`,最终显示 `Hello`,不是 `HelloHello`。 +结构化修复还可能用同一 ID 替换终态消息,所以不能永久忽略同 ID 的后续快照。 + +```java +if (event instanceof AgentEvent.MessageDelta delta) { + text.merge(delta.messageId(), delta.text(), String::concat); +} else if (event instanceof AgentEvent.Message message) { + text.put(message.messageId(), message.message().text()); +} +``` + +这只是文本展示投影。需要角色、工具调用或其他内容时,请保存完整 `ChatMessage`。 + +## ID 边界与失败行为 + +- 当前基线使用 `model-0`、`model-1` 等模型轮次 ID,工具结果使用 `tool-`。 + 应使用事件返回的 ID,不要解析或自行构造这些格式。 +- 同一轮增量与快照共享 ID,不同轮次和工具结果分别存储。 +- ID 只在单次调用内有效。第二次调用也可以从 `model-0` 开始。 + 每次调用新建视图;汇总多次调用时,用应用层调用标识与消息 ID 组成联合键, + 不能只按会话 ID 或消息 ID 汇总。 +- 没有文本增量的工具轮也可能有快照;不能要求快照前一定有 delta。 +- 模型轮次要求恰好一条 assistant 消息,多消息响应会被拒绝。 +- 失败或取消可能留下增量而没有快照,应显示为未完成,不能当作已交付答案。 + 取消订阅不保证还会收到终止回调,应用也要维护自己的取消状态。 +- 本契约不保证跨进程恢复、重放去重、全局唯一性或提供商 ID 原样透传。 + +## 运行离线示例 + +网站仓库的 `examples/stream-message-identity/` 包含完整假 `ChatClient` 和消息视图, +通过真实 ReAct 引擎产生事件。要求 JDK 17+、Maven 3.9.1+。 +在 Core 仓库检出固定提交后执行: + +```bash +git checkout ef67b8e083746899da43c0a056b76b71db9e92ab +./mvnw -B -pl :argi-agent-core -am install -DskipTests +``` + +在网站仓库根目录执行: + +```bash +mvn -B -f examples/stream-message-identity/pom.xml compile exec:java +``` + +依赖下载需要网络,示例执行无需网络或凭据。成功时输出: + +```text +PASS: turn identity, snapshot replacement, invocation isolation, failure projection +``` + +断言失败会使命令失败,不依赖 `-ea`。 + +## 验证映射与限制 + +| 内容 | 离线示例中的验证 | +| --- | --- | +| 增量和快照不重复显示 | 拆分文本并替换快照,断言最终值。 | +| 多轮与工具隔离 | 两轮模型调用加本地工具,检查三个消息。 | +| 调用间隔离 | 同一个 agent 运行两次,新建独立视图,允许重复的 `model-0`。 | +| 失败的部分文本 | delta 后失败,检查部分文本保留且没有快照。 | +| 取消、修复、无文本工具轮 | 本示例未重复测试,契约依据下方固定提交的上游测试。 | + +依据:[ReActAgent 源码](https://github.com/agentic-ai-java/argi/blob/ef67b8e083746899da43c0a056b76b71db9e92ab/argi-agent/argi-agent-core/src/main/java/io/github/agentic/ai/agent/react/ReActAgent.java) +和[消息 ID 回归测试](https://github.com/agentic-ai-java/argi/blob/ef67b8e083746899da43c0a056b76b71db9e92ab/argi-agent/argi-agent-core/src/test/java/io/github/agentic/ai/agent/react/ReActAgentStreamMessageIdTest.java)。 +离线通过不代表真实提供商、浏览器 UI 或网络取消已验证。 +本页及英文对应页只覆盖 [#372](https://github.com/agentic-ai-java/argi/issues/372) 的消息标识项。 diff --git a/examples/stream-message-identity/.gitignore b/examples/stream-message-identity/.gitignore new file mode 100644 index 00000000..b83d2226 --- /dev/null +++ b/examples/stream-message-identity/.gitignore @@ -0,0 +1 @@ +/target/ diff --git a/examples/stream-message-identity/README.md b/examples/stream-message-identity/README.md new file mode 100644 index 00000000..4d8053f4 --- /dev/null +++ b/examples/stream-message-identity/README.md @@ -0,0 +1,56 @@ +# Streaming message identity example + +Scope: only the streaming-message-identity item in +[ARGI #372](https://github.com/agentic-ai-java/argi/issues/372). +See the Chinese and English `stream-message-identity` website guides for the +consumer contract. This fixture is intentionally not a reusable provider adapter. + +## Reproduce + +Use JDK 17+ and Maven 3.9.1+. Build Core commit +`ef67b8e083746899da43c0a056b76b71db9e92ab` first, not an arbitrary artifact with +the same `2.1.0-RC2-SNAPSHOT` version: + +```bash +./mvnw -B -pl :argi-agent-core -am install -DskipTests +``` + +Then, from the website repository: + +```bash +mvn -B -f examples/stream-message-identity/pom.xml compile exec:java +``` + +After dependencies/plugins are cached, the same command works with `-o`. +The fixture's subscribers request unbounded demand; it is not a general-purpose +backpressure test. No credentials, provider adapters or Extensions artifacts are used. + +## Validation record + +Checked 2026-11-17 on macOS arm64 using JDK 21, Java release target 17 and Maven +3.10.1. JDK 17 runtime execution was not tested. +Website base: `7974c3b40392722557a4404210cfb6cb4a975a16`. +Core base: `ef67b8e083746899da43c0a056b76b71db9e92ab`. + +- Core dependency installation passed using + `./mvnw -B -pl :argi-agent-core -am install -DskipTests -Dcheckstyle.skip -Dspring-javaformat.skip`. +- The following separate Core check passed, without those skip flags: + + ```bash + ./mvnw -B -pl :argi-agent-core -am test \ + -Dtest=ReActAgentStreamMessageIdTest -Dsurefire.failIfNoSpecifiedTests=false + ``` + + Result: 11 tests, zero failures/errors/skips. This is a targeted test run, not + a full Core test-suite claim. +- The example's `compile exec:java` passed, then passed again with Maven `-o`. + Assertions cover multi-turn/tool isolation, delta/snapshot replacement, + fresh views across invocations, and partial text on stream failure. +- Website `npm run typecheck`, `npm run lint`, `npm run verify:contract` and + `npm run build` passed. The build includes both `zh-Hans` and `en`, with + broken Markdown links treated as errors, followed by search indexing. + The pre-existing contract checker still contains old API literal checks; + its pass is not used as proof of Java compatibility. The compiled example is. + +No live-provider, browser-UI or network-cancellation validation is claimed. +Other #372 capabilities and the site-wide onboarding migration remain out of scope. diff --git a/examples/stream-message-identity/pom.xml b/examples/stream-message-identity/pom.xml new file mode 100644 index 00000000..b445dd90 --- /dev/null +++ b/examples/stream-message-identity/pom.xml @@ -0,0 +1,24 @@ + + 4.0.0 + io.github.agentic-ai-java.examples + stream-message-identity + 1.0-SNAPSHOT + + 17 + UTF-8 + + + + + io.github.agentic-ai-java + argi-agent-core + 2.1.0-RC2-SNAPSHOT + + + + org.apache.maven.pluginsmaven-compiler-plugin3.14.1 + org.codehaus.mojoexec-maven-plugin3.6.3 + example.StreamMessageIdentity + + + diff --git a/examples/stream-message-identity/src/main/java/example/StreamMessageIdentity.java b/examples/stream-message-identity/src/main/java/example/StreamMessageIdentity.java new file mode 100644 index 00000000..f303c785 --- /dev/null +++ b/examples/stream-message-identity/src/main/java/example/StreamMessageIdentity.java @@ -0,0 +1,145 @@ +/* + * Copyright 2026 the original author or authors. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy at https://www.apache.org/licenses/LICENSE-2.0 + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package example; + +import io.github.agentic.ai.agent.*; +import io.github.agentic.ai.agent.react.ReActAgent; +import io.github.agentic.ai.api.chat.*; +import io.github.agentic.ai.api.tool.*; +import io.github.agentic.ai.runtime.execution.*; +import java.time.Clock; +import java.util.*; +import java.util.concurrent.*; + +/** Offline executable example: no provider adapter, network, or credentials. */ +public final class StreamMessageIdentity { + // Each instance belongs to ONE invocation. Never share it across runs. + static final class MessageView implements Flow.Subscriber { + final Map text = new LinkedHashMap<>(); + final Set snapshots = new HashSet<>(); + final CompletableFuture completed = new CompletableFuture<>(); + AgentOutcome outcome; + public void onSubscribe(Flow.Subscription s) { s.request(Long.MAX_VALUE); } + public void onNext(AgentEvent event) { + if (event instanceof AgentEvent.MessageDelta delta) { + text.merge(delta.messageId(), delta.text(), String::concat); + } else if (event instanceof AgentEvent.Message message) { + // A snapshot is the complete value, NOT another delta. + // A later repair can replace this same key again. + text.put(message.messageId(), message.message().text()); + snapshots.add(message.messageId()); + } else if (event instanceof AgentEvent.Finished done) { + outcome = done.outcome(); + } + } + public void onError(Throwable error) { completed.completeExceptionally(error); } + public void onComplete() { completed.complete(null); } + } + + record Turn(List events, RuntimeException failure) {} + static ChatResponse response(String text, List calls) { + return new ChatResponse(null, "offline", List.of(ChatMessage.assistant(text, calls)), + calls, FinishReason.STOP, new Usage(1L, 1L, 2L), Map.of()); + } + static Turn turn(String text, List calls) { + return new Turn(List.of(ChatEvent.textDelta(text.substring(0, 1)), + ChatEvent.textDelta(text.substring(1)), ChatEvent.response(response(text, calls))), null); + } + static ChatClient client(List turns) { + Queue queue = new ArrayDeque<>(turns); + return new ChatClient() { + public CompletionStage call(ChatRequest request) { + return CompletableFuture.failedFuture(new UnsupportedOperationException("stream only")); + } + public ChatClientCapabilities capabilities() { return ChatClientCapabilities.basic(); } + public Flow.Publisher stream(ChatRequest request) { + return subscriber -> { + final Turn script; + synchronized (queue) { script = queue.remove(); } + subscriber.onSubscribe(new Flow.Subscription() { + boolean sent; + volatile boolean cancelled; + public void request(long n) { + if (sent || cancelled) return; + sent = true; + if (n <= 0) { subscriber.onError(new IllegalArgumentException("positive demand required")); return; } + // Fixture subscriber requests unbounded demand. + for (ChatEvent event : script.events()) { + if (cancelled) return; + subscriber.onNext(event); + } + if (cancelled) return; + if (script.failure() == null) subscriber.onComplete(); + else subscriber.onError(script.failure()); + } + public void cancel() { cancelled = true; } + }); + }; + } + }; + } + static AgentExecutionContext context(String runId) { + var trusted = TrustedExecutionContext.builder() + .tenant(new TenantReference("example", "tenant")) + .principal(new PrincipalReference("example", "user")) + .runId(runId).correlationId(runId) + .budget(ExecutionBudget.unlimited()).delegationScope(DelegationScope.none()).build(); + return new AgentExecutionContext(trusted, Clock.systemUTC()); + } + static MessageView run(ReActAgent agent, String runId, boolean expectFailure) throws Exception { + MessageView view = new MessageView(); + try (var context = context(runId)) { + agent.stream(AgentRequest.messages(List.of(ChatMessage.user("hello"))), context).subscribe(view); + try { + view.completed.get(5, TimeUnit.SECONDS); + check(!expectFailure, "expected a failed stream"); + check(view.outcome != null, "missing Finished outcome"); + } catch (ExecutionException error) { + if (!expectFailure) throw error; + check("fixture failure".equals(error.getCause().getMessage()), "unexpected failure"); + } + } + return view; + } + static void check(boolean condition, String message) { + if (!condition) throw new AssertionError(message); + } + public static void main(String[] args) throws Exception { + ToolCall call = new ToolCall("lookup-1", "lookup", "{}"); + Tool tool = new Tool() { + public ToolDefinition definition() { return new ToolDefinition("lookup", "offline lookup", "{}"); } + public CompletionStage execute(ToolCall call, ToolContext context) { + return CompletableFuture.completedFuture(ToolResult.text("found")); + } + }; + ReActAgent multi = ReActAgent.builder(client(List.of(turn("Look", List.of(call)), turn("Done", List.of())))) + .streamModel(true).tools(new ToolRegistry(List.of(tool))).build(); + MessageView view = run(multi, "multi", false); + check(view.text.equals(Map.of("model-0", "Look", "tool-lookup-1", "found", "model-1", "Done")), + "deltas/snapshots duplicated text or mixed turns: " + view.text); + check(view.snapshots.containsAll(view.text.keySet()), "unsealed successful turn"); + + ReActAgent repeated = ReActAgent.builder(client(List.of(turn("First", List.of()), turn("Second", List.of())))) + .streamModel(true).build(); + MessageView first = run(repeated, "first", false); + MessageView second = run(repeated, "second", false); + check(first.text.equals(Map.of("model-0", "First")), "first run changed"); + check(second.text.equals(Map.of("model-0", "Second")), "cross-run text leaked"); + + ReActAgent failing = ReActAgent.builder(client(List.of(new Turn(List.of(ChatEvent.textDelta("partial")), + new IllegalStateException("fixture failure"))))).streamModel(true).build(); + MessageView failed = run(failing, "failed", true); + check(failed.text.equals(Map.of("model-0", "partial")), "partial text lost"); + check(failed.snapshots.isEmpty(), "failed turn incorrectly sealed"); + System.out.println("PASS: turn identity, snapshot replacement, invocation isolation, failure projection"); + } +} diff --git a/i18n/en/docusaurus-plugin-content-docs/current/frameworks/agent-framework/stream-message-identity.md b/i18n/en/docusaurus-plugin-content-docs/current/frameworks/agent-framework/stream-message-identity.md new file mode 100644 index 00000000..5fb0760d --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/frameworks/agent-framework/stream-message-identity.md @@ -0,0 +1,109 @@ +--- +title: Streaming message identity and views +description: Append deltas, replace snapshots, and scope independent ReAct message IDs to one invocation. +--- + +# Streaming message identity and views + +## Baseline and dependencies + +This guide covers the independent `io.github.agentic.ai.agent.react.ReActAgent`, +not graph-based `ReactAgent` or Graph streaming. It targets Core +[ef67b8e08](https://github.com/agentic-ai-java/argi/tree/ef67b8e083746899da43c0a056b76b71db9e92ab), +checked on 2026-11-17, including merged [#358](https://github.com/agentic-ai-java/argi/pull/358). +Its source version is `2.1.0-RC2-SNAPSHOT`; this does not imply publication to +Maven Central, and the same SNAPSHOT string does not identify the source. +This page does not replace the historically pinned +[runtime contracts](https://github.com/agentic-ai-java/argi-website/blob/7974c3b40392722557a4404210cfb6cb4a975a16/docs/frameworks/agent-framework/runtime-contracts.md). + +The example depends on `io.github.agentic-ai-java:argi-agent-core:2.1.0-RC2-SNAPSHOT`, +bringing neutral ChatClient, Agent and Runtime contracts transitively. No Spring +Boot, Graph, Extensions BOM, provider adapter or API key is needed. Install the +pinned source first. + +Explicitly enable model streaming with `ReActAgent.builder(client).streamModel(true).build()`; +subscribe to the `Flow.Publisher` from `agent.stream(request, context)`. +This guide covers that explicitly enabled path, not ordinary `call`. + +## Consumer rules + +| Event | Action | +| --- | --- | +| `AgentEvent.MessageDelta` | Append `text()` under `messageId()`. | +| `AgentEvent.Message` | Replace that key with `message().text()`; do not append again. | +| `AgentEvent.Finished` | Retain `outcome()`; a snapshot does not prove the whole run succeeded. | +| `onError` | Mark the run failed; deltas without a snapshot remain incomplete. | + +Deltas `He`, `llo` followed by snapshot `Hello` must display `Hello`, not +`HelloHello`. Structured repair can replace the terminal message under the same +ID again; do not permanently ignore subsequent snapshots with that ID. + +```java +if (event instanceof AgentEvent.MessageDelta delta) { + text.merge(delta.messageId(), delta.text(), String::concat); +} else if (event instanceof AgentEvent.Message message) { + text.put(message.messageId(), message.message().text()); +} +``` + +This is a text projection only. Retain the full `ChatMessage` when roles, tool +calls or other content matter. + +## Identity boundaries and failures + +- This baseline uses `model-0`, `model-1`, etc. for model turns and `tool-` + for tool results. Use event-supplied IDs; do not parse or manufacture these formats. +- One turn's deltas and snapshot share an ID. Keep turns and tool results separate. +- IDs are invocation-local. A second invocation can start at `model-0` again. + Create a fresh view per invocation; aggregate with an application-owned invocation + identifier plus message ID, not session ID alone or message ID alone. +- A textless tool turn can still have a snapshot; a preceding delta is not required. +- Each model turn requires exactly one assistant message; multi-message responses + are rejected. +- Failure or cancellation may leave deltas without a snapshot. Display them as + incomplete, not delivered answers. Subscription cancellation does not guarantee + a terminal callback; track cancellation in the application too. +- This is not a cross-process recovery, replay-deduplication, global-uniqueness + or provider-ID pass-through guarantee. + +## Run the offline example + +The website repository's `examples/stream-message-identity/` contains a complete +fake `ChatClient` and message view, with events generated by the real ReAct engine. +Requirements: JDK 17+ and Maven 3.9.1+. In a Core checkout: + +```bash +git checkout ef67b8e083746899da43c0a056b76b71db9e92ab +./mvnw -B -pl :argi-agent-core -am install -DskipTests +``` + +From the website repository root: + +```bash +mvn -B -f examples/stream-message-identity/pom.xml compile exec:java +``` + +Dependency downloads need network access; execution needs neither network nor +credentials. Success prints: + +```text +PASS: turn identity, snapshot replacement, invocation isolation, failure projection +``` + +Failed assertions fail the command without relying on `-ea`. + +## Validation mapping and limitations + +| Coverage | Offline example check | +| --- | --- | +| No duplicate delta/snapshot text | Split text, replace snapshot, assert final value. | +| Turn/tool isolation | Two model turns and one local tool produce three messages. | +| Invocation isolation | Reuse one agent with two fresh views, allowing `model-0` in both. | +| Partial text on failure | Fail after a delta; retain partial text without a snapshot. | +| Cancellation, repair, textless tool turns | Not repeated here; grounded in pinned upstream tests below. | + +References: [ReActAgent source](https://github.com/agentic-ai-java/argi/blob/ef67b8e083746899da43c0a056b76b71db9e92ab/argi-agent/argi-agent-core/src/main/java/io/github/agentic/ai/agent/react/ReActAgent.java) +and [message-ID regression tests](https://github.com/agentic-ai-java/argi/blob/ef67b8e083746899da43c0a056b76b71db9e92ab/argi-agent/argi-agent-core/src/test/java/io/github/agentic/ai/agent/react/ReActAgentStreamMessageIdTest.java). +Offline success does not validate live providers, browser UI or network cancellation. +This guide and its Chinese counterpart cover only the message-identity item of +[#372](https://github.com/agentic-ai-java/argi/issues/372). diff --git a/sidebars.ts b/sidebars.ts index cdaa7b66..04e99333 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -101,6 +101,7 @@ const sidebars: SidebarsConfig = { collapsed: false, items: [ 'frameworks/agent-framework/messages', + 'frameworks/agent-framework/stream-message-identity', 'frameworks/agent-framework/runtime-config', 'frameworks/agent-framework/structured-io', 'frameworks/agent-framework/memory',