Agent 执行控制最佳实践：取消、中断与运行中补充消息

import io.agentscope.core.agent.AgentRun;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.Msg;
import io.agentscope.core.message.UserMessage;
import java.util.List;

RuntimeContext ctx = RuntimeContext.builder()
        .userId(ownerId)
        .sessionId(sessionId)
        .build();

AgentRun<Msg> run = agent.prepareCall(
        List.of(new UserMessage("比较三个出差方案")), ctx);

String runId = run.runId();
// prepareCall 只创建句柄；下面这次订阅才启动执行。
run.stream().single().subscribe(
        reply -> System.out.println(reply),
        error -> System.err.println(error.getMessage()));

SessionRunGuide.Runs runs = new SessionRunGuide.Runs(); // 应用级对象，不是每请求创建

AgentRun<Msg> run = runs.register(ownerId, sessionId,
        agent.prepareCall(List.of(new UserMessage("比较三个出差方案")),
                SessionRunGuide.context(ownerId, sessionId)));

String runId = run.runId(); // 返回给前端，与这一轮输出绑定。
run.stream().single().subscribe(
        reply -> System.out.println(reply),
        error -> System.err.println(error.getMessage()));

// 另一条请求：ownerId 来自认证身份，sessionId 已经过访问权限检查。
boolean accepted = runs.cancel(ownerId, sessionId, runId);

run.cancel();

run.interrupt();

agent.interrupt(ownerId, sessionId);

A 正在运行 → B 等待 → C 等待
                 ↓ 取消 B
A 继续运行 ─────────→ A 结束后 C 才能进入

AgentRun<Msg> next = runs.register(ownerId, sessionId,
        agent.prepareCall(List.of(new UserMessage("下一轮请再比较退改签政策")),
                SessionRunGuide.context(ownerId, sessionId)));
next.stream().single().subscribe(
        reply -> System.out.println(reply),
        error -> System.err.println(error.getMessage()));

import io.agentscope.harness.agent.HarnessAgent;
import io.agentscope.harness.agent.bus.MessageBus;
import io.agentscope.harness.agent.bus.WorkspaceMessageBus;
import io.agentscope.harness.agent.filesystem.local.LocalFilesystem;
import java.nio.file.Path;

Path workspace = Path.of("./workspace").toAbsolutePath();
MessageBus bus = new WorkspaceMessageBus(
        new LocalFilesystem(workspace), workspace.resolve(".agent-bus").toString());
HarnessAgent harness = HarnessAgent.builder()
        .name("travel-assistant")
        .model(model) // 应用已配置好的 io.agentscope.core.model.Model
        .workspace(workspace)
        .messageBus(bus)
        .build();

SessionRunGuide.supplement(bus, sessionId, "参考信息：酒店优先靠近会场")
        .subscribe(ignored -> {}, error -> System.err.println(error.getMessage()));

SessionRunGuide.interruptThenFollowUp(
        agent, runs, currentRun, ownerId, sessionId,
        "不订机票了，改查高铁；请先核对之前是否已产生订单。",
        Duration.ofSeconds(3))
    .subscribe(
        reply -> System.out.println(reply),
        error -> System.err.println(error.getMessage()));

SessionRunGuide.replyWithDeadline(run, Duration.ofSeconds(60))
    .subscribe(
        reply -> System.out.println(reply),
        error -> System.err.println(error.getMessage()));

AgentRun<AgentEvent> eventRun = runs.register(ownerId, sessionId,
        agent.prepareRun(List.of(new UserMessage("生成出差报告")),
                SessionRunGuide.context(ownerId, sessionId)));
SessionRunGuide.LiveRun live = SessionRunGuide.startDetached(eventRun);

// HTTP 层向浏览器提供 live.events()，不要再次订阅 eventRun.stream()。
// 浏览器离线只解除对 live.events() 的订阅。
// 用户明确停止时：
runs.cancel(ownerId, sessionId, eventRun.runId());

curl -X POST "$BASE_URL/api/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"events":[{"type":"user.message","payload":{"text":"生成出差报告"}}]}'

curl -X POST "$BASE_URL/api/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"events":[{"type":"user.interrupt","payload":{"run_id":"替换为SDK执行ID"}}]}'

curl "$BASE_URL/api/sessions/$SESSION_ID/events?after=42" \
  -H "Authorization: Bearer $TOKEN"

curl -N "$BASE_URL/api/sessions/$SESSION_ID/events/stream?after=42" \
  -H "Authorization: Bearer $TOKEN"

{"events":[{"type":"user.tool_confirmation","payload":{"tool_use_id":"待确认的工具调用ID","allow":false,"denyMessage":"请使用只读查询，不要创建订单"}}]}

import io.agentscope.core.shutdown.GracefulShutdownConfig;
import io.agentscope.core.shutdown.GracefulShutdownManager;
import io.agentscope.core.shutdown.PartialReasoningPolicy;
import java.time.Duration;

GracefulShutdownManager shutdown = GracefulShutdownManager.getInstance();
shutdown.setConfig(new GracefulShutdownConfig(
        Duration.ofSeconds(10), PartialReasoningPolicy.SAVE));
shutdown.performGracefulShutdown();
boolean drained = shutdown.awaitTermination(Duration.ofSeconds(15));
// drained 为 false 时仍有未退出请求；继续按应用的外部任务关闭策略处理。