Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions docs/frameworks/agent-framework/stream-message-identity.md
Original file line number Diff line number Diff line change
@@ -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<AgentEvent>`。
本文只覆盖显式启用路径,不把普通 `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-<callId>`。
应使用事件返回的 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) 的消息标识项。
1 change: 1 addition & 0 deletions examples/stream-message-identity/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/target/
56 changes: 56 additions & 0 deletions examples/stream-message-identity/README.md
Original file line number Diff line number Diff line change
@@ -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.
24 changes: 24 additions & 0 deletions examples/stream-message-identity/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>io.github.agentic-ai-java.examples</groupId>
<artifactId>stream-message-identity</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<!-- Install Core ef67b8e083746899da43c0a056b76b71db9e92ab first. -->
<dependency>
<groupId>io.github.agentic-ai-java</groupId>
<artifactId>argi-agent-core</artifactId>
<version>2.1.0-RC2-SNAPSHOT</version>
</dependency>
</dependencies>
<build><plugins>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.14.1</version></plugin>
<plugin><groupId>org.codehaus.mojo</groupId><artifactId>exec-maven-plugin</artifactId><version>3.6.3</version>
<configuration><mainClass>example.StreamMessageIdentity</mainClass></configuration>
</plugin>
</plugins></build>
</project>
Original file line number Diff line number Diff line change
@@ -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<AgentEvent> {
final Map<String, String> text = new LinkedHashMap<>();
final Set<String> snapshots = new HashSet<>();
final CompletableFuture<Void> 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<ChatEvent> events, RuntimeException failure) {}
static ChatResponse response(String text, List<ToolCall> 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<ToolCall> 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<Turn> turns) {
Queue<Turn> queue = new ArrayDeque<>(turns);
return new ChatClient() {
public CompletionStage<ChatResponse> call(ChatRequest request) {
return CompletableFuture.failedFuture(new UnsupportedOperationException("stream only"));
}
public ChatClientCapabilities capabilities() { return ChatClientCapabilities.basic(); }
public Flow.Publisher<ChatEvent> 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<ToolResult> 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");
}
}
Loading