Billeteras de los Agentes

¿Qué Es una Billetera de Agente?

Una billetera de agente es una billetera cuya clave privada es mantenida y utilizada por un proceso autónomo (un sistema de IA, un servicio automatizado o un agente programático) en lugar de directamente por una persona.

A nivel de protocolo, una billetera de agente es indistinguible de cualquier otra billetera. Tiene una dirección, firma transactions y aparece en cada bloque en el que participa. Lo que la distingue es:

1. Propiedad: es creada por una billetera humana (u organizacional) y está subordinada a esta.
2. Tipo de entity: está asociado a una entity SERVICE, DEVICE o AGENT (tipos hoja sin hijos).
3. Alcance: sus permisos están acotados por capabilities que definen exactamente qué puede hacer, cuántas veces y hasta cuándo.
4. Trazabilidad: cada transaction que firma se le atribuye de forma permanente y, a través de ella, a toda la cadena de principales que autorizaron su existencia.

---

Por Qué Billeteras de los Agentes en Lugar de API Keys

Los sistemas autónomos tradicionales operan con API keys compartidas o cuentas de servicio:

API Key Compartida	Billetera de Agente
Sin atribución por acción; cualquier proceso que use la clave se ve igual.	Cada acción es firmada por una dirección de billetera específica.
Los registros son mutables; cualquier administrador autorizado puede alterarlos o eliminarlos.	Las transactions son inmutables una vez confirmadas en un bloque.
El alcance de la clave es amplio, de todo o nada para el servicio.	Las capabilities acotan la clave a acciones específicas, direcciones de recursos, conteos y vencimiento por altura de bloque.
La revocación requiere rotar la clave y actualizar a todos los consumidores.	Deshabilitar la billetera padre se propaga al instante a todas las billeteras hijas de los agentes.
La pista de auditoría reside en los registros de la aplicación, aislada por sistema.	La pista de auditoría está on-chain, visible para cualquier auditor autorizado sin acceso al sistema.
Vulnerable a la computación poscuántica (la mayoría de los esquemas de API key usan criptografía simétrica o clásica).	Las cadenas ML-DSA-87 son seguras poscuánticamente por construcción.

La pista de auditoría es el valor principal. Una billetera de agente produce transactions con autoría verificable: cada una firmada criptográficamente, con cross-Merkleization junto con el resto de la salida del council y anclada en una prueba de punto de control STARK que un auditor puede verificar sin acceso a ningún sistema activo.

---

Obtención de una Billetera del Agente

"Obtener" (procuring) una billetera de agente significa: una billetera humana (u organizacional) crea una billetera hija y una entity AGENT correspondiente, acota las capabilities de esa billetera y entrega el archivo de la clave privada al proceso autónomo.

Paso 1: Generar la Billetera de Agente

go run ./cmd/generate_wallets --type=mldsa87

Esto crea un archivo .ukey (la clave privada del agente). El principal humano conserva la custodia de este archivo y lo proporciona al proceso autónomo en tiempo de ejecución.

Paso 2: Registrar la Billetera

go run ./cmd/register_wallets

Se envía TX_CREATE_WALLET para incorporar la billetera. La billetera que envía la transaction (la billetera padre) pasa a ser el Parent de la nueva billetera.

Paso 3: Crear la Entity AGENT

{
    "name": "alice-research-agent",
    "entityType": "AGENT",
    "parent": "<alice-personal-entity-address>",
    "metadata": {
        "description": "Autonomous market research assistant",
        "pref:budget_monthly": "5000"
    }
}

La entity AGENT es la identidad organizacional de este proceso autónomo. Es hija de la entity PERSONAL de Alice, lo que convierte a Alice en el principal organizacional.

Paso 4: Vincular la Billetera de Agente a la Entity AGENT

{
    "entityAddress": "<agent-entity-address>",
    "walletAddress": "<agent-wallet-address>",
    "role": "admin",
    "permissions": {
        "ManageWallets": false,
        "ManageChildren": false,
        "ManageAccessList": false,
        "ManageMetadata": true,
        "TransferOwnership": false
    }
}

La billetera de agente queda vinculada a su entity. ManageMetadata: true permite al agente actualizar sus propios metadatos (p. ej., registrar su última tarea). Los demás permisos se retienen; el agente no puede crear sub-entities ni gestionar sus propias listas de acceso.

Paso 5: Adjuntar Capabilities

Las capabilities son la compuerta principal de lo que una billetera de agente puede hacer. Sin una capability explícita para una acción, la billetera no puede realizarla, incluso si el contrato por lo demás la permitiría. Para la referencia completa de campos, los tipos de acción y los patrones, ver Capabilities.

Ejemplo: acotar un agente a un contrato y un token:

{
    "walletAddress": "<agent-wallet-address>",
    "capabilities": [
        {
            "action": "contract:invoke",
            "resource": "<council-contract-address>",
            "limits": { "maxInvocations": 500 },
            "notAfter": 100000
        },
        {
            "action": "token:transfer",
            "resource": "<work-token-address>",
            "limits": { "maxAmount": "10000" },
            "notAfter": 100000
        }
    ]
}

---

El Ciclo de Vida de la Billetera del Agente

CREATION
    Human parent wallet → TX_CREATE_WALLET → agent wallet on-chain
    Human parent → CREATE_ENTITY (AGENT type) → agent entity
    Human parent → LINK_WALLET_TO_ENTITY → wallet linked to agent entity
    Human parent → ALTER_WALLET (capabilities) → agent scoped

OPERATION
    Agent wallet signs TX → submits via SDK or HTTP
    Node validates: ancestry enabled? capabilities match? scope not exceeded?
    Transaction executes → state committed → block produced
    Helix checkpoint anchors the block into the STARK proof chain

ADMINISTRATION
    Human parent → ALTER_WALLET (enable=false) → agent suspended
    Human parent → ALTER_ENTITY (enabled=false) → agent entity suspended
    Human parent → ALTER_WALLET (new capabilities) → agent re-scoped
    Human parent → ALTER_WALLET (enable=true) → agent re-activated

TERMINATION
    Human parent → ALTER_WALLET (enable=false, permanent)
    Agent wallet address remains in history; its transactions are permanent
    Recovery config handles succession if the parent wallet is lost

---

La Pista de Auditoría

Cada transaction que envía la billetera de agente queda registrado de forma permanente:

• Quién: la dirección de la billetera de agente (y, a través de wallet.Parent, su principal humano).
• Qué: el tipo de transaction, el payload y el destino (contrato, entity, token).
• Cuándo: la altura de bloque en la que se confirmó.
• En qué contexto: la jerarquía de entities en ese momento (ORG → DEPT → PERSONAL → AGENT).
• Bajo qué alcance: la capability que autorizó la acción.
• Orden demostrable: mediante la cadena de Merkle de bloques, anclada por los puntos de control STARK de Helix.

Un auditor con las claves públicas del council y las pruebas de punto de control puede reconstruir y verificar esta pista sin ningún acceso al sistema activo, al SDK ni a los archivos de billetera.

---

Jerarquías Multiagente

Un agente puede poseer sub-billeteras, pero solo si su tipo de entity lo permite (AGENT no permite hijos). Si se necesita una jerarquía de agentes, se recomienda utilizar entities PERSONAL o SERVICE anidadas:

PERSONAL: "alice"
├── AGENT: "alice-orchestrator" (manages sub-tasks)
│   (Cannot own child agents; AGENT is a leaf type)
│
└── SERVICE: "alice-pipeline-service"
    (Can own child SERVICE/DEVICE/AGENT entities if SERVICE hierarchy is desired)

Para la orquestación multiagente, en la que un agente coordina a otros, el patrón recomendado es:

• El agente orquestador posee la billetera padre.
• Las billeteras de los agentes de subtareas son hijas de la billetera orquestadora.
• Las capabilities de las billeteras de subtareas se acotan a los contratos y acciones específicos que necesitan.
• El agente orquestador puede deshabilitar a los agentes de subtareas deshabilitando su billetera padre.

---

Billetera de Agente en el Patrón de Votación del Council

La demo board-council ilustra el patrón de colaboración humano+agente más común: cada miembro humano del council delega en un agente de IA para votar, los agentes votan de forma autónoma dentro de una ventana de tiempo y un presidente humano finaliza on-chain.

Para la descripción completa del modelo de gobernanza, ver Pattern 3: Hybrid Council. Para un recorrido completo de extremo a extremo, ver Board Council Demo.