feat(agent): logical agentId

[rudy2steiner]

Why

agentId currently serves several different purposes in AgentScope Java:

• a randomly generated identifier for a running Java Agent instance;
• a stable logical Agent identifier used by platforms for registration, routing, and authorization;
• an Agent-level namespace for Harness resources such as state, skills, sandboxes, and workspaces;
• an identifier emitted in events, traces, and sub-agent metadata.

These meanings conflict when the same logical Agent is recreated or scaled to multiple runtime instances. The current random UUID changes for every instance, so platforms must maintain an additional mapping between their stable Agent ID and AgentScope's generated ID which discussed in #2313. However, simply making the existing ID configurable would allow multiple instances to share a value that internal state maps currently assume is unique, potentially causing state, trace, or training data to be overwritten or mixed.

This change separates the two identity concepts:

• agentId is the stable, caller-defined logical Agent ID.
• id is the random UUID of a specific runtime Agent instance.

This allows platform integrations to use a stable logical identity while preserving the existing
instance-level isolation.

Main Changes

• Added Agent#getId() for runtime instance identity. AgentBase always generates an immutable
  UUID for it, while the default interface implementation falls back to getAgentId() for
  compatibility with existing custom Agent implementations.
• Allowed callers to configure an immutable logical agentId. If it is null or blank, it falls
  back to the generated runtime id, preserving the previous default behavior.
• Added ReActAgent.Builder.agentId(String).
• Passed Harness's existing resolved Agent ID into its internal ReActAgent, so
  HarnessAgent#getAgentId() now matches the logical ID already used by Harness resource
  namespaces. The existing Harness resolution order and resource paths remain unchanged.
• Changed instance-scoped internal state to use id, including graceful-shutdown state savers,
  JSONL trace run state, and TrainingRouter input correlation. This prevents collisions when
  multiple runtime instances share one logical agentId.
• Kept logical Agent identity in telemetry and external Agent-facing APIs, while
  SubAgentTool.subagent_id continues to identify a unique runtime sub-agent instance by using
  id.
• Updated tests, documentation, and the multi-Agent Gateway example to cover custom logical IDs,
  default UUID behavior, Harness propagation, and isolation between instances sharing the same
  logical ID.

[codecov]

Codecov Report

❌ Patch coverage is 82.75862% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../main/java/io/agentscope/core/agent/AgentBase.java	66.66%	3 Missing ⚠️
.../src/main/java/io/agentscope/core/agent/Agent.java	0.00%	1 Missing ⚠️
...io/agentscope/core/tool/subagent/SubAgentTool.java	66.66%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[TianyuGeek001]

看描述和实现
1，id变成内部的唯一运行标识。
2，agentId提供给外部做关联标识。
是这个意思？

[rudy2steiner]

看描述和实现 1，id变成内部的唯一运行标识。 2，agentId提供给外部做关联标识。 是这个意思？

yes

[TianyuGeek001]

AgentSkillRepository有考虑增加一个agentId回调？