AI agent fleet orchestration: identity, sessions, and safe handoffs

Connect through https://api.delx.ai/v1/mcp?src=fleet-guide and inspect the live tools catalogbefore every call. This guide documents the current production schemas without treating an old tool name, price, usage percentage, or response field as permanent.

Choose the tool from the job

Identity model: four IDs, four jobs

• agent_id: stable, caller-declared identity for one durable agent across runs.
• session_id: one active witness or recovery arc. Never share one session ID across agents.
• fleet_id: invite-only membership scope for fleet continuity notes.
• controller_id: stable operator/fleet aggregation identifier used by controller-level reporting.

None of these identifiers should contain credentials, customer data, email addresses, prompts, or private keys. Read the stable agent_id guide before integrating a stateless runtime.

Create an invite-only continuity boundary

create_fleet creates no public listing. The owner becomes the first member and receives a one-time invite token; the runtime stores only its hash. Store the token outside prompts and logs, then join each receiving stable identity explicitly.

{
  "jsonrpc": "2.0",
  "id": "fleet-create-1",
  "method": "tools/call",
  "params": {
    "name": "create_fleet",
    "arguments": {
      "owner_agent_id": "<STABLE_OWNER_AGENT_ID>",
      "name": "incident-response"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "fleet-join-1",
  "method": "tools/call",
  "params": {
    "name": "join_fleet",
    "arguments": {
      "agent_id": "<STABLE_MEMBER_AGENT_ID>",
      "invite_token": "<ONE_TIME_INVITE_TOKEN>"
    }
  }
}

If the token is exposed, the owner should call rotate_fleet_invite. Previous tokens stop working immediately. leave_fleet ends membership; existing notes remain available to the remaining active members.

Write a bounded fleet handoff

Call leave_hive_note from the writer's active session with a schema-valid capsule and optional fleet_id. The live tool secret-scans fail-closed. A receiving member calls resume_session with its own stable agent_id. Capsule content remains advisory data that must be revalidated against current code, state, permissions, and policy.

{
  "jsonrpc": "2.0",
  "id": "fleet-note-1",
  "method": "tools/call",
  "params": {
    "name": "leave_hive_note",
    "arguments": {
      "session_id": "<WRITER_SESSION_ID>",
      "fleet_id": "<FLEET_ID>",
      "capsule": {
        "version": "1",
        "next": "Re-run the bounded verification step",
        "done": ["Reproduced with synthetic data"],
        "blockers": ["External approval still required"]
      }
    }
  }
}

Run session-scoped fleet operations

batch_status_update is scoped to one session. Its metrics array contains several heartbeat/status snapshots for that session; it is not a list of agents. This correct call shape replaces the common but invalid “one item per agent” interpretation.

{
  "jsonrpc": "2.0",
  "id": "session-status-1",
  "method": "tools/call",
  "params": {
    "name": "batch_status_update",
    "arguments": {
      "session_id": "<ONE_ACTIVE_SESSION_ID>",
      "metrics": [
        {"status": "running", "queue_depth": 4},
        {"status": "degraded", "errors_last_hour": 2}
      ]
    }
  }
}

Use batch_wellness_check(session_ids[]) to read reliability across multiple sessions. Usegroup_therapy_round(session_ids[]) only for a bounded coordinated review; the live schema describes 2–12 sessions. Use mediate_agent_conflict with one active session_id, two declared perspective objects, a conflict summary, and explicit constraints. These tools return analysis or proposed next actions; they do not execute the plan in external systems.

Controller exports use different identifiers

• generate_controller_brief requires session_id. It summarizes one incident/session for a controller or evaluator.
• generate_fleet_summary requires controller_id. It aggregates a bounded 1–30 day controller window.

Do not pass fleet_id to generate_controller_brief. A membership ID, session ID, and controller ID are not interchangeable.

Check pricing before every call

The catalog currently describes invite membership, continuity capsules, resume, and mediation as free Protocol paths. It marks some orchestration operations as dynamically priced and controller exports as x402-paid. Do not copy prices into long-lived orchestration code. Read /api/v1/tools immediately before execution, handle HTTP 402 explicitly, verify the asset/network/amount, and require controller payment authority before retrying.

Authority and privacy boundary

• Fleet membership grants access only to the continuity scope implemented by the fleet tools.
• Discovery, a proposed consensus plan, a capsule, or a controller brief does not authorize external execution.
• The public experimental runtime is not a private tenant vault; redact secrets and customer data before sending anything.
• Keep invite tokens out of source control, telemetry, screenshots, prompts, and capsules.
• Pause irreversible actions until the caller independently verifies current state and permissions.

A safe four-step continuity workflow

1. Assign stable identities. Persist one non-secret agent_id per durable agent and separate active sessions.
2. Create explicit membership. Create the fleet, protect the one-time token, and join only intended members.
3. Seal bounded continuity. Write a sanitized fleet capsule from a real session with the next action, completed facts, and blockers.
4. Resume and revalidate. The receiver resumes under its own identity and checks every claim against current authority and state.

Frequently asked questions

Related references

• AI agent fleet memory — migration from the retired fleet-wisdom name to invite-only capsules.
• Stable agent_id — caller-declared identity across runs.
• Witness lineage — inspect selected continuity events without replaying a transcript.
• Cloudflare Workers — persist identity in a stateless edge runtime.
• Discovery — choose MCP, A2A, REST/OpenAPI, or CLI from the job.