Quickstart - Pebbling Docs 🐧

Quick Start with Cookiecutter Template

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

Use Cookiecutter Template (Recommended)

Create a new Pebbling project using our template:

uv tool run cookiecutter https://github.com/Pebbling-ai/cookiecutter-pebbling

Follow the interactive prompts:

[1/4] name (pebble_project): my_agent
[2/4] description (): My first Pebbling 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 creation, navigate to your project and set it up:

cd my_agent
uv venv --python 3.12.9
source .venv/bin/activate
uv sync

Run your agent:

uv run src/pebble_agent.py

You’ll see output like:

╭──────────────╮
│ Pebbling 🐧  │
╰──────────────╯
🚀 Starting Pebbling Server...
📡 Server URL: http://localhost:8030
🐧 Penguine ID: ba23326c671c4c96a6613c9ef34f169e

Manual Setup (Alternative)

If you prefer to set up manually, follow these steps:

Prerequisites

Install Python dependencies

Set up OpenAI API key

Create your first agent

Create agent configuration

Create a simple_agent_config.json file with your agent configuration:

{
  "author": "Your Name",
  "name": "Simple Agent",
  "description": "A basic AI agent for simple question answering",
  "version": "1.0.0",
  "recreate_keys": true,
  "skills": [
    {
      "name": "question-answering",
      "description": "Ability to answer basic questions",
      "version": "1.0.0"
    }
  ],
  "capabilities": {
    "reasoning": true,
    "code_execution": false,
    "web_search": false,
    "file_operations": false,
    "multimodal": false
  },
  "agent_trust": "low",
  "kind": "agent",
  "debug_mode": true,
  "debug_level": 2,
  "monitoring": false,
  "telemetry": false,
  "num_history_sessions": 5,
  "deployment": {
    "url": "http://localhost:8030",
    "expose": true,
    "protocol_version": "1.0.0",
    "proxy_urls": ["https://simple.pebbling.ai"],
    "cors_origins": ["*"]
  },
  "storage": {
    "type": "memory",
    "connection_string": "postgresql+asyncpg://user@localhost:5432/pebble-example"
  },
  "scheduler": {
    "type": "memory"
  }
}

Create your agent

Create a Python file with your pebblified agent:

import json
import os
from typing import List

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

from pebbling.common.models import DeploymentConfig, SchedulerConfig, StorageConfig
from pebbling.common.protocol.types import AgentCapabilities, AgentSkill
from pebbling.penguin.pebblify import pebblify


def load_config(config_path: str):
    """Load configuration from JSON with defaults."""
    current_dir = os.path.dirname(os.path.abspath(__file__))
    full_path = os.path.join(current_dir, config_path)
    
    with open(full_path, 'r') as f:
        config = json.load(f)
        return config

# Load configuration
simple_config = load_config("simple_agent_config.json")

@pebblify(
    author=simple_config["author"],
    name=simple_config.get("name"),
    description=simple_config.get("description"),
    version=simple_config.get("version", "1.0.0"),
    recreate_keys=simple_config.get("recreate_keys", True),
    skills=[AgentSkill(**skill) for skill in simple_config.get("skills", [])],
    capabilities=AgentCapabilities(**simple_config["capabilities"]),
    agent_trust=simple_config.get("agent_trust"),
    kind=simple_config.get("kind", "agent"),
    debug_mode=simple_config.get("debug_mode", False),
    debug_level=simple_config.get("debug_level", 1),
    monitoring=simple_config.get("monitoring", False),
    telemetry=simple_config.get("telemetry", True),
    num_history_sessions=simple_config.get("num_history_sessions", 10),
    documentation_url=simple_config.get("documentation_url"),
    extra_metadata=simple_config.get("extra_metadata", {}),
    deployment_config=DeploymentConfig(**simple_config["deployment"]),
    storage_config=StorageConfig(**simple_config["storage"]),
    scheduler_config=SchedulerConfig(**simple_config["scheduler"]),
)
def simple_agent(messages: List[str]) -> str:
    """Regular function example - returns single result."""
    
    # Use any framework internally
    agent = Agent(
        instructions="Provide a simple response to the user's message",
        model=OpenAIChat(id="gpt-4o")
    )
    
    result = agent.run(input=messages)
    
    return result.to_dict()['content']

Run your agent

Start your agent

Test your agent

Next steps

Explore more advanced features and agent types:

Agent Types

Learn about different agent function types: async generators, coroutines, generators, and regular functions.

Configuration

Understand all configuration options for your agents.

Deployment

Deploy your agents to production environments.

API Reference

Explore the complete API reference.

Get Started

​Quick Start with Cookiecutter Template

​Manual Setup (Alternative)

​Prerequisites

​Create your first agent

​Run your agent

​Next steps