README.md

Agent Permissions Python Library

This package provides utilities for discovering, fetching, validating, and enforcing agent-permissions.json manifest files exposed by websites. It is designed to plug into agentic frameworks that need to respect site-defined automation policies.

Features

• Discover manifests from HTML via <link rel="agent-permissions">
• Fetch and cache manifests over HTTP (sync and async)
• Validate manifests against the published JSON Schema along with semantic checks
• Check planned UI interactions against resource rules
• Generate prompt text for higher-level action guidelines

Installation

pip install agent-permissions

Quick Start

import httpx
from lxml import html

from agent_permissions import fetch_manifest, validate_interaction

manifest = fetch_manifest("https://example.com/.well-known/agent-permissions.json")

# Fetch the current page HTML remotely (or inject your own source).
page_html = httpx.get("https://example.com/products").text

root = html.fromstring(page_html)
element = root.cssselect("#buy")[0]
validation = validate_interaction(
    manifest,
    verb="click_element",
    element=element,
)

print(validation.allowed)            # -> True or False
print(validation.requirements)       # -> e.g. {"human_in_the_loop": True}

Check out samples/demo.html with its paired samples/agent-permissions.json for a realistic playground to experiment with validation.

Action guidelines and API info

manifest = fetch_manifest("https://example.com/.well-known/agent-permissions.json")

# Action guidelines are in manifest.action_guidelines
for guideline in manifest.action_guidelines:
    print(f"{guideline.directive}: {guideline.description}")
    if guideline.exceptions:
        print(f"  Exceptions: {guideline.exceptions}")

# API integrations are in manifest.api
for api_ref in manifest.api:
    print(f"{api_ref.type} endpoint: {api_ref.endpoint} — {api_ref.description}")
    if api_ref.docs:
        print(f"  Docs: {api_ref.docs}")

For more detailed documentation, consult design/library.md.