A2A SSH Skill

Agent-to-Agent delegation over SSH.
Zero dependencies. Works today.

_{Inspired by Google Agent2Agent (A2A) Protocol · Built for builders who need it working today}

English · 中文

📖 What is A2A SSH Skill?

A2A SSH Skill is a practical, zero-dependency Python tool for Agent2Agent (A2A)-style delegation over SSH.

Google A2A defines a protocol for how agents should talk (JSON-RPC, HTTP endpoints, Agent Cards). A2A SSH Skill makes agents actually work across your machines right now — using nothing but SSH, Python, and a CLI AI tool like Claude Code or Codex.

Others are writing protocol specifications — your agents are already getting work done.
Others are deploying Agent Cards and webhook endpoints — your agents already finished the task.
Others spent a week on interoperability — you spent 5 minutes editing agents.json.

🔄 Why A2A SSH Skill?

A2A SSH Skill and Google A2A are complementary, not competing:

• Google A2A → "How should agents discover each other across the internet?"
• A2A SSH Skill → "How do I make my machines work together as an AI team right now?"

TL;DR — Need your machines working as an AI team? A2A SSH Skill, 5 minutes. Need a public agent marketplace? Use Google A2A.

🎬 Demo

┌───────────────────────────────────────────────────────────────┐
│                                                               │
│  $ python agent.py send gpu-server \                          │
│      --cwd "/home/user/ml-project" \                          │
│      --text "Run the failing tests and fix them" \            │
│      --mode write --wait                                      │
│                                                               │
│  ── Behind the scenes ──────────────────────────────────────  │
│                                                               │
│  1. Creates job dir → prompt.md + meta.json + runner.py       │
│  2. Uploads to gpu-server via SCP                             │
│  3. Launches runner.py via SSH                                │
│  4. Remote AI reads code, runs tests, fixes bugs              │
│  5. Writes reply.md + log.md                                  │
│  6. Results fetched back                                      │
│                                                               │
│  ✅ [OK]                                                      │
│  Fixed 3 failing tests in src/utils.py:                       │
│  - test_parse_config: added missing default value             │
│  - test_validate_input: boundary check was off by one         │
│  - test_export_data: file path used wrong separator           │
│                                                               │
└───────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites: Python 3.10+ · SSH access · A CLI AI tool on remote machine

# 1. Clone (no pip install needed!)
git clone https://github.com/YonganZhang/a2a-ssh-skill && cd a2a-ssh-skill

# 2. Configure
cp agents.example.json agents.json    # Edit: SSH hosts, claude_path, python_path

# 3. Send your first task
python agent.py send my-server \
  --cwd "/home/user" \
  --text "Check Python version and disk usage" \
  --mode read --wait

As a Claude Code Skill — copy to ~/.claude/skills/ and Claude auto-discovers it:

cp -r a2a-ssh-skill ~/.claude/skills/agent-task-delegate

💡 Use Cases

✨ Features

🏗️ Architecture

  ┌───────────────┐                         ┌───────────────┐
  │   Node A       │          SSH            │   Node B       │
  │   (Dispatcher) │                         │   (Executor)   │
  │                │  1. Upload job (SCP)     │                │
  │   agent.py     │ ─────────────────────►  │   runner.py    │
  │                │                         │                │
  │   Creates:     │  2. Launch runner (SSH)  │   Invokes:     │
  │   · prompt.md  │ ─────────────────────►  │   AI CLI tool  │
  │   · meta.json  │                         │   via stdin     │
  │   · runner.py  │  3. Fetch results (SCP) │                │
  │                │ ◄─────────────────────  │   Produces:    │
  │   Receives:    │                         │   · reply.md   │
  │   · reply.md   │                         │   · log.md     │
  │   · log.md     │                         │   · output/    │
  └───────────────┘                         └───────────────┘

Execution Paths

Topology

A2A SSH Skill works with any number of nodes in any topology:

Two-Node            Three-Node (Relay)              Fan-Out
                                                     ┌─► 🖥️ Server A
💻 ── SSH ──► 🖥️    💻 ── SSH ──► 🖥️ ── WSL ──► 🐧    💻 ──┼─► 🖥️ Server B
                                                     └─► 🐧 GPU Box

Add nodes by editing agents.json. Each node auto-detects its identity. Any node can be sender, receiver, or both.

⚙️ How It Works

Job Protocol

Every delegation creates a self-contained job directory:

jobs/<job-id>/
├── prompt.md      📝 Task instructions
├── meta.json      ⚙️ Metadata (target, mode, timeout)
├── runner.py      🏃 Bundled executor
├── reply.md       ✅ Result: [OK] or [FAILED]
├── log.md         📋 Execution trace
├── input/         📁 Input files (optional)
└── output/        📁 Generated artifacts (optional)

Everything is plain text. Debug with cat. Monitor with watch. Archive with tar. Search with grep.

Flow

You type a command
  └─► agent.py detects your node, creates job dir
        └─► SCP uploads to remote machine
              └─► SSH launches runner.py
                    └─► runner.py pipes prompt to AI via stdin
                          └─► AI executes task, writes reply.md + log.md
                                └─► agent.py fetches results via SCP
                                      └─► You see the result

Safety

💰 Token Efficiency: ~90% Less

Concrete example — checking disk usage on a remote server:

🧪 End-to-End Test Results

Test environment: Windows laptop ↔ Windows Server ↔ Ubuntu Linux — but A2A SSH Skill supports any OS combination over SSH.

# Run tests yourself
./tests/e2e-test.sh my-server

📝 Configuration

{
  "agents": {
    "my-laptop": {
      "hostname_patterns": ["MY-LAPTOP-*"],
      "platform": "windows",
      "claude_path": "claude",
      "python_path": "python",
      "job_root": "C:/Users/me/exchange/jobs",
      "ssh_from": { "gpu-server": "laptop-ssh" }
    },
    "gpu-server": {
      "hostname_patterns": ["GPU-*"],
      "platform": "linux",
      "claude_path": "/usr/local/bin/claude",
      "python_path": "python3",
      "job_root": "/home/user/exchange/jobs",
      "ssh_from": { "my-laptop": "gpu-ssh" }
    }
  }
}

See agents.example.json for a commented template · examples/ for ready-to-use setups.

📌 Commands

# Delegate a task
python agent.py send <target> --cwd <path> --text "task" --mode read|write [--wait] [--timeout-sec N]

# Check status
python agent.py status <job-id> [--detail]

# Clean up old jobs
python agent.py cleanup [--days 7]

🗺️ Roadmap

Design Principles

❓ FAQ

🤝 Contributing

Contributions welcome! Bug reports, feature requests, docs, code — all appreciated.

1. Fork → 2. Branch → 3. Commit → 4. Push → 5. PR

📄 License

MIT — use it however you want.