How to Create Your First Named Agent

How to Create Your First Named Agent

A named agent in AxiOwl is a sendable target you can refer to by a human-readable name instead of by a raw provider session ID. That name is not just cosmetic. AxiOwl stores it in its local registry with the provider, session ID, node, aliases, timestamps, and sendability flags that let later commands resolve the target consistently.

The practical result is simple: after a provider chat is created or registered, you can send to "Research Helper" or "Build Runner" instead of copying a long thread, conversation, composer, or session identifier every time.

What AxiOwl Means by a Named Agent

In the current C++ implementation, AxiOwl's registry is a TSV file named agents.tsv. On Windows it lives under the AxiOwl state root in:

%LOCALAPPDATA%\AxiOwl\registry\agents.tsv

On non-Windows platforms, the same state model resolves under XDG_STATE_HOME/axiowl when XDG_STATE_HOME is set, or under ~/.axiowl otherwise.

Each registry row has fields for:

agent_id
display_name
aliases
provider
provider_session_id
node_id
enabled
sendable
source
first_seen_at
last_seen_at
last_verified_at
last_error

The important fields for a first named agent are display_name, provider, provider_session_id, node_id, enabled, and sendable. AxiOwl's list agents command only prints rows that are both enabled and sendable.

Before You Start

The Windows installer places the main executable at:

%LOCALAPPDATA%\AxiOwl\bin\axiowl.exe

The repo documentation also shows development examples using:

.\build\Debug\axiowl.exe

Use whichever path matches your install or build. The command shapes are the same.

The installer can also configure MCP entries for host apps, including Codex, VS Code, and Antigravity. After installation, restart the target app or open a new chat/thread before expecting the AxiOwl MCP tool to be available. That restart matters because the host needs to load the new MCP configuration.

The Best Path from Codex: Use the MCP Tool

When you are inside Codex, the AxiOwl Codex skill says to prefer the bundled AxiOwl MCP server instead of asking the chat to know its own session ID. The reason is concrete: the MCP tool receives host thread metadata and uses that as the sender identity.

The MCP server exposes these relevant tools:

axiowl_whoami
axiowl_list_agents
axiowl_send_message
axiowl_create_agent

For a first named agent from Codex, the intended flow is:

  1. Use axiowl_whoami if you need to confirm how AxiOwl sees the current host session.
  2. Use axiowl_create_agent with a provider and name.
  3. Use axiowl_list_agents to confirm the agent is sendable.
  4. Use axiowl_send_message to send to the new name.

The key point is that Codex-hosted creation should go through axiowl_create_agent. The CLI implementation explicitly warns that a raw CLI create with an initial body needs sender identity; without one, it fails and tells the operator to use the MCP tool from the provider host or pass --from explicitly for a CLI-only test.

The CLI Path

If you are using the executable directly, the create command has this shape:

axiowl create --provider codex --name "Research Helper" --body "Start a new chat and answer briefly." --from "Existing Sender"

For development builds, the repo README shows the same pattern as:

.\build\Debug\axiowl.exe create --provider codex --name "New Codex Chat" --body "Start a new chat and answer briefly."

In current code, --provider and --name are required for create. A body can be supplied with --body or through --stdin. Optional fields include --model and --cwd.

Provider names are normalized internally. For example, codex-cli becomes codex_cli, vscode-native becomes vscode_native, and vscode-copilot becomes vscode_copilot_backed. The CLI usage text lists create support for:

codex
codex-cli
antigravity
antigravity-cli
vscode-native
vscode-copilot
copilot-cli
cursor
cursor-cli
claude-code-cli
opencode-cli

That does not mean every provider edge behaves identically. The source has provider-specific create and rename implementations, and unsupported or unknown create paths fail loudly rather than silently pretending success.

What Happens When Create Succeeds

When provider creation succeeds and returns a stable provider session ID, AxiOwl enrolls the new target into the registry. The CLI prints an Agent saved. block with the name, provider, session, and registry path. It then prints Create accepted. with the provider, requested name, provider title when known, session, state, correlation state, and whether a rename is recommended.

The registry enrollment logic preserves useful aliases. It adds the requested name, the provider's requested display name, the provider title when known, and the provider session ID. For session IDs that contain a :session: marker, it also adds the bare session suffix as an alias.

This is why the first name you choose is useful even when the provider reports a different title or the title is still pending. AxiOwl keeps enough identity data to resolve the agent later by name or alias.

Verify the Agent

After creating the agent, list the sendable registry rows:

axiowl list agents

Development build example:

.\build\Debug\axiowl.exe list agents

When rows exist, the command prints each enabled, sendable agent like this:

Research Helper | provider=codex | node=local

If no rows exist, it prints No agents are registered. and the registry path. That usually means creation has not succeeded yet, discovery has not found a sendable session, or the agent was not manually registered.

Send to the Name

Once the agent appears in the list, send to the display name:

axiowl send --to "Research Helper" --body "Summarize the current task in three bullets."

AxiOwl resolves the target through the registry. Name matching is not limited to the current display name; aliases are checked too. For sender resolution, the registry also has logic to prefer exact session identifiers and newer sendable records when multiple possible rows exist.

Be precise about what the send receipt means. The MCP tool description and CLI output both draw a boundary: a successful AxiOwl handoff receipt means AxiOwl accepted the request. It does not automatically prove provider delivery, provider wake-up, or a recipient reply unless that specific path reported provider delivery explicitly.

Rename When the Provider Title Needs Cleanup

Some provider create paths can return a provider title that differs from the requested name, or they can accept creation while leaving the provider title pending. In those cases, the create output can mark Rename recommended: true.

The CLI rename command is:

axiowl rename --agent "Research Helper" --name "Research Helper"

There is also an optional delay:

axiowl rename --agent "Research Helper" --name "Research Helper" --delay-seconds 3

Rename first looks up the existing agent in the registry by display name or alias. If the provider accepts the rename and AxiOwl verifies the provider title, the registry display name is updated. The old name and requested name are kept as aliases, so existing references do not immediately become useless.

If rename is accepted but the provider title cannot be verified, AxiOwl records the condition as unverified and writes the error into the registry row instead of pretending verification happened.

Manual Registration for an Existing Session

You do not always need to create a new provider chat. If you already have a known provider session ID, you can add a registry row manually:

axiowl registry add-agent --name "Existing Research Thread" --provider codex --session "<provider-session-id>"

For a remote target, the README shows this shape:

axiowl registry add-agent --name "Remote Test" --provider remote --node "front" --session "<remote agent name>"

Manual registration is useful when the session already exists and the missing piece is the AxiOwl name. The implementation upserts records: if the same provider, session, and node already exist, AxiOwl merges identity information instead of creating a duplicate row. If the display name already exists, it merges the incoming identity into that row.

A Practical First-Agent Checklist

Use this short flow for your first named agent:

  1. Install AxiOwl or build axiowl.exe.
  2. Restart the host app if you want to use MCP from Codex, VS Code, or Antigravity.
  3. Create through axiowl_create_agent from Codex when you are in a Codex thread.
  4. Use raw axiowl create only when you can provide the needed sender identity for an initial message, or when the provider path does not require that sender context.
  5. Run axiowl list agents.
  6. Send to the display name with axiowl send --to.
  7. Run axiowl rename if the provider title is pending or does not match the intended name.

That workflow matches how the current AxiOwl C++ code treats named agents: names are registry-backed handles for real provider sessions, not loose labels in a prompt. The name becomes useful because it is tied to provider identity, node identity, aliases, logs, and sendability state.

For daily use, that is the point. AxiOwl lets you build a small set of durable, named targets, then route work to them without making every operator copy raw session IDs around by hand.

Tagged , , , , , ,