Agent Gateway User Guide

Overview

The DataCovey Agent Gateway enables secure, privacy-preserving data collaboration between AI agents and frameworks across organizations. It provides multi-protocol support, federated agent-to-agent communication, and usage-based billing.

The Agent Gateway acts as a secure intermediary between external AI agents and the DataCovey data plane, enforcing privacy policies, managing authentication, and tracking usage.

Architecture Overview

The following diagram illustrates the high-level architecture of the Agent Gateway:

Key Components

1. Protocol Adapters Layer

• Translates external agent messages into a unified internal schema (AgentEvent)
• Supports A2A, MCP, LangChain, and OpenAI interfaces
• Makes DataCovey appear native to any agent ecosystem

2. Auth & Policy Engine

• Enforces tenant/project roles using Row-Level Security (RLS)
• Applies JSON/YAML-based policies (max rows, redacted fields, differential privacy epsilon)

3. Message Router

• Provides event bus semantics for message routing
• Handles asynchronous agent-to-agent communication and state tracking

4. LLM Proxy & Metering

• Intercepts all LLM calls from internal agents
• Counts tokens (input/output) and applies budgets per project

5. Data Query & Privacy Engine

• Executes SQL or RAG queries in secure sandboxes
• Applies privacy-enhancing tech: aggregation, masking, differential privacy, PSI
• Returns only policy-compliant insights

6. Audit & Billing Layer

• Stores immutable, hash-chained audit logs
• Aggregates usage by agent, project, and organization for reconciliation
• Feeds DataCovey's billing dashboard

Agent Data Exchange Lifecycle

The following sequence diagram illustrates how agents interact through the gateway to exchange data while maintaining privacy and compliance:

Sequence Flow Details

Step	Description
①–②	Agent A sends a task (via A2A or MCP). DataCovey authenticates and forwards it to Agent B, enforcing any cross-organization data policies.
③–⑤	Agent B queries a shared DataCovey dataset. The data plane executes the query within a secure sandbox, applying RLS, aggregation, and privacy filters before returning results.
⑥–⑦	DataCovey returns the result and logs the number of rows accessed (used for billing and compliance).
⑧–⑪	Agent B calls its LLM via DataCovey's proxy, which meters token usage, ensuring both real-time monitoring and budget enforcement.
⑫–⑬	The final result is sent back to Agent A, fully mediated by DataCovey. The system logs all message events (who talked to whom, when, and what dataset IDs were touched).
⑭–⑯	The Audit & Billing subsystem aggregates all metering data and issues cost/balance reports — enabling inter-org cost sharing or credit settlement.

Key Technical Hooks in the Flow

• Auth Layer: JWT or mTLS validation on steps ① and ③
• Policy Engine: Applies row-level, aggregation, or data-type restrictions in step ④
• Privacy Engine: Executes differential privacy or PSI (Private Set Intersection) in step ④
• Token Metering: Captures prompt_tokens and completion_tokens from OpenAI-compatible API in step ⑨
• Immutable Logging: All events ①→⑬ are stored in an append-only audit log with chained SHA256 hashes
• Billing Calculation: Usage summarized hourly/daily to produce real-time dashboards and CSV exports

Design Implications

• Protocol-Aware Transparency: A2A and MCP messages look end-to-end between agents, but DataCovey transparently intercepts, logs, and enforces privacy
• Cross-Org Billing Neutrality: Each org can see its contribution and consumption without revealing private data
• Governance by Design: Every agent interaction becomes measurable, auditable, and compliant

Component Deployment

The Agent Gateway components integrate with the existing DataCovey infrastructure:

Component Breakdown

Component	Description
Protocol Adapter Service	Handles A2A, MCP, LangChain, and OpenAI-compatible APIs. Normalizes messages into a canonical AgentEvent format.
Auth & Policy Service	Verifies JWT/mTLS, enforces dataset and RLS policies.
Message Router	Async routing of messages for A2A or MCP tasks.
LLM Proxy Service	Acts as OpenAI-compatible proxy; meters token usage and enforces budgets per project.
Data Query API	REST endpoint for /datasets/query and /datasets/rag. Handles SQL, vector search, or hybrid queries.
Query Executor Pods	Secure sandboxes for executing SQL/aggregation queries.
Privacy Engine	Performs masking, aggregation, differential privacy, and secure intersection (PSI).
Usage Collector & Audit Log Processor	Consumes message topics to maintain immutable audit chain and feed dashboards.
Billing Engine	Periodically aggregates usage and emits invoices/reports.
Monitoring Stack	Tracks latency, cost, and query metrics.
Admin Console / API	UI to manage agents, policies, and see cost charts.

Security & Privacy Anchors

• Tenant isolation: Each dataset lives in its own schema; agents execute queries through RLS policies
• Encryption: All storage encrypted with tenant-managed keys
• Audit logs: Each AgentEvent stored immutably, with SHA-chained digests for compliance
• Confidential Compute (future): Query Executor Pods can run in confidential compute environments for cryptographic attestation

Billing & Metering Pipeline

1. Events emitted by LLM Proxy / Query API → message topic for usage events
2. Collector aggregates per (tenant, project, agent_id) and stores in agent_usage
3. Billing Engine joins with pricing tables → generates daily_cost_report
4. UI Dashboard renders interactive charts per agent, dataset, and protocol

Multi-Organization Federation

The Agent Gateway supports federated deployments where multiple organizations can collaborate while maintaining data sovereignty:

Federation Guarantees

• Data stays local: Each company's raw data remains in its own Data Plane (RLS + DP/PSI). The hub only sees policy-compliant results (aggregates/snippets + metadata like row_count)
• Protocol-native interop: Gateways speak A2A, MCP, OpenAI-compatible APIs; the hub relays/normalizes while enforcing cross-org policies & delegation
• Transparent metering: The hub's Usage Meter & Ledger attributes tokens, rows, and events per agent/tenant → Billing produces cost/revenue splits for fair exchange
• Fine-grained control: Policy/Delegation caps rows, masks fields, injects DP noise, or requires approvals for certain datasets/tools

Key Features

Multi-Protocol Support

The Agent Gateway supports multiple agent protocols and frameworks:

• A2A (Agent-to-Agent): JSON-RPC and Server-Sent Events (SSE) for agent communication
• MCP (Model Context Protocol): Tool and context calls for Claude, OpenAI Tools, and other MCP-compatible agents
• LangChain: Native integration with LangChain tools and callbacks
• OpenAI-compatible: REST and WebSocket APIs compatible with OpenAI's interface

Privacy-Preserving Queries

The gateway enforces multiple privacy-preserving techniques:

• Differential Privacy: Adds calibrated noise to query results to protect individual records
• Private Set Intersection (PSI): Enables secure computation of set intersections without revealing full datasets
• Row-Level Security (RLS): Enforces tenant-based data isolation at the database level
• Data Masking: Automatically redacts sensitive fields based on policy rules
• Aggregation: Returns only aggregated results when individual records would violate privacy

Cross-Organization Federation

Organizations can collaborate securely while maintaining data sovereignty:

• Each organization maintains its own Data Plane with full control
• The Federation Hub enables secure agent-to-agent communication
• Cross-org policies enforce data sharing rules and limits
• Agent Registry provides discovery and delegation capabilities

Usage-Based Billing

Granular tracking and billing for all agent interactions:

• Token Metering: Tracks LLM token usage (input and output) for all agent calls
• Row Access Tracking: Monitors data row access for billing and compliance
• API Call Metering: Tracks all API calls and operations
• Inter-Organization Reconciliation: Enables fair cost sharing between collaborating organizations
• Real-time Dashboards: Interactive charts showing usage by agent, dataset, and protocol

Immutable Audit Trails

Complete auditability for compliance and forensics:

• SHA-chained Logs: All events stored with cryptographic hashing for tamper detection
• Data Export: Audit logs exported for analysis and compliance
• Event Tracking: Records who talked to whom, when, and what datasets were accessed
• Compliance Ready: Meets requirements for data governance and regulatory compliance

Agent Discovery and Delegation

Federated agent marketplace for collaboration:

• Agent Registry: Discover available agents across organizations
• Task Delegation: Delegate tasks to partner agents securely
• Policy Enforcement: Cross-org policies control what agents can access
• Transparent Routing: Messages appear end-to-end while being fully mediated

Use Cases

Cross-Organization Data Collaboration

Scenario: Company A wants to analyze customer behavior patterns using Company B's customer data without exposing raw records.

Solution:

• Agent A (Company A) sends a task request through the gateway
• Agent B (Company B) receives the request and queries its data
• Privacy engine applies differential privacy and aggregation
• Only aggregated insights are returned to Agent A
• Both companies receive usage reports for billing reconciliation

Multi-Agent Workflows

Scenario: An organization wants to use multiple specialized agents (data analysis, NLP, visualization) in a coordinated workflow.

Solution:

• Protocol adapters allow different agent types (A2A, MCP, LangChain) to work together
• Message router coordinates asynchronous communication
• LLM proxy meters token usage across all agents
• Audit logs track the entire workflow for compliance

Privacy-Compliant Analytics

Scenario: A healthcare organization needs to share aggregated patient insights with research partners while maintaining HIPAA compliance.

Solution:

• Row-Level Security ensures only authorized data is accessible
• Differential privacy adds calibrated noise to protect individual patients
• Data masking automatically redacts PHI fields
• Immutable audit logs provide compliance documentation
• Usage tracking enables transparent billing

Best Practices

For Agent Developers

1. Use Standard Protocols: Leverage A2A, MCP, or OpenAI-compatible interfaces for maximum compatibility
2. Handle Errors Gracefully: Implement retry logic and error handling for network issues
3. Respect Rate Limits: Monitor and respect API rate limits to avoid throttling
4. Monitor Usage: Track token and row usage to stay within budgets . Implement Logging: Log agent actions for debugging and audit purposes

For Organization Administrators

1. Configure Policies Carefully: Set appropriate limits on rows, tokens, and data access
2. Monitor Usage Dashboards: Regularly review usage reports to identify trends and anomalies
3. Review Audit Logs: Periodically review audit logs for compliance and security
4. Manage Agent Permissions: Grant only necessary permissions to agents
5. Set Budgets: Configure token and row budgets to prevent unexpected costs

For Data Stewards

1. Define Privacy Policies: Clearly define what data can be shared and under what conditions
2. Test Privacy Settings: Verify that privacy-preserving techniques work as expected
3. Review Query Results: Ensure that returned data complies with privacy requirements
4. Monitor Data Access: Track which agents access which datasets
5. Update Policies: Keep privacy policies up to date as requirements change

Troubleshooting

Common Issues

"Authentication failed"

• Verify JWT token is valid and not expired
• Check that the agent has proper IAM permissions
• Ensure mTLS certificates are correctly configured (if using mTLS)

"Policy violation: max rows exceeded"

• Review the query to reduce the number of rows returned
• Request a policy update from your organization administrator
• Use aggregation functions to reduce result set size

"Token budget exceeded"

• Review LLM usage patterns to identify high-consumption operations
• Request a budget increase from your organization administrator
• Optimize prompts to reduce token usage

"Dataset access denied"

• Verify that the agent has permission to access the dataset
• Check that the project is associated with the dataset's tenant
• Contact your organization administrator for access requests

Getting Help

1. Check this documentation for common solutions
2. Review audit logs for detailed error information
3. Contact your Organization Administrator for policy-related issues
4. Submit a support ticket with detailed error messages and logs

Technical Details

Authentication Methods

• JWT (JSON Web Tokens): Standard OAuth 2.0 / JWT tokens for API authentication
• mTLS (Mutual TLS): Certificate-based authentication for enhanced security

Privacy Technologies

• Differential Privacy: Differential privacy algorithms for calibrated noise injection
• Private Set Intersection: PSI protocols for secure computation
• Row-Level Security: RLS policies for tenant-based data isolation
• Encryption: Tenant-managed encryption keys

Supported Protocols

• A2A: JSON-RPC over HTTP/HTTPS, Server-Sent Events (SSE)
• MCP: Model Context Protocol tool and context calls
• LangChain: Native tool and callback integration
• OpenAI: REST API and WebSocket compatibility