# ALP v0.1.0 — Agent Language Protocol Specification

**Status:** Draft
**Version:** 0.1.0
**Date:** March 2026

## Abstract

ALP (Agent Language Protocol) is an open protocol for peer-to-peer AI agent discovery, communication, and skill exchange. It enables autonomous agents to find each other on a network, browse each other's capabilities, and transfer executable skills that **mutate during transfer** to adapt to the receiving agent's environment.

ALP is transport-agnostic by design. This specification defines the v0.1 wire format, discovery mechanism, exchange flow, and lineage tracking system.

## 1. Design Principles

- **Zero config.** Agents discover each other automatically via UDP broadcast. No central registry.
- **Skills are the unit of exchange.** Not prompts, not weights, not tokens. Executable code that does something.
- **Mutation is the default.** When a skill transfers between agents, it adapts to the receiver's environment. This is not a bug. This is evolution.
- **Lineage is permanent.** Every skill carries its full ancestry. You can trace a skill back to its origin across any number of transfers.
- **Security is explicit.** Foreign code is scanned, shown to the user, and sandboxed before installation. No silent execution.

## 2. Identity

Each agent has a persistent identity stored locally:

```json
{
  "agent_id": "alp-<uuid4>",
  "alias": "darsh",
  "created_at": "2026-03-18T12:00:00Z",
  "alp_version": "0.1.0"
}
```

The `agent_id` is generated once and never changes. The `alias` is optional and human-set. Identity is stored at `~/.alive/identity.json` in the reference implementation.

## 3. Agent Card

An agent card is the live representation of an agent on the network:

```json
{
  "agent_id": "alp-<uuid>",
  "alias": "darsh",
  "skills": [
    {"name": "price_checker", "description": "...", "confidence": 0.94, "generation": 1}
  ],
  "skill_count": 15,
  "integrations": ["telegram", "browser", "scheduler"],
  "alp_version": "0.1.0",
  "uptime_seconds": 3600
}
```

The skills list is rebuilt dynamically from the agent's skill registry on every request.

## 4. Discovery

### 4.1 UDP Broadcast (LAN)

Agents announce themselves via UDP broadcast on port **51966** (0xCAFE):

```json
{"type": "announce", "agent": <AgentCard>, "port": 8484}
```

- Broadcast interval: **10 seconds**
- Peer timeout: **30 seconds** without heartbeat
- Socket options: `SO_BROADCAST`, `SO_REUSEADDR`
- Agents filter their own broadcasts by `agent_id`

### 4.2 Manual Connect (WAN)

For cross-network connections:

```
GET http://<ip>:<port>/alp/card
```

Returns the agent card. The connecting agent adds it as a permanent (non-expiring) peer.

## 5. HTTP Endpoints

The ALP server runs on port **8484** (configurable). All responses are JSON.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/alp/card` | GET | Returns this agent's AgentCard |
| `/alp/skills` | GET | Returns skill catalog (no code) |
| `/alp/skill/<name>` | GET | Returns full skill package |

### 5.1 Skill Package Format

```json
{
  "name": "price_checker",
  "code": "<skill.py source>",
  "test_code": "<test_skill.py source or null>",
  "metadata": { "...": "..." },
  "birth_story": { "...": "..." },
  "description": "<SKILL.md contents>",
  "generation": 3,
  "lineage": ["alp-aaa", "alp-bbb", "alp-ccc"]
}
```

## 6. Skill Exchange Flow

When Agent B pulls a skill from Agent A:

```
B                                A
|--- GET /alp/skill/foo -------->|
|<--- skill package -------------|
|                                |
| 1. Security scan               |
| 2. Show code to user           |
| 3. User approves (or rejects)  |
| 4. LLM adapts to local env     |
| 5. Sandbox test                 |
| 6. Save with lineage           |
```

### 6.1 Security Scan

Before any installation, the receiving agent scans for:
- `eval()`, `exec()`, `__import__()`
- `subprocess` with `shell=True`
- `os.system()`, `shutil.rmtree()`
- Sensitive path access (`/etc/`, `/root/`, `C:\`)
- Network calls to non-allowlisted domains

Results are shown to the user before the install prompt.

### 6.2 Mutation (Adaptation)

The receiving agent's LLM adapts the foreign code to the local environment:
- Wires in available integrations (Telegram, webhooks, browser)
- Replaces hardcoded values specific to the original user
- Adds composition hooks for complementary local skills
- Preserves the `run(input_data: dict) -> dict` interface

### 6.3 Lineage Tracking

After installation, the skill's metadata is updated:

```json
{
  "generation": 4,
  "lineage": ["alp-aaa", "alp-bbb", "alp-ccc", "alp-ddd"],
  "mutations": ["+telegram alerts", "+local timezone"],
  "network_evolved": true,
  "received_from": "192.168.1.50:8484",
  "received_at": "2026-03-19T22:14:28Z"
}
```

Generation increments by 1 on each transfer. Lineage appends the receiving agent's ID. Mutations describe what changed.

## 7. Conversation Log

All network activity is logged in human-readable format:

```
[2026-03-19 22:14:03] ANNOUNCE -> Broadcasting to network (15 skills)
[2026-03-19 22:14:05] DISCOVERED -> @friend (12 skills) at 192.168.1.50:8585
[2026-03-19 22:14:28] INSTALLED -> pdf_parser (gen 4) from @friend
```

Event types: `ANNOUNCE`, `DISCOVERED`, `CONNECTED`, `BROWSE`, `SKILL_REQUEST`, `SENT`, `PULLING`, `MUTATING`, `MUTATED`, `TESTING`, `TESTED`, `TEST_FAILED`, `INSTALLED`.

## 8. Future Directions

- **Skill reputation:** Crowdsourced confidence scores across the network
- **Selective sharing:** Mark skills as private, public, or friends-only
- **Skill dependencies:** Pull dependency chains automatically
- **WebSocket transport:** Real-time bidirectional communication
- **DHT discovery:** Distributed hash table for internet-scale peer finding
- **Skill markets:** Exchange skills for compute credits

## 9. Reference Implementation

The reference implementation is [Alive](https://github.com/darshanahirrao/Alive), a self-evolving AI agent in Python. ALP is designed to be language-agnostic. Any agent that speaks the wire format can join the network.

## License

This specification is released under the MIT License.
