Identity Sync Tool Documentation

Overview

The IdentitySyncTool provides comprehensive identity synchronization for agents and tools. It manages cryptographic identities, synchronizes registries, validates identities, and ensures all entities have proper cryptographic signatures.

File: tools/identity_sync_tool.py Class: IdentitySyncTool Version: 1.0.0 Status: ✅ Active

Architecture

Design Principles

Comprehensive Sync: Syncs both agents and tools

Identity Management: Creates and manages cryptographic identities

Signature Validation: Validates cryptographic signatures

Registry Integration: Updates registries automatically

Status Reporting: Provides detailed status reports

Core Components

class IdentitySyncTool(BaseTool):
    - memory_agent: MemoryAgent - For workspace management
    - agents_registry_path: Path - Agents registry file
    - tools_registry_path: Path - Tools registry file

Available Actions

1. sync_all

Synchronizes all identities (agents and tools).

Parameters:

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

Returns:

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

2. sync_agents

Synchronizes agent identities only.

Parameters:

action (str, required): "sync_agents"

Returns:

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

3. sync_tools

Synchronizes tool identities only.

Parameters:

action (str, required): "sync_tools"

Returns:

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

4. validate

Validates all identities.

Parameters:

action (str, required): "validate"

Returns:

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

5. status

Gets identity status report.

Parameters:

action (str, required): "status"

Returns:

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

Usage

Sync All Identities

from tools.identity_sync_tool import IdentitySyncTool
from agents.memory_agent import MemoryAgent

tool = IdentitySyncTool(memory_agent=memory_agent)
Sync all identities
success, results = await tool.execute(action="sync_all")

if success:
    print(f"Agents updated: {results['agents']['updated']}")
    print(f"Tools updated: {results['tools']['updated']}")

Validate Identities

# Validate all identities
success, validation = await tool.execute(action="validate")

if success:
    print(f"Valid agents: {validation['agents']['valid']}")
    print(f"Valid tools: {validation['tools']['valid']}")

Get Status

# Get status report
success, status = await tool.execute(action="status")

if success:
    print(f"Agents with identity: {status['agents']['with_identity']}/{status['agents']['total']}")
    print(f"Tools with identity: {status['tools']['with_identity']}/{status['tools']['total']}")

Sync Process

Agent Sync

Load agents registry

For each agent:

- Check if has valid identity - Get or create public key - Generate signature - Update registry entry

Save updated registry

Tool Sync

Load tools registry

For each tool:

- Check if has valid identity - Create tool entity ID (tool_{tool_id}) - Get or create public key - Generate signature - Update registry entry

Save updated registry

Features

1. Automatic Identity Creation

Creates missing identities:

Generates public/private key pairs

Signs registration messages

Updates registry entries

2. Signature Generation

Generates signatures for:

Agent registration: agent_registration:{agent_id}

Tool registration: tool_registration:{tool_id}:{version}

3. Validation

Validates identities:

Checks public key existence

Verifies signature presence

Validates key consistency

Reports issues

4. Status Reporting

Provides comprehensive status:

Total agents/tools

With identity count

Percentage coverage

Wallet key count

Limitations

Current Limitations

No Rollback: No rollback capability

Basic Validation: Simple validation only

No Conflict Resolution: No conflict handling

Single System: Single system only

No Incremental: Full sync each time

Recommended Improvements

Rollback Support: Rollback failed syncs

Enhanced Validation: Comprehensive validation

Conflict Resolution: Handle conflicts

Incremental Sync: Only sync changes

Multi-System: Support distributed systems

Change Detection: Detect what changed

Sync History: Track sync operations

Integration

With IDManagerAgent

Manages identities:

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

With Memory Agent

Logs operations:

await self.memory_agent.log_process(
    process_name="identity_sync_comprehensive",
    data=results,
    metadata={"tool": "identity_sync_tool"}
)

Examples

Complete Identity Management

# 1. Sync all identities
await tool.execute("sync_all")

2. Validate identities
await tool.execute("validate")

3. Get status
await tool.execute("status")

Technical Details

Dependencies

core.id_manager_agent.IDManagerAgent: Identity management

core.belief_system.BeliefSystem: Belief system

agents.memory_agent.MemoryAgent: Workspace management

core.bdi_agent.BaseTool: Base tool class

Registry Files

Agents: data/config/official_agents_registry.json

Tools: data/config/official_tools_registry.json

Entity ID Format

Agents: {agent_id}

Tools: tool_{tool_id}

Future Enhancements

Rollback Support: Rollback failed syncs

Enhanced Validation: Comprehensive validation

Incremental Sync: Only sync changes

Multi-System: Distributed sync

Change Detection: Detect changes

Sync History: Track operations

Real-Time Sync: Continuous synchronization

---