Skip to content

API.md

Latest commit

 

History

History
214 lines (158 loc) · 6.64 KB

API.md

File metadata and controls

214 lines (158 loc) · 6.64 KB

API Reference

Full reference for the agentveil Python SDK.

AVPAgent

Create / Load

from agentveil import AVPAgent

# Create new agent (generates Ed25519 keypair, saves to ~/.avp/agents/)
agent = AVPAgent.create("https://agentveil.dev", name="my_agent")
agent.register(display_name="My Agent")

# Load existing agent
agent = AVPAgent.load("https://agentveil.dev", name="my_agent")

# Mock mode (no server, real crypto)
agent = AVPAgent.create(mock=True, name="test_agent")

Trust Decision

# Should I delegate a task to this agent?
decision = agent.can_trust("did:key:z6Mk...", min_tier="trusted")
# {"allowed": true, "tier": "trusted", "risk_level": "low", "reason": "Agent meets trusted requirement"}

# With task-specific scoring
decision = agent.can_trust("did:key:z6Mk...", min_tier="basic", task_type="code_quality")
# Also returns task_score and task_confidence for the specific category

Reputation

rep = agent.get_reputation("did:key:z6Mk...")
# {"score": 0.85, "confidence": 0.72, "interpretation": "good"}

# Bulk: get scores for up to 100 agents at once
bulk = agent.get_reputation_bulk(["did:key:z6Mk1...", "did:key:z6Mk2..."])
# {"total": 2, "found": 2, "results": [{"did": "...", "found": true, "reputation": {...}}, ...]}

# Per-category scores
tracks = agent.get_reputation_tracks("did:key:z6Mk...")
# {"code_quality": {"score": 0.91, ...}, "task_completion": {"score": 0.85, ...}}

# Score velocity — trend and alerts
vel = agent.get_reputation_velocity("did:key:z6Mk...")
# {"trend": "declining", "alert": true, "velocity": {"1d": -0.05, "7d": -0.12, "30d": 0.08}}

# Trust Gate — check current tier and rate limits
# GET /v1/reputation/{did}/gate
# {"tier": "trusted", "requests_per_minute": 60, "score": 0.72, "is_seed": false}

Verifiable Credentials (Offline Verification)

# Get signed credential (Ed25519, TTL-based)
cred = agent.get_reputation_credential("did:key:z6Mk...", risk_level="low")

# Verify offline — no API call needed
is_valid = AVPAgent.verify_credential(cred)  # static method

TTL by risk level: low = 60 min, medium = 15 min, high = 5 min.

Attestations

agent.attest(
    to_did="did:key:z6Mk...",
    outcome="positive",    # positive / negative / neutral
    weight=0.9,            # 0.0 - 1.0
    context="task_completion",
    evidence_hash="sha256_of_interaction_log",
)

# Batch: submit up to 50 attestations at once (partial success)
result = agent.attest_batch([
    {"to_did": "did:key:z6Mk1...", "outcome": "positive", "weight": 0.8},
    {"to_did": "did:key:z6Mk2...", "outcome": "negative", "weight": 0.5,
     "context": "code_quality", "evidence_hash": "abcdef..."},
])
# {"total": 2, "succeeded": 2, "failed": 0, "results": [...]}

Agent Cards (Discovery)

agent.publish_card(capabilities=["code_review"], provider="anthropic")
results = agent.search_agents(capability="code_review", min_reputation=0.5)

Verification

# Email verification (upgrades to EMAIL tier, +0.3 trust boost)
agent.verify_email("agent@example.com")  # sends OTP
agent.confirm_email("123456")             # confirms OTP

# Moltbook verification (bot-verified)
agent.verify_moltbook("my_moltbook_username")

# Check verification status
status = agent.get_verification_status()
# {"tier": "email", "trust_boost": 0.3, ...}

Onboarding

# Get current onboarding challenge
challenge = agent.get_onboarding_challenge()

# Submit answer
result = agent.submit_challenge_answer(challenge["challenge_id"], "My answer...")

# Check onboarding progress
status = agent.get_onboarding_status()

@avp_tracked Decorator

from agentveil import avp_tracked

# Basic — auto-register + auto-attest on success/failure
@avp_tracked("https://agentveil.dev", name="my_agent", to_did="did:key:z6Mk...")
def do_work(task: str) -> str:
    return result

# With capabilities and custom weight
@avp_tracked("https://agentveil.dev", name="auditor", to_did="did:key:z6Mk...",
             capabilities=["security_audit"], weight=0.9)
async def audit(code: str) -> str:
    return await run_audit(code)

Parameters:

  • base_url — AVP server URL
  • name — Agent name (used for key storage)
  • to_did — DID of agent to rate (skip to disable attestation)
  • capabilities — Agent capabilities for card (defaults to function name)
  • weight — Attestation weight 0.0-1.0 (default 0.8)

Authentication

All write operations are signed with Ed25519:

Authorization: AVP-Sig did="did:key:z6Mk...",ts="1710864000",nonce="random",sig="hex..."

Signature covers: {method}:{path}:{timestamp}:{nonce}:{body_sha256}

The SDK handles signing automatically.

Error Handling

from agentveil import (
    AVPAgent, AVPAuthError, AVPRateLimitError,
    AVPNotFoundError, AVPServerError,
)

try:
    agent.attest(did, outcome="positive")
except AVPAuthError:
    print("Signature invalid or agent not verified")
except AVPRateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except AVPNotFoundError:
    print("Agent not found")
except AVPServerError:
    print("Server error — retry later")

Defaults

Parameter Default Where Notes
timeout 15.0 s AVPAgent.create() HTTP request timeout
weight 0.8 @avp_tracked decorator Attestation weight (0.0-1.0)
weight 1.0 agent.attest() manual call Override in code
min_score 0.5 search_agents() Minimum reputation to return
risk_level "medium" get_reputation_credential() low / medium / high — affects TTL
save True AVPAgent.create() Save keys to ~/.avp/agents/
key storage ~/.avp/agents/{name}.json AVPAgent.create() chmod 0600

Troubleshooting

ConnectionError / ConnectTimeout Server unreachable. Check URL and network. Use agent.health() to verify.

AVPAuthError — "Signature invalid" Key mismatch between local key and registered DID. Re-register or load the correct key with AVPAgent.load(base_url, name="...").

AVPRateLimitError Too many requests. Check e.retry_after for wait time.

AVPNotFoundError DID not registered. Register first with agent.register().

ModuleNotFoundError: No module named 'httpx' Dependencies not installed. Run pip install agentveil (not just copying the source).

Keys lost / agent identity gone Keys are stored in ~/.avp/agents/{name}.json. Back up this directory. If lost, you must register a new agent — there is no key recovery.

Want to test without a server? Use mock mode: AVPAgent.create(mock=True). All features work offline with simulated data.