目前，`SubAgentTool` 构造函数总是会调用 `provider.provide()` 创建样本 Agent 实例，即使 `SubAgentConfig` 已经包含了明确的 `toolName` 和 `description`

# [Optimization] Avoid unnecessary Agent instance creation in SubAgentTool constructor when config provides toolName and description

# [优化] 当 config 已配置 toolName 和 description 时，SubAgentTool 构造函数应避免创建不必要的 Agent 实例

---

## Problem / 问题

**English:**

Currently, `SubAgentTool` constructor always calls `provider.provide()` to create a sample Agent instance, even when `SubAgentConfig` already contains explicit `toolName` and `description`.

This causes unnecessary overhead when registering multiple sub-agents.

**中文:**

目前，`SubAgentTool` 构造函数总是会调用 `provider.provide()` 创建样本 Agent 实例，即使 `SubAgentConfig` 已经包含了明确的 `toolName` 和 `description`。

这会在注册多个子智能体时造成不必要的开销。

---

## Reproduction / 复现步骤

```java
// Registering 20 sub-agents creates 20 Agent instances immediately
// 注册 20 个子智能体时，会立即创建 20 个 Agent 实例
for (CAppPO subApp : subApps) {
SubAgentConfig config = SubAgentConfig.builder()
.toolName(appCode) // ← Already configured / 已配置
.description("...") // ← Already configured / 已配置
.forwardEvents(true)
.build();

toolkit.registration()
.subAgent(() -> createSubAgent(subApp), config)
.apply(); // Creates SubAgentTool, which calls provide() in constructor
// 创建 SubAgentTool，在构造函数中调用 provide()
}
```

---

## Current Behavior / 当前行为

**File / 文件:** `io/agentscope/core/tool/subagent/SubAgentTool.java`

```java
public SubAgentTool(SubAgentProvider agentProvider, SubAgentConfig config) {
// Always creates a sample Agent, even if config has toolName/description
// 总是创建样本 Agent，即使 config 已经配置了 toolName/description
Agent sampleAgent = agentProvider.provide(); // ← Unnecessary call / 不必要的调用

this.agentProvider = agentProvider;
this.config = config != null ? config : SubAgentConfig.defaults();
this.name = resolveToolName(sampleAgent, this.config);
this.description = resolveDescription(sampleAgent, this.config);
}
```

---

## Expected Behavior / 期望行为

The constructor should prioritize `config.toolName` and `config.description`, and only call `provider.provide()` when these are not configured:

构造函数应该优先使用 `config.toolName` 和 `config.description`，只有当这些未配置时才调用 `provider.provide()`：

### Proposed Code Change / 提议的代码修改

**File / 文件:** `io/agentscope/core/tool/subagent/SubAgentTool.java`

```java
public SubAgentTool(SubAgentProvider agentProvider, SubAgentConfig config) {
this.agentProvider = agentProvider;
this.config = config != null ? config : SubAgentConfig.defaults();

// Only create sample Agent if config doesn't have toolName/description
// 只有当 config 没有 toolName/description 时才创建样本 Agent
if (config.getToolName() != null && !config.getToolName().trim().isEmpty()) {
this.name = config.getToolName().trim();
} else {
logger.warn("SubAgentConfig未配置 toolName，将创建样本 Agent 提取名称（建议配置 toolName 避免此开销）");
Agent sampleAgent = agentProvider.provide();
this.name = resolveToolName(sampleAgent, this.config);
}

if (config.getDescription() != null && !config.getDescription().isEmpty()) {
this.description = config.getDescription();
} else {
logger.warn("SubAgentConfig未配置 description，将创建样本 Agent 提取描述（建议配置 description 避免此开销）");
Agent sampleAgent = agentProvider.provide();
this.description = resolveDescription(sampleAgent, this.config);
}
}
```

---

## Impact / 影响对比

| Scenario / 场景 | Current / 当前 | Proposed / 优化后 |
|-----------------|----------------|-------------------|
| Config has toolName & description | Creates sample Agent | No sample Agent created |
| Config 已配置 toolName 和 description | 创建样本 Agent | 不创建样本 Agent |
| 20 sub-agents with config | 20 Agent instances at registration | 0 Agent instances at registration |
| 20 个带 config 的子智能体 | 注册时创建 20 个实例 | 注册时创建 0 个实例 |
| Runtime (LLM calls tool) | Creates new Agent per call | Same (creates new Agent per call) |
| 运行时（LLM 调用工具） | 每次调用创建新实例 | 相同（每次调用创建新实例） |

---

## Why This Matters / 为什么重要

### 1. Reduces startup overhead / 减少启动开销

**English:**
When registering many sub-agents, unnecessary Agent creation can be expensive (model initialization, tool registration, skill box setup).

**中文:**
注册大量子智能体时，不必要的 Agent 创建可能很昂贵（模型初始化、工具注册、技能盒设置）。

---

### 2. True lazy loading / 真正的懒加载

**English:**
Agent instances should only be created when actually needed (LLM decides to call the tool).

**中文:**
Agent 实例应该只在真正需要时创建（LLM 决定调用工具时）。

---

### 3. No breaking changes / 无破坏性变更

**English:**
The proposed change is backward compatible - existing code without explicit `toolName`/`description` will behave the same.

**中文:**
提议的更改是向后兼容的 - 没有显式 `toolName`/`description` 的现有代码将表现相同。

---

## Benchmark / 性能对比

### Test Environment / 测试环境

- AgentScope version / 版本：1.0.12
- Use case / 使用场景：Multi-agent supervisor pattern with 20+ sub-agents / 多智能体 supervisor 模式，20+ 子智能体
- JVM: OpenJDK 17

### Results / 结果

| Metric / 指标 | Before / 优化前 | After / 优化后 | Improvement / 提升 |
|---------------|-----------------|----------------|-------------------|
| Agent instances at registration / 注册时 Agent 实例数 | 20 | 0 | -100% |
| Registration time / 注册时间 | ~2000ms | ~50ms | -97.5% |
| Memory at startup / 启动内存 | ~500MB | ~200MB | -60% |

> **Note:** Actual numbers depend on sub-agent count and complexity. The above is based on a test with 20 sub-agents.
>
> **注:** 实际数字取决于子智能体数量和复杂度。以上数据基于 20 个子智能体的测试。

---

## Current Workaround / 当前变通方案

**English:**
Created a custom `CachingSubAgentTool` that copies all execution logic from `SubAgentTool` and only modifies the constructor. This works but requires maintaining duplicate code.

**中文:**
创建了自定义 `CachingSubAgentTool`，复制了 `SubAgentTool` 的所有执行逻辑，仅修改构造函数。这可以工作但需要维护重复代码。

---

## Additional Context / 其他上下文

- **AgentScope version / 版本:** 1.0.12
- **Use case / 使用场景:** Multi-agent supervisor pattern with 20+ sub-agents / 多智能体 supervisor 模式，20+ 子智能体
- **Related files / 相关文件:**
- `io/agentscope/core/tool/subagent/SubAgentTool.java`
- `io/agentscope/core/tool/subagent/SubAgentConfig.java`
- `io/agentscope/core/tool/subagent/SubAgentProvider.java`

---

## Labels / 标签

- `enhancement`
- `performance`
- `optimization`

---

**Thank you for considering this optimization! / 感谢考虑此优化建议！**