Renaming & Converting Agents

An agent's memory, experience and channel connections belong to the agent — not to its name. So you can rename an agent, or turn a person's seat into an AI agent, and everything it learned comes with it.

Every agent has a stable identity

Each agent is given a permanent identity the first time the mesh starts with it. You can set one yourself with an agent-level id:, but you do not need to.

Changing what kind of agent it is — say, from human to llm — keeps the identity. Nothing else is needed.
Renaming is the one change the mesh cannot follow on its own: a new name looks like a new agent. Tell it, using one of the two ways below.

Option 1 — say it in the YAML

On the renamed agent, name what it used to be called:

agents:
  refunds_specialist:
    name: refunds_specialist
    agent_type: llm
    model: claude-sonnet-4-6
    previous_name: refunds_desk

The next start moves the identity — and with it the memory, experience and channel connections — from refunds_desk to refunds_specialist. Once the move has happened the line is ignored, so it is safe to leave in the file.

The mesh refuses the move, and tells you why at startup, when:

the old name is still a declared agent,
the renamed agent already has an identity of its own,
two agents claim the same previous_name, or an agent names itself.

Option 2 — one API call

POST /api/yaml/agents/{agent_name}/migrate

{
  "to_name": "refunds_specialist",
  "to_type": "llm",
  "fields": { "model": "claude-sonnet-4-6" }
}

All three fields are optional. to_type is llm, human, programmatic or external. fields supplies what the new kind of agent needs — an AI agent needs a model. Settings that do not apply to the new kind are dropped. Studio uses this same call.

Turning a person into an AI agent

A human agent builds experience from the decisions the person makes (see Agent Experience). Converting it keeps that experience, so the AI agent starts out knowing how the person worked:

{
  "to_type": "llm",
  "fields": { "model": "claude-sonnet-4-6" }
}

Next Steps

Agent Experience — what moves with the agent
Human Agents — people as members of the mesh

LeafMesh — the agent keeps what it learned, whatever you call it