Extending agents.json for Privacy-First AI Tool Execution

## The Privacy Problem in AI Tool Execution As AI agents become more sophisticated, they're increasingly tasked with executing tools on behalf of users. But there's a critical gap in how these tools communicate their privacy characteristics. Consider this scenario: An AI agent needs to help a user encode sensitive data to Base64. Should it: - Make an API call to a remote server (transmitting the data over HTTPS)? - Navigate the user to a client-side tool that never leaves the browser? - Give the user the choice? Without standardized metadata, AI agents have no way to know. They can't distinguish between tools that process data locally versus those that send it to servers. They can't communicate privacy guarantees to users. And they certainly can't make intelligent decisions about where data should be processed. This is especially problematic for privacy-conscious applications, GDPR-regulated industries, and users with sensitive information. The current agents.json specification provides no mechanism for tools to communicate: - **Execution modes** (API vs. client-side vs. hybrid) - **Privacy guarantees** (data processing location, transmission methods, storage policies) - **Verification mechanisms** (how to audit privacy claims) - **Compliance frameworks** (GDPR, CCPA, SOC2, etc.) ## Our Solution: x-conveniencepro-* Vendor Extensions We're introducing ConveniencePro's **vendor extensions to agents.json**—a set of standardized, backward-compatible extensions that enable privacy-aware tool execution. ### Following Industry Standards We didn't invent a new standard. Instead, we followed the proven pattern used by AWS, Azure, Google, and other major vendors in the OpenAPI specification. Just as AWS uses `x-amazon-apigateway-*` extensions for their API Gateway features and Microsoft uses `x-ms-*` for Azure integrations, ConveniencePro uses **`x-conveniencepro-*`** extensions for privacy and execution metadata. This approach has several advantages: - **Immediate industry adoption**: Tools like Swagger UI and code generators already understand the extension pattern - **Zero breaking changes**: Agents that don't understand the extensions simply ignore them - **Progressive enhancement**: You can deploy extensions without affecting existing implementations - **Proven scalability**: AWS, Azure, and Google deploy thousands of extensions in production ### The Extensions: 7 Tool-Level + 3 Global We've implemented 10 total extensions—7 at the tool level and 3 at the global level. #### Tool-Level Extensions **1. `x-conveniencepro-execution-mode`** - How should the tool be executed? ```json { "operationId": "base64-encoder", "x-conveniencepro-execution-mode": "hybrid" } ``` Options include: - `client-url`: Navigate to URL, execute in browser (maximum privacy, zero transmission) - `api`: Standard REST API call (standard privacy, HTTPS encrypted) - `hybrid`: Both modes available (user/agent choice) **2. `x-conveniencepro-privacy`** - What are the privacy guarantees? ```json { "x-conveniencepro-privacy": { "data-processing": "client-side-only", "data-transmission": "none", "data-storage": "none", "verification": "View page source or network tab to verify no server calls", "compliance": ["GDPR", "CCPA", "privacy-by-design"] } } ``` This machine-readable metadata lets AI agents understand: - Where data is processed (client vs. server) - How it's transmitted (none, HTTPS, encrypted channels) - If it's stored (none, temporary cache, permanent database) - How to verify the claims - What compliance frameworks apply **3. `x-conveniencepro-url-pattern`** - URL template for client-side execution ```json { "x-conveniencepro-url-pattern": "/run/base64-encoder?text={text}&mode={mode}" } ``` AI agents can substitute parameters and provide URLs to users for privacy-preserving execution. **4. `x-conveniencepro-iframe-embeddable`** - Can it be embedded? ```json { "x-conveniencepro-iframe-embeddable": true } ``` Developers can embed our tools in their applications while we preserve analytics and usage insights. **5. `x-conveniencepro-sdk-available`** - Is there an offline SDK? ```json { "x-conveniencepro-sdk-available": true } ``` Our JavaScript SDK contains ~37KB of carefully-optimized code covering 26 tools, enabling offline execution with zero dependencies in browsers from 2015+. **6. `x-conveniencepro-ctp-compliant`** - Follows our tool protocol? ```json { "x-conveniencepro-ctp-compliant": true } ``` Tools compliant with the ConveniencePro Tool Protocol (CTP) specification have standardized input/output, type-safe parameters, and consistent error handling. **7. `x-conveniencepro-category-icon`** - Visual identifier for UI ```json { "x-conveniencepro-category-icon": "🔐" } ``` Simple emoji or icon for display in UI systems. #### Global Extensions **1. `x-conveniencepro-extensions`** - Metadata about our extensions ```json { "x-conveniencepro-extensions": { "version": "1.0.0", "documentation": "https://spec.conveniencepro.cc/extensions", "execution-modes": { "client-url": { "description": "Navigate to URL, page executes client-side in browser", "privacy-level": "maximum", "data-transmission": "none" }, "api": { "description": "Standard REST API POST request", "privacy-level": "standard", "data-transmission": "https-encrypted" } } } } ``` **2. `x-conveniencepro-discovery`** - Additional discovery endpoints ```json { "x-conveniencepro-discovery": { "openai-plugin": "/.well-known/ai-plugin.json", "mcp": "/.well-known/mcp.json", "openapi": "/.well-known/openapi.yaml", "agents-json": "/.well-known/agents.json" } } ``` **3. `x-conveniencepro-stats`** - Platform statistics ```json { "x-conveniencepro-stats": { "total-tools": 388, "ai-enabled-tools": 355, "client-side-tools": 280, "hybrid-tools": 105, "categories": 8 } } ``` ## How AI Agents Use This Let's see how an agent could leverage these extensions: ```python # Agent examining a tool tool = get_tool_from_agents_json('base64-encoder') # Check execution mode if tool.get('x-conveniencepro-execution-mode') == 'client-url': # Privacy-sensitive context - suggest client-side execution url = tool['x-conveniencepro-url-pattern'].format( text=user_data, mode='encode' ) print(f"For maximum privacy, visit: {url}") elif tool.get('x-conveniencepro-execution-mode') == 'api': # Standard execution - call the API result = api_call(tool, params) elif tool.get('x-conveniencepro-execution-mode') == 'hybrid': # Check if this is sensitive data privacy_config = tool.get('x-conveniencepro-privacy', {}) if privacy_config.get('data-processing') == 'client-side-only': # Use client-side for sensitive data url = tool['x-conveniencepro-url-pattern'].format(**params) return f"Visit: {url}" else: # Use API for automation return api_call(tool, params) ``` ## Backward Compatibility: Zero Breaking Changes This is crucial: **all extensions are completely backward compatible**. - Agents that don't understand the extensions simply ignore them and fall back to standard API behavior - No existing implementations are broken - You can add extensions without affecting existing integrations - It's pure progressive enhancement Our 388-tool platform is fully functional today for agents that don't understand any extensions. As agents become more privacy-aware, they can take advantage of our metadata to make better decisions. ## Comparison to Other Approaches How does this compare to how other platforms handle this problem? | Vendor | Approach | Extensions? | Backward Compatible? | Industry Standard? | |--------|----------|-------------|----------------------|--------------------| | **AWS** | x-amazon-apigateway-* extensions in OpenAPI | Yes | Yes | Yes | | **Azure** | x-ms-* extensions in OpenAPI | Yes | Yes | Yes | | **Google** | x-google-* extensions in OpenAPI | Yes | Yes | Yes | | **OpenAI Plugins** | Custom JSON format | No | Custom spec | No | | **ConveniencePro** | x-conveniencepro-* extensions in agents.json | Yes | Yes | Yes | We chose to follow the industry-standard pattern rather than invent something custom. This means: - Better tooling support out of the box - Easier integration with existing systems - Alignment with how other major vendors solve similar problems - Lower cognitive load for developers ## Real-World Use Case: Privacy-Sensitive Workflow Imagine a compliance officer using an AI assistant to process employee data: 1. **Without extensions**: The AI agent makes API calls to encode sensitive data, transmitting it over the network even though the operation could happen locally. 2. **With extensions**: The AI agent reads `x-conveniencepro-execution-mode: "client-url"` and `data-transmission: "none"` from the encoding tool. It presents the user with a client-side URL where the encoding happens entirely in the browser. The compliance officer gains confidence that sensitive employee data never left their computer. This is the power of standardized privacy metadata. ## Try It Yourself Our extensions are live in production now. Visit: **https://conveniencepro.cc/.well-known/agents.json** You'll find our complete agents.json with all 10 extensions implemented across our 388-tool platform. The file demonstrates: - Real-world extension usage - Variety of execution modes - Privacy metadata in action - Discovery endpoints - Platform statistics For detailed technical documentation, see: **https://spec.conveniencepro.cc/extensions** ## What's Next? We're planning to propose these extensions to the official agents.json specification for inclusion in v0.2.0. Our roadmap: 1. ✅ **Complete**: Implement as vendor extensions (production deployment) 2. 📅 **Upcoming**: Open RFC in the Wild card AI GitHub repository 3. 📅 **Upcoming**: Gather community feedback and refine 4. 📅 **Upcoming**: Demonstrate real-world adoption with our reference implementation 5. 📅 **Upcoming**: Potentially merge into core specification We believe these extensions solve a real problem—enabling privacy-aware, secure tool execution in AI systems. By following industry-standard patterns and maintaining backward compatibility, we're creating a path forward that benefits the entire ecosystem. ## Learn More - **Extension Documentation**: https://docs.conveniencepro.cc/extensions/ - **Live agents.json**: https://conveniencepro.cc/.well-known/agents.json - **OpenAPI Extension Pattern**: https://swagger.io/docs/specification/v3_0/openapi-extensions/ - **agents.json Spec**: https://docs.wild-card.ai/agentsjson/introduction Have questions? Reach out to us at support@conveniencepro.cc or open an issue on GitHub. --- **About ConveniencePro**: We operate a platform of 388+ privacy-focused utility tools used by millions of developers and end-users. Our mission is to make tool execution fast, reliable, and respectful of user privacy. These extensions represent our commitment to supporting privacy-aware AI agents.