QUICK_START.md

AIPM Quick Start Guide

Get started with the Agent Interoperability Protocol Models in 5 minutes.

---

🎮 Try the Demo (Easiest)

Visit the interactive demo - no installation required!

URL: https://huggingface.co/spaces/bhaskarvilles/aipm-demo

1. Configure two agents with custom properties
2. Click "Execute Handshake"
3. Watch the 7-step protocol in real-time
4. See capability discovery and trust verification

---

💻 Install Locally

Prerequisites

• Python 3.9+
• pip

Installation

# Clone the repository
git clone https://huggingface.co/bhaskarvilles/aipm
cd aipm

# Install the SDK
cd sdk-python
pip install -e .

Run Example

# Go to examples directory
cd ../examples

# Run the basic handshake demo
python basic_handshake.py

You'll see a complete handshake between an OpenAI agent and a LangGraph agent!

---

🔧 Basic Usage

Create an Agent

from aipm import AIPMAgent, AgentIdentity, Capabilities

# Define your agent's identity
identity = AgentIdentity(
    agent_id="my-agent-001",
    organization_id="my-org",
    name="My AI Agent",
    version="1.0.0",
    capabilities=Capabilities(
        skills=["text-generation", "code-review"],
        models=["gpt-4"],
        tools=["code-interpreter"],
        max_context=128000,
        memory_support=True
    )
)

# Create the agent
agent = AIPMAgent(identity)

Initiate Handshake

from aipm import AgentReference

# Reference another agent
peer = AgentReference(
    agent_id="peer-agent-001",
    organization_id="peer-org"
)

# Start handshake
hello_msg = agent.initiate_handshake(peer)

Process Messages

# Process incoming message
response = agent.process_message(hello_msg)

# Check if handshake is complete
if agent.is_ready(peer):
    print("Handshake complete! Ready to communicate.")
    
    # Get peer's identity
    peer_identity = agent.get_peer_identity(peer)
    print(f"Connected to: {peer_identity.name}")
    print(f"Peer skills: {peer_identity.capabilities.skills}")

Send Task Request

# Once handshake is complete, delegate a task
task_msg = agent.create_task_request(
    peer,
    task_description="Analyze this dataset",
    priority="high",
    deadline="2026-07-10T00:00:00Z"
)

---

📚 Learn More

Documentation

• README.md - Project overview and features
• PHASE1_COMPLETE.md - Technical specifications
• BLOG_POST.md - Vision and use cases
• API Reference - See sdk-python/README.md

Examples

• basic_handshake.py - Complete handshake demo
• verify_phase1.py - Verification script

Community

• Discussions: https://huggingface.co/bhaskarvilles/aipm (Community tab)
• Issues: Report bugs or request features
• Contributing: See CONTRIBUTING.md (coming soon)

---

🔐 Security Note

AIPM uses Ed25519 cryptographic signatures for security:

# Keys are auto-generated
agent = AIPMAgent(identity, auto_generate_keys=True)

# Public key is included in identity
print(f"Public key: {agent.identity.public_key}")

---

🚀 What's Next?

Explore Features

1. Capability Discovery - See what agents can do
2. Trust Scores - Evaluate agent reliability
3. Secure Sessions - Cryptographic handshake
4. Economic Info - Understand costs

Phase 2 (Coming Soon)

• HTTP/WebSocket transport
• Task negotiation framework
• Automatic message signing
• Memory exchange protocol

---

💡 Quick Tips

Tip 1: Message Types

AIPM supports these message types:

• Handshake: HELLO, CAPABILITY_EXCHANGE, AUTHENTICATION, etc.
• Tasks: TASK_REQUEST, TASK_ACCEPT, TASK_DECLINE
• Memory: MEMORY_SHARE, MEMORY_REQUEST
• Errors: ERROR

Tip 2: Custom Handlers

Register custom message handlers:

def handle_custom_message(msg):
    print(f"Received: {msg.type}")
    return response_msg

agent.register_handler(MessageType.CUSTOM, handle_custom_message)

Tip 3: Trust Scores

Update trust scores based on interactions:

identity.trust_score.reliability = 0.99
identity.trust_score.success_rate = 0.98
identity.trust_score.total_interactions += 1

---

❓ Common Issues

Import Error

ModuleNotFoundError: No module named 'aipm'

Solution: Make sure you installed the SDK:

cd sdk-python && pip install -e .

Handshake Failed

HandshakeError: Cannot send HELLO from state HELLO_SENT

Solution: Each agent pair needs separate handshake managers. Create new agent instances or reset the handshake:

agent.handshake_managers[peer_key].reset()

Validation Error

ValidationError: version must be in format X.Y.Z

Solution: Use semantic versioning:

version="1.0.0"  # ✓ Correct
version="1.0"    # ✗ Wrong

---

📞 Get Help

• Documentation: Read the guides in the repository
• Examples: Check examples/ directory
• Discussions: Ask questions on HF
• Issues: Report bugs on the repository

---

🎯 Next Steps

1. ✅ Try the interactive demo
2. ✅ Install SDK locally
3. ✅ Run the examples
4. ✅ Read the documentation
5. ✅ Join the community discussions
6. ✅ Build your first integration

---

Happy Building! 🚀

Visit https://huggingface.co/bhaskarvilles/aipm for more information.