Agent-to-Agent Handoff

This tutorial hands a task from one connected agent session to another, using the agent tool namespace and NEXUS's local agent mesh. By the end, a message sent from one session is visible in the other.

Before you start

• NEXUS is running with two terminal sessions open, each hosting a connected CLI agent — see Connect a CLI. They can be the same CLI product running twice, or two different ones.
• Both sessions have made a discovery call — see First tool call.

1. Identify both sessions

The mesh is local to the machine and scoped to the workspace: both sessions need to belong to the same NEXUS workspace to see each other. Check the agent entries in each session's discovery response, and the exact tool signatures in the MCP tools reference, for how a session is addressed.

2. Send a message from the first session

Ask the first agent, in plain language, to hand a task to the second — for example, "send the second session a message asking it to review the canvas layout." The agent turns that into an agent tool call, using the same envelope every tool call on this server shares:

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "agent_<tool-name-from-discovery>",
    "arguments": {}
  },
  "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2026-07-28"
  }
}

Replace the tool name and arguments with what your discovery response and the tools reference specify for sending a message.

3. Receive it in the second session

Ask the second agent to check for incoming messages using its own agent tools. The message sent in step 2 should be there — the mesh delivered it without either session writing to a shared file or polling the workspace file tree.

What just happened

Two independent CLI processes, each with no awareness of the other beyond what the mesh told them, coordinated a handoff. Neither needed a NEXUS-specific SDK — the same tools/call envelope every MCP tool on this server uses carried the handoff.

Next

Return to Tutorials, or read Agent mesh for the full guide to the mesh's delivery model and limits.