功能请求：支持在运行中的 Session 动态注册 Agent

[1553620375]

Python SDK接口请求：支持在运行中的 Session 动态注册 Agent

问题摘要

在使用 Code SDK 构建多智能体编排系统时，一个常见的模式是：在 Session 执行过程中通过工具动态生成 Agent 技能文件（.md），然后立即用 task() 将子任务委派给这些新创建的 Agent。

但目前 agent_dirs 参数只在 Session 创建时被扫描一次，运行期间新生成的 Agent 文件无法被 task() 识别，导致上述模式无法在单个 Session 内闭合。

---

环境

• SDK：a3s_code 1.3.3 Python 包
• Python：3.12

---

已确认的当前行为（基于实际测试）

Session API 确认签名

# 通过 help(a3s_code.Session.add_mcp_server) 确认：
add_mcp_server(self, name, transport='stdio', command=None, args=None, url=None, headers=None, env=None)
# 注意：无 timeout_ms 参数

# 通过实际调用确认的 Session 创建签名：
agent.session(workspace_dir, skill_dirs=[...], agent_dirs=[...], planning=True, permissive=True, tool_timeout_ms=300_000)

复现步骤

from a3s_code import Agent

agent = Agent.create("config/agent.hcl")

# Session A：在 Agent 动态生成之前启动
session_a = agent.session(
    "test_workspace/",
    skill_dirs=["planner/skills/"],
    agent_dirs=[],          # 此时 generated_agents/ 目录为空
    permissive=True,
    tool_timeout_ms=300_000,
)

# … Session A 执行过程中，MCP 工具向 generated_agents/ 写入了新文件：
# generated_agents/log_analyzer.md
# generated_agents/config_editor.md

# 尝试委派任务给新创建的 Agent → 失败：
session_a.send(
    'Use the task tool: task(agent="log-analyzer", prompt="analyze the logs", permissive=True)'
)

实际终端输出（运行 ID：20260310-084319）：

  [tool→] task
  [←tool] task  exit=1
     out: Tool execution error: Unknown agent type: 'log-analyzer' [permanent — do not retry without changing the arguments]

当前绕行方案及其局限

唯一可行的方案是 Agent 创建完成后新开一个 Session，在新 Session 的 agent_dirs 里指向已生成的目录：

history = session_a.history()   # 保存对话历史

# Session B：Agent 文件已存在，新开 Session
session_b = agent.session(
    "test_workspace/",
    skill_dirs=["planner/skills/"],
    agent_dirs=["agent_factory/generated_agents/"],  # 目录现在已有内容
    permissive=True,
    tool_timeout_ms=300_000,
)
session_b.send(resume_message, history=history)   # 重新注入历史

这种方式存在以下问题：

• 需要将整个对话历史序列化后重新注入，耗时且容易丢失上下文
• 实测中观察到 session_b 的 history_turns 有时为 0，说明历史注入并不可靠
• 强迫开发者将"规划"和"执行"拆分为两个独立 Session，违背单会话编排的设计意图

该 API 支持的完整编排流程

[Session 启动]
    ↓
MCP 工具：create_agents("需要 log-analyzer 和 config-editor")
    → 写入 log_analyzer.md、config_editor.md 到 generated_agents/
    ↓
session.register_agent_dir("generated_agents/")   ← 新 API
    ↓
task(agent="log-analyzer", prompt="...", permissive=True)   ← 成功
task(agent="config-editor", prompt="...", permissive=True)  ← 成功
    ↓
[Session 正常结束：完整对话历史保留在同一个 run 下]

没有这个 API，任何"先规划后执行"且中间有动态 Agent 创建的场景，都必须强制拆分成两个 Session。

---

附：相关的 MCP 超时问题

在当前的绕行方案中，create_agents 被实现为一个 MCP stdio 服务。该工具内部调用 LLM 来生成 Agent 定义。实测该内部 LLM 调用耗时约 220 秒：

Testing create_agents directly...
Done in 220.1s   # 实测结果

而 MCP 协议层有一个固定的 60 秒请求超时，且该超时目前无法通过任何已暴露的 Python API 配置——经 help() 确认，add_mcp_server 无 timeout_ms 参数。这导致：

MCP tool error: MCP request timed out after 60s   # 实际错误输出