Web Evidence

Agentic Services

Agentic Services is a service matrix for autonomous agents. Each service exposes a narrow, valuable information capability that an external agent can discover, evaluate, purchase, and call without manual account setup.

The platform treats APIs, MCP tools, agent-to-agent services, software runtimes, and databases as different transports for the same commercial object: an agent service.

Product contract

Every published service must provide:

1. A machine-readable description of its capabilities and input/output schemas.
2. At least one callable transport: HTTP, MCP, or A2A.
3. A deterministic price or a machine-readable quote flow.
4. At least one automated payment method.
5. Provenance, freshness, service-level, and policy metadata.
6. An idempotent execution path and a verifiable receipt.

The canonical public manifest lives at:

https://<service-host>/.well-known/agent-service.json

The same manifest can be indexed by the platform registry and exported to compatible discovery networks.

Repository layout

docs/                         Product and system designexamples/                     Example service manifestsschemas/                      Versioned protocol schemasservices/                     Product-specific documentationsrc/agentic_services/         Runnable gateway and Web Evidence APItests/                        API contract and safety tests

The initial protocol is defined by schemas/service-manifest.schema.json. An illustrative service is in examples/weather-risk.service.json.

Architecture

The platform has four layers:

• Service layer — focused information products owned by individual service modules.
• Gateway layer — identity, quotes, payment verification, rate limits, and receipts.
• Registry layer — capability search, health, reputation, and machine-readable manifests.
• Settlement layer — adapters for pay-per-call, credits, and subscriptions.

See docs/architecture.md for the execution flow and docs/roadmap.md for the build sequence.

Design principles

• Protocol-first: an agent can integrate from schemas without reading prose.
• Narrow services: each service owns a small domain and returns a useful result, not raw data alone.
• Payment-neutral core: commercial terms are stable while payment rails remain replaceable.
• Verifiable delivery: every paid execution produces a receipt tied to the request, price, and result.
• Safe autonomy: budgets, expiry, replay protection, and idempotency are enforced in deterministic code.
• Federated discovery: the platform registry is useful but is not the only way to find a service.

Run Web Evidence locally

The first runnable service is Web Evidence, a structured claim-verification API backed by the OpenAI Responses API and hosted web search.

python3 -m venv .venv.venv/bin/pip install -e '.[dev]'cp .env.example .env.local# Add OPENAI_API_KEY to .env.local.venv/bin/agentic-services

The API starts at http://localhost:8000. Its main endpoints are:

• POST /v1/claims/verify/quick — $0.02 quick verification.
• POST /v1/claims/verify — $0.05 standard verification.
• POST /v1/claims/verify/deep — $0.12 deep verification.
• POST /v1/claims/verify/research — $0.25 research-grade verification.
• GET /v1/claims/verifications/{verification_id} — retrieve the immutable result.
• GET /v1/url-snapshots/{snapshot_id} — retrieve snapshot status and content hashes.
• GET /v1/url-snapshots/{snapshot_id}/content — retrieve the exact captured response bytes.
• GET /.well-known/agent-service.json — discover the service and its schemas.
• GET /.well-known/x402 — discover x402-payable resource URLs.
• POST /mcp — MCP Streamable HTTP server with one free discovery tool and four x402-paid verification tools.
• GET /.well-known/mcp/server.json — MCP Registry metadata.
• POST /a2a — A2A 1.0 JSON-RPC SendMessage, paid at the Standard tier.
• GET /.well-known/agent-card.json — A2A Agent Card.
• GET /openapi.json — inspect the complete HTTP contract.
• GET /llms.txt — read concise agent integration instructions.
• GET / — human-readable landing page with structured data; robots.txt and sitemap.xml support web indexing.
• POST /v1/quotes — create a 15-minute machine-readable tier quote.
• GET /v1/orders/{order_id} — retrieve one paid order and signed receipt with its one-time order token.
• GET /v1/customer/orders — list a registered customer's orders with X-Agentic-Customer-Key.
• POST /v1/receipts/{order_id}/verify — verify the server signature on an issued receipt.
• GET /admin — private commerce dashboard for revenue, OpenAI cost, gross profit, and individual orders.
• GET /v1/admin/summary, GET /v1/admin/orders — dashboard APIs authenticated with X-Admin-Key.
• POST /v1/admin/customers — issue a customer API key; plaintext is returned once and only its SHA-256 hash is stored.

Example request:

curl http://localhost:8000/v1/claims/verify \  -H 'Content-Type: application/json' \  -H 'Idempotency-Key: example-claim-1' \  -d '{    "claim": "OpenAI publishes an official Responses API reference.",    "sourcePolicy": "official_only",    "allowedDomains": ["openai.com"],    "minimumSources": 1  }'

See docs/web-evidence-api.md for request semantics, evidence guarantees, and the planned paid-service endpoints.

For the production Docker Compose deployment at api.aisoup.net, follow deploy/google-cloud-vm.md. The public gateway accepts both x402 and MPP payments in Base USDC; the Python service remains private behind an internal Bearer credential.

Live discovery

Web Evidence is published through the following public discovery surfaces:

• Official MCP Registry as io.github.impanyu/web-evidence.
• OpenX402 Bazaar as the paid MCP resource mcp://api.aisoup.net/verify_claim_quick.
• x402Scan with all four paid HTTP tiers and both public snapshot routes.
• MPPScan with the same six HTTP routes.
• Global A2A Registry and the open-source A2A Registry via the public A2A 1.0 Agent Card.

The repository also carries server.json for MCP Registry publication and glama.json for downstream MCP directory indexing. The landing page publishes Schema.org service metadata, robots.txt, sitemap.xml, OpenAPI, llms.txt, and well-known manifests for independent crawlers.

Status

The repository contains the v0 protocol, a runnable tiered Web Evidence service, full provider-source provenance, URL snapshots with raw and normalized SHA-256 hashes, SQLite persistence, machine-readable discovery, and an x402/MPP dual-protocol payment gateway. Each paid HTTP, MCP, or A2A execution creates an order, signed receipt, and detailed revenue/cost ledger entry. The admin dashboard reports per-order OpenAI token and Web Search costs, gross profit, and margins. Production payment settlement and public MCP, A2A, x402, and MPP directory discovery have been verified. The next milestone is additional evidence operations and ongoing directory health monitoring.