Registry Sync Tool Documentation

Overview

The RegistrySyncTool synchronizes runtime agent registries with persistent registry files, ensuring all agents have proper cryptographic identities and signatures. It maintains consistency between in-memory and on-disk registries.

File: tools/registry_sync_tool.py Class: RegistrySyncTool Version: 1.0.0 Status: ✅ Active

Architecture

Design Principles

Bidirectional Sync: Syncs runtime ↔ persistent registries

Identity Management: Ensures all agents have cryptographic identities

Signature Validation: Validates cryptographic signatures

Automatic Key Creation: Creates missing keys automatically

Comprehensive Logging: Detailed sync operation logging

Core Components

class RegistrySyncTool(BaseTool):
    - memory_agent: MemoryAgent - For workspace management
    - coordinator_ref: CoordinatorAgent - Runtime registry access
    - agents_registry_path: Path - Persistent agents registry
    - tools_registry_path: Path - Persistent tools registry

Available Actions

1. sync_all

Synchronizes all registries comprehensively.

Parameters:

action (str, default: "sync_all"): Action to perform

validate_signatures (bool, default: True): Validate signatures

update_missing_keys (bool, default: True): Create missing keys

Returns:

Tuple[bool, Dict[str, Any]]  # (success, sync_results)

Sync Results:

{
    "agents_synced": int,
    "keys_updated": int,
    "signatures_validated": int,
    "errors": List[str]
}

2. update_keys

Updates missing public keys for all agents.

Parameters:

action (str, required): "update_keys"

Returns:

Tuple[bool, Dict[str, Any]]  # (success, update_results)

Update Results:

{
    "keys_created": int,
    "keys_updated": int,
    "errors": List[str]
}

Usage

Sync All Registries

from tools.registry_sync_tool import RegistrySyncTool
from agents.memory_agent import MemoryAgent
from orchestration.coordinator_agent import CoordinatorAgent

tool = RegistrySyncTool(
    memory_agent=memory_agent,
    coordinator_ref=coordinator
)
Sync all registries
success, results = await tool.execute(
    action="sync_all",
    validate_signatures=True,
    update_missing_keys=True
)

if success:
    print(f"Agents synced: {results['agents_synced']}")
    print(f"Keys updated: {results['keys_updated']}")

Update Missing Keys

# Update missing keys only
success, results = await tool.execute(action="update_keys")

if success:
    print(f"Keys created: {results['keys_created']}")

Sync Process

Step 1: Load Registries

Loads runtime registry from coordinator

Loads persistent registry from file

Compares entries

Step 2: Identity Management

Gets or creates public keys

Updates missing identities

Tracks key creation

Step 3: Entry Updates

Updates persistent entries with runtime info

Adds missing public keys

Generates signatures

Updates metadata

Step 4: Validation

Validates signatures (if enabled)

Checks identity consistency

Reports validation results

Step 5: Save Registry

Saves updated persistent registry

Updates metadata

Logs sync completion

Features

1. Automatic Key Creation

Creates missing identities:

Generates public/private key pairs

Signs registration messages

Updates registry entries

2. Signature Validation

Validates cryptographic signatures:

Verifies agent identities

Ensures registry integrity

Reports validation status

3. Bidirectional Sync

Syncs both directions:

Runtime → Persistent: Updates file with runtime state

Persistent → Runtime: Could update runtime (future)

4. Error Handling

Comprehensive error handling:

Continues on individual failures

Collects all errors

Reports error summary

Limitations

Current Limitations

One-Way Sync: Only syncs runtime → persistent

No Conflict Resolution: No handling of conflicts

No Rollback: No rollback capability

Basic Validation: Simple signature validation

No Incremental: Full sync each time

Recommended Improvements

Bidirectional Sync: Sync both directions

Conflict Resolution: Handle conflicts intelligently

Incremental Sync: Only sync changes

Enhanced Validation: Comprehensive validation

Rollback Support: Rollback failed syncs

Change Detection: Detect what changed

Sync History: Track sync operations

Integration

With Coordinator Agent

Accesses runtime registry:

runtime_registry = self.coordinator_ref.agent_registry

With IDManagerAgent

Manages identities:

id_manager = await IDManagerAgent.get_instance()
public_key = await id_manager.get_public_address(agent_id)

Examples

Regular Sync

# Regular sync operation
success, results = await tool.execute("sync_all")

if results["errors"]:
    print(f"Sync completed with {len(results['errors'])} errors")

Key Update Only

# Update missing keys without full sync
success, results = await tool.execute("update_keys")

Technical Details

Dependencies

core.id_manager_agent.IDManagerAgent: Identity management

agents.memory_agent.MemoryAgent: Workspace management

orchestration.coordinator_agent.CoordinatorAgent: Runtime registry

core.bdi_agent.BaseTool: Base tool class

Registry File Paths

Agents: data/config/official_agents_registry.json

Tools: data/config/official_tools_registry.json

Signature Generation

Signatures created for:

Agent registration

Registry updates

Identity verification

Future Enhancements

Bidirectional Sync: Full two-way synchronization

Change Detection: Only sync what changed

Conflict Resolution: Intelligent conflict handling

Sync History: Track all sync operations

Rollback Support: Rollback failed syncs

Real-Time Sync: Continuous synchronization

Multi-System Sync: Sync across systems

---