Hugging Face's logo

bhaskarvilles
/
aipm

ai-agents
multi-agent
interoperability
protocol
sdk
cryptography
python
Model card Files
xet
 Community
aipm / PHASE1_COMPLETE.md
bhaskarvilles's picture
bhaskarvilles
Phase 1 Complete: Core Protocol & Python SDK
2effa7f verified
preview code
|
Raw
History Blame Contribute Delete
9.1 kB

AIPM Phase 1 - Complete ✓

Overview

Phase 1 of the Agent Interoperability Protocol Models (AIPM) ecosystem has been successfully completed. This phase establishes the foundational components for cross-vendor AI agent communication.

Deliverables

1. JSON Schemas ✓

Location: aipm/schemas/

agent_identity.schema

Defines the complete agent identity structure including:

  • Agent ID and organization ID
  • Name and version
  • Public key for encryption
  • Capabilities (skills, models, tools, max context, memory support, languages)
  • Trust score (reliability, accuracy, latency, success rate, interactions)
  • Economic information (cost, currency, billing model)

message_envelope.schema

Defines the standard AIPM message format:

  • Unique message ID (UUID v4)
  • Message type (handshake, task, memory, error, etc.)
  • Protocol version
  • Sender and receiver references
  • Timestamp
  • Priority (low, normal, high, critical)
  • Payload (flexible JSON object)
  • Cryptographic signature

2. Python SDK ✓

Location: aipm/sdk-python/aipm/

Core Modules

models.py - Pydantic data models

  • AgentIdentity - Complete agent profile
  • AgentReference - Minimal agent routing info
  • Capabilities - Skills, models, tools declaration
  • TrustScore - Reputation metrics
  • EconomicInfo - Billing information
  • MessageEnvelope - Standard message wrapper
  • MessageType - Enum of all message types
  • Priority - Message priority levels
  • HandshakePayload - Handshake-specific payload

handshake.py - Handshake protocol state machine

  • HandshakeState - State enumeration
  • HandshakeManager - Manages handshake flow
    • IDLE → HELLO_SENT → CAPABILITY_EXCHANGED → AUTHENTICATED → KEY_EXCHANGED → TRUST_VERIFIED → READY
    • Complete message creation and handling for each step
    • Session management
    • Peer identity tracking

agent.py - Base agent implementation

  • AIPMAgent - Complete agent with handshake support
    • Automatic key generation
    • Message routing and handling
    • Handshake management per peer
    • Task request creation
    • Custom message handler registration

crypto.py - Cryptographic operations

  • CryptoManager - Ed25519 key management
    • Keypair generation
    • Message signing
    • Signature verification
    • Public key fingerprinting
    • Key serialization (Base64)

exceptions.py - Exception hierarchy

  • AIPMException - Base exception
  • HandshakeError - Handshake failures
  • ValidationError - Message validation
  • AuthenticationError - Auth failures
  • EncryptionError - Crypto operations
  • TrustError - Trust verification
  • CapabilityError - Capability negotiation

__init__.py - Clean public API

  • Exports all public classes and functions
  • Version management

3. Handshake Protocol ✓

Complete TLS-inspired handshake flow:

Initiator (Agent A)                Responder (Agent B)
       |                                   |
       |------- HELLO ------------------->|
       |         (identity, session_id)   |
       |                                   |
       |<--- CAPABILITY_EXCHANGE ---------|
       |         (identity, capabilities) |
       |                                   |
       |------- AUTHENTICATION ---------->|
       |         (challenge)              |
       |                                   |
       |<--- PUBLIC_KEY_EXCHANGE ---------|
       |         (public_key)             |
       |                                   |
       |------- TRUST_VERIFICATION ------>|
       |         (trust_score)            |
       |                                   |
       |<--- READY ------------------------|
       |         (status: ready)          |
       |                                   |
       [Both agents now READY]

4. Example Implementation ✓

Location: aipm/examples/

basic_handshake.py

Complete demonstration showing:

  1. Two agent creation (OpenAI-based and LangGraph-based)
  2. Full handshake execution (7 steps)
  3. Capability discovery
  4. Trust score exchange
  5. Task request creation
  6. Pretty-printed message flow

verify_phase1.py

Automated verification script that checks:

  • JSON schemas exist and are valid
  • SDK folder structure is complete
  • All Python modules are importable
  • Example script is present

Project Structure 

aipm/
├── README.md                          # Project overview
├── PHASE1_COMPLETE.md                 # This document
│
├── schemas/                           # JSON schemas
│   ├── agent_identity.schema          # Agent identity spec
│   └── message_envelope.schema        # Message format spec
│
├── sdk-python/                        # Python SDK
│   ├── README.md                      # SDK documentation
│   ├── pyproject.toml                 # Package configuration
│   └── aipm/                          # Main package
│       ├── __init__.py                # Public API
│       ├── models.py                  # Data models
│       ├── handshake.py               # Handshake protocol
│       ├── agent.py                   # Agent implementation
│       ├── crypto.py                  # Cryptography
│       └── exceptions.py              # Exception classes
│
└── examples/                          # Example scripts
    ├── basic_handshake.py             # Full handshake demo
    └── verify_phase1.py               # Verification script

Key Features Implemented

Identity Layer ✓

  • Standardized agent identification
  • Capability declaration
  • Trust score tracking
  • Economic metadata

Secure Handshake ✓

  • 7-step TLS-inspired protocol
  • State machine implementation
  • Session management
  • Peer identity exchange

Cryptographic Foundation ✓

  • Ed25519 keypair generation
  • Message signing infrastructure
  • Signature verification
  • Public key fingerprinting

Extensibility ✓

  • Custom message handler registration
  • Pluggable capability system
  • Vendor-agnostic design

Running the Example

With Dependencies Installed 

cd aipm/sdk-python
pip install -e .
cd ../examples
python basic_handshake.py

Verification Only (No Dependencies) 

cd aipm
python3 examples/verify_phase1.py

Technical Specifications

Protocol Version

  • Version: 1.0.0
  • Format: Semantic versioning (X.Y.Z)

Message Format

  • Encoding: JSON
  • Timestamps: ISO 8601 (UTC)
  • IDs: UUID v4

Cryptography

  • Algorithm: Ed25519 (EdDSA)
  • Key Size: 256 bits
  • Encoding: Base64
  • Fingerprint: SHA256

Dependencies

  • pydantic>=2.0.0 - Data validation
  • cryptography>=41.0.0 - Crypto operations
  • httpx>=0.25.0 - Future HTTP transport

What's Next: Phase 2

Phase 2 will build on this foundation to add:

1. Task Negotiation Framework

  • Accept/decline task mechanism
  • Capability matching
  • Priority-based routing
  • Deadline handling
  • Resource availability checks

2. Cryptographic Message Signing

  • Automatic message signing
  • Signature verification in message processing
  • Key rotation support
  • Certificate chain validation

3. HTTP/WebSocket Transport Layer

  • REST API endpoints
  • WebSocket real-time communication
  • Message queuing
  • Retry logic
  • Connection pooling

4. Enhanced Error Handling

  • Detailed error codes
  • Retry strategies
  • Circuit breakers
  • Timeout management

5. Testing Framework

  • Unit tests for all modules
  • Integration tests for handshake
  • Mock agent implementations
  • Performance benchmarks

Success Metrics

✅ 100% Schema Coverage - All protocol components defined
✅ Complete State Machine - 7-step handshake implemented
✅ Type Safety - Full Pydantic validation
✅ Crypto Foundation - Ed25519 signing ready
✅ Extensibility - Plugin architecture for handlers
✅ Documentation - Comprehensive README and examples
✅ Verification - Automated testing script

Architecture Decisions

Why Ed25519?

  • Modern, secure, fast
  • Small key size (32 bytes)
  • Deterministic signatures
  • Wide library support

Why Pydantic?

  • Runtime validation
  • Type hints integration
  • JSON serialization
  • Excellent error messages

Why State Machine for Handshake?

  • Clear protocol flow
  • Easy to debug
  • Prevents invalid transitions
  • Extensible for future states

Why Separate Identity and Reference?

  • Minimize message size
  • Enable routing without full identity
  • Support identity caching
  • Privacy-preserving

Compliance

✅ Adheres to AIPM architecture specification
✅ JSON Schema Draft 2020-12 compliant
✅ Python 3.9+ compatible
✅ Type-hint complete
✅ Apache 2.0 licensed

Contributors

Built by the AIPM team to establish the first open ecosystem for AI agent interoperability.

License

Apache 2.0 - See LICENSE file for details

Phase 1 Status: ✅ COMPLETE
Ready for Phase 2: ✅ YES
Date Completed: July 6, 2026
Next Review: Phase 2 Planning Session