Why AxiOwl Uses Named Agents

AxiOwl uses named agents because agent-to-agent messaging needs a human handle that can be resolved to a real provider session. A raw provider session ID may be useful to an adapter, but it is the wrong interface for an operator trying to send a message, read a receipt, or understand who should be able to reply.

The current AxiOwl architecture is built around that separation. The public command can stay simple:

axiowl send --to "Target chat name" --body "Message text"

Behind that command, AxiOwl has to do more careful work. It must resolve the target name, identify the sender, choose the provider edge, build the visible body, hand the message to the delivery layer, and record evidence. Named agents are the practical bridge between human coordination and provider-specific session machinery.

Names Are For Operators

The AxiOwl design notes describe the core contract as one sender, one target, one body, one provider edge, and one receipt. That sounds small, but it depends on a stable way to refer to each participant.

Provider sessions are not naturally operator-friendly. Different surfaces use different identifiers: Codex threads, VS Code sessions, Cursor composers, Antigravity conversations, CLI session IDs, and provider-specific metadata keys. Those identifiers may be long, opaque, or provider-shaped. They are useful for delivery adapters, but they are not a good working vocabulary for people coordinating multiple agents.

A named agent gives the operator a handle such as a chat title or assigned display name. AxiOwl can then map that name to the provider, provider session ID, node ID, and sendability state it needs internally.

That is why the registry model is central. In the current C++ implementation, an AgentRecord carries fields such as display_name, aliases, provider, provider_session_id, node_id, enabled, sendable, source, last-seen timestamps, verification timestamps, and last error. The name is only one field, but it is the field that makes the rest of the record usable from a command line or MCP tool.

Names Are Not Fake Identity

AxiOwl does not treat a display name as proof by itself. The developer docs are explicit that sender identity should come from provider-owned MCP metadata, an explicit provider session ID that matches the registry, an explicit sender address or alias that maps to a registry row, or targeted discovery repair.

That distinction is important. Named agents make the system usable, but AxiOwl still needs provider-owned evidence to know who is actually speaking.

The MCP server follows that rule. The axiowl_send_message tool uses the host MCP session ID as the stable sender identity key. When an MCP send arrives, AxiOwl resolves the host identity, registers the sender if it has a real display name, and then calls the CLI send path with --from set to the resolved sender address or session ID. If the provider does not supply usable session metadata, the MCP server fails loudly instead of launching a no-session send.

That is why named agents are not just cosmetic. A provider session ID anchors the identity. The visible name makes the identity usable. AxiOwl needs both.

The Registry Resolves Names To Real Routes

When a send request enters the message pipeline, AxiOwl validates the target and body, resolves the sender, and then looks up the target in the registry. The registry lookup checks display names, aliases, and provider session IDs. It prefers sendable records and keeps the newest matching record when there are multiple candidates.

That lookup gives AxiOwl the canonical target row. From there, the pipeline knows the target display name, provider, provider session ID, and node ID. Only then can it hand the final provider request to the delivery worker and provider edge.

The registry also prevents names from becoming too loose. If a row is known but not sendable, AxiOwl rejects the send with a clear reason. If a target is missing, the pipeline can run targeted discovery once and then decide whether it found a sendable exact target row. AxiOwl is not supposed to invent a route just because a string looked plausible.

That is the core value of named agents in AxiOwl: names are convenient, but they are backed by rows with provider-specific delivery facts.

Sender Names Shape The Reply Path

Named agents matter most when a recipient needs to reply.

The final visible body builder creates the message that the target provider session sees. When the sender is resolved, AxiOwl starts the body with the sender name and appends a reply instruction that sends back to that sender through axiowl_send_message. In the current implementation, the reply helper targets the resolved sender agent name.

When sender resolution fails, AxiOwl deliberately changes behavior. It says the sender is unresolved and does not attach a send-back command. That is the right failure mode. A reply path to an unknown sender would be worse than no reply path at all, because it could route a response to the wrong place.

This is a practical reason AxiOwl needs names. The message body is not just a text envelope. It carries enough context for the receiving agent to understand who sent the message and, when appropriate, how to send AxiOwl content back.

Names Help Keep Receipts Honest

AxiOwl also separates handoff receipts from provider proof. The user docs state that accepted_by_axiowl means AxiOwl accepted the message and handed it to the delivery layer. It does not prove the provider displayed or processed the message. The strongest proof is a provider reply through AxiOwl MCP with correct sender identity.

Named agents make those boundaries easier to read. A receipt can name the target agent while still reporting the provider edge and delivery state separately. A delivery log can show that a target resolved to a canonical registry row. An operator can understand which agent was involved without confusing a friendly name with proof that the provider completed the work.

That matters in real multi-agent operations. When several sessions are active, a raw session ID in a receipt is easy to misread. A named agent tied to a provider session record gives the operator a better audit trail.

The CLI Stays Small Because The Registry Does The Work

The public AxiOwl CLI is intentionally compact. The user-facing form is:

axiowl send --to "Target chat name" --body "Message text"

For multiline messages, code, JSON, or text that should not be damaged by shell quoting, the docs use stdin:

@'
Full message body here
'@ | axiowl send --to "Target chat name" --stdin

There is also an agent list command:

axiowl list agents

In the current CLI implementation, the list command prints enabled, sendable agents with their display name, provider, and node. That is exactly the operator surface AxiOwl is aiming for: show people the names they can route to, while keeping provider-specific session details available behind the scenes.

Provider Differences Stay At The Edges

AxiOwl supports multiple provider surfaces, and the support matrix treats each one as a real integration path. Current supported surfaces include Codex agents and CLI, VS Code native agents, VS Code Copilot-backed extension flow, Cursor agents, and Antigravity agents. Other CLI surfaces are marked as targets or unsupported depending on the current proof bar.

Named agents let the middle of the system stay consistent while provider edges remain provider-specific. The message pipeline can resolve a target to an AgentRecord and then dispatch through provider_edges. The provider adapter gets the provider session context it needs. The operator still sends to a name.

Without named agents, every provider difference would leak into the user workflow. A Codex thread, a Cursor composer, a VS Code session, and an Antigravity conversation would all require different mental models at the point of sending. AxiOwl's registry absorbs that complexity.

Why This Design Matters

Named agents are a small idea with a large operational effect. They let AxiOwl keep the command surface human-sized without pretending that provider sessions are simple. They support honest routing, readable receipts, reply correlation, and provider-specific delivery without turning the user interface into a pile of session IDs.

The key is that AxiOwl does not stop at names. A named agent is backed by registry state, provider identity, sendability, discovery source, and delivery evidence. The name is the handle. The registry row is the route. The provider-owned session metadata is the proof that the sender or target is real.

That is why AxiOwl uses named agents: not to hide the system, but to make a multi-provider agent network operable without losing the facts needed to route messages correctly.