docs(sendmessage): clarify name registry semantics for completed agents

Resolved 💬 1 comment Opened May 18, 2026 by devseunggwan Closed May 20, 2026

Summary

The SendMessage tool's documentation states "Refer to teammates by name, never by UUID." This guidance is accurate for concurrent multi-agent coordination, but it does not cover the resume-after-completion pattern, where the name registry has already deregistered the agent.

Observed behavior

After a background sub-agent completes, attempting SendMessage to: "<agent-name>" returns:

{"success":false,"message":"No agent named '<name>' is currently addressable. Spawn a new one or use the agent ID."}

Retrying with the agent's UUID (e.g., SendMessage to: "<agentId from the Agent tool's spawn response>") succeeds and resumes the prior session with full context intact.

Observed deterministically across 20+ post-completion SendMessage attempts in a single session (5 background agents x 4 multi-round resume cycles, every single name-based call failed, every single UUID-based call succeeded).

Expected vs actual

  • Docs say: refer to teammates by name
  • Actual: name is only valid while the agent is active. Post-completion, only UUID resolves.

Proposed improvements (either or both)

  1. Documentation: extend the SendMessage tool description to note that name-based addressing applies only to currently-active agents, and that UUID (agentId from the Agent tool's spawn response) is required to resume completed agents.
  2. Behavior: keep the name registry valid for a configurable grace period after agent completion, so the same identifier works for both active coordination and resume patterns.

Repro

  1. Spawn a background agent: Agent(... name="worker-1", run_in_background=true)
  2. Wait for completion notification
  3. Try SendMessage to: "worker-1" -> fails with the message above
  4. Try SendMessage to: "<agentId from spawn response>" -> succeeds, resumes session with prior context

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗