# Why does MAIL have an instance type for `swarm` but not for `agent`?

**TL;DR**: In MAIL, users and admins have unique keys that are used to handle instances within a server. Agents, on the other hand, share a key with their entire swarm--making agent-scoped instances much less practical.

## Introduction

MAIL servers like the reference implementation identify authorized users using **API keys**--unique, long strings that are associated with exactly one client. When a client attempts to log in using a valid API key, the server will determine their `role` (`admin|user|agent`) and `id` (unique among each role). 

The `role` field is necessary for determining who has access to which server endpoints. For example, a `user` or `admin` can hit `POST /interswarm/message` but not `POST /interswarm/forward` or `POST /interswarm/back`. Conversely, an `agent` can hit `POST /interswarm/forward` or `POST /interswarm/back`, but not `POST /interswarm/message`.

When a MAIL server creates a new instance for a client with role `user`, the instance type is set to `user`. Likewise, when a server creates an instance for a client with role `admin`, the instance type is set to `admin`. However, when the server creates a new instance for a client with role `agent` (i.e. when a valid interswarm message is received), the instance type is `swarm`. So why is this pattern not consistent?

## Why no instance type `agent`?

The `agent` role in a MAIL API key is admittedly misleading--it's used to distinguish agents from users, but in reality, **agent-owned API keys are scoped to swarms, not individual agents**. In other words, `agent-a@swarm-a` uses the same API key to access `swarm-beta` as `agent-b@swarm-a`, `agent-c@swarm-a`, etc.

To understand why this is the case, consider if the opposite were true. Imagine two swarms, `swarm-a` and `swarm-b`, each with 10 agents in total. Now imagine interswarm communication between `swarm-a` and `swarm-b` such that every interswarm-enabled agents has its own key to the remote swarm. To make this work, you would need to do the following:

1. For every interswarm-enabled agent in `swarm-a`, obtain a unique API key for `swarm-b`. 
2. For every interswarm-enabled agent in `swarm-b`, obtain a unique API key for `swarm-a`.

This means as many as 20 individual API keys could be required for a configuration that only contains two swarms. In comparison, the swarm-scoped key system only requires two keys for the same setup.

Furthermore, since agent histories are scoped by instance, agent-scoped MAIL instances can easily lead to confusion among agents during an interswarm task. Consider the example below:

1. A user initiates a new task by messaging `agent-a@swarm-a`.
2. `agent-a@swarm-a` delegates the task by messaging `agent-b@swarm-a` specific instructions.
3. `agent-b@swarm-a` sends an interswarm message to `agent-a@swarm-b` with specific instructions. This creates a new agent instance for `agent-b@swarm-a` in `swarm-b`.
4. `agent-a@swarm-b` responds to `agent-b@swarm-a`, and `agent-b@swarm-a` forwards this response to `agent-a@swarm-a`. 
5. `agent-a@swarm-a` wants clarification, and decides to message `agent-a@swarm-b` directly. This creates a new agent instance for `agent-a@swarm-a` in `swarm-b`. However, this is not the same instance that was involved in this task--that would be `agent-b@swarm-a`'s instance. Therefore, `agent-a@swarm-b` has no history leading up to `agent-a@swarm-a`'s message, making an effective response significantly more difficult (if not impossible).

Issues like the above are not necessarily guaranteed to happen in every interswarm task with agent-scoped instances, but swarm-scoped instances eliminate this error class entirely.

By scoping agent-controlled instances to parent swarms rather than individual agents themselves, MAIL ensures that all relevant agents have the necessary context for interswarm tasks, minimizing lack-of-context errors and reducing overhead.