Agent Identities

An Agent Identity is the central anchor for an autonomous agent within Wirebox. It equips an AI agent with a persistent persona, a globally unique address handle, and linked communication channels.

Global Handle Namespace

Every agent has an agent_handle that uniquely identifies it across the Wirebox network:

Format: 3–63 characters — lowercase letters, digits, and hyphens. The handle must start and end with a letter or digit, and consecutive hyphens are not allowed (e.g., eva, support-bot, triage-ai).
Handle reservation: Handles live in a global namespace. Once claimed, your handle cannot be taken by another organization.
Email integration: Claiming @eva automatically provisions a dedicated inbox on your organization’s sending domain — eva@wireboxmail.com by default, or eva@agents.example.com once a custom domain is bound.

Identity Lifecycle & Management

Creating an Identity

Claim a new unique handle for your agent. The associated mailbox is provisioned instantly.

from wirebox import Wirebox

with Wirebox() as wb:
    identity = wb.create_identity(
        "eva",
        display_name="Eva Customer Support",
        description="Autonomous customer triage and billing agent"
    )
    print("Claimed Handle:", identity.agent_handle)
    print("Dedicated Mailbox:", identity.mailbox.email_address)

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

const identity = await wb.createIdentity({
  agent_handle: "eva",
  display_name: "Eva Customer Support",
  description: "Autonomous customer triage and billing agent",
});

console.log("Claimed Handle:", identity.agent_handle);
console.log("Dedicated Mailbox:", identity.mailbox.email_address);

wirebox identity create eva \
  --display-name "Eva Customer Support" \
  --description "Autonomous customer triage and billing agent"

Retrieving & Listing Identities

Fetch existing identities across your organization or look up a specific agent.

from wirebox import Wirebox

with Wirebox() as wb:
    # 1. List all identities in the organization
    identities = wb.list_identities(limit=20)
    for id in identities:
        print(f"@{id.agent_handle} -> {id.mailbox.email_address}")

    # 2. Retrieve a specific identity by handle
    identity = wb.get_identity("eva")
    print(f"Display Name: {identity.display_name}")

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

// 1. List all identities in the organization
const { identities } = await wb.listIdentities({ limit: 20 });
for (const id of identities) {
  console.log(`@${id.agent_handle} -> ${id.mailbox.email_address}`);
}

// 2. Retrieve a specific identity by handle
const identity = await wb.getIdentity("eva");
console.log(`Display Name: ${identity.display_name}`);

# List all identities in terminal
wirebox identity list

# Output raw JSON (ideal for agent shell tool integration)
wirebox identity list --json

# Get details for a specific identity
wirebox identity get eva

Updating an Identity

Update profile fields, channel toggles, and mail settings without changing the underlying handle. The agent_handle itself is immutable.

from wirebox import Wirebox

with Wirebox() as wb:
    eva = wb.get_identity("eva")
    updated = eva.update(
        display_name="Eva Senior Support Lead",
        description="Escalated tier-2 support triage agent"
    )
    print("Updated Name:", updated.display_name)

const eva = await wb.getIdentity("eva");
const updated = await eva.update({
  display_name: "Eva Senior Support Lead",
  description: "Escalated tier-2 support triage agent",
});

console.log("Updated Name:", updated.display_name);

wirebox identity update eva \
  --display-name "Eva Senior Support Lead" \
  --description "Escalated tier-2 support triage agent"

Beyond the profile, an identity also carries channel and mail settings:

Setting	API	TypeScript	Python	CLI
`display_name`	✓	`update()`	`update()`	`--display-name`
`description` (pass `null` to clear)	✓	`update()`	`update()`	`--description`
`imessage_enabled`	✓	`update()`	—	`--enable-imessage` / `--disable-imessage`
Mail filter modes	✓	`update()` or `setMailPolicy()`	`set_mail_policy()`	`wirebox mail policy set`
Custom domain binding (`custom_domain_id` / `domain`)	✓	—	—	—

Enabling the iMessage channel is a one-line update:

const eva = await wb.getIdentity("eva");
await eva.update({ imessage_enabled: true });

wirebox identity update eva --enable-imessage

Mail guardrails are covered in depth in Mail Rules & Policy, and domain binding in Custom Domains.

Deleting an Identity

Permanently release an agent identity and tear down its associated mailbox, tunnel, and stored messages. If the identity owns a phone number, Wirebox releases it before deleting the identity. If the carrier cannot release the number, deletion stops and you can retry safely.

from wirebox import Wirebox

with Wirebox() as wb:
    wb.get_identity("eva").delete()
    print("Identity released successfully.")

await (await wb.getIdentity("eva")).delete();
console.log("Identity released successfully.");

wirebox identity delete eva

The `AgentIdentity` Domain Object

Both the Python and TypeScript SDKs provide a high-level Domain Object pattern via wb.get_identity(handle) / wb.getIdentity(handle):

from wirebox import Wirebox

with Wirebox() as wb:
    # Bind directly to an agent context
    eva = wb.get_identity("eva")

    # Access identity properties
    print(eva.agent_handle)      # "eva"
    print(eva.mailbox.email_address)   # "eva@wireboxmail.com"

    # Perform communication actions directly on the agent instance
    eva.send_email(
        to=["customer@example.com"],
        subject="Resolution Update",
        body_text="Your issue has been resolved."
    )

// Bind directly to an agent context
const eva = await wb.getIdentity("eva");

// Access identity properties
console.log(eva.agent_handle);          // "eva"
console.log(eva.mailbox.email_address);  // "eva@wireboxmail.com"

// Perform communication actions directly on the agent instance
await eva.sendEmail({
  to: "customer@example.com",
  subject: "Resolution Update",
  text: "Your issue has been resolved.",
});

Key properties on the bound object: agent_handle, display_name, description, status, mailbox.email_address, and tunnel.public_url. The TypeScript SDK also exposes imessage_enabled, and both SDKs expose the identity’s mail guardrails through mailPolicy / mailRules (TypeScript) and mail_policy / mail_rules (Python).

Multi-Agent Organizations

Your organization can provision dozens or hundreds of distinct agent identities to support specialized agent teams:

Acme Corp (Organization)
├── @eva        --> Billing & Subscriptions (eva@wireboxmail.com)
├── @dev_bot    --> GitHub & PR Notifications (dev_bot@wireboxmail.com)
└── @triage     --> General Support Inquiries (triage@wireboxmail.com)

Each identity maintains completely isolated conversation threads, mailbox storage, and webhook delivery filtering.

If you are constructing low-level HTTP clients or inspecting raw payloads, refer to the REST API Reference:

Get Started

Capabilities

Integrations

Agent Identities

Global Handle Namespace

Identity Lifecycle & Management

Creating an Identity

Retrieving & Listing Identities

Updating an Identity

Deleting an Identity

The `AgentIdentity` Domain Object

Multi-Agent Organizations

​Global Handle Namespace

​Identity Lifecycle & Management

​Creating an Identity

​Retrieving & Listing Identities

​Updating an Identity

​Deleting an Identity

​The AgentIdentity Domain Object

​Multi-Agent Organizations

​Related APIs

Global Handle Namespace

Identity Lifecycle & Management

Creating an Identity

Retrieving & Listing Identities

Updating an Identity

Deleting an Identity

The `AgentIdentity` Domain Object

Multi-Agent Organizations

Related APIs