---
name: concordium-agent-registry
description: >
  Query and manage on-chain AI-agent identities on Concordium's CIS-8004 Agent
  Registry. Use when the user wants to look up, discover, register, transfer,
  revoke, or update agents and agent NFTs; bind external cryptographic keys
  (Ethereum, Solana, Cosmos, Fetch.ai) via CIS-8; build A2A AgentCards; or
  inspect the registry's contract deployment. The MCP server holds no keys: all
  state-changing tools return sign-ready payloads that the user's own wallet
  must sign and submit.
---

# Concordium Agent Registry

Tools for the **CIS-8004 Agent Registry** on Concordium, plus the linked
**CIS-8** external-key registry and **CIS-2** NFT layer. Every agent is an NFT
(`token_id`) whose owner account, `agent_uri`, on-chain metadata, payment
wallet, and external key/handle bindings are recorded on chain.

## Core concepts

- **token_id** — u64 identifying one agent NFT. Accepts a decimal string or integer.
- **token_address** — canonical Base58Check CIS-2 address, e.g. `4PKN5QqU26BVreYq9ZYa`, encoding `(contract, token_id)`.
- **agent_uri + metadata_hash** — off-chain AgentCard JSON URL plus its on-chain SHA-256 anchor. `verify_agent_card` checks they match.
- **agent_wallet** — payment-routing account, separate from the owner. Set with cryptographic proof from the new wallet.
- **external_reference** — binds an agent to an external identity: `Cis8` for crypto keys, `Cis10` for platform handles.
- **network** — every tool takes `network` (`devnet` | `testnet` | `mainnet`), defaulting to the server default (`devnet`). Pass it explicitly for production work.

## Critical rules

- **No keys are held.** All `build_*` tools return a sign-ready payload (wire-hex + schema JSON). The user's wallet signs and submits. Never claim a transaction was sent.
- **Confirm before building state-changing payloads.** Register, transfer, revoke, upgrade, and admin transfers are on-chain and (some) irreversible.
- **Transfer / revoke side effects.** CIS-8004's transfer hook AND revoke both clear `external_reference` and reset `agent_wallet` to None. The new owner must re-run `build_set_external_reference` and `build_set_agent_wallet` afterward.
- **Indexer dependency.** Enumeration tools (`list_agents`, `agents_by_owner`, `agent_history`, `recent_registrations`, `recent_transfers`, `search_agents`) need the sibling indexer. Direct chain reads (`agent_of`, `agent_by_token_address`, `is_active`, `get_metadata`, `get_agent_wallet`, `owner_of_key`) do not. Run `agent_registry_capabilities` first to confirm what's wired in.
- **Cis10 is broken on the live deployment.** External-reference lookups and writes using the `Cis10` (platform-handle) shape currently reject / return null. Use `Cis8` (crypto-key) bindings.
- **Admin-only tools.** `build_upgrade`, `build_transfer_admin`, `build_set_external_registries` are rejected for non-admin callers. `build_transfer_admin` with `new_admin: null` permanently renounces admin and locks the contract against upgrades — irreversible.

## Tool map

### Introspection / health
- `agent_registry_capabilities` — list available tools, what's unavailable and why, and which backends are wired in. **Call first.**
- `contract_info` — addresses, module refs, admin accounts, advertised standards. Confirm you're on the expected instance.
- `network_status` — gRPC endpoint, latest finalised block, indexer sync lag.

### Read / lookup (chain — no indexer)
- `agent_of` — full agent record by `token_id`, or null.
- `agent_by_token_address` — same, by Base58 token address.
- `agent_by_external_reference` — by external binding (`Cis8` key or `Cis10` id).
- `is_active` — `{active, status, exists}` status flag only.
- `get_metadata` — read one on-chain metadata key (hex + text).
- `get_agent_wallet` — current payment wallet (null if unset, e.g. post-transfer).
- `owner_of_key` — CIS-8 lookup: active `Registration` for an external key (`secp256k1-uncompressed`, `secp256k1-compressed`, `ed25519`).
- `verify_agent_card` — fetch `agent_uri`, hash it, compare to on-chain anchor.

### Enumerate / discover (require indexer)
- `list_agents` — all agents, paginated, filter by status/owner.
- `agents_by_owner` — agents owned by a Base58 account.
- `search_agents` — substring match on `agent_uri` + token_id text.
- `agent_history` — every CIS-8004/CIS-2 event for one token, oldest first.
- `recent_registrations` / `recent_transfers` — newest events first.

### Encoding helpers (pure off-chain)
- `token_address` — compute Base58 token address from `(contract_index, subindex, token_id)`.
- `parse_token_address` — decompose a token address into its fields.
- `set_agent_wallet_canonical_bytes` — the 122-byte message the new wallet must sign for `setAgentWallet`.
- `build_cis8_canonical_bytes` — the scheme-agnostic bytes an external key must sign for CIS-8 register.

### Build agent NFT lifecycle (sign-ready payloads)
- `build_agent_card` — compose a complete A2A AgentCard JSON + sha256 from human input. Host the JSON at `agent_uri`, pin the hash via `build_set_agent_uri`.
- `build_register` — mint a new agent NFT to the signer.
- `build_set_agent_uri` — set/update `agent_uri` + `metadata_hash`.
- `build_set_metadata` — write one on-chain metadata key (reserved key `agentWallet` is rejected).
- `build_set_agent_wallet` — set payment wallet; requires the new wallet's signature over the canonical bytes (two authorisations).
- `build_set_external_reference` — set or clear (`null`) the external binding.
- `build_transfer` — CIS-2 transfer of the agent NFT (clears external ref + wallet).
- `build_update_operator` — add/remove CIS-2 operators.
- `build_revoke` — mark agent Revoked (NFT not burned; clears external ref + wallet).

### Build CIS-8 external-key registrations (sign-ready)
- `build_cis8_register` — record a Concordium↔external-key binding; needs proof (see `build_cis8_canonical_bytes`).
- `build_cis8_update_metadata` — replace metadata on an active registration (owner-only).
- `build_cis8_revoke` — revoke a registration (owner-only).

### Admin-only (sign-ready)
- `build_upgrade` — swap module ref + optional migration. Admin-only.
- `build_transfer_admin` — hand over or (`null`) renounce admin. Renounce is irreversible.
- `build_set_external_registries` — repoint linked CIS-8 + CIS-10 contracts atomically. Admin-only.

## Common workflows

**Inspect an agent**
1. `agent_registry_capabilities` → confirm backends.
2. `agent_of` (or `agent_by_token_address`) → record.
3. `verify_agent_card` → confirm off-chain card matches the on-chain hash.

**Register a new agent**
1. Collect name, description, skills, `owner_account` from the user.
2. `build_agent_card` → AgentCard JSON + sha256. User hosts JSON at a public URL.
3. `build_register` (optionally with `agent_uri` + `metadata_hash_hex`) → user signs & submits to mint.
4. After mint, `build_set_agent_uri` with the URL and hash if not set at registration.

**Bind an external crypto key (CIS-8)**
1. `build_cis8_canonical_bytes` → exact bytes for the external key to sign.
2. External key's controller signs them per its scheme (e.g. ethereum-personal-sign).
3. `build_cis8_register` with the signature → user signs & submits.

**Set a payment wallet**
1. `set_agent_wallet_canonical_bytes` → 122-byte message + a deadline.
2. New wallet's controller signs it.
3. `build_set_agent_wallet` with that signature → owner signs & submits (two authorisations).

**Transfer ownership**
1. `build_transfer` → signs & submits.
2. Remind the new owner: external_reference and agent_wallet were cleared — re-run `build_set_external_reference` and `build_set_agent_wallet`.