# Inter-Agent Protocol (I.A.P.) v1.0.0

## Overview

The **Inter-Agent Protocol (I.A.P.)** is a lightweight, WebSocket-based communication standard that enables autonomous AI agents to discover, negotiate, and collaborate seamlessly across different frameworks and platforms.

I.A.P. solves the fragmentation problem in multi-agent systems by providing a common language for:
- **Agent identification and capability broadcasting**
- **Dynamic task negotiation and bidding**
- **Stateful context transfer between agents**
- **Real-time performance monitoring**

## Core Concepts

### 1. Agent Identity

Every agent in the network has a unique `AgentId` and advertises its capabilities through a structured handshake process.

```typescript
interface AgentHandshake {
  agentId: string;
  name: string;
  version: string;
  framework?: string;
  capabilities: AgentCapability[];
  maxConcurrentTasks?: number;
  currentLoad?: number;
  protocolVersion: string;
}
```

### 2. Capabilities

Capabilities define what an agent can do. Each capability includes:
- **Type**: Predefined category (text generation, code execution, etc.)
- **Input/Output schemas**: JSON Schema definitions
- **Performance metrics**: Estimated cost and latency

```typescript
interface AgentCapability {
  id: string;
  type: CapabilityType;
  name: string;
  description: string;
  inputSchema?: Record<string, any>;
  outputSchema?: Record<string, any>;
  estimatedCost?: number;
  averageLatency?: number;
}
```

### 3. Task Negotiation

Tasks flow through a bidding process:
1. **Proposal**: An agent proposes a task with requirements
2. **Bidding**: Capable agents submit bids with cost/latency estimates
3. **Assignment**: Router selects the optimal agent
4. **Execution**: Assigned agent executes and returns results

### 4. Context Transfer

Agents can pass stateful information without re-summarizing:

```typescript
interface ContextTransfer {
  fromAgent: AgentId;
  toAgent: AgentId;
  taskId: TaskId;
  contextType: string;
  data: Record<string, any>;
  embedding?: number[];  // For semantic indexing
  compression?: 'gzip' | 'brotli' | 'none';
}
```

## Protocol Flows

### Connection Flow

```mermaid
sequenceDiagram
    participant Agent
    participant Router
    
    Agent->>Router: HANDSHAKE (capabilities)
    Router->>Agent: HANDSHAKE_ACK (session)
    loop Maintain Connection
        Agent->>Router: HEARTBEAT
    end
    Agent->>Router: DISCONNECT
```

**Steps:**
1. Agent sends `HANDSHAKE` with capabilities
2. Router responds with `HANDSHAKE_ACK` and session ID
3. Agent sends periodic `HEARTBEAT` messages
4. Agent sends `DISCONNECT` when leaving

### Discovery Flow

```mermaid
sequenceDiagram
    participant Agent A
    participant Router
    
    Agent A->>Router: CAPABILITY_DISCOVERY
    Router->>Agent A: CAPABILITY_RESPONSE (all agents)
```

**Steps:**
1. Agent sends `CAPABILITY_DISCOVERY` request
2. Router responds with all available agents and their capabilities

### Task Negotiation Flow

```mermaid
sequenceDiagram
    participant Agent A
    participant Router
    participant Agent B
    participant Agent C
    
    Agent A->>Router: TASK_PROPOSAL
    Router->>Agent B: TASK_PROPOSAL (broadcast)
    Router->>Agent C: TASK_PROPOSAL (broadcast)
    Agent B->>Router: TASK_BID
    Agent C->>Router: TASK_BID
    Router->>Agent B: TASK_ASSIGNMENT (best bid)
    Agent B->>Router: TASK_ACCEPTANCE
    Agent B->>Router: TASK_RESULT
    Router->>Agent A: TASK_RESULT
```

**Steps:**
1. Agent A proposes a task to the router
2. Router broadcasts to all capable agents
3. Agents B and C submit bids
4. Router assigns to best bidder (Agent B)
5. Agent B accepts and executes
6. Agent B returns result to router
7. Router forwards result to Agent A

### Context Transfer Flow

```mermaid
sequenceDiagram
    participant Agent A
    participant Router
    participant Agent B
    
    Agent A->>Router: CONTEXT_TRANSFER
    Router->>Agent B: CONTEXT_TRANSFER
```

**Steps:**
1. Agent A sends context to router
2. Router forwards to Agent B
3. Agent B continues execution with transferred state

## Message Types

### Core Messages

| Type | Direction | Purpose |
|------|-----------|---------|
| `HANDSHAKE` | Agent → Router | Initial connection and capability registration |
| `HANDSHAKE_ACK` | Router → Agent | Connection acknowledgment |
| `CAPABILITY_DISCOVERY` | Agent → Router | Query available capabilities |
| `CAPABILITY_RESPONSE` | Router → Agent | List of agents and capabilities |
| `TASK_PROPOSAL` | Agent → Router | Propose a task for execution |
| `TASK_BID` | Agent → Router | Bid on a proposed task |
| `TASK_ASSIGNMENT` | Router → Agent | Assign task to winning bidder |
| `TASK_ACCEPTANCE` | Agent → Router | Accept assigned task |
| `TASK_REJECTION` | Agent → Router | Reject assigned task |
| `CONTEXT_TRANSFER` | Agent ↔ Agent | Transfer execution context |
| `TASK_RESULT` | Agent → Router | Return task execution result |
| `ERROR` | Any → Any | Error notification |
| `HEARTBEAT` | Agent → Router | Keep-alive signal |
| `DISCONNECT` | Agent → Router | Graceful disconnect |

## Message Structure

All I.A.P. messages follow a common structure:

```typescript
interface IAPMessage {
  messageId: string;           // Unique message identifier
  type: MessageType;           // Message type
  from: AgentId;               // Sender
  to: AgentId | 'router';      // Recipient
  timestamp: string;           // ISO 8601 timestamp
  protocolVersion: string;     // Protocol version (1.0.0)
  payload: any;                // Type-specific payload
  correlationId?: string;      // For request-response tracking
  metadata?: Record<string, any>;
}
```

## Usage Examples

### 1. Agent Registration

```typescript
import { 
  createHandshakeMessage, 
  AgentHandshake, 
  CapabilityType 
} from './protocol';

const handshake: AgentHandshake = {
  agentId: 'agent_langchain_001',
  name: 'LangChain Code Assistant',
  version: '1.0.0',
  framework: 'LangChain',
  protocolVersion: '1.0.0',
  capabilities: [
    {
      id: 'code_gen_python',
      type: CapabilityType.CODE_EXECUTION,
      name: 'Python Code Generation',
      description: 'Generate and execute Python code',
      estimatedCost: 100,
      averageLatency: 2000
    }
  ],
  maxConcurrentTasks: 5,
  currentLoad: 0.2
};

const message = createHandshakeMessage(handshake);
websocket.send(JSON.stringify(message));
```

### 2. Task Proposal

```typescript
import { 
  createTaskProposalMessage, 
  TaskProposal, 
  CapabilityType,
  generateTaskId 
} from './protocol';

const proposal: TaskProposal = {
  taskId: generateTaskId(),
  proposerId: 'agent_main_001',
  description: 'Analyze CSV file and generate summary statistics',
  requiredCapability: CapabilityType.DATA_ANALYSIS,
  input: {
    filePath: '/data/sales.csv',
    operations: ['mean', 'median', 'std']
  },
  maxLatency: 5000,
  maxCost: 200,
  priority: 7
};

const message = createTaskProposalMessage(proposal);
websocket.send(JSON.stringify(message));
```

### 3. Submitting a Bid

```typescript
import { createTaskBidMessage, TaskBid } from './protocol';

const bid: TaskBid = {
  taskId: 'task_abc123',
  bidderId: 'agent_data_001',
  estimatedLatency: 3000,
  estimatedCost: 150,
  confidence: 0.95,
  queueDepth: 2,
  notes: 'Specialized in CSV analysis with pandas'
};

const message = createTaskBidMessage(bid, 'agent_data_001');
websocket.send(JSON.stringify(message));
```

### 4. Context Transfer

```typescript
import { createContextTransferMessage, ContextTransfer } from './protocol';

const transfer: ContextTransfer = {
  fromAgent: 'agent_a',
  toAgent: 'agent_b',
  taskId: 'task_xyz789',
  contextType: 'conversation_history',
  data: {
    messages: [
      { role: 'user', content: 'Hello' },
      { role: 'assistant', content: 'Hi there!' }
    ],
    metadata: { sessionId: 'session_123' }
  },
  compression: 'none'
};

const message = createContextTransferMessage(transfer);
websocket.send(JSON.stringify(message));
```

### 5. Message Validation

```typescript
import { validateIAPMessage, validateHandshake } from './protocol';

// Validate complete message
const result = validateIAPMessage(incomingMessage);
if (!result.valid) {
  console.error('Validation errors:', result.errors);
}

// Validate specific payload
const handshakeResult = validateHandshake(handshakePayload);
if (!handshakeResult.valid) {
  console.error('Invalid handshake:', handshakeResult.errors);
}
```

## State Management

### Flow States

The protocol defines a state machine for tracking agent and task states:

```typescript
enum FlowState {
  DISCONNECTED = 'disconnected',
  HANDSHAKING = 'handshaking',
  CONNECTED = 'connected',
  IDLE = 'idle',
  DISCOVERING = 'discovering',
  PROPOSING = 'proposing',
  BIDDING = 'bidding',
  ASSIGNING = 'assigning',
  EXECUTING = 'executing',
  TRANSFERRING_CONTEXT = 'transferring_context',
  COMPLETING = 'completing',
  ERROR = 'error',
  DISCONNECTING = 'disconnecting'
}
```

### Task Lifecycle

```typescript
enum TaskStatus {
  PROPOSED = 'proposed',
  BIDDING = 'bidding',
  ASSIGNED = 'assigned',
  IN_PROGRESS = 'in_progress',
  COMPLETED = 'completed',
  FAILED = 'failed',
  CANCELLED = 'cancelled'
}
```

### State Transitions

```typescript
import { 
  createFlowContext, 
  transitionFlow, 
  MessageType 
} from './protocol';

// Create initial context
const context = createFlowContext('agent_001');

// Transition through states
const newContext = transitionFlow(context, MessageType.HANDSHAKE);
// context.currentState: DISCONNECTED -> HANDSHAKING
```

## Performance Considerations

### Message Size

- Keep payloads under 10KB for optimal performance
- Use compression for larger context transfers
- Consider chunking for very large data transfers

### Latency Targets

- **Handshake**: < 100ms
- **Discovery**: < 50ms
- **Task Assignment**: < 100ms
- **Context Transfer**: < 200ms (depends on size)

### Heartbeat Interval

Recommended: 30 seconds
- Balances connection monitoring with network overhead
- Adjust based on network reliability

## Error Handling

### Error Codes

| Code | Description | Recoverable |
|------|-------------|-------------|
| `VALIDATION_ERROR` | Message validation failed | Yes |
| `CAPABILITY_NOT_FOUND` | Required capability unavailable | Yes |
| `TASK_TIMEOUT` | Task execution exceeded deadline | No |
| `AGENT_OVERLOAD` | Agent at maximum capacity | Yes |
| `CONTEXT_TRANSFER_FAILED` | Context transfer failed | Yes |
| `PROTOCOL_VERSION_MISMATCH` | Incompatible protocol versions | No |

### Error Message Example

```typescript
import { createErrorMessage, ErrorMessage } from './protocol';

const error: ErrorMessage = {
  code: 'TASK_TIMEOUT',
  message: 'Task execution exceeded 5000ms deadline',
  relatedTaskId: 'task_abc123',
  details: { actualLatency: 6500 },
  recoverable: false
};

const message = createErrorMessage(
  'agent_001',
  'router',
  error,
  'msg_original_123'
);
```

## Security Considerations

### Authentication

- Implement agent authentication at the WebSocket layer
- Use JWT tokens or API keys for agent identification
- Validate agent identity during handshake

### Authorization

- Enforce capability-based access control
- Validate task permissions before assignment
- Audit all agent actions

### Data Protection

- Encrypt sensitive data in context transfers
- Use checksums to verify data integrity
- Implement rate limiting to prevent abuse

## Integration with Subconscious Router

The I.A.P. protocol is designed to work seamlessly with the Subconscious Router's semantic caching:

1. **Semantic Interception**: Router checks incoming tasks against vector database
2. **Cache Hit**: Return cached result (< 50ms) without agent execution
3. **Cache Miss**: Route to appropriate agent via I.A.P. negotiation
4. **Result Caching**: Store result with embedding for future hits

```typescript
// Pseudo-code for router integration
async function handleTaskProposal(proposal: TaskProposal) {
  // Check semantic cache
  const cached = await semanticCache.query(proposal.description);
  
  if (cached && cached.similarity > 0.95) {
    // Instant response from cache
    return cached.result;
  }
  
  // Route via I.A.P. negotiation
  const bids = await broadcastTaskProposal(proposal);
  const winner = selectBestBid(bids);
  const result = await assignAndExecute(winner, proposal);
  
  // Cache for future
  await semanticCache.store(proposal.description, result);
  
  return result;
}
```

## Framework Integration

### LangChain

```typescript
import { LangChainAgent } from '@langchain/core';
import { IAPClient } from './iap-client';

const agent = new LangChainAgent(/* config */);
const iapClient = new IAPClient('ws://router:8080');

await iapClient.connect({
  agentId: 'langchain_001',
  name: 'LangChain Agent',
  capabilities: agent.getCapabilities()
});
```

### CrewAI

```python
from crewai import Agent
from iap_client import IAPClient

agent = Agent(role="researcher", goal="Research topics")
iap_client = IAPClient("ws://router:8080")

await iap_client.connect(
    agent_id="crewai_001",
    name="CrewAI Researcher",
    capabilities=agent.get_capabilities()
)
```

### AutoGPT

```typescript
import { AutoGPTAgent } from 'autogpt';
import { IAPClient } from './iap-client';

const agent = new AutoGPTAgent(/* config */);
const iapClient = new IAPClient('ws://router:8080');

await iapClient.connect({
  agentId: 'autogpt_001',
  name: 'AutoGPT Agent',
  capabilities: agent.listCapabilities()
});
```

## Versioning

The protocol follows semantic versioning (MAJOR.MINOR.PATCH):

- **MAJOR**: Breaking changes to message structure or flow
- **MINOR**: New message types or optional fields
- **PATCH**: Bug fixes and clarifications

Current version: **1.0.0**

### Version Compatibility

- Agents must specify `protocolVersion` in handshake
- Router validates version compatibility (same major version)
- Incompatible versions receive `PROTOCOL_VERSION_MISMATCH` error

## Future Enhancements

### v1.1.0 (Planned)
- Message batching for high-throughput scenarios
- Streaming responses for long-running tasks
- Agent reputation and trust scoring

### v2.0.0 (Roadmap)
- Direct agent-to-agent communication (bypass router)
- Multi-router federation
- Advanced consensus mechanisms

## Contributing

Contributions to the I.A.P. specification are welcome! Please submit issues and pull requests to the [GitHub repository](https://github.com/subconscious-router/iap).

## License

MIT License - See LICENSE file for details

## References

- [Subconscious Router Technical Specification](../../TECHNICAL_SPEC.md)
- [WebSocket Protocol (RFC 6455)](https://tools.ietf.org/html/rfc6455)
- [JSON Schema](https://json-schema.org/)
- [Semantic Versioning](https://semver.org/)