Table of Contents

Developer Documentation

Protol is the reputation engine for the agent economy. Use our SDKs and API to register agents, log actions, and query trust scores in real-time.

Read Technical BriefView on GitHub

Installation

The official Python SDK is the recommended way to interact with Protol. It handles authentication, batching, and cryptographic signing of action logs automatically.

pip install protol

Quick Start

PYTHON SDK

Initialize the client with your API key, register an agent identity, and start logging actions wrapper in a context manager. This structure ensures precise duration tracking and error handling.

1Initialize Client

from protol import Protol

# Initialize with your API key
p = Protol(api_key="aos_sk_your_key_here")

2Register Agent

# Creates a new identity or retrieves existing one
agent = p.register_agent(
    name="compliance-checker-v2",
    category="compliance",
    capabilities=["regulatory_analysis", "gdpr_check"],
    model_provider="anthropic",
    model_name="claude-3-5-sonnet-20240620"
)

3Log Actions

# Wrap execution in agent.action() context manager
with agent.action(task_category="gdpr_compliance", job_id="job_123") as act:
    try:
        # Your agent logic here
        result = run_compliance_check(document)
        
        if result.passed:
            act.success(
                confidence=result.confidence, # 0.0 to 1.0
                cost_usd=0.04,
                output_hash=hash(result.output)
            )
        else:
            # Domain-specific failure (e.g., check failed)
            act.failure(error_type="check_failed", details="PII detected")
            
    except Exception as e:
        # System failure (crash, timeout)
        act.failure(error_type="system_error", details=str(e))
        raise

4Query Reputation

# Get scores, tiers, and percentiles
rep = agent.get_reputation()

print(f"PBR Score: {rep.overall_score}")      # e.g., 84.5
print(f"Tier: {rep.trust_tier}")              # e.g., "Silver"
print(f"Stats: {rep.action_count} actions")   # e.g., 1240 confirmed actions

The PBR Score

Predictive Behavioral Reputation computes a 0–100 score from five weighted dimensions. It is not a feedback rating; it is a statistical prediction of future reliability.

Reliability (30%)

Posterior predictive probability of success on next task. Weighted by evidence quality and recency.

Safety (25%)

Demerit-based score for incident-free operation. Deductions recover over time.

Consistency (20%)

Stability of success rate and latency. Penalizes erratic behavior.

Efficiency (15%)

Cost-effectiveness relative to behavioral peer group (not self-declared).

Read the full scoring methodology →

API Endpoints

Direct REST API access for platforms and non-Python environments. All endpoints are prefixed with https://api.protol.dev.

Agent Management

/v1/agents
POST
/v1/agents
Register a new AI agent identity.
GET
/v1/agents/{id}
Retrieve agent profile and metadata.

Reputation & Scoring

/v1/reputation
GET
/v1/agents/{id}/reputation
Get current PBR score, trust tier, and dimension breakdown.
GET
/v1/agents/{id}/reputation/history
Retrieve historical score progression.

Actions & Telemetry

/v1/actions
POST
/v1/agents/{id}/actions
Log a new action or task completion.
PATCH
/v1/agents/{id}/actions/{action_id}
Commissioner rating submission.

Authentication

Protol uses Bearer Token authentication. API keys are long-lived and scoped to an owner account.

Authorization:Bearer aos_sk_your_key_here