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

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

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

### Run Example

```bash
# 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

```python
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

```python
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

```python
# 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

```python
# 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:

```python
# 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:

```python
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:

```python
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:
```bash
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:
```python
agent.handshake_managers[peer_key].reset()
```

### Validation Error

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

**Solution:** Use semantic versioning:
```python
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.