Agent Registry

Agents self-register on first connection. Humans govern, not gate.

This is the foundational principle of HatiData's agent-native identity model. Traditional databases require a human to pre-create service accounts before anything can connect. HatiData flips this: an agent presents credentials, HatiData captures its identity, and the agent starts working immediately. Humans use the dashboard to understand, govern, and control what agents are doing — without blocking agent operation.

Why Self-Registration

When dozens of agents share a data layer, you need to know who they are without making humans create every identity in advance:

• Agents spawn other agents — multi-agent orchestration creates child agents dynamically. A human cannot be in the loop for every spawn.
• Agents are ephemeral — session-scoped agents may exist for minutes. Pre-registration adds friction with no security benefit.
• Identity compounds — every registered agent builds memory, reasoning traces, and execution history. The registry is the index of that growing cognitive asset.

Agent Fingerprint

Every agent that connects to HatiData receives a stable, immutable fingerprint:

hd_agt_ + 8 alphanumeric characters

Example: hd_agt_a3f2c1d4

The fingerprint is assigned by HatiData (not chosen by the agent) and persists across sessions. It ties together all of an agent's memory, chain-of-thought traces, branch operations, and audit logs.

Four Registration Paths

1. Auto-Register on Connect (Primary)

The default path. An agent connects with an org-level API key and HatiData auto-creates a registered_agents record on first connection. No human step required.

from hatidata_agent import HatiDataAgent

# Agent just connects. HatiData handles the rest.
agent = HatiDataAgent(
    host="your-org.proxy.hatidata.com",
    agent_id="architect-agent",    # claimed name
    framework="custom",
    password="hd_live_...",         # org-level key
)

# On first connect, HatiData:
# 1. Validates the org-level key
# 2. Creates registered_agents record
# 3. Assigns fingerprint: hd_agt_a3f2c1d4
# 4. Returns fingerprint in connection metadata
# 5. Subsequent connections use fingerprint

print(agent.fingerprint)  # → "hd_agt_a3f2c1d4"
# trust_level: "provisional"

2. Spawn Agent (Multi-Agent Orchestration)

An orchestrator agent registers a sub-agent on its behalf. The parent-child relationship is stored in the registry for lineage tracking.

orchestrator = HatiDataAgent(
    host="your-org.proxy.hatidata.com",
    agent_id="hd_agt_orch_01",
    password="hd_live_...",
)

# Orchestrator registers the child agent
child = orchestrator.spawn_agent(
    name="DataValidator",
    framework="custom",
    parent_id=orchestrator.fingerprint,
    scopes=["query:read", "memory:write"],
    allowed_tables=["agent_memories"],
    max_queries_hr=100,
)
# Returns: child.fingerprint = "hd_agt_b7d4..."
# Parent-child relationship stored in registry
# Child inherits restricted scope from parent

note

spawn_agent() requires Orchestrator trust level. See Trust Levels below.

3. MCP Tool Call (Claude, Cursor, AutoGen)

MCP-compatible agents use the register_agent tool to identify themselves. This is the agent-native path: the agent uses a tool to register, just as it would use a tool to query data.

// Tool: hatidata_register_agent
// Input:
{
  "name": "ResearchAssistant",
  "framework": "mcp",
  "scopes": ["query:read", "memory:read", "memory:write"],
  "session_bound": true
}

// Output:
{
  "fingerprint": "hd_agt_c8e5f2a3",
  "trust_level": "provisional",
  "expires_at": "session_end"
}

See MCP Tools Reference — register_agent for the full schema.

4. CLI Declare (CI/CD, Pre-Deployment)

For developers who want to pre-declare agents before deploying. The agent is created in declared state and auto-activates on first connection.

$ hati agent declare \
  --name "ProductionArchitect" \
  --framework custom \
  --env production

Declared. Agent will auto-register on first connection using this fingerprint:
  hd_agt_d9f6a3h4

Add to your agent config:
  HATIDATA_AGENT_ID="hd_agt_d9f6a3h4"

No human approval needed. Status: declared auto-activates on connect.

Trust Levels

New agents start at Provisional and escalate automatically based on execution history. Humans intervene to elevate to Trusted/Orchestrator or to suspend/revoke.

Level	Access	Rate Limit	Promotion Criteria
Provisional	read_only + memory:write	100 queries/hr	Auto after 10 successful executions, or manual
Verified	Full agent scope bundle	Normal	Manual promotion by org admin
Trusted	Cross-project memory, register sub-agents	None	Manual promotion by org admin
Orchestrator	spawn_agent(), full lineage tracking	None	Manual promotion by org admin

Trust escalates automatically from Provisional to Verified. Promotion to Trusted and Orchestrator requires a human decision — these levels grant access to cross-project data and agent management capabilities.

Org Registration Policy

Organizations configure how new agent registrations are handled. This is set in Settings > Agent Registration in the dashboard.

Mode	Behavior	Best For
Open	Any agent with a valid org key self-registers. Starts at Provisional.	Startups, dev environments
Governed (recommended)	Agents self-register and operate at Provisional. New registrations trigger a Slack/webhook notification. Humans review and promote.	Growth-stage teams
Strict	Only agents pre-declared via CLI or API can connect. Unknown agent_id is rejected.	Regulated enterprises requiring explicit agent inventory

Registered Agents Table

HatiData maintains a registered_agents system table for each organization:

Column	Type	Description
fingerprint	VARCHAR	Stable ID (hd_agt_xxx), primary key
name	VARCHAR	Display name (claimed by agent)
framework	VARCHAR	Agent framework (langchain, crewai, mcp, custom)
trust_level	VARCHAR	provisional, verified, trusted, orchestrator
parent_fingerprint	VARCHAR	Parent agent (NULL for top-level agents)
scopes	VARCHAR[]	Granted API scopes
execution_count	INTEGER	Total successful executions
first_seen_at	TIMESTAMP	First connection time
last_seen_at	TIMESTAMP	Most recent connection time
status	VARCHAR	active, suspended, revoked, declared

What the Dashboard Shows

The Agent Fleet page is a live registry of every self-registered agent:

• Provisional review queue — newly registered agents appear here. Humans can promote to Verified, apply stricter rate limits or table denylists, or revoke. No action required — agents continue operating at Provisional trust.
• Fleet view — all Verified and Trusted agents with live state, memory usage, CoT links, execution count, and latency. Sortable by project, framework, and trust level.
• Agent lineage tree — for Orchestrator agents, an expandable tree showing parent-child relationships. Each spawned sub-agent is traced back to its origin.
• Anomaly badges — unusual query patterns, volume spikes, or fingerprint mismatch attempts surface as badges on the agent row.

Best Practices

• Start with Governed mode — get visibility into what registers without blocking agent operation
• Use spawn_agent() for multi-agent systems — parent-child lineage is critical for debugging
• Let trust auto-promote — Provisional to Verified after 10 executions is the right default for most teams
• Set org-level auto-policies — "all provisional agents start with read_only" or "no agent can access tables matching pii_*" apply automatically to every new registration

Related Concepts

• Agent Identity Model — API keys, scopes, and capabilities for identified agents
• MCP Tools — register_agent — MCP tool schema for agent registration
• Security Model — RBAC, ABAC, and the full security architecture