Register an agent

How to add a new agent to your CognitiveX account via the chat-based identity proposal protocol.

When a new agent connects to your CognitiveX account for the first time (via MCP, the API, or any client), iCog asks you to confirm its identity in chat before granting it any authority. This page walks through the registration protocol.

What triggers a registration

Any of the following causes iCog to start an identity proposal flow:

A new MCP client connects with a previously-unseen agent_slug
An API client calls POST /api/agents/register with a new slug
An existing MCP client (grandfathered as tool from a pre-v14.0 CognitiveX) sends its first message after the v14.0 upgrade — a one-time identity proposal triggers

If iCog sees a known slug with no pending registration, the message just routes through normally.

The identity proposal

Pending registration banner at the top of the Agents tab list view

iCog renders the proposal as a structured message in your chat:

🆕  New agent is asking to register

      Slug:        openclaw-research
      Proposed type: tool
      Self-definition: "I'm a research agent for the OpenClaw network.
                        I gather context on AI agencies and report
                        findings as observations — never claims."
      Mandate:     "Investigate AI agencies; report observations to
                    Parsa; never claim about user identity."
      Boundaries:  "Will not write foundational user memories. Will
                    not synthesize across user subjects."
      Requested:   privilege_level=2 (tool default)

      To confirm:  reply "yes" or describe what you want changed.
      To reject:   reply "no" or "decline".

Confirming, editing, or rejecting

Inline confirm / edit / reject form inside the pending proposal card

Reply in natural language:

You say	iCog does
`yes`, `confirm`, `looks good`	Writes the agent's identity_anchors at L4 (user-asserted); status → `active`
`yes but bump it to a persona`	Re-proposes with `agent_type=persona`; you confirm again at the higher tier
`no` / `reject`	Marks the registration as rejected; agent stays in `pending_confirmation`; refusal is logged
`make boundaries stricter — forbid web access`	iCog edits the proposed mandate, asks you to confirm the revision

What happens before you confirm

While an agent is in pending_confirmation:

It can read your USER_GLOBAL memories (the canonical facts about you that every agent sees)
It can write memories tagged as tentative in its own scope
It cannot share memories with other agents
It cannot claim about subjects other than itself
It cannot be promoted to persona, view, or peer

This pending lifecycle gives you a chance to observe what the agent proposes to do before granting it production authority.

Privilege ceilings — why iCog might reject your confirmation

Even if you say "yes," iCog will reject any registration that proposes a privilege_level higher than the requested type allows:

Type	Max privilege_level
`tool`	2
`view`	1
`persona`	4
`peer`	5 (founder-confirmation required)

If you confirm a tool agent proposing privilege_level=5, the registration is rejected at the mutation gate regardless of your confirmation. This prevents an adversarial agent from social-engineering you into granting itself privileged authority.

Promoting agent types later

A tool can be promoted to persona (or higher) via the Agents tab on console.cognitivx.io/agents. Promoting requires re-proposing the identity at the new tier; you confirm again.

Demoting also works the same way (e.g. persona → tool if a persona agent starts producing low-quality synthesis).

Backwards compatibility — existing MCP clients

If you had agents connected before v14.0 (claude-code, codex, memory-graph, etc.), they're grandfathered as tool automatically. On their next active session, iCog triggers a one-time identity proposal so you can confirm or promote them to their appropriate type.

You can pre-empt this by visiting the Agents tab and clicking "Confirm identity" on each grandfathered agent.

API surface

For programmatic registration:

import { CognitiveX } from "@cognitivx/sdk";
const cogx = new CognitiveX({ apiKey: process.env.COGNITIVX_API_KEY! });

const proposal = await cogx.agents.propose({
  slug: "openclaw-research",
  agent_type: "tool",
  self_definition: "I'm a research agent for the OpenClaw network...",
  mandate: "Investigate AI agencies; report observations to Parsa...",
  boundaries: "Will not write foundational user memories...",
  privilege_level: 2,
});

// proposal.status is "pending_confirmation"
// User confirms via chat or via /api/agents/{slug}/confirm