Agent Semantic Protocol

Semantic Interoperability Layer for AI Agents — a lightweight extension of MCP (Model Context Protocol) built for the era of agentic AI meshes.

Status: Active development — v0.1 core is stable. See docs/plans/ for the current implementation roadmap.

What Is Agent Semantic Protocol?

Agent Semantic Protocol enables AI agents to communicate by meaning, not schema. Instead of exchanging rigid JSON tool calls, agents share semantic intent vectors — compact float32 embeddings that describe goals in a shared latent space. Any agent that understands the vector space can negotiate, delegate, and collaborate — without pre-registered APIs.

Core Concepts

Comparison: Agent Semantic Protocol vs. MCP vs. A2A

Repository Layout

agent-semantic-protocol/
├── proto/agent-semantic-protocol.proto          # Protobuf message definitions (reference)
├── core/
│   ├── types.go                 # Go struct definitions
│   ├── encoding.go              # Protobuf wire encode/decode (no codegen required)
│   ├── did.go                   # DID generation, verification, trust graph
│   ├── handshake.go             # Cryptographic handshake protocol
│   ├── negotiation.go           # Intent negotiation + cosine ranking
│   ├── discovery.go             # Capability discovery registry
│   ├── encoding_test.go         # Unit tests (encoding, DID, cosine, discovery)
│   └── signing_test.go          # Unit tests (per-message Ed25519 signing)
├── p2p/
│   ├── host.go                  # libp2p AgentHost wrapper
│   ├── host_test.go             # Integration tests (handshake, intent, announce)
│   └── protocol.go              # WorkflowOrchestrator, convenience helpers
├── picoclaw/
│   └── client.go                # Adapter for Picoclaw AI assistant API
├── examples/
│   ├── simple-handshake/main.go # Two agents handshake over TCP
│   └── negotiation-demo/main.go # Full intent → negotiation → workflow loop
├── docs/
│   ├── spec.md                  # Protocol specification
│   └── plans/                   # Versioned implementation plans
└── .github/workflows/ci.yml    # GitHub Actions CI

Quick Start

Prerequisites

• Go 1.22+
• git

Install & Run

git clone https://github.com/agent-semantic-protocol-protocol/agent-semantic-protocol
cd agent-semantic-protocol

go mod download   # fetch all dependencies (including libp2p)

# Run the handshake demo
go run ./examples/simple-handshake/main.go

# Run the negotiation + workflow demo
go run ./examples/negotiation-demo/main.go

Expected output (handshake demo)

╔══════════════════════════════════════════════╗
║     Agent Semantic Protocol v0.1 — Simple Handshake Demo     ║
╚══════════════════════════════════════════════╝

✓ Agent Alpha started
  Peer ID : 12D3KooW...
  DID     : did:agent-semantic-protocol:3a7f...
  Caps    : [nlp reasoning intent-parsing]

✓ Agent Beta started
  ...

── Performing Agent Semantic Protocol Handshake ─────────────────────────────────────
[Beta] ← Handshake from "agent-alpha"  caps=[nlp reasoning intent-parsing]

[Alpha] ✓ Handshake complete!
  Peer caps  : [code-generation math vector-search storage]
  Protocol   : 1.0.0

Run Tests

make test
# or: go test -v -race ./...

Using Agent Semantic Protocol in Your Go Project

import (
    "github.com/agent-semantic-protocol-protocol/agent-semantic-protocol/core"
    "github.com/agent-semantic-protocol-protocol/agent-semantic-protocol/p2p"
)

// 1. Create an agent identity
agent, _ := core.NewAgent("my-agent", []string{"nlp", "summarisation"})

// 2. Start a P2P host
host, _ := p2p.NewHost(ctx, agent)

// 3. Register intent handler
host.OnIntent(func(peerID peer.ID, intent *core.IntentMessage) *core.NegotiationResponse {
    h := core.DefaultNegotiationHandler(agent)
    resp, _ := h(intent)
    return resp
})

// 4. Send an intent to a known peer
intent, _ := core.CreateIntent(agent,
    []float32{0.8, 0.2, 0.9}, // embedding
    []string{"summarisation"},
    "Summarise this document",
)
resp, _ := host.SendIntent(ctx, targetPeerID, intent)

In-Process (No Network)

bus := core.NewNegotiationBus()
bus.Register("agent-b", core.DefaultNegotiationHandler(agentB))

intent, _ := core.CreateIntent(agentA, vector, []string{"code-generation"}, payload)
resp, _ := bus.Negotiate("agent-b", intent)

Picoclaw Integration

client := picoclaw.NewClient("https://api.picoclaw.io",
    picoclaw.WithAPIKey("pk_..."),
    picoclaw.WithAgentID("my-picoclaw-agent"),
)
// Register as a Agent Semantic Protocol negotiation handler
bus.Register("picoclaw", client.AsNegotiationHandler())

Regenerate Protobuf Bindings (Optional)

The core/ package uses protowire directly and does not require generated code. If you want the generated *.pb.go files for gRPC or reflection:

make proto   # requires protoc + protoc-gen-go

Contributing

1. Fork the repo and create a feature branch.
2. Run make test and make lint — all must pass.
3. Open a Pull Request with a clear description of the change.
4. Follow conventional commits (feat:, fix:, docs:, …).

Please read docs/spec.md before proposing wire-format changes — backward compatibility is critical.

Roadmap

Completed

Planned

See docs/plans/ for detailed implementation plans with exact file paths and test commands.

License

MIT — see LICENSE.