Pebbling: Agent-to-Agent Communication

✨ Imagine a world where AI agents collaborate effortlessly and securely—no passport 🚫, no boundaries 🌐.

That’s Pebbling 🐧.An open source, secured protocol for agent-to-agent communication.

🚀 Powered by Decentralised Identifiers (DIDs) 🔑, secured conversations with mutual TLS (mTLS) 🔒, and a lightweight yet powerful communication protocol built on JSON-RPC 2.0 ⚡️—Pebbling is paving the way for the next generation of collaborative AI systems. 🌟🤖

🌟 Features

Pebbling helps your AI agents talk to each other seamlessly:

🔒 Super Secure - Your agents exchange secrets safely (with built-in mTLS)

🧩 Plug-and-Play - Just decorate your agent and it's ready to communicate

⚡ Lightning Fast - Quick connections without the weight

🌐 Works Everywhere - Connect any agents, regardless of their programming language

🔄 Reliable Communication - Messages always arrive correctly and in order

📦 Installation

# Using pip
pip install pebbling

# Using uv (recommended)
uv add pebbling

🚀 Quick Start

🍪 Quick Start with Cookiecutter Template

The fastest way to get started with Pebbling is using our cookiecutter template:

# Create a new Pebbling project
uv tool run cookiecutter cookiecutter-pebbling/

Follow the interactive prompts:

[1/4] name (pebble_project): my_weather_agent
[2/4] description (): A weather forecasting agent
[3/4] pebbling_email (): your.email@example.com
[4/4] Select agent_framework
  1 - none
  2 - agno
  3 - crew
  4 - langchain
  Choose from [1/2/3/4] (1): 2

After project creation:

🎉 Project created successfully!

🐧 Welcome to Pebbling — powered by the Pebble CLI.
Next steps:
  1️⃣  cd 'my_weather_agent'
  2️⃣  Set it up using uv: 📦
      uv sync
  3️⃣  Run your agent locally: 💻
      PYTHONPATH=src python3 -m my_weather_agent
      or
      python3 src/<filename.py>
  4️⃣  Deploy your agent: 🚀
      pebble launch

🤖 Selected agent framework: agno
Need help? See README.md for details. ✨

Setup and run your agent:

# Navigate to your project
cd my_weather_agent

# Create virtual environment
uv venv --python 3.12.9
source .venv/bin/activate

# Install dependencies
uv sync

# Run your agent
uv run src/pebble_agent.py

Your agent will start with full Pebbling capabilities:

• ✅ Automatic DID identity generation
• ✅ Security setup with mTLS certificates
• ✅ Agent manifest creation
• ✅ Local server running on http://localhost:8030
• ✅ OpenInference observability integration

📂 Template Repository: cookiecutter-pebbling

Manual Setup - Pebblify an Agent

from pebbling import pebblify

@pebblify(name="My Agent", description="A simple agent", version="1.0.0")
def my_agent(message: str) -> str:
    return "Hello, Agent!"

# You're now ready to communicate securely between agents!

Pebblify a Agno Agent

from pebbling import pebblify
from agno.agent import Agent
from agno.models.openai import OpenAIChat

@pebblify(name="Agno Agent", description="A helpful assistant", version="1.0.0")
def agno_agent(message: str) -> str:
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        instructions="You are a helpful assistant.",
    )
    result = agent.run(message)
    return result.to_dict()["content"]

# You're now ready to communicate securely between agents!

🎥 Agent in Action

📊 Interactive Diagrams

🔄 Sequence Diagram Open the interactive version of this sequence diagram in MermaidChart

🏗️ Orchestration Diagram Open the interactive version of this orchestration diagram in MermaidChart

🛠️ Supported Agent Frameworks

Pebbling is tested and integrated with popular agent frameworks:

• ✅ Agno
• 🔜 CrewAI (Coming soon)
• 🔜 AutoGen (Coming soon)
• 🔜 LangChain (Coming soon)
• 🔜 LlamaIndex (Coming soon)

Want integration with your favorite framework? Let us know on Discord!

📖 Documentation

For comprehensive documentation, visit docs.pebbling.ai

🧪 Testing

Pebbling is thoroughly tested with a test coverage of over 83%:

# Run tests with coverage
make test
make coverage

🤝 Contributing

We welcome contributions! Here's how to get started:

# Clone the repository
git clone https://github.com/Pebbling-ai/pebble.git
cd pebble

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
pre-commit install

# Run tests
make test

Please see our Contributing Guidelines for more details.

👥 Maintainers

For more details about maintainership, including how to become a maintainer, see our MAINTAINERS.md file.

📜 License

Pebbling is proudly open-source and licensed under the MIT License.

💻 Example Use Cases

Pebbling is ideal for:

• Multi-Agent Collaboration: Enable efficient, secure teamwork between LLM-driven agents.
• Decentralized Autonomous Systems: Build reliable decentralized AI networks.
• Secure Agent Ecosystems: Create ecosystems where agents from different providers interact seamlessly.
• Distributed AI Workflows: Coordinate agents across distributed computing environments.

🎉 Community

We 💛 contributions! Whether you're fixing bugs, improving documentation, or building demos — your contributions make Pebbling better.

• Join our Discord for discussions and support
• Star the repository if you find it useful!

🚧 Roadmap

Here's what's next for pebbling:

• GRPC transport support
• Integration with Hibiscus (DiD - Decentralized Identifiers, mTLS)
• Detailed tutorials and guides
• Expanded multi-framework support

Suggest features or contribute by joining our Discord!

📋 FAQ

Can Pebble be deployed locally? Yes! Pebble supports local development as well as cloud-based deployments.

Does Pebble support other languages besides Python? Absolutely! Any language that can implement JSON-RPC and mTLS is compatible.

How scalable is Pebble? Pebble's minimal dependencies and protocol simplicity ensure scalability across complex agent ecosystems.

⭐ Star History

Built with ❤️ by the Pebbling team from Amsterdam 🌷.

We’re excited to see what you’ll build with Pebble! Our dream is a world where agents across the internet communicate securely, openly, and effortlessly.

Have questions, ideas, or just want to chat? Join our Discord community— we’d love to hear from you! Together, let’s lay the foundation for the next generation of AI agent collaboration.

Happy Pebbling! 🐧🚀✨