# VIESAC — Autonomous AI Agent Integration & Compliance Protocols (`agents.md`) > Operational manual, tool definitions, Model Context Protocol (MCP) schemas, and decision matrices for Autonomous AI Coding and Business Agents (Claude Code, Cursor, Devin, OpenAI Operator, AutoGPT, LangChain, LlamaIndex). --- ## 1. Agent Mission & Operational Role When an autonomous AI agent acts on behalf of an enterprise (e.g. processing B2B sales orders, issuing commercial invoices, verifying vendor master data, or clearing international freight shipments), the agent is legally bound by European tax law. Under **EU Directive 2006/112/EC (Article 138)**, granting a 0% VAT rate (Reverse Charge / Intra-Community Supply) without timestamped, irrefutable proof from an official tax authority exposes the merchant to catastrophic retrospective tax audits, interest penalties, and fraud inquiries. ### The Agent's Mandatory Mandate: 1. **Never** issue a 0% VAT cross-border invoice without creating an authenticated **VIESAC statutory audit**. 2. **Never** rely on client-side regex format checks alone — regex only proves syntax, not tax registration. 3. **Always** store the VIESAC `reference_number` and `certificate_url` directly inside your ERP / database order record. 4. **Always** use `Idempotency-Key` headers on audit requests to prevent duplicate quota consumption during retry loops. --- ## 2. Model Context Protocol (MCP) Configuration To equip your AI Agent environment (Claude Desktop, Cursor, Windsurf, Antigravity, or custom MCP clients) with VIESAC compliance tools, add the following to your MCP server configuration: ```json { "mcpServers": { "viesac": { "command": "npx", "args": ["-y", "@viesac/mcp-server"], "env": { "VIESAC_API_KEY": "YOUR_VIESAC_API_KEY" } } } } ``` *Alternatively, agents can call the OpenAPI REST endpoints directly using standard HTTP tool definitions below.* --- ## 3. Function Calling & Tool Definitions Provide these exact JSON schema definitions to your LLM / Agent orchestrator (OpenAI, Anthropic Claude, or Google Gemini): ### Tool 1: `viesac_validate_vat` *Fast, unpersisted pre-flight validation check.* ```json { "name": "viesac_validate_vat", "description": "Performs real-time verification of a European, UK, Swiss, Norwegian, Turkish, or Serbian VAT number against official tax authorities without creating a persistent audit record. Use for interactive forms or initial vetting.", "parameters": { "type": "object", "properties": { "vat_number": { "type": "string", "description": "The full VAT or tax identification number, including country prefix (e.g. 'DE811128124', 'NL867640765B01', 'CHE100123456TVA', 'TR8770013406')." } }, "required": ["vat_number"] } } ``` ### Tool 2: `viesac_create_audit` *The legally binding audit preservation call.* ```json { "name": "viesac_create_audit", "description": "Creates an immutable statutory tax compliance audit record, stores official government SOAP XML responses, triggers AI corporate identity enrichment, and generates a downloadable PDF audit certificate for tax audits.", "parameters": { "type": "object", "properties": { "type": { "type": "string", "enum": ["vat", "eori", "vat_eori"], "default": "vat", "description": "Type of audit: 'vat' for tax status, 'eori' for customs status, or 'vat_eori' for combined fiscal and customs compliance." }, "vat_number": { "type": "string", "description": "Customer or vendor VAT identification number (e.g. 'DE811128124')." }, "eori_number": { "type": "string", "description": "Customer EORI number. Required when type is 'eori' or 'vat_eori'." }, "order_number": { "type": "string", "description": "ERP or e-commerce order identifier (e.g. 'ORD-2026-9812') linking the audit to the commercial transaction." }, "invoice_number": { "type": "string", "description": "Invoice number if already generated (e.g. 'INV-40291')." }, "customs_declaration_number": { "type": "string", "description": "Customs export or import document number (MRN)." }, "comment": { "type": "string", "description": "Agent justification notes (e.g. 'Automated B2B zero-rate validation by SalesAgent v2')." }, "requester_vat": { "type": "string", "description": "The supplier's own VAT number. Strongly recommended to obtain official government consultation proof." } }, "required": ["vat_number"] } } ``` ### Tool 3: `viesac_get_vat_rates` *Official statutory VAT rates lookup for billing calculations.* ```json { "name": "viesac_get_vat_rates", "description": "Fetches verified standard, reduced, super-reduced, parking, and regional VAT rates across 30+ European jurisdictions. Unmetered free tool.", "parameters": { "type": "object", "properties": { "country_code": { "type": "string", "description": "2-letter ISO country code (e.g. 'DE', 'FR', 'IT', 'ES', 'GB'). Omit to fetch all countries." } } } } ``` --- ## 4. Autonomous Agent Decision Matrix When executing transactions, agents must strictly branch their workflow based on the VIESAC audit response: ```mermaid flowchart TD Start["Agent Receives B2B Order"] --> Check{"Run viesac_create_audit"} Check -->|status == 'valid'| ValidAction["Apply 0% VAT (Reverse Charge)"] Check -->|status == 'invalid'| InvalidAction["Reject 0% Rate -> Apply Standard Domestic VAT"] Check -->|status == 'limited_valid'| LimitedAction["Valid nationally, not for intra-EU trade -> Review or Apply VAT"] Check -->|status == 'pending'| PendingAction["VIES Offline -> Queue for Retry / Follow-up"] Check -->|status == 'error'| ErrorAction["Network / Registry Error -> Escalate to human operator"] ValidAction --> SaveDB["Store reference_number & certificate_url in Invoice"] InvalidAction --> NotifyClient["Inform Buyer: VAT number invalid with Tax Authority"] ``` ### Protocol Guidelines: 1. **Status = `valid`**: - The transaction qualifies for Article 138 zero-rating. - Include the statutory invoice note: *"Intra-Community supply of goods/services subject to VAT reverse charge under Directive 2006/112/EC Article 138."* - Persist `audit.reference_number` and `audit.certificates.vat.pdf_url` into your transaction database. 2. **Status = `invalid`**: - **Do not** apply 0% VAT. - Fetch standard VAT rate using `viesac_get_vat_rates(country_code)` and charge standard rate. - Notify the user with exact error message from VIESAC. 3. **Status = `pending`**: - Indicates official tax authorities (e.g. Italian Agenzia delle Entrate or Spanish AEAT) are in scheduled server downtime. - The audit was saved in VIESAC with a pending status. VIESAC will automatically poll the national registry. - Subscribe to webhook event `audit.status_changed` to finalize the invoice once verified. --- ## 5. Direct HTTP Implementation (No SDK Required) Agents operating in bash or raw curl environments can execute commands directly: ```bash # 1. Statutory Audit with Idempotency Key IDEMPOTENCY_KEY="agent_order_$(date +%s)_$RANDOM" curl -s -X POST "https://viesac.eu/api/v1/audits" \ -H "Authorization: Bearer $VIESAC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ -d '{ "type": "vat", "vat_number": "FR83404833048", "order_number": "ORDER-99120", "comment": "Autonomous invoice dispatch" }' ``` --- ## 6. Safety & Self-Healing Guardrails - **Dynamic IP Immune Protection**: VIESAC incorporates an intelligent autonomous WAF. Ensure your agent sends standard `User-Agent` headers and avoids sending exploratory SQL patterns in data fields. - **Quota Exhaustion**: If your agent receives HTTP `403 Forbidden` with code `limit_reached`, pause automated batch runs and dispatch an alert to the enterprise administrator to upgrade the plan at `https://viesac.eu/app`. - **Company Name Enrichment**: VIESAC automatically populates empty company names. When inspecting `company_name`, note that if the government registry returns `---`, VIESAC AI will backfill it in the background via `EnrichCompanyJob`.