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

Status Fixed / completed
Maintainer reply None cached
Activity 1 comment · opened May 18, 2026 · 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 ↗