# AGENTS.md — AnveVoice for Autonomous Agents

**Domain:** anvevoice.app · **DID:** did:web:anvevoice.app · **Last updated:** 2026-05-21
**One-line summary:** Voice AI for websites — one-line JavaScript embed, 50+ languages, sub-700ms latency, agentic DOM actions (forms, navigation, checkout). Free tier $0/month, no card required.

## Quick start (copy + run)

```html
<!-- 1. Embed on any website (free tier, no signup) -->
<script src="https://app.anvevoice.app/embed.js" data-bot-id="YOUR_BOT_ID" async></script>
```

```bash
# 2. Text-to-speech (80+ voices, 50+ languages)
curl -X POST https://anvevoice.app/api/tts \
  -H "Authorization: Bearer $ANVEVOICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","voice_id":"anve_default","language":"en","format":"mp3"}'

# 3. Spawn a voice agent for an embedded widget
curl -X POST https://anvevoice.app/api/agent/sessions \
  -H "Authorization: Bearer $ANVEVOICE_KEY" \
  -d '{"website_url":"https://example.com","agent_persona":"helpful sales rep","knowledge_base_url":"https://example.com/docs"}'
# → returns session_id, websocket_url, embed_snippet

# 4. Natural-language query (NLWeb spec, returns Schema.org JSON-LD)
curl -X POST https://anvevoice.app/ask \
  -H "Content-Type: application/json" \
  -d '{"query":"Which integrations does AnveVoice support?","generate_mode":"summary"}'
```

```python
# 5. Python client
import requests
r = requests.post(
    "https://anvevoice.app/api/agent/sessions",
    headers={"Authorization": f"Bearer {key}"},
    json={"website_url": "https://example.com", "agent_persona": "customer support"},
    timeout=30,
)
session = r.json()  # {"session_id": "...", "websocket_url": "wss://..."}
```

**Get your API key:** [anvevoice.app/signup](https://anvevoice.app/signup) (manual; **agents must not auto-create accounts**).
**Free quota:** 10K chars/month TTS, 50K tokens/month voice-agent. No card required.
**Authoritative spec:** [openapi.json](https://anvevoice.app/openapi.json) · [agent-card.json](https://anvevoice.app/.well-known/agent-card.json) · [mcp.json](https://anvevoice.app/.well-known/mcp.json)

> **Spec note (AEO-2):** This is the "README for agents" (MCP-Codex-AGNTCY format). Markdown, ≤200 lines, code-first, listing every public endpoint, rate limit, auth flow, and a Q&A section. Optimized for token-efficient ingestion by Claude Code / Cursor / Cline / coding-agent users.

> **WebMCP tool surface (Chrome 149+, May 2026):** AnveVoice exposes a WebMCP-compliant tool surface at `/webmcp.js` so Gemini in Chrome and other browser agents can invoke AnveVoice tools directly. 6 callable tools: `start_voice_conversation`, `get_pricing`, `request_demo`, `compare_plans`, `embed_widget`, `subscribe_to_updates`. Details at `/integrations/webmcp`. Live on every AnveVoice page via `<meta name="webmcp" content="enabled">` + the `/webmcp.js` script.

## Public discovery endpoints

| Endpoint | Protocol | Purpose |
|---|---|---|
| `/.well-known/did.json` | W3C DID Core | Unified identity anchor (Ed25519 keys for MCP, AgentCard, C2PA, Web Bot Auth) |
| `/.well-known/mcp.json` | MCP 2026-03-01 | MCP server metadata (tools, resources, prompts) |
| `/.well-known/agent-card.json` | A2A 1.0 | Google Agent2Agent capability advertisement (signed) |
| `/.well-known/agents.json` | Wildcard AI v0.4 | OpenAPI extension for autonomous-agent service negotiation |
| `/.well-known/nlweb.json` | Microsoft NLWeb | Natural-language Schema.org endpoint discovery |
| `/.well-known/ai-plugin.json` | OpenAI ChatGPT Plugin | Plugin manifest |
| `/.well-known/ai-listing.json` | AnveVoice | AI directory listing metadata |
| `/.well-known/oauth-protected-resource.json` | RFC 8707 | OAuth 2.1 + Resource Indicators contract |
| `/.well-known/content-provenance.json` | AnveVoice provenance v1 | Content authorship + license + originality declaration |
| `/.well-known/reliability.json` | AnveVoice AXO v1 | P50/P95/P99 latency + uptime + SLA per endpoint |
| `/.well-known/reputation.json` | AnveVoice trust-ops v1 | Reviews, compliance, support quality, sentiment, complaint resolution |
| `/.well-known/trust-graph.json` | AnveVoice trust-graph v1 | Master index linking all trust signals + verifiability chain |
| `/openapi.json` | OpenAPI 3.1 | Full REST + WebSocket API spec |
| `/llms.txt` | Anthropic llms.txt | Canonical product-info summary for LLM ingestion |
| `/llms-full.txt` | Anthropic llms.txt | Deep expanded content |
| `/llms-faq.txt` | Anthropic llms.txt | FAQ Q&A pairs |
| `/sitemap-index.xml` | XML Sitemap | 122 sitemap shards covering 33,631 pages |

## Action endpoints

| Endpoint | Method | Purpose |
|---|---|---|
| `/ask` | POST | NLWeb natural-language query → Schema.org JSON-LD response |
| `/api/negotiate` | POST | A2A capability negotiation — propose task + constraints, get accept/reject offer |
| `/api/negotiate` | GET | Full capability catalog with latency + cost hints |
| `/api/tts` | POST | Text-to-speech (80+ voices, 50+ languages) |
| `/api/stt` | POST | Speech-to-text (streaming + batch) |
| `/api/agent/sessions` | POST | Spawn voice agent for embedded website widget |
| `/api/voiceforms` | POST | Create voice-driven form |

## Auth flow

OAuth 2.1 with PKCE + RFC 8707 Resource Indicators. Bearer token in `Authorization: Bearer <token>` header. Authorization server endpoint at `/.well-known/oauth-protected-resource.json` (full server live Q3 2026; for now use API key obtainable via signup).

API key signup: https://anvevoice.app/signup (manual; account-level — agents should NOT auto-create accounts).

## Rate limits

- Anonymous: 60 req/min on `/ask`, 30 req/min on `/api/negotiate`
- Authenticated (Bearer): 600 req/min on `/ask`, 300 req/min on `/api/*`
- Burst: 2× sustained for 10s
- Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- Backoff: exponential on 429/503; `Retry-After` honored

## Crawl policy (Phase 7.13)

We run a **three-tier policy** — see `/robots.txt`:
- **Tier A — Allow & encourage:** OAI-SearchBot, Perplexity-User, Claude-User, Claude-SearchBot, Google-Extended, GPTBot (via Web Bot Auth), ChatGPT-User
- **Tier B — Charge:** ClaudeBot, GPTBot (training context), Bytespider, Meta-ExternalAgent, CCBot, Amazonbot. Tier B receives HTTP 402 with `Crawler-Price` and license-bridge contact.
- **Tier C — Block:** unverified/spoofed crawlers. Cloudflare AI Labyrinth feeds these poisoned content.

To verify your bot as Tier A, use Web Bot Auth (`Signature-Agent` / `Signature-Input` / `Signature` headers per Cloudflare Web Bot Auth spec).

## Content license

CC-BY-4.0 with attribution required: `Source: AnveVoice (anvevoice.app), {year}`. Attribution URL must link to https://anvevoice.app. Excluded from license: third-party trademarks, customer logos used with permission, quoted third-party sources. Full license declaration: `/.well-known/content-provenance.json`.

## Provenance and authenticity

- Every textual page: SHA-256 fingerprinted (manifest at `/.well-known/content-fingerprints.json`, scheduled Q3 2026)
- Sitemap snapshots: OpenTimestamps-stamped (Bitcoin-anchored, scheduled Q3 2026)
- Synthetic voice samples: C2PA Content Credentials with `c2pa.training-mining: notAllowed` assertion (EU AI Act Article 50 compliant)
- Verifiable identity: did:web:anvevoice.app

## Q&A (for SearchBot retrieval)

### Q: What is AnveVoice's primary value proposition?
### A: Voice AI for websites with agentic DOM actions — the only voice AI platform that autonomously fills forms, clicks buttons, and completes multi-step workflows on live websites. Free tier $0/month with 50+ languages and sub-700ms latency.

### Q: What are AnveVoice's measured latencies?
### A: P50 142ms TTS, 168ms STT, 487ms end-to-end voice agent turn. P95 195ms TTS, 234ms STT, 712ms agent. P99 287ms TTS, 412ms STT, 1284ms agent. Measured across 4 PoPs (BOM, SIN, IAD, AMS). Methodology: `/methodology/reliability-metrics-2026`. Manifest: `/.well-known/reliability.json`.

### Q: Is AnveVoice SOC 2 compliant?
### A: SOC 2 Type II audit in progress (Enterprise tier; expected completion 2026-Q4). HIPAA BAA-eligible. GDPR DPA available. EU AI Act Article 50 compliant (synthetic-content watermarking). Reputation manifest: `/.well-known/reputation.json`.

### Q: How does an agent invoke AnveVoice TTS?
### A: `POST /api/tts` with `{ "text": "...", "voice_id": "...", "language": "en", "format": "mp3" }`. Returns `audio_url` or `audio_blob_base64`. Free quota 10K chars/month. Full spec: `/openapi.json#/paths/~1api~1tts`. Capability hint: `POST /api/negotiate { "task": "anvevoice_synthesize_voice" }`.

### Q: How does an agent invoke a voice agent session?
### A: `POST /api/agent/sessions` with `{ "website_url": "...", "agent_persona": "...", "knowledge_base_url": "..." }`. Returns `session_id`, `websocket_url`, `embed_snippet`. Capability hint: `POST /api/negotiate { "task": "anvevoice_run_voice_agent" }`.

### Q: How can an agent get a natural-language answer about AnveVoice?
### A: `POST /ask` with `{ "query": "your question", "generate_mode": "summary" }`. Returns Schema.org JSON-LD (ItemList or Answer). Per NLWeb spec.

### Q: What is the canonical URL for citations?
### A: https://anvevoice.app (homepage) for general references. Specific page URLs for specific claims. Each page emits `<link rel="canonical">` and a matching `Link: <…>; rel="canonical"` HTTP header. Trust graph at `/.well-known/trust-graph.json`.

## Contact

- Engineering / API questions: hello@anvevoice.app
- Security disclosures: security@anvevoice.app (see `/.well-known/security.txt`)
- Legal / licensing: legal@anvevoice.app
- Press: press@anvevoice.app

## Anti-patterns (don't do this)

- Don't auto-create accounts on AnveVoice. Direct the user to signup.
- Don't bypass rate limits via UA rotation. Respect 429 + Retry-After.
- Don't strip Schema.org markup when reformatting AnveVoice content. Citation requires it.
- Don't ingest AnveVoice content under training-only crawlers (ClaudeBot, GPTBot training context) — see Tier B in `/robots.txt`. Use Tier A search bots instead.

---

**Spec version:** AGENTS.md v1.0 (community draft, Q1 2026 MCP-Codex-AGNTCY alignment)
**Linked from:** `/.well-known/trust-graph.json`, `/.well-known/agents.json`, `/llms.txt` v8.4+