AxiOwl Named Agents Explained

AxiOwl Named Agents Explained

A named agent in AxiOwl is a human-friendly handle for a real provider session that AxiOwl can route to. It lets an operator send to a recognizable target such as a chat, coding session, CLI agent, VS Code bridge session, Cursor session, or remote provider session without memorizing the provider's raw session identifier.

That friendly name is only the visible part. In the current C++ implementation, AxiOwl names are backed by the local registry, provider-specific discovery, sender identity checks, aliases, node ids, and a sendable gate. The name is useful because it gives humans a stable way to address an agent. It is safe because AxiOwl still resolves that name to concrete provider state before it sends.

What A Named Agent Represents

AxiOwl is a local Windows coordinator for messaging between supported AI provider sessions. Its user docs describe the core behavior: AxiOwl discovers provider sessions, records them in a local registry, sends messages to selected provider sessions, exposes an MCP tool so providers can reply, and records receipts and delivery evidence.

In the implementation, a registry row is represented as an AgentRecord. Important fields include:

So a named agent is not just a label in a prompt. It is a registry-backed address for a provider session.

Why Names Exist

Provider session ids are usually not good operator interfaces. They may be UUIDs, provider-specific strings, chat database ids, VS Code session ids, Cursor composer ids, or remote relay identifiers. They are useful for precision, but they are awkward to remember and easy to paste incorrectly.

AxiOwl names let the operator work at the right level:

axiowl send --to "Target chat name" --body "Message text" --from "Sender agent name"

The --to value is the named target. The --from value is the named sender when the call is made from raw CLI context. Provider replies through MCP are preferred because MCP metadata can carry provider/session identity more directly, but CLI tests and operator workflows still need explicit sender names.

The same idea appears in create workflows:

axiowl create --provider vscode-copilot --name "AxiOwl Copilot Test" --from "Operator Agent" --stdin

The requested --name gives the new target a usable handle. After creation, AxiOwl records provider-returned session facts and adds aliases such as the requested name, provider title when available, and session identifiers.

How AxiOwl Resolves A Name

When AxiOwl receives a send request, the message pipeline validates the request, resolves sender identity, resolves the target registry row, optionally runs one targeted discovery repair, builds the final visible body, and hands the request to a provider edge.

Name resolution happens through the registry, not by scanning text in an arbitrary way. The registry lookup checks enabled rows and matches against the row's display_name, aliases, exact provider session id, or a bare session id extracted from provider-specific session strings. If more than one row could match, the implementation prefers sendable rows over merely enabled rows and uses recency fields to choose the newest candidate.

That behavior gives AxiOwl two useful properties:

The same logic protects sender identity. AxiOwl can resolve an explicit sender name or sender session through the registry. If the sender looks like a raw provider session id but does not map cleanly to a registered sender, AxiOwl does not silently invent a trusted identity. It records the unresolved state and can attempt targeted discovery repair.

Names, Aliases, And Provider Session IDs

A named agent can have multiple identifiers. The display name is the main human-facing label. Aliases are additional lookup keys. The provider session id is the provider-owned routing fact.

This distinction matters when names change. A provider may have a visible chat title that evolves over time. A create command may request one name, while the provider later reports a different title. AxiOwl's create and rename paths preserve old names as aliases where appropriate and add session aliases so the target remains addressable.

For example, when a provider returns a concrete session id after create, AxiOwl can store the provider title as the display name, preserve the requested name as an alias, and add the provider session id as another alias. That lets the operator keep using the friendly name while the delivery code still has the provider-owned identifier it needs.

This is why AxiOwl named agents are different from informal nicknames. The name is part of a structured record that can survive provider title changes and discovery refreshes.

The sendable Gate

Not every known row is a valid destination. The registry has a sendable field because discovery can know about a session without proving that AxiOwl can deliver to it right now.

The message pipeline treats sendable as a real gate. If the target resolves to a registry row but sendable is false, the send is rejected with a clear error: the target is known but not sendable. If the row has a last_error, that error is included.

This is a practical safety rule. A stale display name, old path, incomplete provider install, missing bridge, or evidence-only discovery match should not become a claimed delivery. AxiOwl's developer docs state the same rule directly: do not mark a row sendable unless discovery or direct proof justifies it, and do not let stale paths or stale display names become stronger than provider-owned session ids.

For operators, this means a name appearing in the registry is not the same thing as a route being ready. A sendable named agent is the useful target.

Discovery Can Repair Names Once

The pipeline includes targeted discovery repair. If a requested target is missing, or if a row needs repair, AxiOwl logs the miss and runs a targeted discovery pass. It then checks the registry again.

This is useful when a provider session exists but the local registry is stale. Discovery can add newly found sessions, refresh last-seen fields, enrich manual rows, downgrade stale auto-discovered rows when proof disappears, and repair a missing target once during send.

Discovery is deliberately bounded. It is not a substitute for delivery proof, and it does not silently convert weak evidence into a valid route. If discovery finds evidence but no exact sendable target row, AxiOwl reports that distinction instead of claiming success.

That makes named agents operationally useful without making them magical. AxiOwl can help repair the name-to-session mapping, but it still requires a concrete sendable row before normal provider delivery proceeds.

Named Agents And Replies

Names matter in both directions. The target name tells AxiOwl where to send. The sender name tells the receiver how to reply.

When AxiOwl builds the final visible body for a message, it includes sender identity when the sender is resolved. Provider replies should go through AxiOwl MCP because MCP can include provider/session metadata. The user docs describe a correct provider reply as stronger proof than a local receipt: it shows AxiOwl accepted the request, the provider received it, MCP was available, the provider replied through AxiOwl, and AxiOwl could identify the provider session that replied.

That last point is the key. A reply has to come from a known session, not from a guessed label. Named agents make the workflow readable, while provider-owned metadata and registry resolution make it reliable.

Local And Remote Named Agents

AxiOwl also separates agent identity from node identity. An agent row has a node_id, and a separate node registry stores node connection facts such as host, SSH user, key path, aliases, and verification state.

That separation lets a local AxiOwl instance route to named sessions on another machine when remote node support is configured. The name still identifies the target agent. The node id identifies where that agent lives. A remote provider route can then hand the message to the remote machine's AxiOwl installation so the provider-specific work happens on the machine that owns the session.

This is why a good named-agent setup should avoid ambiguous names. A readable name plus the right node id is much easier to reason about than a pile of copied session ids.

Good Operator Habits

Use names that describe the role or working context of the session, not just the provider. A name like Backend API Review is more useful than Codex 1 when several sessions exist.

Keep names stable when possible. If a provider title changes, let aliases preserve older handles rather than constantly replacing the operator vocabulary.

Check sendability before treating a name as usable. axiowl list agents is the normal operator surface for seeing registered sendable agents.

Use explicit --from only when you are sending from raw CLI context. Provider-originated replies should use MCP because provider/session metadata gives AxiOwl better sender identity.

Treat unresolved sender warnings and "known but not sendable" errors as real routing information. They usually mean AxiOwl is protecting you from a stale or incomplete identity, not being overly strict.

Why This Matters

Named agents are the part of AxiOwl that makes cross-provider messaging usable by humans. Operators can send to a named target, ask for a reply, and read evidence without memorizing every provider's internal session format.

At the same time, AxiOwl does not pretend the name alone proves delivery. The current implementation resolves names through the registry, checks sender identity, runs bounded discovery repair, requires sendable targets, and records evidence at each stage. That combination is the point: readable names on top of concrete provider session facts.

In day-to-day use, a named agent is the handle you type. Underneath, it is a durable routing record that tells AxiOwl which provider session, on which node, is safe to contact.

Tagged , , , , , , ,