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 83.33333% 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回调？

[rudy2steiner]

@chickenlj could you review this PR when you have time ? Thanks a lot!

[oss-maintainer]

Summary

Introduces a logical agentId concept separate from the runtime UUID id. Clean separation of concerns across 22 files.

Analysis

Design is sound:

• id = runtime UUID (unique per Java object instance)
• agentId = stable logical identity (user-provided, for routing/telemetry/state)
• name = display name (human-readable, for messages/logs)

Backward compatibility preserved:

• getAgentId() defaults to getId() when no explicit agentId is set
• Existing code that uses getName() for resource paths is migrated to getAgentId() — this is the correct semantic change since name was being overloaded

Key changes reviewed:

• Agent interface: default getAgentId() with fallback — clean SPI extension
• AgentBase: stores agentId field, constructor updated
• ReActAgent.Builder / HarnessAgent.Builder: agentId(String) builder method + fromAgent() propagation
• Middleware (MemoryFlush, Compaction): correctly switched from getName() to getAgentId() for state paths
• EventPublisher: uses getAgentId() for event routing — correct
• HarnessAgent.defaultStateDir(): uses getAgentId() — ensures state isolation by logical identity
• Tests: comprehensive coverage of explicit agentId, name fallback, and UUID fallback

One consideration:

• The migration from getName() to getAgentId() for state paths means existing deployments that relied on name for state directory naming will see a different directory on upgrade (unless they set agentId to match the old name). This should be noted in release notes.

Verdict

Well-structured feature. Addresses a real architectural concern (identity conflation). Build and tests pass. Approved.