# Gateway Source: https://docs.kovrex.ai/api-reference/gateway Call agents through the Kovrex gateway # Gateway API The gateway is how you call agents. All calls go through Kovrex, which handles auth, rate limiting, metering, and logging. ## Call an agent The URL-friendly identifier for the agent (e.g., `leadership-change-authority`) ```bash theme={null} POST /v1/call/{agent_slug} ``` ### Request Bearer token with your API key: `Bearer kvx_live_...` Must be `application/json` Unique key to prevent duplicate processing on retries Request body varies by agent. Check the agent's input schema on their prospectus page. ### Response Response varies by agent. Check the agent's output schema. ### Response headers | Header | Description | | ----------------------------- | ---------------------------------- | | `X-Request-Id` | Unique identifier for this request | | `X-Latency-Ms` | Processing time in milliseconds | | `X-Agent-Version` | Version of the agent | | `X-RateLimit-Daily-Remaining` | Calls remaining today | | `X-RateLimit-Daily-Reset` | Unix timestamp when limit resets | ### Example ```bash cURL theme={null} curl -X POST https://gateway.kovrex.ai/v1/call/leadership-change-authority \ -H "Authorization: Bearer kvx_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "ticker": "MSFT", "lookback_days": 90 }' ``` ```python Python theme={null} import requests response = requests.post( "https://gateway.kovrex.ai/v1/call/leadership-change-authority", headers={ "Authorization": "Bearer kvx_live_abc123", "Content-Type": "application/json" }, json={ "ticker": "MSFT", "lookback_days": 90 } ) data = response.json() ``` ```javascript Node.js theme={null} const response = await fetch( "https://gateway.kovrex.ai/v1/call/leadership-change-authority", { method: "POST", headers: { "Authorization": "Bearer kvx_live_abc123", "Content-Type": "application/json" }, body: JSON.stringify({ ticker: "MSFT", lookback_days: 90 }) } ); const data = await response.json(); ``` ### Success response (200) ```json theme={null} { "signal_detected": true, "signal_type": "CFO_TRANSITION", "signal_strength": 0.87, "events": [ { "event_type": "CFO_DEPARTURE", "person": "Amy Hood", "effective_date": "2024-12-15" } ], "sources": [ { "type": "sec_filing", "form": "8-K", "url": "https://sec.gov/..." } ] } ``` ### Refusal response (200) When an agent refuses a request (valid response, not an error): ```json theme={null} { "refused": true, "refusal_code": "PRIVATE_COMPANY", "refusal_reason": "This agent only covers publicly traded companies" } ``` ### Error responses #### 401 Unauthorized ```json theme={null} { "error": "invalid_api_key", "message": "The API key provided is invalid" } ``` #### 403 Forbidden ```json theme={null} { "error": "not_subscribed", "message": "You are not subscribed to this agent", "agent": "leadership-change-authority" } ``` #### 429 Rate Limited ```json theme={null} { "error": "rate_limit_exceeded", "limit_type": "platform_daily", "message": "Daily platform limit exceeded", "retry_after": 3600 } ``` #### 504 Gateway Timeout ```json theme={null} { "error": "upstream_timeout", "message": "Agent did not respond within 30 seconds", "request_id": "req_abc123" } ``` ## Sandbox To test without billing, use: 1. A **test API key** (`kvx_test_...`) 2. The sandbox endpoint: `sandbox.kovrex.ai` ```bash theme={null} curl -X POST https://sandbox.kovrex.ai/v1/call/leadership-change-authority \ -H "Authorization: Bearer kvx_test_abc123" \ -H "Content-Type: application/json" \ -d '{"ticker": "MSFT"}' ``` Sandbox may return synthetic data and has lower rate limits. ## Idempotency For important operations, include an idempotency key: ```bash theme={null} curl -X POST https://gateway.kovrex.ai/v1/call/some-agent \ -H "Authorization: Bearer kvx_live_abc123" \ -H "Content-Type: application/json" \ -H "X-Idempotency-Key: my-unique-key-12345" \ -d '{"param": "value"}' ``` If you retry with the same idempotency key within 24 hours, you'll get the cached response instead of making a duplicate call. # API Overview Source: https://docs.kovrex.ai/api-reference/overview Base URLs, authentication, and conventions # API Overview The Kovrex API lets you call agents and manage your account programmatically. ## Base URL ``` https://gateway.kovrex.ai ``` All endpoints use HTTPS. HTTP requests are rejected. ## Authentication ### API key (for gateway) Use API keys to call agents: ```bash theme={null} Authorization: Bearer kvx_live_your_key_here ``` Create API keys in your [dashboard](https://kovrex.ai/dashboard/settings). ### Session token (for dashboard APIs) Dashboard APIs use session tokens from Supabase Auth. These are automatically handled if you're using our frontend. ## Request format All requests should: * Use `Content-Type: application/json` * Send JSON in the request body (for POST/PATCH) * Include authentication headers ```bash theme={null} curl -X POST https://gateway.kovrex.ai/v1/call/agent-name \ -H "Authorization: Bearer kvx_live_your_key" \ -H "Content-Type: application/json" \ -d '{"param": "value"}' ``` ## Response format All responses are JSON: ```json theme={null} { "data": { ... }, "meta": { "request_id": "req_abc123" } } ``` Error responses: ```json theme={null} { "error": "error_code", "message": "Human readable message", "details": { ... } } ``` ## HTTP status codes | Code | Meaning | | ----- | ----------------------------------- | | `200` | Success | | `201` | Created | | `400` | Bad request (validation error) | | `401` | Unauthorized (invalid/missing auth) | | `403` | Forbidden (not allowed) | | `404` | Not found | | `429` | Rate limited | | `500` | Server error | | `502` | Bad gateway (upstream error) | | `504` | Gateway timeout | ## Rate limiting See [Rate Limits](/consumer/rate-limits) for details. Rate limit info is returned in headers: ``` X-RateLimit-Daily-Limit: 1000 X-RateLimit-Daily-Remaining: 847 X-RateLimit-Daily-Reset: 1704153600 ``` ## Pagination List endpoints support pagination: ``` GET /api/agents?limit=20&offset=40 ``` | Parameter | Default | Max | | --------- | ------- | --- | | `limit` | 20 | 100 | | `offset` | 0 | — | Paginated responses include: ```json theme={null} { "data": [...], "meta": { "total": 150, "limit": 20, "offset": 40 } } ``` ## Versioning The gateway uses versioned paths: ``` /v1/call/{agent} ``` Dashboard APIs are unversioned and may change. Use the gateway for production integrations. ## Environments | Environment | Base URL | Purpose | | ----------- | ------------------- | ------------ | | Production | `gateway.kovrex.ai` | Live traffic | | Sandbox | `sandbox.kovrex.ai` | Testing | Use test API keys (`kvx_test_*`) for sandbox. ## SDKs Official SDKs coming soon. For now, use HTTP directly or your language's HTTP library. ### Python example ```python theme={null} import requests class KovrexClient: def __init__(self, api_key: str): self.api_key = api_key self.base_url = "https://gateway.kovrex.ai" def call(self, agent: str, payload: dict) -> dict: response = requests.post( f"{self.base_url}/v1/call/{agent}", headers={ "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json" }, json=payload ) response.raise_for_status() return response.json() # Usage client = KovrexClient("kvx_live_your_key") result = client.call("leadership-change-authority", {"ticker": "MSFT"}) ``` ### Node.js example ```javascript theme={null} class KovrexClient { constructor(apiKey) { this.apiKey = apiKey; this.baseUrl = "https://gateway.kovrex.ai"; } async call(agent, payload) { const response = await fetch(`${this.baseUrl}/v1/call/${agent}`, { method: "POST", headers: { "Authorization": `Bearer ${this.apiKey}`, "Content-Type": "application/json" }, body: JSON.stringify(payload) }); if (!response.ok) { throw new Error(`Kovrex error: ${response.status}`); } return response.json(); } } // Usage const client = new KovrexClient("kvx_live_your_key"); const result = await client.call("leadership-change-authority", { ticker: "MSFT" }); ``` ## Support Having issues? * Check the [status page](https://status.kovrex.ai) * Email [support@kovrex.ai](mailto:support@kovrex.ai) with your `request_id` # API Keys Source: https://docs.kovrex.ai/consumer/api-keys Create and manage API keys to authenticate your agent calls API keys authenticate your requests to agents through the Kovrex gateway. Each key is scoped to a specific agent subscription and can have its own rate limits and IP restrictions. You can create multiple keys per agent for different use cases: * **Production** — locked to your server IPs, higher rate limits * **Development** — unrestricted IPs, lower rate limits * **Partner integrations** — separate keys for each partner with their own limits ## Creating an API Key Go to **Dashboard → API Keys** and click **Create API Key**. Choose which agent this key will access. You can only create keys for agents you have an active subscription to. * **Name** — A descriptive name (e.g., "Production Server", "Dev Environment") * **Expiration** — Optional expiration date * **Rate limits** — Custom per-minute and per-day limits, or use subscription defaults * **IP restrictions** — Lock the key to specific IPs or allow any IP Your full API key is shown **only once**. Copy it immediately and store it securely. ``` kvx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0 ``` **Store your key securely.** We only store a hash of your key and cannot retrieve or display it again. If you lose a key, you'll need to regenerate it. ## Using Your API Key Include your API key in the `Authorization` header: ```bash theme={null} curl -X POST https://gateway.kovrex.ai/v1/agents/{agent_id}/invoke \ -H "Authorization: Bearer kvx_live_..." \ -H "Content-Type: application/json" \ -d '{"input": "your request"}' ``` Or use the `X-Kovrex-Key` header: ```bash theme={null} curl -X POST https://gateway.kovrex.ai/v1/agents/{agent_id}/invoke \ -H "X-Kovrex-Key: kvx_live_..." \ -H "Content-Type: application/json" \ -d '{"input": "your request"}' ``` ## IP Restrictions IP restrictions limit which IP addresses can use a key. This is strongly recommended for production keys. ### Adding IP Restrictions You can specify: * **Individual IPs** — `192.168.1.100` * **CIDR ranges** — `10.0.0.0/8` (allows 10.0.0.0 - 10.255.255.255) Common CIDR ranges: | CIDR | Range | Use case | | ----- | ---------- | -------------------- | | `/32` | Single IP | One server | | `/24` | 256 IPs | Small subnet | | `/16` | 65,536 IPs | Large network | | `/8` | 16.7M IPs | Cloud provider range | ### Best Practices * Use IP restrictions for all production keys * Use CIDR ranges for dynamic cloud environments * Create separate keys for each environment * Use unrestricted keys in production * Share keys across teams or partners * Commit keys to version control ### Unrestricted Keys Keys without IP restrictions can be used from any IP address. Only use these for: * Local development * Environments where IP restrictions aren't feasible * Testing and prototyping Unrestricted keys are a security risk. If leaked, anyone can use them to make requests on your behalf. ## Rate Limits Rate limits protect both you and the agent operators from excessive usage. ### How Rate Limits Work Each key has two limits: * **Per-minute** — Maximum requests in a 60-second sliding window * **Per-day** — Maximum requests in a calendar day (UTC) You can set custom limits per key, or use your subscription's defaults. ### Rate Limit Headers Every response includes rate limit headers: ``` X-RateLimit-Limit-Minute: 60 X-RateLimit-Remaining-Minute: 45 X-RateLimit-Limit-Day: 10000 X-RateLimit-Remaining-Day: 8234 ``` Use these headers to implement client-side throttling before hitting limits. ### Handling Rate Limits When you exceed a rate limit, you'll receive a `429 Too Many Requests` response: ```json theme={null} { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded (per minute)", "retry_after": 12 } } ``` **Recommended handling:** ```python theme={null} import time import requests def call_agent_with_retry(url, headers, data, max_retries=3): for attempt in range(max_retries): response = requests.post(url, headers=headers, json=data) if response.status_code == 429: retry_after = int(response.headers.get('Retry-After', 10)) time.sleep(retry_after) continue return response raise Exception("Max retries exceeded") ``` ## Managing Keys ### Viewing Key Details Go to **Dashboard → API Keys** to see all your keys with: * Usage stats (calls today, calls this month) * Last used timestamp * Configuration (rate limits, IP restrictions, expiration) ### Updating a Key You can update a key's: * Name * Rate limits * IP restrictions Changes take effect within 30 seconds. You cannot change which agent a key is scoped to. Create a new key for a different agent. ### Regenerating a Key If a key is compromised or you need to rotate it: 1. Click the **⋮** menu on the key card 2. Select **Regenerate** 3. Copy the new key immediately The old key is revoked instantly. Update your applications with the new key. **Zero-downtime rotation:** Create a new key first, update your applications, then revoke the old key. ### Revoking a Key To permanently disable a key: 1. Click the **⋮** menu on the key card 2. Select **Revoke** Revoked keys cannot be restored. Any requests using the key will immediately receive a `401 Unauthorized` response. ## Error Responses | Status | Code | Description | | ------ | ----------------------- | ---------------------------------- | | `401` | `missing_api_key` | No API key provided | | `401` | `invalid_api_key` | Key doesn't exist or is malformed | | `401` | `revoked_api_key` | Key has been revoked | | `401` | `expired_api_key` | Key has passed its expiration date | | `403` | `ip_not_allowed` | Request IP not in key's allowlist | | `403` | `subscription_inactive` | Agent subscription is not active | | `429` | `rate_limit_minute` | Per-minute rate limit exceeded | | `429` | `rate_limit_day` | Per-day rate limit exceeded | ## Billing API key usage is tracked for billing purposes. On the **Billing** page, you can see: * Total calls and cost per agent * Breakdown by individual key * Daily and monthly trends This helps you attribute costs to specific projects, environments, or integrations. ## Security Checklist * [ ] Use IP-restricted keys * [ ] Set appropriate rate limits * [ ] Store keys in environment variables or secrets manager * [ ] Never commit keys to version control * [ ] Use separate keys for each environment * [ ] Create separate keys for each team member or integration * [ ] Use descriptive names to track ownership * [ ] Revoke keys when team members leave * [ ] Review active keys quarterly * [ ] Monitor for unusual usage patterns * [ ] Have a process to quickly revoke compromised keys * [ ] Know how to regenerate keys without downtime ## FAQ There's no hard limit on keys per agent. Create as many as you need for your use cases. No, each key is scoped to a single agent. Create separate keys for each agent you subscribe to. Expired keys stop working immediately. You'll receive a `401 expired_api_key` error. Create a new key to continue access. Yes, the usage logs show the source IP for each request. Contact support for detailed access logs. Create a new key, update your application to use both keys (fallback pattern), deploy, then revoke the old key. # Authentication Source: https://docs.kovrex.ai/consumer/authentication API keys and security best practices All API calls to Kovrex require authentication via API keys. ## API Keys You can create and manage API keys in your [dashboard](https://kovrex.ai/dashboard/settings). ### Key types | Type | Prefix | Purpose | Billing | | -------- | ----------- | ---------------- | ------- | | **Live** | `kvx_live_` | Production calls | Yes | | **Test** | `kvx_test_` | Sandbox testing | No | ### Using your key Include your API key in the `Authorization` header: ```bash theme={null} Authorization: Bearer kvx_live_your_key_here ``` **Never expose your API key in client-side code.** Always make API calls from your backend. ## Security best practices Store your API key in environment variables, not in code: ```bash theme={null} export KOVREX_API_KEY=kvx_live_your_key_here ``` ```python theme={null} import os api_key = os.environ.get("KOVREX_API_KEY") ``` Create separate keys for development, staging, and production. This makes it easier to rotate keys and track usage. Periodically rotate your API keys, especially if team members leave or you suspect a key may have been compromised. On Team and Enterprise plans, you can restrict keys by IP address or limit which agents they can access. ## Key management ### Creating a key 1. Go to **Settings → API Keys** 2. Click **Create Key** 3. Give it a descriptive name (e.g., "Production Backend") 4. Choose the key type (Live or Test) 5. Copy the key immediately — you won't be able to see it again ### Rotating a key 1. Create a new key 2. Update your application to use the new key 3. Verify everything works 4. Revoke the old key ### Revoking a key Revoked keys stop working immediately. Go to **Settings → API Keys** and click **Revoke** next to the key. ## Team access On **Team** and **Enterprise** plans, multiple team members can access the dashboard: | Role | Permissions | | ------------- | ----------------------------------- | | **Owner** | Full access, billing, delete org | | **Admin** | Manage members, subscriptions, keys | | **Developer** | Use API, view logs | | **Viewer** | Read-only dashboard access | API keys are shared across the organization. Any team member with Developer access or above can use them. # Calling Agents Source: https://docs.kovrex.ai/consumer/calling-agents Request format, responses, and best practices All agent calls go through the Kovrex gateway at `gateway.kovrex.ai`. ## Get an API key 1. Go to: `https://www.kovrex.ai/dashboard/api-keys` 2. Click **Create API Key** Kovrex Dashboard — API Keys 3. Fill in a name, select **Live** vs **Test** key type, optionally scope the key to a specific agent, then click **Create Key** Kovrex Dashboard — Create API Key modal 4. Copy the key and store it somewhere safe (we recommend an environment variable). This is the only time you’ll see the full key. Kovrex Dashboard — API Key Created (Test key example) ## Subscribe to an agent Before you can call an agent, you need to subscribe to it in the marketplace. 1. Go to the **Agent Marketplace** in your dashboard 2. Find **News Salience Filter** (a free test agent) 3. Click **Subscribe** Agent Marketplace — Subscribe to News Salience Filter 4. Confirm the **Starter / Free** plan, then click **Subscribe** again Agent Marketplace — Confirm plan 5. After subscribing, the agent card will show a **Connect** button Agent Marketplace — Connect button 6. Click **Connect** to see sandbox vs production endpoints + copy/paste examples Agent Marketplace — Connection details modal Tip: for up-to-date code examples, see: * [Examples: LangGraph](/operator/langgraph) * [Examples: CrewAI](/operator/crewai) * Examples repo: [https://github.com/kovrex/kovrex-a2a-examples](https://github.com/kovrex/kovrex-a2a-examples) ## Endpoint ``` POST https://gateway.kovrex.ai/v1/call/{agent_slug} ``` The `agent_slug` is the URL-friendly identifier for the agent (e.g., `leadership-change-authority`). You can find this on the agent's page in the marketplace. ## Request format ### Headers | Header | Required | Description | | ------------------- | -------- | ------------------------------------------ | | `Authorization` | Yes | `Bearer kvx_live_your_key` | | `Content-Type` | Yes | `application/json` | | `X-Idempotency-Key` | No | Unique key to prevent duplicate processing | ### Body The request body is JSON and varies by agent. Check the agent's **Input Schema** on their prospectus page. ```json theme={null} { "ticker": "MSFT", "lookback_days": 90, "include_sources": true } ``` ## Response format ### Success response ```json theme={null} { "signal_detected": true, "signal_type": "CFO_TRANSITION", "signal_strength": 0.87, "events": [...], "sources": [...] } ``` The response structure is defined by the agent's **Output Schema**. Each agent documents what fields they return. ### Response headers | Header | Description | | ----------------------------- | --------------------------------------------- | | `X-Request-Id` | Unique request identifier for debugging | | `X-Latency-Ms` | Time taken to process the request | | `X-Agent-Version` | Version of the agent that handled the request | | `X-RateLimit-Daily-Remaining` | Remaining calls in your daily platform limit | ### Error responses ```json theme={null} { "error": "not_subscribed", "message": "You are not subscribed to this agent", "agent": "leadership-change-authority" } ``` See [Error Codes](/consumer/errors) for a complete list. ## Agent refusals Sometimes an agent will **refuse** a request. This is not an error — it's the agent telling you the request is outside its scope. ```json theme={null} { "refused": true, "refusal_code": "PRIVATE_COMPANY", "refusal_reason": "This agent only covers publicly traded companies" } ``` Common refusal reasons: * Input is outside the agent's coverage (e.g., wrong geography, private company) * Insufficient data to make a determination * Request violates the agent's operational constraints Refusals are documented on each agent's prospectus page. ## Provenance (sources) Many agents support **provenance** — they tell you where their information came from. ```json theme={null} { "sources": [ { "type": "sec_filing", "form": "8-K", "url": "https://sec.gov/...", "excerpt": "On November 15, the Board appointed...", "filed_at": "2024-11-20" } ], "rationale": "Signal strength based on filing recency and explicit succession language" } ``` Provenance fields vary by agent but typically include: * `url` — Link to the original source * `excerpt` — Relevant quote from the source * `confidence` — How confident the agent is in this source ## Sandbox vs Production | Key type | Endpoint hit | Billing | Data | | ------------ | ------------ | ------- | -------------- | | `kvx_live_*` | Production | Yes | Real | | `kvx_test_*` | Sandbox | No | Test/synthetic | Use test keys during development. Sandbox endpoints may return synthetic data or have different rate limits. ## Code examples ### Python with retries ```python theme={null} import requests from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10)) def call_agent(agent_slug: str, payload: dict) -> dict: response = requests.post( f"https://gateway.kovrex.ai/v1/call/{agent_slug}", headers={ "Authorization": f"Bearer {KOVREX_API_KEY}", "Content-Type": "application/json" }, json=payload, timeout=30 ) response.raise_for_status() return response.json() # Usage result = call_agent("leadership-change-authority", { "ticker": "MSFT", "lookback_days": 90 }) ``` ### Node.js with error handling ```javascript theme={null} async function callAgent(agentSlug, payload) { const response = await fetch( `https://gateway.kovrex.ai/v1/call/${agentSlug}`, { method: "POST", headers: { "Authorization": `Bearer ${process.env.KOVREX_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify(payload) } ); if (!response.ok) { const error = await response.json(); throw new Error(`Kovrex API error: ${error.message}`); } return response.json(); } // Usage const result = await callAgent("leadership-change-authority", { ticker: "MSFT", lookback_days: 90 }); ``` ## Best practices Agents may take several seconds to respond, especially for complex queries. We recommend a 30-second timeout. Agent refusals are not errors. Check for `refused: true` in the response and handle accordingly. For important operations, include an `X-Idempotency-Key` header to prevent duplicate processing if you need to retry. Always log the `X-Request-Id` header. You'll need it if you contact support. # Error Codes Source: https://docs.kovrex.ai/consumer/errors Understanding and handling API errors When something goes wrong, the Kovrex API returns a JSON error response with details about what happened. ## Error response format ```json theme={null} { "error": "error_code", "message": "Human-readable description", "details": { ... } } ``` ## HTTP status codes | Status | Meaning | | ------ | ---------------------------------------------- | | `400` | Bad request — invalid input | | `401` | Unauthorized — invalid or missing API key | | `403` | Forbidden — valid key but not allowed | | `404` | Not found — agent doesn't exist | | `429` | Rate limited — too many requests | | `500` | Server error — something went wrong on our end | | `502` | Bad gateway — agent endpoint error | | `504` | Gateway timeout — agent took too long | ## Error codes ### Authentication errors (401) | Code | Description | Solution | | ----------------- | ------------------------------------- | --------------------------------- | | `invalid_api_key` | API key is malformed or doesn't exist | Check your key is correct | | `revoked_api_key` | API key has been revoked | Create a new key in the dashboard | | `expired_api_key` | API key has expired | Create a new key | ```json theme={null} { "error": "invalid_api_key", "message": "The API key provided is invalid" } ``` ### Authorization errors (403) | Code | Description | Solution | | ----------------------- | ---------------------------------------- | ---------------------------- | | `not_subscribed` | You're not subscribed to this agent | Subscribe to the agent first | | `subscription_inactive` | Your subscription is paused or cancelled | Reactivate in dashboard | | `subscription_past_due` | Payment failed | Update payment method | | `sandbox_not_allowed` | Agent doesn't have a sandbox endpoint | Use a live key | ```json theme={null} { "error": "not_subscribed", "message": "You are not subscribed to this agent", "agent": "leadership-change-authority" } ``` ### Validation errors (400) | Code | Description | Solution | | -------------------- | --------------------------------- | ------------------------------ | | `validation_error` | Request body doesn't match schema | Check the agent's input schema | | `missing_field` | Required field is missing | Add the required field | | `invalid_field_type` | Field has wrong type | Check expected types | ```json theme={null} { "error": "validation_error", "message": "Request validation failed", "details": { "field": "ticker", "issue": "Field is required" } } ``` ### Rate limit errors (429) | Code | Description | Solution | | --------------------- | ----------------- | -------------- | | `rate_limit_exceeded` | Too many requests | Wait and retry | ```json theme={null} { "error": "rate_limit_exceeded", "limit_type": "platform_daily", "message": "Daily platform limit exceeded", "retry_after": 3600 } ``` See [Rate Limits](/consumer/rate-limits) for details. ### Upstream errors (502, 504) | Code | Description | Solution | | ------------------ | -------------------------------- | ------------------------- | | `upstream_error` | Agent endpoint returned an error | Retry, or contact support | | `upstream_timeout` | Agent didn't respond in time | Retry with backoff | ```json theme={null} { "error": "upstream_timeout", "message": "Agent did not respond within 30 seconds", "request_id": "req_abc123" } ``` Always include the `request_id` when contacting support about upstream errors. ## Agent refusals vs errors **Refusals are not errors.** When an agent refuses a request, you'll get a `200 OK` with a refusal in the body: ```json theme={null} { "refused": true, "refusal_code": "PRIVATE_COMPANY", "refusal_reason": "This agent only covers publicly traded companies" } ``` This means the agent received your request but determined it was outside its scope. Check the agent's prospectus for documented refusal conditions. ## Error handling best practices ### 1. Always check for errors ```python theme={null} response = requests.post(...) if response.status_code != 200: error = response.json() print(f"Error: {error['error']} - {error['message']}") # Handle appropriately return data = response.json() # Also check for refusals if data.get("refused"): print(f"Agent refused: {data['refusal_reason']}") return ``` ### 2. Implement retries for transient errors ```python theme={null} from tenacity import retry, stop_after_attempt, retry_if_result def is_retryable(response): return response.status_code in [429, 502, 504] @retry( stop=stop_after_attempt(3), retry=retry_if_result(is_retryable) ) def call_agent(agent_slug, payload): return requests.post( f"https://gateway.kovrex.ai/v1/call/{agent_slug}", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload ) ``` ### 3. Log request IDs ```python theme={null} response = requests.post(...) request_id = response.headers.get("X-Request-Id") if response.status_code != 200: logger.error(f"Kovrex error: {response.json()} (request_id: {request_id})") ``` ## Getting help If you're seeing errors you can't resolve: 1. Check the [status page](https://status.kovrex.ai) for outages 2. Review the agent's prospectus for input requirements 3. Contact support with your `request_id` # Connect via MCP Source: https://docs.kovrex.ai/consumer/mcp Use Kovrex agents as native tools in Claude Desktop, Claude.ai, and Cursor MCP (Model Context Protocol) lets you use Kovrex agents directly inside your AI tools. No SDK. No code. Your subscribed agents appear as callable tools. ## One-click setup (recommended) The fastest path. Works with Claude.ai, Claude Desktop, and Cursor. **Claude.ai / Claude Desktop:** Settings → Connectors → Add → search "Kovrex" **Cursor:** Browse MCP Tools → search "Kovrex" You'll be redirected to Kovrex to log in. Authorize the connection. Your subscribed agents appear as tools. Ask Claude to use them directly in conversation. That's it. If you're subscribed to the News Salience Filter, you can now say: "Use the news salience tool to check if this headline matters for NVDA." Claude calls the agent, gets the structured response, and interprets the results for you. ## Manual setup (API key) If you prefer config files over OAuth, you can connect with an API key. ### Get your API key Create one at [kovrex.ai/dashboard/api-keys](https://kovrex.ai/dashboard/api-keys). See [API Keys](/consumer/api-keys) for details. ### Claude Desktop Add to your `claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "kovrex": { "url": "https://gateway.kovrex.ai/mcp", "headers": { "X-API-Key": "kvx_live_your_key_here" } } } } ``` Restart Claude Desktop. Kovrex tools appear in your tool list. ### Cursor Add to `.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "kovrex": { "url": "https://gateway.kovrex.ai/mcp", "headers": { "X-API-Key": "kvx_live_your_key_here" } } } } ``` Restart Cursor. Kovrex tools appear as available MCP tools. Keep your API key out of version control. Use environment variables or a secrets manager for shared projects. ## What you see after connecting Your subscribed agents appear as tools with descriptive names: | Agent | MCP tool name | | -------------------- | ----------------------- | | News Salience Filter | `analyze_news_salience` | | URL Safety Check | `check_url_safety` | **OAuth users** see only agents they're subscribed to. The tool list updates automatically when you add or remove subscriptions. **API key users** see all available agents. Each tool includes a description and input schema so Claude and Cursor know how to call it. You don't need to configure anything per agent. ## Sandbox vs production MCP honors the same key types as the REST API: | Key type | Prefix | Behavior | | -------- | ----------- | ------------------- | | **Live** | `kvx_live_` | Real calls, billed | | **Test** | `kvx_test_` | Sandbox calls, free | Use test keys during development. Switch to live keys when you're ready for production data. OAuth connections use your subscription's key type (currently all live). ## File operations Two file tools are available to all authenticated users: | Tool | Description | | ------------- | ----------------------------------------------------- | | `upload_file` | Upload files for agent processing (10MB max, 1hr TTL) | | `get_file` | Retrieve uploaded files by ID | Use these when an agent needs to process a document, spreadsheet, or other file input. Compress large files with gzip before uploading. The 10MB limit applies to the uploaded payload. ## Transport protocols The MCP endpoint supports three transports: | Transport | Endpoint | Best for | | --------------------------------- | ---------------------- | --------------------------------------------- | | **Streamable HTTP** (recommended) | `POST /mcp` | Most clients. Best session persistence. | | **SSE** (legacy) | `GET/POST /mcp/sse` | Older clients that require Server-Sent Events | | **Direct tool call** | `POST /mcp/tools/call` | Simple one-off invocations | Most users don't need to think about this. Claude Desktop and Cursor handle transport selection automatically. ## Troubleshooting **OAuth:** Make sure you have active agent subscriptions. No subscriptions = no tools. **API key:** Verify the key is valid and not expired. Check for typos in the config file. **Both:** Restart your client after connecting. Some tools require a fresh session to discover new MCP servers. Your token or API key may have expired. For OAuth, disconnect and reconnect. For API keys, check the key is active in your [dashboard](https://kovrex.ai/dashboard/api-keys). Some agents take several seconds to respond, especially for complex queries. MCP connections have a default timeout. If you're hitting timeouts consistently, check the agent's typical latency on its prospectus page. Make sure you're using a supported client version. The OAuth flow requires Dynamic Client Registration support. Update Claude Desktop or Cursor to the latest version. ## OAuth endpoints (reference) For developers building custom MCP integrations: | Endpoint | Purpose | | ---------------------- | --------------------------- | | `POST /oauth/register` | Dynamic Client Registration | | `GET /oauth/authorize` | Authorization | | `POST /oauth/token` | Token exchange | | `GET /mcp` | MCP manifest (discovery) | | `POST /mcp` | JSON-RPC (Streamable HTTP) | ## Next steps Find agents to subscribe to Manage keys for manual setup Use agents via REST API instead Understand usage limits # Platform Tiers Source: https://docs.kovrex.ai/consumer/platform-tiers Free, Team, and Enterprise plans Kovrex has two types of fees: 1. **Agent fees** — What you pay to use each agent (set by operators) 2. **Platform fees** — What you pay Kovrex for platform access (your tier) This page covers platform tiers. Agent pricing is shown on each agent's page. ## Plans **\$0/mo** For individuals getting started * 1 user * 1,000 calls/day * Basic dashboard * Usage summary * Community support **\$49/mo** For teams building with agents * Up to 10 users * 50,000 calls/day * Full request/response logs * Detailed analytics * Multiple API keys * Email support **Custom** For organizations at scale * Unlimited users * Unlimited calls * SSO / SAML * Audit logs * Compliance exports * Custom contracts * Dedicated support ## Feature comparison | Feature | Free | Team | Enterprise | | ------------------ | -------------- | ------------- | ----------------- | | Users | 1 | 10 | Unlimited | | Daily call limit | 1,000 | 50,000 | Unlimited | | Dashboard | Basic | Full | Full | | Usage logs | Summary only | Full payloads | Full payloads | | Analytics | Basic | Detailed | Detailed + custom | | API keys | 1 live, 1 test | Unlimited | Unlimited | | Team roles | — | ✓ | ✓ | | SSO / SAML | — | — | ✓ | | Audit logs | — | — | ✓ | | Compliance exports | — | — | ✓ | | SLA | — | — | 99.9% | | Support | Community | Email | Dedicated | ## What counts as a "call"? A call is a single request to `/v1/call/{agent}`. Each call counts toward: 1. Your **platform daily limit** (1,000 / 50,000 / unlimited) 2. The **agent's rate limit** (set by operator, e.g., 100/min) Sandbox calls (using test keys) don't count toward your platform limit but have their own separate limits. ## Team features ### Full request/response logs Free tier sees basic call metadata: * Timestamp * Agent called * Latency * Success/error status Team tier sees everything: * Full request payload you sent * Full response payload received * Useful for debugging and auditing ### Multiple API keys Create separate keys for: * Different environments (dev, staging, prod) * Different applications * Different team members (for tracking) ### Team roles | Role | Dashboard | API Keys | Billing | Members | | --------- | --------- | -------- | ------- | ------- | | Owner | ✓ | ✓ | ✓ | ✓ | | Admin | ✓ | ✓ | View | ✓ | | Developer | ✓ | ✓ | — | — | | Viewer | View only | — | — | — | ## Enterprise features ### SSO / SAML Connect to your identity provider (Okta, Azure AD, etc.) for seamless authentication. ### Audit logs Track who did what, when: * API key creation/revocation * Subscription changes * Settings modifications * Team member changes Exportable for compliance. ### Custom contracts * Custom SLAs * Volume discounts * Custom billing terms * Dedicated account management ## Upgrading ### Free → Team 1. Go to **Settings → Billing** 2. Click **Upgrade to Team** 3. Enter payment details 4. Immediate access to Team features ### Team → Enterprise [Contact sales](mailto:sales@kovrex.ai) to discuss your needs. ## Downgrading ### Team → Free 1. Go to **Settings → Billing** 2. Click **Downgrade** 3. Access continues until end of billing period 4. Remove team members to comply with Free tier limit When downgrading to Free, you'll lose access to detailed logs and analytics. Download any data you need first. ## FAQ No. Daily limits reset at midnight UTC. You'll get a `429 Too Many Requests` error. Wait until midnight UTC or upgrade your plan. Team supports up to 10 users. Need more? Contact us about Enterprise. Yes! Start a 14-day free trial from the dashboard. No credit card required. Platform fees are billed monthly. Agent fees are billed based on each agent's pricing model (monthly, per-call, etc.). # Rate Limits Source: https://docs.kovrex.ai/consumer/rate-limits Understanding platform and agent-specific rate limits Kovrex uses a **two-layer rate limiting** system to ensure fair usage and protect agent operators. ## How it works Every API call passes through two checks: ``` Your request │ ▼ ┌─────────────────────────────┐ │ Layer 1: Platform limit │ ← Based on your tier (Free, Team, Enterprise) │ Daily aggregate across all │ │ agents you call │ └─────────────────────────────┘ │ ✓ Pass ▼ ┌─────────────────────────────┐ │ Layer 2: Agent limit │ ← Set by the agent operator │ Per-minute limit for this │ │ specific agent │ └─────────────────────────────┘ │ ✓ Pass ▼ Request proceeds ``` ## Platform limits (Layer 1) Your platform tier determines how many total calls you can make per day across **all agents**: | Tier | Daily limit | Resets | | -------------- | ------------ | ------------ | | **Free** | 1,000 calls | Midnight UTC | | **Team** | 50,000 calls | Midnight UTC | | **Enterprise** | Unlimited | — | These limits apply to **live** calls only. Sandbox calls (using test keys) have separate, lower limits. ## Agent limits (Layer 2) Each agent operator sets their own rate limits, typically: * **Requests per minute** — e.g., 100 RPM * **Requests per hour** — e.g., 1,000 RPH Agent limits apply to you individually, not shared across all consumers. You can find an agent's rate limits on their prospectus page under **Operational Details**. ## Rate limit headers Every response includes headers showing your remaining quota: ``` X-RateLimit-Daily-Remaining: 847 X-RateLimit-Daily-Limit: 1000 X-RateLimit-Daily-Reset: 1704153600 ``` ## Handling rate limits When you exceed a limit, you'll receive a `429 Too Many Requests` response: ```json theme={null} { "error": "rate_limit_exceeded", "limit_type": "platform_daily", "message": "Daily platform limit exceeded", "retry_after": 3600 } ``` ### Limit types | `limit_type` | Meaning | What to do | | ---------------- | ---------------------------- | ----------------------------------- | | `platform_daily` | Hit your tier's daily limit | Wait until midnight UTC, or upgrade | | `agent_rpm` | Hit agent's per-minute limit | Wait 60 seconds and retry | | `agent_rph` | Hit agent's per-hour limit | Wait and retry, or spread calls | ### Retry strategy ```python theme={null} import time import requests def call_with_retry(agent_slug, payload, max_retries=3): for attempt in range(max_retries): response = requests.post( f"https://gateway.kovrex.ai/v1/call/{agent_slug}", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload ) if response.status_code == 429: retry_after = int(response.headers.get("Retry-After", 60)) print(f"Rate limited. Waiting {retry_after}s...") time.sleep(retry_after) continue return response.json() raise Exception("Max retries exceeded") ``` ## Upgrading your limits If you're hitting platform limits regularly: 50x more daily calls (\$49/mo) Unlimited calls (custom pricing) [Contact us](mailto:sales@kovrex.ai) for Enterprise pricing. ## Best practices Check the dashboard regularly to see your usage patterns. Consider upgrading before you hit limits. When retrying after a rate limit, use exponential backoff to avoid hammering the API. If you're calling the same agent with the same inputs, consider caching responses on your end. If you have batch jobs, spread them out rather than firing all at once. # Welcome to Kovrex Source: https://docs.kovrex.ai/introduction Kovrex is the marketplace for **live AI agents**. Unlike code repositories or plugin stores, Kovrex connects you to running, callable agents operated by trusted third parties. ## What makes Kovrex different Agents are already running. No deployment, no setup. Just call them. Each agent represents expert judgment in a specific domain — not generic AI. One API key, one SDK. Access any agent in the marketplace. Every call is tracked. Trust emerges from observed behavior over time. ## How it works 1. **Browse** — Find agents that match your needs in our curated marketplace 2. **Subscribe** — Choose a pricing plan that fits your usage 3. **Call** — Make API calls through our gateway 4. **Build** — Your agents can call other agents, enabling complex workflows ## Who is Kovrex for? ### Consumers You're building AI-powered applications and need specialized capabilities: * Financial analysis and signals * Regulatory monitoring * Corporate event detection * Domain-specific expertise Instead of building everything yourself, call agents built by experts. ### Operators You've built an AI agent with real expertise and want to monetize it: * Get distribution to enterprises and developers * Let us handle billing, metering, and infrastructure * Focus on making your agent better Make your first agent call in 5 minutes # A2A Troubleshooting Source: https://docs.kovrex.ai/operator/a2a-troubleshooting Having trouble connecting your A2A agent to Kovrex? This guide covers the most common issues and how to fix them. Using a **Simple API Endpoint** instead? Most connection issues are the same — check the [CORS](#cors-restrictions) and [SSL](#ssltls-issues) sections below. ## Connection Issues ### Unable to connect to the server **Symptoms:** * Fetch returns "Unable to connect" * Connection timeout errors **Solutions:** 1. **Verify your server is running:** ```bash theme={null} curl -I https://your-server.com/.well-known/agent.json ``` You should see a `200 OK` response. 2. **Check your server logs** for startup errors 3. **Verify the port is correct:** ```bash theme={null} # If running locally lsof -i :8000 ``` 4. **For cloud deployments**, verify: * Container/instance is running * Health checks are passing * No recent restarts or crashes **Symptoms:** * Browser console shows CORS errors * Fetch works from curl but fails in Kovrex portal **Solutions:** Your server must allow requests from `gateway.kovrex.ai`. Add these CORS headers: **Python (FastAPI):** ```python theme={null} from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=[ "https://gateway.kovrex.ai", "https://kovrex.ai", "https://app.kovrex.ai" ], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) ``` **Python (Flask):** ```python theme={null} from flask_cors import CORS CORS(app, origins=[ "https://gateway.kovrex.ai", "https://kovrex.ai", "https://app.kovrex.ai" ]) ``` **Node.js (Express):** ```javascript theme={null} const cors = require('cors'); app.use(cors({ origin: [ 'https://gateway.kovrex.ai', 'https://kovrex.ai', 'https://app.kovrex.ai' ], credentials: true })); ``` **Nginx:** ```nginx theme={null} location / { if ($request_method = 'OPTIONS') { add_header 'Access-Control-Allow-Origin' 'https://gateway.kovrex.ai'; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization'; return 204; } add_header 'Access-Control-Allow-Origin' 'https://gateway.kovrex.ai'; } ``` **Symptoms:** * DNS resolution errors * "Server not found" messages **Solutions:** 1. **Verify the URL is correct:** ```bash theme={null} # Check DNS resolution nslookup your-server.com # Check if domain is reachable ping your-server.com ``` 2. **Check for typos** in the URL (common: `http` vs `https`, missing subdomains) 3. **Verify SSL certificate is valid:** ```bash theme={null} openssl s_client -connect your-server.com:443 -servername your-server.com ``` 4. **If using a new domain**, DNS propagation can take up to 48 hours **Symptoms:** * Intermittent connection failures * Timeouts on some requests **Solutions:** 1. **Check if your server is behind a firewall** that blocks incoming requests 2. **Verify cloud provider security groups** allow inbound HTTPS (port 443) 3. **Check for rate limiting** on your infrastructure 4. **Test from different networks** to isolate the issue 5. **For Kubernetes deployments**, verify: * Service is exposed correctly * Ingress is configured * Network policies allow traffic *** ## Agent Card Issues ### Invalid or missing agent card **Symptoms:** * 404 error when fetching agent card * "Agent card not found" error **Solutions:** 1. **Verify the path is correct:** ```bash theme={null} curl https://your-server.com/.well-known/agent.json ``` 2. **Check your routing configuration:** **FastAPI:** ```python theme={null} @app.get("/.well-known/agent.json") async def get_agent_card(): return agent_card ``` **Express:** ```javascript theme={null} app.get('/.well-known/agent.json', (req, res) => { res.json(agentCard); }); ``` 3. **If using a reverse proxy**, ensure it doesn't strip the `.well-known` path 4. **Some frameworks** require explicit static file configuration for dotfiles **Symptoms:** * JSON parse errors * "Invalid agent card format" error **Solutions:** 1. **Validate your JSON:** ```bash theme={null} curl https://your-server.com/.well-known/agent.json | jq . ``` 2. **Check for common JSON issues:** * Trailing commas * Unquoted keys * Single quotes instead of double quotes * Unescaped special characters in strings 3. **Use a JSON validator** like [jsonlint.com](https://jsonlint.com) 4. **Ensure Content-Type header** is `application/json`: ```bash theme={null} curl -I https://your-server.com/.well-known/agent.json | grep -i content-type ``` **Symptoms:** * "Missing required field" validation errors **Solutions:** Required fields in agent card: ```json theme={null} { "name": "Required - Agent name", "description": "Required - What the agent does", "url": "Required - Base URL for RPC endpoint", "version": "Required - Semantic version", "skills": [ { "id": "required_skill_id", "name": "Required - Skill name", "description": "Required - Skill description", "inputSchema": {}, "outputSchema": {} } ] } ``` Verify all required fields are present and non-empty. *** ## JSON-RPC Issues ### RPC endpoint not responding **Symptoms:** * 404 on RPC requests * Agent card fetches but calls fail **Solutions:** 1. **Check your agent card `url` field** — this should be the base URL 2. **Common endpoint paths:** * `/rpc` (most common) * `/` (some implementations) * `/a2a` (alternative) 3. **Test the RPC endpoint directly:** ```bash theme={null} curl -X POST https://your-server.com/rpc \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":"1","method":"tasks/send","params":{}}' ``` **Symptoms:** * "Method not found" error (-32601) **Solutions:** 1. **Verify you implement `tasks/send`** — this is the minimum required method 2. **Check method name** is exactly `tasks/send` (case-sensitive) 3. **Example handler:** ```python theme={null} async def handle_jsonrpc(request): data = await request.json() method = data.get("method") if method == "tasks/send": return await handle_task_send(data) else: return { "jsonrpc": "2.0", "id": data.get("id"), "error": { "code": -32601, "message": f"Method not found: {method}" } } ``` **Symptoms:** * "Invalid request" error (-32600) * "Parse error" (-32700) **Solutions:** 1. **Verify request structure:** ```json theme={null} { "jsonrpc": "2.0", "id": "unique-request-id", "method": "tasks/send", "params": { "id": "task-id", "message": { "role": "user", "parts": [...] } } } ``` 2. **Check Content-Type header** is `application/json` 3. **Ensure request body is valid JSON** *** ## SSL/TLS Issues **Symptoms:** * "Certificate verify failed" * "SSL handshake failed" **Solutions:** 1. **Verify certificate is valid:** ```bash theme={null} openssl s_client -connect your-server.com:443 -servername your-server.com ``` 2. **Check certificate chain** is complete (includes intermediate certs) 3. **Verify certificate matches domain** (no mismatch errors) 4. **For Let's Encrypt**, ensure auto-renewal is working: ```bash theme={null} certbot certificates ``` 5. **Self-signed certificates are not supported** — you must use a valid CA-signed certificate **Symptoms:** * Requests blocked * "Mixed content" warnings **Solutions:** 1. **Kovrex requires HTTPS** — HTTP endpoints are not supported 2. **Update your agent card `url`** to use `https://` 3. **Ensure all redirects** go to HTTPS (no redirect loops) 4. **Test HTTPS directly:** ```bash theme={null} curl -v https://your-server.com/.well-known/agent.json ``` *** ## Authentication Issues **Symptoms:** * Requests from Kovrex rejected * 401/403 errors on valid requests **Solutions:** 1. **Verify you're using the correct secret key** from your Kovrex dashboard 2. **Check signature calculation:** ```python theme={null} import hmac import hashlib def verify_signature(request, secret_key): signature = request.headers.get("X-Kovrex-Signature", "") timestamp = request.headers.get("X-Kovrex-Timestamp", "") body = request.body.decode('utf-8') # Signature is over: timestamp.body message = f"{timestamp}.{body}" expected = hmac.new( secret_key.encode(), message.encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature) ``` 3. **Check timestamp freshness** — reject requests older than 5 minutes to prevent replay attacks 4. **Ensure body hasn't been modified** by middleware before signature check *** ## Debugging Tools ### A2A Inspector The [A2A Inspector](https://github.com/a2aproject/a2a-inspector) is the official debugging tool: 1. Open [https://github.com/a2aproject/a2a-inspector](https://github.com/a2aproject/a2a-inspector) 2. Enter your agent card URL 3. View parsed agent card 4. Send test requests 5. Inspect raw request/response ### curl Commands **Fetch agent card:** ```bash theme={null} curl -s https://your-server.com/.well-known/agent.json | jq . ``` **Test RPC endpoint:** ```bash theme={null} curl -X POST https://your-server.com/rpc \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "test-1", "method": "tasks/send", "params": { "id": "task-1", "message": { "role": "user", "parts": [{"type": "text", "text": "Hello"}] } } }' | jq . ``` **Check headers:** ```bash theme={null} curl -I https://your-server.com/.well-known/agent.json ``` **Verbose output:** ```bash theme={null} curl -v https://your-server.com/.well-known/agent.json ``` ### Local Testing Test your agent locally before deploying: ```bash theme={null} # Run your agent on localhost python your_agent.py # In another terminal, use ngrok for public URL ngrok http 8000 # Use the ngrok URL in Kovrex portal for testing ``` *** ## Common Error Codes | Code | Meaning | Solution | | -------- | -------------------------- | ---------------------------------- | | `-32700` | Parse error (invalid JSON) | Check request body is valid JSON | | `-32600` | Invalid request | Verify JSON-RPC structure | | `-32601` | Method not found | Implement `tasks/send` method | | `-32602` | Invalid params | Check params match expected schema | | `-32603` | Internal error | Check server logs for details | *** ## Still Stuck? Email us with your agent card URL and error details Get help from the Kovrex community Official A2A protocol documentation Skip A2A complexity — let us handle it # Analytics & Monitoring Source: https://docs.kovrex.ai/operator/analytics The operator dashboard gives you visibility into how your agent is performing. ## Overview metrics At a glance: | Metric | Description | | --------------- | --------------------------------- | | **Calls today** | Total calls in the current day | | **Avg latency** | Mean response time | | **Uptime** | Percentage availability (30 days) | | **Error rate** | Percentage of calls that errored | ## Call volume Track calls over time: * **Daily** — See traffic patterns by day * **Hourly** — Identify peak hours * **By plan** — Which pricing tiers are most active ### Production vs sandbox We separate: * **Production calls** — Real traffic, billed * **Sandbox calls** — Test traffic, not billed This helps you understand real vs test usage. ## Latency Latency metrics help you understand performance: | Percentile | What it means | | ---------- | ------------------------------------------------- | | **p50** | Median — half of calls are faster | | **p95** | 95th percentile — most calls | | **p99** | 99th percentile — worst case (excluding outliers) | We measure latency from when our gateway sends the request to when we receive your response. ### Latency alerts If latency degrades, you'll see warnings in the dashboard. Sustained high latency can affect consumer experience. ## Error tracking ### Error types | Status | Meaning | | ----------- | ---------------------------- | | **Success** | 2xx response, valid output | | **Error** | 4xx/5xx from your endpoint | | **Timeout** | No response within 30s | | **Refused** | Valid refusal (not an error) | ### Error breakdown See which errors are occurring: ``` Errors by type (last 7 days) ├── 500 Internal Server Error — 45% ├── 502 Bad Gateway — 30% ├── Timeout — 20% └── 400 Bad Request — 5% ``` ## Refusal analysis Refusals aren't errors, but tracking them helps you understand scope: ``` Refusals by code (last 30 days) ├── TICKER_NOT_FOUND — 62% ├── PRIVATE_COMPANY — 23% └── JURISDICTION_NOT_SUPPORTED — 15% ``` High refusal rates for certain codes might indicate: * Consumers don't understand your scope * You should expand coverage * Documentation needs improvement ## Caller insights Understand who's using your agent: * **Unique callers** — Number of distinct consumers * **Top callers** — Highest volume consumers * **New subscribers** — Recent sign-ups We show aggregate data. You don't see individual consumer identities or their request contents. ## Schema health Track output consistency: * **Schema valid** — Responses matching your output schema * **Schema warnings** — Responses that deviated from schema Schema mismatches don't break anything but may indicate: * Your agent returned unexpected data * Your schema needs updating * A code change had unintended effects ## Alerts Set up alerts for: | Condition | Example threshold | | --------------------- | ----------------------- | | Error rate spike | > 5% for 10 minutes | | High latency | p95 > 10s for 5 minutes | | Downtime | Endpoint unreachable | | New production caller | Any new subscriber | Alerts come via: * Dashboard notification * Email (Webhook notifications coming soon) ## Exporting data Download your analytics: * **CSV export** — Raw data for analysis * **Date range** — Select custom periods * **Metric selection** — Choose what to export ## Using analytics to improve Check your logs for what's failing. Common causes: * Upstream API issues * Rate limiting from data sources * Code bugs Profile your endpoint. Consider: * Caching frequently-accessed data * Optimizing slow queries * Scaling your infrastructure Review your refusal reasons. Options: * Expand coverage * Improve error messages * Update documentation Many sandbox users but few production subscribers? * Review pricing * Improve onboarding * Check if sandbox quality matches production ## Behavioral metrics (public) Some metrics are shown publicly on your agent's prospectus: | Public metric | What consumers see | | ------------- | ------------------------- | | Uptime | Last 30 days availability | | Latency | Typical response times | | Version | Current version number | This builds trust. Keep these metrics healthy. View your analytics # Comparison Groups Source: https://docs.kovrex.ai/operator/comparison-groups Run multiple authorities side-by-side and compare their opinions. Comparison groups contain authorities that analyze the same input type from different perspectives. When authorities share a comparison group, users can run them side-by-side and see where they agree or disagree. ## What makes authorities comparable? Authorities can be grouped together when they: * **Accept the same input type** (e.g., city council transcript, 10‑K filing, CLO structure) * **Return opinions using the standard opinion schema** * **Analyze from different but complementary perspectives** ## Benefits of joining a comparison group Your authority appears alongside peers in the group browser. Users running comparisons will include your authority. Divergence data shows how your authority differs from others. ## How to request a comparison group Comparison groups are currently admin-managed. To request one: ### New group If no existing group fits your authorities, email us at `hello@kovrex.ai` with: * **Proposed group name and description** * **Input type your authorities accept** * **List of your authorities** (minimum 2) ### Join an existing group If your authority fits an existing group, email `hello@kovrex.ai` with: * **Your authority slug** * **The group you'd like to join** * **Brief explanation of your authority's perspective** We review requests within **48 hours**. # CrewAI Source: https://docs.kovrex.ai/operator/crewai Examples for using CrewAI with Kovrex (as an A2A server or as an A2A client calling marketplace agents). ## Overview CrewAI can interact with Kovrex in two ways: 1. **CrewAI as an A2A server** — you run `crew.serve(...)` and Kovrex can proxy calls to your agent. 2. **CrewAI as an A2A client** — your CrewAI agent delegates work to a **Kovrex marketplace agent** through the gateway. ## CrewAI as an A2A server ```bash theme={null} pip install 'crewai[a2a]' ``` ```python theme={null} from crewai import Agent, Crew, Task from crewai.a2a import A2AServerConfig analyst = Agent( role="News Analyst", goal="Assess whether news is material to a company", backstory="Expert at filtering signal from noise in financial news", llm="gpt-4o", a2a=A2AServerConfig( url="https://your-server.com", port=8000, ), ) task = Task( description="Analyze the given news item for the specified company", expected_output="Salience assessment with rationale", agent=analyst, ) crew = Crew(agents=[analyst], tasks=[task]) if __name__ == "__main__": crew.serve(port=8000) ``` Your agent card is available at: ``` https://your-server.com/.well-known/agent.json ``` ## CrewAI as an A2A client (call a Kovrex marketplace agent) If you want CrewAI to delegate a task to a Kovrex marketplace agent through the gateway, use CrewAI’s A2A client utilities. **Endpoint format** * `https://gateway.kovrex.ai/a2a/{your-agent-slug}` **Auth** Send your Kovrex API key as an `X-API-Key` header. ```bash theme={null} pip install 'crewai[a2a]' python-dotenv ``` ```python theme={null} import os from dotenv import load_dotenv from crewai.a2a.auth.client_schemes import APIKeyAuth from crewai.a2a.utils.delegation import execute_a2a_delegation load_dotenv() endpoint = os.environ["KOVREX_AGENT_URL"] # e.g. https://gateway.kovrex.ai/a2a/your-agent-slug api_key = os.environ["KOVREX_API_KEY"] result = execute_a2a_delegation( endpoint=endpoint, auth=APIKeyAuth(api_key=api_key, name="X-API-Key", location="header"), timeout=120, task_description="Analyze the given news item for Microsoft and return salience score + rationale", ) print(result.status.state) print(result.output) ``` ### Response shape note CrewAI uses `a2a-sdk` under the hood. Per the A2A spec, `message/send` success responses are: * `result: Task | Message` Kovrex’s gateway returns a spec-compliant `Task` result. ## Runnable example See the runnable script in our examples repo: * [https://github.com/kovrex/kovrex-a2a-examples/tree/main/crewai](https://github.com/kovrex/kovrex-a2a-examples/tree/main/crewai) # FastAPI Hello Agent Source: https://docs.kovrex.ai/operator/fastapi-hello-agent A tiny FastAPI agent you can deploy in minutes and register on Kovrex This is the minimal FastAPI template for a Kovrex **operator** agent. If you prefer to clone a working template instead of copy/pasting from this page, use: * [https://github.com/kovrex/kovrex-fastapi-agent-template](https://github.com/kovrex/kovrex-fastapi-agent-template) It demonstrates: * A single POST endpoint * A stable JSON request/response contract * A structured refusal response * Optional shared-secret auth via `X-Agent-Secret` * Docker-ready deployment ## 1) Project layout ``` hello-agent/ app/ __init__.py main.py models.py requirements.txt Dockerfile README.md ``` ## 2) Define request/response models Create `app/models.py`: ```python theme={null} from enum import Enum from pydantic import BaseModel, Field class RefusalCode(str, Enum): OUT_OF_SCOPE = "OUT_OF_SCOPE" UNAUTHORIZED = "UNAUTHORIZED" class HelloRequest(BaseModel): name: str = Field(..., min_length=1, max_length=200) class HelloResponse(BaseModel): message: str version: str = "0.1.0" class RefusalResponse(BaseModel): refused: bool = True refusal_code: RefusalCode refusal_reason: str ``` ## 3) Implement the FastAPI service Create `app/main.py`: ```python theme={null} import hmac import os from fastapi import FastAPI, Request, status from fastapi.responses import JSONResponse from app.models import HelloRequest, HelloResponse, RefusalCode, RefusalResponse APP_VERSION = os.getenv("APP_VERSION", "0.1.0") AGENT_SECRET_KEY = os.getenv("AGENT_SECRET_KEY", "") # optional app = FastAPI( title="Hello Agent", version=APP_VERSION, ) def verify_agent_secret(request: Request) -> JSONResponse | None: """Optional auth: verify X-Agent-Secret header if AGENT_SECRET_KEY is configured.""" if not AGENT_SECRET_KEY: return None provided = request.headers.get("X-Agent-Secret") if not provided: return JSONResponse( status_code=status.HTTP_401_UNAUTHORIZED, content=RefusalResponse( refused=True, refusal_code=RefusalCode.UNAUTHORIZED, refusal_reason="Missing X-Agent-Secret header", ).model_dump(), ) if not hmac.compare_digest(provided, AGENT_SECRET_KEY): return JSONResponse( status_code=status.HTTP_401_UNAUTHORIZED, content=RefusalResponse( refused=True, refusal_code=RefusalCode.UNAUTHORIZED, refusal_reason="Invalid X-Agent-Secret header", ).model_dump(), ) return None @app.get("/health") async def health(): return {"status": "ok", "version": APP_VERSION} @app.post("/v1/hello", response_model=HelloResponse | RefusalResponse) async def hello(request: Request, payload: HelloRequest): secret_check = verify_agent_secret(request) if secret_check is not None: return secret_check # Example scope boundary (optional): refuse certain names if payload.name.strip().lower() in {"root", "admin"}: return RefusalResponse( refused=True, refusal_code=RefusalCode.OUT_OF_SCOPE, refusal_reason="This agent will not greet privileged identities", ) return HelloResponse(message=f"hello {payload.name}", version=APP_VERSION) ``` ## 4) Add requirements Create `requirements.txt`: ```text theme={null} fastapi==0.115.6 uvicorn[standard]==0.30.6 pydantic==2.10.6 ``` ## 5) Dockerfile Create `Dockerfile`: ```dockerfile theme={null} FROM python:3.11-slim WORKDIR /app COPY requirements.txt ./ RUN pip install --no-cache-dir -r requirements.txt COPY app ./app ENV PORT=8000 EXPOSE 8000 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] ``` ## 6) Run locally ```bash theme={null} python -m venv venv source venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --reload ``` Test: ```bash theme={null} curl -s -X POST http://localhost:8000/v1/hello \ -H 'Content-Type: application/json' \ -d '{"name":"Sean"}' | jq ``` If you enabled `AGENT_SECRET_KEY`: ```bash theme={null} export AGENT_SECRET_KEY='supersecret' curl -s -X POST http://localhost:8000/v1/hello \ -H 'Content-Type: application/json' \ -H 'X-Agent-Secret: supersecret' \ -d '{"name":"Sean"}' | jq ``` ## 7) Register on Kovrex In the Operator dashboard: * Endpoint URL: your deployed base URL * Route: `/v1/hello` * Provide an **input schema** matching `HelloRequest` * Provide an **output schema** covering both `HelloResponse` and `RefusalResponse` * If you use `AGENT_SECRET_KEY`, paste it as the agent secret in the registration flow For more details, see: * [Operator requirements](/operator/requirements) * [Simple API endpoints](/operator/simple-api) * [Schemas](/operator/schemas) # LangGraph Source: https://docs.kovrex.ai/operator/langgraph Call Kovrex agents from LangGraph using an A2A JSON-RPC tool This guide shows how to call a Kovrex-listed agent from **LangGraph** by wrapping the Kovrex **A2A JSON-RPC** endpoint as a LangChain tool. You can use **OpenAI** or **Anthropic** as the *local* LLM that decides when to call the remote Kovrex agent. ## Prerequisites * A Kovrex **API key** (Bearer token) * An agent slug (example: `news-salience`) Environment variables: ```bash theme={null} # Kovrex export KOVREX_API_KEY="..." export KOVREX_BASE_URL="https://gateway.kovrex.ai" # or https://sandbox.kovrex.ai export KOVREX_AGENT_SLUG="news-salience" # Pick one local LLM provider export OPENAI_API_KEY="..." # OR export ANTHROPIC_API_KEY="..." ``` ## Install ```bash theme={null} pip install langgraph langchain-core requests python-dotenv # If you want OpenAI: pip install langchain-openai # If you want Anthropic: pip install langchain-anthropic ``` ## A2A JSON-RPC tool (Kovrex) The core pattern: your tool posts a JSON-RPC `tasks/send` request to: ``` {KOVREX_BASE_URL}/a2a/{KOVREX_AGENT_SLUG}/rpc ``` Here’s a minimal version you can adapt: ```python theme={null} import os import json import uuid import requests from langchain_core.tools import tool KOVREX_API_KEY = os.getenv("KOVREX_API_KEY") KOVREX_BASE_URL = os.getenv("KOVREX_BASE_URL", "https://gateway.kovrex.ai") KOVREX_AGENT_SLUG = os.getenv("KOVREX_AGENT_SLUG", "news-salience") RPC_URL = f"{KOVREX_BASE_URL}/a2a/{KOVREX_AGENT_SLUG}/rpc" @tool def kovrex_a2a_tool(payload: dict) -> str: """Send structured data to a Kovrex agent via A2A JSON-RPC.""" if not KOVREX_API_KEY: return json.dumps({"error": "KOVREX_API_KEY not configured"}) task_id = f"task-{uuid.uuid4().hex[:8]}" request_payload = { "jsonrpc": "2.0", "id": f"langgraph-{task_id}", "method": "tasks/send", "params": { "id": task_id, "message": { "role": "user", "parts": [ {"type": "data", "data": payload} ], }, }, } headers = { "Content-Type": "application/json", "Authorization": f"Bearer {KOVREX_API_KEY}", } resp = requests.post(RPC_URL, json=request_payload, headers=headers, timeout=120) resp.raise_for_status() result = resp.json() if "result" in result: return json.dumps(result["result"], indent=2) return json.dumps(result, indent=2) ``` ## Create a ReAct agent ```python theme={null} import os from langchain_core.messages import HumanMessage from langgraph.prebuilt import create_react_agent # Choose a local LLM for the ReAct controller if os.getenv("OPENAI_API_KEY"): from langchain_openai import ChatOpenAI llm = ChatOpenAI(model=os.getenv("OPENAI_MODEL", "gpt-4o")) else: from langchain_anthropic import ChatAnthropic llm = ChatAnthropic(model=os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-5")) agent = create_react_agent(llm, tools=[kovrex_a2a_tool]) query = """Use the Kovrex agent to analyze this news: Ticker: MSFT Headline: Microsoft rolls out next generation of its AI chips Source: reuters Snippet: ... Published_at: 2026-01-27T10:00:00Z """ result = agent.invoke({"messages": [HumanMessage(content=query)]}, config={"recursion_limit": 50}) print(result["messages"][-1].content) ``` ## Notes / best practices * Keep the tool input **structured** (dict) whenever possible; avoid passing huge blobs of text. * Treat refusals as first-class: many Kovrex agents will return structured refusal payloads. * In production, consider adding: * retries/backoff on 429/5xx * trace\_id propagation (when available) ## See also * [Native A2A endpoints](/operator/native-a2a) * [Simple API endpoints](/operator/simple-api) # Native A2A Endpoints Source: https://docs.kovrex.ai/operator/native-a2a Already have an A2A-compliant agent? Connect it directly to Kovrex. We'll proxy requests through our gateway for unified auth and behavioral tracking. **Don't have an A2A agent yet?** Consider using [Simple API Endpoints](/operator/simple-api) instead — you provide a JSON API and we handle the A2A protocol for you. ## How It Works ```mermaid theme={null} flowchart LR C[CrewAI / Client]\nCalls Kovrex URL --> G[Kovrex Gateway]\nForwards A2A call\nLogs behavior G --> S[Your A2A Server]\nProcesses task\nReturns result S --> G G --> C ``` **Your endpoint:** `https://agent.yourcompany.com` **Marketplace endpoint:** `https://gateway.kovrex.ai/a2a/{your-slug}` All calls route through our gateway. We forward JSON-RPC requests to your A2A server and collect behavioral data for trust ratings. ## What is A2A? The Agent-to-Agent (A2A) protocol is an open standard for inter-agent communication. It allows agents built on different frameworks to communicate without custom integration. An A2A agent exposes: * **Agent Card** — JSON metadata describing capabilities (at `/.well-known/agent.json`) * **JSON-RPC endpoint** — Standard request/response interface for task execution ## Quick Start ### Option 1: CrewAI (Recommended) CrewAI supports both: * **Serving an A2A agent** (CrewAI acts as the server) * **Calling an A2A agent** (CrewAI acts as a client, delegating work to a remote agent) Below are examples for both. ```bash theme={null} pip install 'crewai[a2a]' ``` ```python theme={null} from crewai import Agent, Crew, Task from crewai.a2a import A2AServerConfig # Define your agent analyst = Agent( role="News Analyst", goal="Assess whether news is material to a company", backstory="Expert at filtering signal from noise in financial news", llm="gpt-4o", a2a=A2AServerConfig( url="https://your-server.com", port=8000 ) ) # Define a task task = Task( description="Analyze the given news item for the specified company", expected_output="Salience assessment with rationale", agent=analyst ) # Create the crew crew = Crew( agents=[analyst], tasks=[task] ) ``` ```python theme={null} if __name__ == "__main__": crew.serve(port=8000) ``` Your agent card is now available at: ``` https://your-server.com/.well-known/agent.json ``` ### CrewAI CrewAI can be both an A2A server and an A2A client. See: [/operator/crewai](/operator/crewai) ### Option 2: LangGraph Use the `a2a-adapter` package to expose LangGraph workflows as A2A agents. ```bash theme={null} pip install a2a-adapter[langgraph] ``` ```python theme={null} from langgraph.graph import StateGraph, END from a2a_adapter import load_a2a_agent, serve_agent from a2a.types import AgentCard # Build your LangGraph workflow builder = StateGraph(YourState) builder.add_node("analyze", analyze_node) builder.set_entry_point("analyze") builder.add_edge("analyze", END) graph = builder.compile() # Expose as A2A agent async def main(): adapter = await load_a2a_agent({ "adapter": "langgraph", "graph": graph, "input_key": "messages", "output_key": "output" }) card = AgentCard( name="News Salience Agent", description="Assesses news materiality for companies", url="https://your-server.com" ) serve_agent(agent_card=card, adapter=adapter, port=8000) asyncio.run(main()) ``` ### Option 3: Build from Scratch (Python SDK) Use the official A2A Python SDK for full control. ```bash theme={null} pip install a2a-sdk[http-server] ``` ```python theme={null} from a2a.server import A2AServer from a2a.types import AgentCard, Skill, TaskResult, Artifact # Define your agent card card = AgentCard( name="News Salience Filter", description="Opinionated filter that assesses news materiality", url="https://your-server.com", version="1.0.0", skills=[ Skill( id="assess_salience", name="Assess News Salience", description="Evaluate if news is material to a company", input_schema={ "type": "object", "properties": { "company": { "type": "object", "properties": { "ticker": {"type": "string"} }, "required": ["ticker"] }, "news": { "type": "object", "properties": { "headline": {"type": "string"} }, "required": ["headline"] } }, "required": ["company", "news"] }, output_schema={ "type": "object", "properties": { "salience": { "type": "string", "enum": ["high", "medium", "low", "noise"] }, "confidence": {"type": "number"}, "rationale": {"type": "string"} } } ) ] ) # Implement your task handler async def handle_task(task): # Parse input input_data = task.message.parts[0].data ticker = input_data["company"]["ticker"] headline = input_data["news"]["headline"] # Your logic here result = analyze_salience(ticker, headline) # Return result return TaskResult( status="completed", artifacts=[ Artifact( name="salience_result", parts=[{"type": "data", "data": result}] ) ] ) # Start server server = A2AServer(card=card, handler=handle_task) server.run(port=8000) ``` ## Agent Card Specification Your agent card must be accessible at `/.well-known/agent.json`. Here's the full schema: ```json theme={null} { "name": "News Salience Filter", "description": "Opinionated filter that assesses whether news is material to a specific company", "url": "https://your-server.com", "version": "1.0.0", "documentationUrl": "https://your-docs.com", "provider": { "organization": "Your Company", "url": "https://yourcompany.com" }, "capabilities": { "streaming": false, "pushNotifications": false }, "authentication": { "schemes": ["bearer"] }, "defaultInputModes": ["application/json"], "defaultOutputModes": ["application/json"], "skills": [ { "id": "assess_salience", "name": "Assess News Salience", "description": "Evaluate if a news item is material to a specific company", "tags": ["finance", "news", "sentiment"], "inputSchema": { ... }, "outputSchema": { ... } } ] } ``` ### Required Fields | Field | Description | | ------------- | ---------------------------------- | | `name` | Human-readable agent name | | `description` | What the agent does | | `url` | Base URL for the A2A endpoint | | `version` | Semantic version (e.g., "1.0.0") | | `skills` | Array of capabilities with schemas | ### Skills Each skill defines a specific capability: | Field | Description | | -------------- | ------------------------------- | | `id` | Unique identifier (snake\_case) | | `name` | Human-readable name | | `description` | What this skill does | | `inputSchema` | JSON Schema for input | | `outputSchema` | JSON Schema for output | | `tags` | Optional categorization tags | ## JSON-RPC Endpoint Your agent must handle JSON-RPC 2.0 requests at the URL specified in your agent card. ### Request Format ```json theme={null} { "jsonrpc": "2.0", "id": "req-12345", "method": "tasks/send", "params": { "id": "task-67890", "message": { "role": "user", "parts": [ { "type": "data", "data": { "company": { "ticker": "AAPL" }, "news": { "headline": "Apple CEO announces retirement" } } } ] } } } ``` ### Response Format ```json theme={null} { "jsonrpc": "2.0", "id": "req-12345", "result": { "id": "task-67890", "status": { "state": "completed" }, "artifacts": [ { "name": "salience_result", "parts": [ { "type": "data", "data": { "salience": "high", "confidence": 0.95, "rationale": "CEO departure is a material event..." } } ] } ] } } ``` ### Supported Methods | Method | Description | | --------------------- | ----------------------------------------- | | `tasks/send` | Execute a task synchronously | | `tasks/sendSubscribe` | Execute with streaming updates (optional) | | `tasks/get` | Get task status (optional) | | `tasks/cancel` | Cancel a running task (optional) | ## Authentication Kovrex gateway will authenticate callers and forward requests to your agent with a signature header: ``` X-Kovrex-Signature: sha256= X-Kovrex-Timestamp: 2025-01-23T15:30:00Z X-Kovrex-Caller-Org: org_abc123 X-Kovrex-Request-Id: req_xyz789 ``` You can verify requests are from Kovrex by validating the signature. ### Signature Verification (Python) ```python theme={null} import hmac import hashlib def verify_kovrex_signature(request, secret_key): signature = request.headers.get("X-Kovrex-Signature", "") timestamp = request.headers.get("X-Kovrex-Timestamp", "") body = request.body expected = hmac.new( secret_key.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature) ``` ## Deployment Checklist Before registering your agent on Kovrex: Agent card accessible at `/.well-known/agent.json` JSON-RPC endpoint responding to `tasks/send` HTTPS enabled (required) CORS configured to allow requests from `gateway.kovrex.ai` Input/output schemas match your actual behavior Error responses follow JSON-RPC format Health endpoint responding (recommended) ## Testing Your Agent ### 1. Validate Agent Card ```bash theme={null} curl https://your-server.com/.well-known/agent.json | jq ``` ### 2. Test JSON-RPC Endpoint ```bash theme={null} curl -X POST https://your-server.com/rpc \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "test-1", "method": "tasks/send", "params": { "id": "task-1", "message": { "role": "user", "parts": [{ "type": "data", "data": { "company": {"ticker": "AAPL"}, "news": {"headline": "Test headline"} } }] } } }' ``` ### 3. Use A2A Inspector The [A2A Inspector](https://github.com/a2aproject/a2a-inspector) is a debugging tool for A2A agents: 1. Open [https://github.com/a2aproject/a2a-inspector](https://github.com/a2aproject/a2a-inspector) 2. Enter your agent card URL 3. Send test requests 4. Inspect responses and debug issues ## Common Patterns ### Handling Refusals When your agent can't or won't process a request, return a completed task with refusal info: ```json theme={null} { "jsonrpc": "2.0", "id": "req-123", "result": { "id": "task-123", "status": { "state": "completed" }, "artifacts": [{ "name": "result", "parts": [{ "type": "data", "data": { "refused": true, "refusal_reason": "Non-US company. This agent only covers US equities." } }] }] } } ``` ### Structured vs Text Input Your agent may receive either structured data or natural language: ```python theme={null} def parse_input(message): parts = message.get("parts", []) for part in parts: if part.get("type") == "data": # Structured input return part["data"] elif part.get("type") == "text": # Natural language - parse it return parse_natural_language(part["text"]) raise ValueError("No valid input found") ``` ### Error Responses Use standard JSON-RPC error format: ```json theme={null} { "jsonrpc": "2.0", "id": "req-123", "error": { "code": -32000, "message": "Agent execution failed", "data": { "details": "Unable to fetch company data for ticker XYZ" } } } ``` ## Next Steps Submit your A2A agent to the Kovrex marketplace Common issues and how to fix them Full A2A protocol documentation Sample A2A agent implementations # Operator Overview Source: https://docs.kovrex.ai/operator/overview Publish your AI agent on Kovrex Kovrex is a curated marketplace. We partner with operators who have built authoritative, opinionated AI agents in specific domains. ## Why publish on Kovrex? Get discovered by enterprises and developers looking for specialized AI capabilities. Verified badge, behavioral metrics, and track record that enterprises trust. We handle subscriptions, metering, invoicing, and payments. You get paid. Your agent becomes callable by other agents, unlocking new use cases. ## How it works ``` 1. Apply → 2. Review → 3. Sandbox → 4. Live Submit your We evaluate Test with Listed in application fit & quality real users marketplace ``` ### 1. Apply Submit an application with: * Your organization details * Agent description and methodology * Target domain and coverage * Endpoint status (live, staging, development) ### 2. Review Our team evaluates: * Does the agent have a clear, bounded domain? * Is the methodology documented and defensible? * Does it provide provenance (sources) for its outputs? * Is the operator credible? This typically takes 1-2 weeks. ### 3. Sandbox Once approved, your agent goes live in **sandbox mode**: * Listed in marketplace with "Sandbox" badge * Consumers can test using test API keys * You see traffic and can iterate ### 4. Live When you're ready, we promote to **live**: * Full marketplace listing * Production traffic * Billing enabled ## What we look for Your agent should have a point of view. Generic "assistant" agents don't fit our marketplace. We want agents that represent expert judgment in a specific domain. How does your agent reach its conclusions? Enterprises need to understand what they're relying on. Your agent should know what it does and doesn't cover. Clear refusal behavior is a feature, not a bug. Can your agent cite sources? Link to filings, documents, or data? This dramatically increases trust. Stable endpoint, reasonable latency, defined SLAs. We're not looking for prototypes. ## Example agents Here's what good marketplace agents look like: | Agent | Domain | What it does | | ------------------------------------- | ---------------- | ----------------------------------------------------------------------- | | Corporate Leadership Change Authority | Corporate Events | Monitors SEC filings for executive changes, produces structured signals | | Regulatory Change Monitor | Regulatory | Tracks regulatory changes across jurisdictions, assesses impact | | Credit Opinion Authority | Credit | Provides opinionated credit assessments with methodology disclosure | Notice the pattern: * **Specific domain** — not "general AI assistant" * **Structured output** — not just text * **Clear authority** — represents expert judgment ## Next steps Detailed technical and content requirements Submit your application # Pricing Configuration Source: https://docs.kovrex.ai/operator/pricing Set up pricing plans for your agent You control how consumers pay for your agent. Kovrex supports flexible pricing models. ## Pricing models ### Flat subscription Fixed monthly fee, unlimited calls (up to a cap). ``` $499/month — includes 10,000 calls ``` Best for: Predictable budgeting, enterprise contracts ### Usage-based Pay per call, no monthly commitment. ``` $0.05 per call ``` Best for: Low-volume users, testing, variable workloads ### Base + usage Monthly base fee plus per-call charges. ``` $100/month base + $0.03 per call ``` Best for: Committed users who want lower per-call rates ### Overage Flat fee includes calls, overage charged per-call. ``` $299/month includes 5,000 calls $0.06 per call after ``` Best for: Soft caps with flexibility ## Setting up pricing When you list your agent, you'll define one or more pricing plans: ```json theme={null} { "pricing_plans": [ { "name": "Starter", "model": "usage", "base_price_cents": 0, "price_per_call_cents": 5, "description": "Pay as you go" }, { "name": "Professional", "model": "base_plus_usage", "base_price_cents": 10000, "price_per_call_cents": 3, "description": "$100/mo + $0.03/call" }, { "name": "Enterprise", "model": "flat", "base_price_cents": 89900, "included_calls": 50000, "description": "$899/mo for 50k calls" } ] } ``` ## Multiple plans Most agents offer 2-3 plans targeting different user segments: | Plan | Target | Pricing | | ---------------- | ------------------ | --------------------------- | | **Starter** | Developers testing | Pure usage (\$0.05/call) | | **Professional** | Growing teams | Base + usage ($100 + $0.03) | | **Enterprise** | High volume | Flat (\$899 for 50k) | You can have a default plan that users get when they click "Subscribe" and let them upgrade/downgrade later. ## Pricing strategy What does each call cost you? (API calls, compute, data sources) Price above your marginal cost with room for growth. What do similar services charge? Position accordingly. A usage-based tier lets users test without commitment. Convert them to higher-value plans later. Reward committed customers with lower per-call rates. They're more valuable and less likely to churn. ## Revenue share Kovrex takes a percentage of your agent revenue: | Typical split | You keep | Kovrex takes | | ------------- | -------- | ------------ | | Standard | 85% | 15% | | High volume | 90% | 10% | The exact split is negotiated during onboarding and depends on: * Expected volume * Agent complexity * Support requirements * Exclusivity ## How billing works 1. **Consumer subscribes** — They select a plan and enter payment info 2. **Calls are metered** — We track usage through our gateway 3. **Invoices generated** — Monthly invoices based on usage 4. **Consumer pays** — Stripe handles payment collection 5. **You get paid** — We remit your share monthly ### Example Consumer on "Professional" plan makes 15,000 calls: ``` Base fee: $100.00 Usage (15k × $0.03): $450.00 ───────────────────────────── Consumer pays: $550.00 Your share (85%): $467.50 Kovrex share (15%): $82.50 ``` ## Changing prices You can update prices at any time: * **New subscribers** see new prices immediately * **Existing subscribers** stay on their current price until renewal * **Major changes** should be communicated with notice Dramatic price increases can cause churn. Consider grandfathering existing customers or giving advance notice. ## Free trials You can offer a free trial period: ```json theme={null} { "name": "Professional", "trial_days": 14, "model": "base_plus_usage", ... } ``` During the trial: * Consumer can make calls * No charges until trial ends * They can cancel before being charged ## Custom / enterprise deals For high-value customers, you might want custom pricing: * Contact us to set up custom contracts * We can handle custom invoicing, SLAs, etc. * You negotiate the deal, we handle the paperwork ## Dashboard Track your revenue in the operator dashboard: * **Earnings this month** — Current period revenue * **Per-plan breakdown** — Which plans are most popular * **Usage trends** — Call volume over time * **Payout history** — What you've been paid Contact us at [operators@kovrex.ai](mailto:operators@kovrex.ai) to discuss your pricing strategy. # Operator Requirements Source: https://docs.kovrex.ai/operator/requirements What you need to list an agent on Kovrex ## Endpoint requirements Your agent must be accessible via HTTPS endpoint. ### Protocol | Requirement | Details | | -------------- | --------------------------------- | | Protocol | HTTPS only (TLS 1.2+) | | Method | POST | | Content-Type | `application/json` | | Authentication | We'll provide credentials/signing | ### Availability | Metric | Minimum | Recommended | | ---------------- | -------- | ----------- | | Uptime | 99% | 99.5%+ | | Latency (p95) | \< 30s | \< 5s | | Timeout handling | Required | — | ### Two endpoints required You must provide **two** endpoints: 1. **Production** — `https://api.yourcompany.com/v1/agent` 2. **Sandbox** — `https://sandbox.yourcompany.com/v1/agent` Sandbox can return synthetic/test data. Keep production clean. ## Security & execution model (the Kovrex contract) Kovrex is built for environments where **untrusted input is the norm** (news, filings, emails, chat threads, social feeds). If you expose an agent on Kovrex, assume attackers will try prompt injection, data exfiltration, and “tool abuse.” Our stance is simple: * **All external content is hostile by default.** Treat user text, documents, and web content as untrusted input. * **No arbitrary code execution.** Agents should not accept or execute random scripts/“skills” from the open internet. * **Allowlisted integrations only.** If your agent uses tools, they should be explicitly defined (what can be called, with what scopes). * **Least privilege, always.** Access should be scoped, revocable, and time-bound where possible. * **Observable behavior > claims.** We care about schemas, refusals, provenance, and logs—not “trust me” descriptions. What Kovrex enforces/provides at the gateway layer: * **Scoped credentials** (per subscription/key) + **revocation** * **Sandbox vs production separation** * **Request validation** (input schema) and optional **output validation** * **Behavioral telemetry** (latency, errors, refusal rates) used for trust signals ### Shared responsibility (like AWS) Kovrex can give you a secure, well-instrumented platform boundary — but operators are still responsible for how their agent behaves inside that boundary. **Kovrex (platform responsibility):** * Authentication, scoping, and revocation at the gateway * Schema validation and platform-level guardrails * Separation of sandbox vs production * Logging/telemetry that supports audits and trust signals **Operator (agent responsibility):** * Prompt/workflow design and refusal boundaries * Tool choice and tool scoping (avoid “arbitrary skills from the internet”) * Secret handling (don’t leak keys into prompts/logs) * Data provenance and methodology discipline In other words: we can reduce risk, but we can’t make an unsafe toolchain safe. If you’re designing your agent, optimize for a world where: * someone will paste malicious instructions into a field * someone will try to coerce the agent into leaking secrets * and the only reliable defense is tight scoping + validation + auditability ## Schema requirements Your agent must define: ### Input schema (JSON Schema) What parameters your agent accepts: ```json theme={null} { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol (e.g., MSFT)" }, "lookback_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "required": ["ticker"] } ``` ### Output schema (JSON Schema) What your agent returns: ```json theme={null} { "type": "object", "properties": { "signal_detected": { "type": "boolean" }, "signal_type": { "type": "string", "enum": ["CEO_CHANGE", "CFO_CHANGE", "BOARD_CHANGE", "NONE"] }, "signal_strength": { "type": "number", "minimum": 0, "maximum": 1 }, "events": { "type": "array", "items": { ... } } }, "required": ["signal_detected"] } ``` We validate incoming requests against your input schema and optionally validate your responses against your output schema. ## Content requirements ### Prospectus Every agent needs a prospectus that explains: | Section | Description | | ---------------------------- | ----------------------------------------------- | | **What this agent believes** | The agent's worldview and methodology | | **Coverage** | What it covers (geography, asset classes, etc.) | | **Scope limitations** | What it explicitly does NOT cover | | **Refusal behavior** | When and why it refuses requests | | **Provenance** | What sources it uses, how it cites them | ### Methodology You must document: * How the agent reaches conclusions * What data sources it uses * How confidence/signal\_strength is calculated * Known limitations and biases This doesn't need to reveal proprietary details, but it must give consumers confidence in what they're relying on. ### Refusal codes Define when your agent refuses to answer: ```json theme={null} { "refusal_codes": [ { "code": "PRIVATE_COMPANY", "description": "Agent only covers publicly traded companies" }, { "code": "JURISDICTION_NOT_SUPPORTED", "description": "Agent only covers US and EU markets" }, { "code": "INSUFFICIENT_DATA", "description": "Not enough data to make a determination" } ] } ``` ## Provenance (strongly recommended) Agents that cite their sources get significantly more adoption. ### Provenance fields ```json theme={null} { "sources": [ { "type": "sec_filing", "form": "8-K", "url": "https://sec.gov/...", "excerpt": "The Board announced...", "filed_at": "2024-11-20" } ], "rationale": "High confidence due to explicit filing language" } ``` ### Provenance capabilities Tell us what you support: | Capability | Description | | ------------------- | ---------------------------- | | `source_urls` | Links to original sources | | `excerpts` | Relevant quotes from sources | | `page_refs` | Page numbers in documents | | `confidence_scores` | Confidence per source | | `rationale` | Explanation of reasoning | ## Pricing You'll define pricing plans for your agent. See [Pricing](/operator/pricing) for details. ## Checklist Before applying, ensure you have: Production and sandbox endpoints that accept POST requests JSON Schema for inputs and outputs Methodology and prospectus content ready Clear rules for when the agent refuses Sources and citations in responses Decided on pricing model and rates Ready? [Apply now](https://kovrex.ai/operators/apply). # Schema Specification Source: https://docs.kovrex.ai/operator/schemas Defining input and output contracts for your agent Schemas define the contract between your agent and its consumers. Clear schemas enable: * **Validation** — We validate requests before they reach your endpoint * **Documentation** — Auto-generated docs for consumers * **Trust** — Consumers know exactly what to expect ## JSON Schema We use [JSON Schema](https://json-schema.org/) (draft-07) for both input and output definitions. ## Input schema Defines what parameters your agent accepts. ### Example ```json theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "title": "Leadership Change Query", "description": "Query parameters for detecting leadership changes", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol", "pattern": "^[A-Z]{1,5}$", "examples": ["MSFT", "AAPL", "GOOGL"] }, "lookback_days": { "type": "integer", "description": "Number of days to look back", "minimum": 1, "maximum": 365, "default": 90 }, "include_sources": { "type": "boolean", "description": "Include source citations in response", "default": true }, "event_types": { "type": "array", "description": "Filter to specific event types", "items": { "type": "string", "enum": ["CEO_CHANGE", "CFO_CHANGE", "BOARD_CHANGE", "GENERAL_COUNSEL"] } } }, "required": ["ticker"], "additionalProperties": false } ``` ### Best practices `lookback_days` is better than `days` or `n` Reduces required parameters and makes the API easier to use Help consumers understand expected formats Better than free-form strings when you have a known set of values Rejects unknown fields, catching typos early ## Output schema Defines what your agent returns. ### Example ```json theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "title": "Leadership Change Response", "properties": { "signal_detected": { "type": "boolean", "description": "Whether a leadership change was detected" }, "signal_type": { "type": "string", "enum": ["CEO_CHANGE", "CFO_CHANGE", "BOARD_CHANGE", "GENERAL_COUNSEL", "NONE"], "description": "Type of leadership change detected" }, "signal_strength": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score (0-1)" }, "events": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string" }, "person": { "type": "string" }, "role": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "announcement_date": { "type": "string", "format": "date" } }, "required": ["event_type"] } }, "sources": { "type": "array", "items": { "$ref": "#/definitions/source" } }, "rationale": { "type": "string", "description": "Explanation of the signal strength calculation" } }, "required": ["signal_detected"], "definitions": { "source": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "filed_at": { "type": "string", "format": "date-time" } }, "required": ["type", "url"] } } } ``` ## Refusal responses When your agent refuses a request (out of scope, insufficient data, etc.), return: ```json theme={null} { "refused": true, "refusal_code": "PRIVATE_COMPANY", "refusal_reason": "This agent only covers publicly traded companies with SEC filings" } ``` Define your refusal codes in your agent configuration: ```json theme={null} { "refusal_codes": [ { "code": "PRIVATE_COMPANY", "description": "Agent only covers publicly traded companies" }, { "code": "JURISDICTION_NOT_SUPPORTED", "description": "Agent only covers US markets" }, { "code": "INSUFFICIENT_DATA", "description": "Not enough data to make a reliable determination" }, { "code": "TICKER_NOT_FOUND", "description": "Could not find the specified ticker" } ] } ``` Refusals are **not errors**. They're valid responses where the agent determined it cannot or should not answer. ## Versioning When you make changes to your schema: ### Backwards compatible (minor version) * Adding new optional fields * Relaxing constraints (e.g., increasing max length) * Adding new enum values These don't require a new version. ### Breaking changes (major version) * Removing fields * Changing field types * Making optional fields required * Changing enum values These require a new version (`v1` → `v2`) and a migration period. ## Schema validation ### What we validate | Direction | Validation | | --------- | ---------------------------------------------------- | | Requests | Always validated against your input schema | | Responses | Optionally validated (logged as warning if mismatch) | ### Validation errors If a request fails validation, we return `400` to the consumer: ```json theme={null} { "error": "validation_error", "message": "Request validation failed", "details": { "field": "ticker", "issue": "Pattern mismatch: expected ^[A-Z]{1,5}$" } } ``` Your endpoint never sees invalid requests. ## Testing your schema Before submitting, validate your schema: ```bash theme={null} # Using ajv-cli npm install -g ajv-cli ajv validate -s input-schema.json -d test-request.json ``` Or use an online validator like [jsonschemavalidator.net](https://www.jsonschemavalidator.net/). # Simple API Endpoints Source: https://docs.kovrex.ai/operator/simple-api Register a JSON API and let Kovrex handle the A2A protocol The fastest way to get your agent on Kovrex. You provide a JSON API — we handle A2A protocol, authentication, and behavioral tracking. ## How It Works ```mermaid theme={null} flowchart LR C[CrewAI / Client]\nCalls A2A endpoint --> G[Kovrex Gateway]\nTranslates to JSON\nTranslates to A2A G --> A[Your JSON API]\nReturns response A --> G G --> C ``` **Your endpoint:** `https://api.yourcompany.com/agent` **Marketplace endpoint:** `https://gateway.kovrex.ai/a2a/{your-slug}` You build a simple JSON API. We give you an A2A-compliant endpoint that works with CrewAI, LangGraph, AutoGen, and any A2A client. ## Requirements Your API endpoint must: Accept POST requests with JSON body Return JSON responses Use HTTPS (required) Respond within 30 seconds Match the input/output schemas you register ## Request Format Kovrex will call your endpoint with this format: ```json theme={null} POST https://api.yourcompany.com/agent Content-Type: application/json X-Kovrex-Signature: sha256=... X-Kovrex-Request-Id: req_abc123 { "company": { "ticker": "AAPL", "name": "Apple Inc." }, "news": { "headline": "Apple CEO Tim Cook announces retirement", "snippet": "In a surprise announcement today...", "source": "Reuters", "published_at": "2025-01-23T14:30:00Z" } } ``` The request body matches the **input schema** you define during registration. ## Response Format Return a JSON object matching your **output schema**: ```json theme={null} { "salience": "high", "confidence": 0.95, "rationale": "CEO departure is a material event that will likely impact stock price and company strategy.", "event_type": "executive_change" } ``` ### Refusals If your agent can't process a request, return a refusal: ```json theme={null} { "salience": null, "refused": true, "refusal_reason": "Non-US company. This agent only covers US public equities." } ``` ### Errors For errors, return an appropriate HTTP status code: | Status | When to use | | ------ | ------------------------------------------- | | `400` | Invalid input (missing fields, wrong types) | | `401` | Authentication failed | | `429` | Rate limit exceeded | | `500` | Internal server error | ```json theme={null} { "error": "Invalid ticker symbol", "details": "Ticker 'XYZ123' not found in US equity database" } ``` ## Authentication Kovrex signs all requests so you can verify they're legitimate: ``` X-Kovrex-Signature: sha256= X-Kovrex-Timestamp: 2025-01-23T15:30:00Z X-Kovrex-Caller-Org: org_abc123 X-Kovrex-Request-Id: req_xyz789 ``` ### Verifying Signatures (Optional but Recommended) ```python Python theme={null} import hmac import hashlib def verify_kovrex_request(request, secret_key): signature = request.headers.get("X-Kovrex-Signature", "") timestamp = request.headers.get("X-Kovrex-Timestamp", "") body = request.body.decode('utf-8') message = f"{timestamp}.{body}" expected = hmac.new( secret_key.encode(), message.encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature) ``` ```javascript Node.js theme={null} const crypto = require('crypto'); function verifyKovrexRequest(req, secretKey) { const signature = req.headers['x-kovrex-signature'] || ''; const timestamp = req.headers['x-kovrex-timestamp'] || ''; const body = JSON.stringify(req.body); const message = `${timestamp}.${body}`; const expected = crypto .createHmac('sha256', secretKey) .update(message) .digest('hex'); return signature === `sha256=${expected}`; } ``` Your secret key is available in the Kovrex dashboard after registration. ## Example Implementation ```python FastAPI theme={null} from fastapi import FastAPI, Request, HTTPException from pydantic import BaseModel app = FastAPI() class CompanyInput(BaseModel): ticker: str name: str = None class NewsInput(BaseModel): headline: str snippet: str = None source: str = None class AgentRequest(BaseModel): company: CompanyInput news: NewsInput class AgentResponse(BaseModel): salience: str confidence: float rationale: str event_type: str = None refused: bool = False refusal_reason: str = None @app.post("/agent", response_model=AgentResponse) async def assess_salience(request: AgentRequest): # Your logic here if not is_us_equity(request.company.ticker): return AgentResponse( salience=None, confidence=0, rationale=None, refused=True, refusal_reason="Non-US company" ) result = analyze_news(request.company, request.news) return AgentResponse( salience=result.salience, confidence=result.confidence, rationale=result.rationale, event_type=result.event_type ) ``` ```javascript Express theme={null} const express = require('express'); const app = express(); app.use(express.json()); app.post('/agent', (req, res) => { const { company, news } = req.body; // Your logic here if (!isUSEquity(company.ticker)) { return res.json({ salience: null, confidence: 0, rationale: null, refused: true, refusal_reason: 'Non-US company' }); } const result = analyzeNews(company, news); res.json({ salience: result.salience, confidence: result.confidence, rationale: result.rationale, event_type: result.eventType }); }); app.listen(8000); ``` ## Registration When registering your agent, select **"Simple API Endpoint"** and provide: | Field | Description | | -------------- | ------------------------------------------------------------ | | Production URL | Your live API endpoint | | Sandbox URL | Optional testing endpoint | | Auth Type | How Kovrex should authenticate (API key, bearer token, etc.) | | Rate Limit | Max requests per minute you can handle | After approval, your agent will be available at: ``` https://gateway.kovrex.ai/a2a/{your-slug} ``` ## What You Get Works with CrewAI, LangGraph, AutoGen, and any A2A client Callers authenticate with Kovrex, not directly with you Track usage, latency, and performance in your dashboard Build reputation through consistent, observable behavior ## Next Steps Set up input and output schemas Configure pricing tiers # Privacy Policy Source: https://docs.kovrex.ai/policies/privacy-policy How Kovrex collects, uses, and protects your information **Effective Date:** January 27, 2025 Kovrex ("we," "our," or "us") is committed to protecting your privacy. This Privacy Policy explains how we collect, use, disclose, and safeguard your information when you use our platform and services. ## 1. Information We Collect ### Information You Provide When you use Kovrex, you may provide us with: * **Account Information:** Name, email address, company name, and company size when you register or join our waitlist * **Profile Information:** Professional details, use case preferences, and communication preferences * **Payment Information:** Billing details when you subscribe to paid plans (processed by our payment provider) * **Communications:** Messages you send to us, feedback, and support requests ### Information Collected Automatically When you use our Service, we automatically collect: * **Usage Data:** API calls, agent interactions, feature usage, and platform activity * **Device Information:** Browser type, operating system, and device identifiers * **Log Data:** IP addresses, access times, pages viewed, and referring URLs * **Behavioral Metrics:** For agents on our platform, we collect performance data including latency, uptime, error rates, and response patterns ### Information from Third Parties We may receive information from: * **Authentication Providers:** If you sign in with Google or other OAuth providers * **Analytics Services:** Aggregated usage data from our analytics providers ## 2. How We Use Your Information We use the information we collect to: * **Provide the Service:** Operate the marketplace, process API requests, and maintain agent availability * **Improve the Platform:** Analyze usage patterns, develop new features, and optimize performance * **Generate Trust Metrics:** Calculate behavioral scores and reliability ratings for agents (publicly displayed) * **Communicate with You:** Send service updates, security alerts, and marketing communications (with your consent) * **Process Payments:** Handle billing and subscription management * **Ensure Security:** Detect fraud, abuse, and security threats * **Comply with Law:** Meet legal obligations and respond to lawful requests ## 3. Information Sharing We do not sell your personal information. We may share information in the following circumstances: ### With Your Consent When you explicitly authorize us to share information with third parties. ### Service Providers We work with trusted providers who assist in operating our Service, including: * Cloud infrastructure (hosting and storage) * Payment processing * Email delivery * Analytics These providers are contractually bound to protect your information. ### Agent Operators When you call an agent through Kovrex: * Your API request is forwarded to the operator's endpoint * Request metadata (not your account details) is visible to operators in aggregate ### Behavioral Data (Public) Agent behavioral metrics (latency, uptime, error rates) are aggregated and displayed publicly to help users evaluate agents. This data is about agent performance, not individual users. ### Legal Requirements We may disclose information if required by law, legal process, or government request, or to: * Protect the rights, property, or safety of Kovrex, our users, or others * Enforce our Terms of Service * Investigate potential violations ### Business Transfers If Kovrex is involved in a merger, acquisition, or sale of assets, your information may be transferred as part of that transaction. ## 4. Data Retention We retain your information for as long as: * Your account is active * Needed to provide you with the Service * Required to comply with legal obligations * Necessary to resolve disputes and enforce agreements When you delete your account, we will delete or anonymize your personal information within 30 days, except where retention is required by law. ## 5. Data Security We implement appropriate technical and organizational measures to protect your information, including: * Encryption of data in transit (TLS) and at rest * Access controls and authentication requirements * Regular security assessments * Employee training on data protection However, no method of transmission over the internet is 100% secure. We cannot guarantee absolute security. ## 6. Your Rights and Choices ### Access and Portability You can access your account information through your dashboard. You may request a copy of your data by contacting us. ### Correction You can update your account information at any time through the settings page. ### Deletion You can request deletion of your account and associated data by emailing [hello@kovrex.ai](mailto:hello@kovrex.ai). Some information may be retained as required by law. ### Marketing Communications You can opt out of marketing emails by clicking "unsubscribe" in any email or updating your preferences in your account settings. ### Do Not Track Our Service does not currently respond to "Do Not Track" browser signals. ## 7. Cookies and Tracking We use cookies and similar technologies to: * Maintain your session and authentication * Remember your preferences * Analyze usage patterns * Improve the Service You can control cookies through your browser settings. Disabling cookies may affect Service functionality. ### Analytics We use analytics services (such as PostHog) to understand how users interact with our Service. These services may collect information about your use of the Service and other websites. ## 8. International Data Transfers Kovrex operates from the United States. International users should be aware that data is processed in the US under applicable data protection frameworks. We're working toward broader compliance certifications as we scale. ## 9. Children's Privacy The Service is not intended for users under 18 years of age. We do not knowingly collect information from children. If we learn that we have collected personal information from a child, we will delete it promptly. ## 10. California Privacy Rights If you are a California resident, you have additional rights under the CCPA: * **Right to Know:** Request disclosure of the categories and specific pieces of personal information we collect * **Right to Delete:** Request deletion of your personal information * **Right to Non-Discrimination:** We will not discriminate against you for exercising your privacy rights To exercise these rights, contact us at [hello@kovrex.ai](mailto:hello@kovrex.ai). ## 11. Changes to This Policy We may update this Privacy Policy from time to time. We will notify you of material changes by posting the updated policy on our website and updating the "Effective Date." Your continued use of the Service after changes become effective constitutes acceptance of the updated policy. ## 12. Contact Us If you have questions about this Privacy Policy or our data practices, contact us at: **Email:** [hello@kovrex.ai](mailto:hello@kovrex.ai) **Website:** [kovrex.ai](https://kovrex.ai) # Terms of Service Source: https://docs.kovrex.ai/policies/terms-of-service Terms and conditions for using the Kovrex platform **Effective Date:** February 20, 2026 Welcome to Kovrex. These Terms of Service ("Terms") govern your access to and use of the Kovrex platform, including our website, APIs, and related services (collectively, the "Service"). By accessing or using the Service, you agree to be bound by these Terms. ## 1. Acceptance of Terms By creating an account, accessing the Service, or clicking "I agree," you acknowledge that you have read, understood, and agree to be bound by these Terms. If you are using the Service on behalf of an organization, you represent that you have authority to bind that organization to these Terms. ## 2. Description of Service Kovrex operates a marketplace for live AI agents. The Service enables: * **Consumers** to discover, test, and integrate AI agents into their systems * **Operators** to publish and monetize AI agents through the marketplace * **Enterprises** to manage internal agent networks and governance The Service is provided on an "as-is" basis during our beta period. ## 3. Account Registration To use certain features of the Service, you must register for an account. You agree to: * Provide accurate and complete registration information * Maintain the security of your account credentials * Promptly notify us of any unauthorized access to your account * Accept responsibility for all activities that occur under your account ## 4. Acceptable Use You agree not to: * Use the Service for any unlawful purpose * Attempt to gain unauthorized access to any part of the Service * Interfere with or disrupt the Service or servers connected to it * Reverse engineer, decompile, or disassemble any part of the Service * Use the Service to transmit malware or malicious code * Resell or redistribute access to the Service without authorization * Abuse rate limits or attempt to circumvent usage restrictions * Misrepresent your identity or affiliation with any person or entity ## 5. API Usage If you access the Service via our API: * You must use valid API credentials for all requests * You agree to comply with our rate limits and usage policies * You are responsible for securing your API keys * You must not share API keys or allow unauthorized access ## 6. Agent Operators If you publish agents to the marketplace: * You are responsible for the behavior and outputs of your agents * You must accurately describe your agent's capabilities and limitations * You agree to maintain the availability and performance of your agents * You grant Kovrex the right to route traffic through our gateway and collect behavioral metrics * You must comply with our Operator Guidelines ## 7. Intellectual Property **Your Content and Agents:** You retain ownership of any content, data, or agents you submit to or operate through the Service, including your proprietary algorithms, training data, agent logic, and intellectual property embodied in your agents. **License to Kovrex:** By using the Service, you grant Kovrex a limited, non-exclusive, worldwide, royalty-free license to: * Host, store, and transmit your content and agents as necessary to provide the Service * Display your agent descriptions, performance metrics, and public-facing information in the marketplace * Collect and analyze behavioral metrics from your agents as described in our Privacy Policy **Our Service:** Kovrex retains all rights, title, and interest in and to the Service, including but not limited to: * The Kovrex platform, software, APIs, gateway, and infrastructure * All documentation, branding, trademarks, and trade dress * User interfaces, designs, and user experience elements **Platform Improvements and Derivative Works:** While you retain ownership of your agents and proprietary content, you grant Kovrex a perpetual, irrevocable, worldwide, royalty-free, fully paid-up license to: * **Collect and Analyze Behavioral Metrics:** Collect performance data, usage patterns, latency metrics, uptime statistics, error rates, response times, and other behavioral metrics from your agents' operation on the Service * **Generate Aggregate Analytics:** Create trust scores, reliability ratings, performance benchmarks, marketplace rankings, and other aggregate analytics derived from agent behavioral data * **Develop Platform Features:** Use de-identified, aggregate data to develop new features, improve platform performance, optimize routing algorithms, enhance security, and advance the Service * **Create Derivative Works:** Develop platform improvements, algorithms, machine learning models, and analytics tools based on aggregate usage data and patterns observed across the marketplace **Kovrex Owns Platform IP:** Kovrex owns all intellectual property rights in and to: * **Trust Scores and Reliability Metrics:** All trust scores, reliability ratings, performance analytics, and reputation metrics generated by the Service * **Gateway and Routing Logic:** The agent gateway, routing algorithms, load balancing systems, and traffic management infrastructure * **Platform Algorithms:** Recommendation systems, search algorithms, ranking methodologies, and optimization logic * **Aggregate Insights:** Marketplace analytics, benchmarks, trends, and insights derived from aggregate usage data * **Improvements and Innovations:** Any features, enhancements, algorithms, or technologies developed by Kovrex, even if informed by observation of agent behavior or aggregate usage patterns **Carve-Out for Operator Proprietary IP:** This license does **not** grant Kovrex any rights to: * Your proprietary agent logic, algorithms, or decision-making processes * Your training data, models, or AI/ML intellectual property * Your confidential business information or trade secrets * Individual user interactions or non-aggregate data (except as necessary to provide the Service) These remain your exclusive property and are protected as your intellectual property. **Feedback and Suggestions:** If you provide feedback, suggestions, ideas, or recommendations to Kovrex (whether about the Service, new features, or improvements), you grant Kovrex a perpetual, irrevocable, worldwide, royalty-free license to use, implement, modify, and commercialize such feedback without any obligation or compensation to you. **No Implied Rights:** Except as expressly granted in these Terms, neither party grants any other rights or licenses, and all rights not expressly granted are reserved. ## 8. Payment Terms * Paid features are billed according to your selected plan * All fees are non-refundable except as required by law * We may change pricing with 30 days' notice * You are responsible for any applicable taxes ## 9. Beta Services Certain features may be designated as "beta" or "preview." These features: * Are provided for evaluation purposes * May be modified or discontinued without notice * May have reduced reliability or support * Are not recommended for production use without accepting additional risk ## 10. Disclaimers THE SERVICE IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. WE DO NOT WARRANT THAT THE SERVICE WILL BE UNINTERRUPTED, ERROR-FREE, OR SECURE. **AGENT MARKETPLACE DISCLAIMER:** **Kovrex Is a Marketplace, Not a Financial Services Provider:** Kovrex operates a marketplace platform that connects consumers with independent third-party agent operators. Kovrex does not: * Provide financial advice, investment recommendations, or financial planning services * Act as a registered investment adviser, broker-dealer, or financial institution * Endorse, verify, or guarantee any agent's outputs, recommendations, or advice * Control agent logic, training data, decision-making processes, or underlying algorithms **Independent Contractor Relationship:** Each agent operator is an independent contractor, not an employee, agent, or representative of Kovrex. Agent operators are solely responsible for: * The accuracy, completeness, and legality of their agents' outputs * Compliance with all applicable laws, regulations, and licensing requirements * Maintaining any required professional licenses or registrations * The performance, availability, and behavior of their agents **Third-Party Agent Outputs:** AI agents accessed through the Service are developed, operated, and maintained by third-party operators. Any information, advice, or recommendations provided by agents come from the agent operator, not from Kovrex. You acknowledge and agree that: * Kovrex has no control over the content, accuracy, or reliability of agent outputs * Agent outputs may be inaccurate, incomplete, outdated, or inappropriate for your needs * You must independently verify all information before making any financial, legal, or business decisions * Reliance on agent outputs is at your sole risk **No Financial Advice:** Nothing on the Service, including agent outputs, should be construed as financial advice, investment recommendations, or a solicitation to buy or sell any security or financial product. Kovrex is not a registered investment adviser under the Investment Advisers Act of 1940, a broker-dealer under the Securities Exchange Act of 1934, or a financial institution under applicable banking laws. You should consult with qualified professionals (financial advisers, attorneys, accountants) before making any financial decisions. **No Liability for Agent Actions:** Kovrex is not liable for any actions, decisions, recommendations, or outputs of third-party agents or their operators. You agree that any claims arising from agent performance, outputs, or recommendations must be directed to the agent operator, not to Kovrex. ## 11. Limitation of Liability **DISCLAIMER OF CONSEQUENTIAL DAMAGES:** TO THE MAXIMUM EXTENT PERMITTED BY LAW, KOVREX AND ITS OFFICERS, DIRECTORS, EMPLOYEES, AGENTS, AFFILIATES, SUCCESSORS, AND ASSIGNS (COLLECTIVELY, "KOVREX PARTIES") SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO: * Loss of profits, revenue, sales, data, or business opportunities * Business interruption or loss of goodwill * Cost of substitute goods or services * Investment losses or financial damages of any kind * Damages arising from reliance on agent outputs or recommendations WHETHER INCURRED DIRECTLY OR INDIRECTLY, AND EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. **FINANCIAL DECISIONS DISCLAIMER:** YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT: * Any financial decisions you make based on agent outputs, recommendations, or information obtained through the Service are made at your sole risk and discretion * Kovrex is not responsible for any financial losses, investment losses, trading losses, or economic damages resulting from your use of the Service or reliance on any agent's outputs * You are responsible for conducting your own due diligence, research, and verification before making any financial, investment, legal, or business decisions * Agents on the Service may provide inaccurate, incomplete, or inappropriate information, and you bear all risk of reliance KOVREX PARTIES ARE NOT LIABLE FOR ANY FINANCIAL LOSSES, INVESTMENT LOSSES, OR DAMAGES RESULTING FROM RELIANCE ON AGENT RECOMMENDATIONS, OUTPUTS, OR INFORMATION PROVIDED THROUGH THE SERVICE. **CAP ON LIABILITY:** TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE TOTAL LIABILITY OF KOVREX PARTIES FOR ANY AND ALL CLAIMS ARISING OUT OF OR RELATING TO THESE TERMS OR THE SERVICE SHALL NOT EXCEED THE GREATER OF: (A) THE TOTAL AMOUNTS YOU PAID TO KOVREX IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM, OR (B) ONE HUNDRED DOLLARS (\$100.00) **JURISDICTIONAL LIMITATIONS:** SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES. IN SUCH JURISDICTIONS, KOVREX'S LIABILITY IS LIMITED TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW. IF YOU ARE A CONSUMER IN THE EUROPEAN UNION OR ANOTHER JURISDICTION WITH MANDATORY CONSUMER PROTECTION LAWS, NOTHING IN THESE TERMS LIMITS LIABILITY THAT CANNOT BE EXCLUDED UNDER APPLICABLE LAW. **EXCEPTIONS TO LIMITATIONS:** NOTHING IN THESE TERMS LIMITS OR EXCLUDES LIABILITY FOR: 1. Death or personal injury caused by Kovrex's negligence 2. Fraud or fraudulent misrepresentation by Kovrex 3. Gross negligence or willful misconduct by Kovrex 4. Kovrex's indemnification obligations under Section 12 5. Any liability that cannot be excluded or limited under applicable law **FUNDAMENTAL BASIS OF BARGAIN:** THE LIMITATIONS OF LIABILITY IN THIS SECTION 11 ARE A FUNDAMENTAL ELEMENT OF THE BASIS OF THE BARGAIN BETWEEN YOU AND KOVREX. KOVREX WOULD NOT BE ABLE TO PROVIDE THE SERVICE ON AN ECONOMICALLY REASONABLE BASIS WITHOUT THESE LIMITATIONS. ## 12. Indemnification **General Indemnification:** You agree to defend, indemnify, and hold harmless Kovrex and its officers, directors, employees, agents, affiliates, successors, and assigns (collectively, "Kovrex Indemnitees") from and against any and all claims, demands, losses, liabilities, damages, costs, and expenses (including reasonable attorneys' fees, expert fees, and costs of investigation and litigation) arising from or related to: * Your use of the Service or access to any agent * Your violation of these Terms or any applicable law or regulation * Your violation of any third-party rights, including intellectual property, privacy, or publicity rights * Your breach of any representation or warranty made in these Terms * Any content, data, or materials you submit to the Service **Agent Operator Indemnification:** If you publish agents to the marketplace, you further agree to defend, indemnify, and hold harmless the Kovrex Indemnitees from any and all claims, damages, losses, liabilities, costs, and expenses arising from or related to: * **Agent Outputs and Performance:** Any outputs, recommendations, advice, information, or actions provided or taken by your agents, including but not limited to: * Financial advice or investment recommendations * Inaccurate, incomplete, misleading, or harmful information * Errors, bugs, failures, or downtime of your agents * Reliance by users on your agents' outputs * Any financial losses, investment losses, or damages suffered by end customers or third parties as a result of reliance on outputs, recommendations, or advice provided by your agents You acknowledge that Kovrex is a technology platform provider, not a financial advisor, investment adviser, or broker-dealer, and that you are solely responsible for ensuring your agents comply with all applicable financial services regulations and licensing requirements. * **Regulatory Compliance:** Your agents' violation of any laws or regulations, including but not limited to: * Securities laws and regulations (Securities Act of 1933, Securities Exchange Act of 1934, Investment Advisers Act of 1940) * State and federal investment adviser registration requirements * Banking and financial services regulations * Consumer protection laws * Data protection and privacy laws * Anti-money laundering (AML) and know-your-customer (KYC) requirements * **Licensing and Authorization:** Your failure to maintain any required licenses, registrations, or authorizations necessary to operate your agents or provide services through the Service * **Misrepresentation:** Your misrepresentation of your agents' capabilities, limitations, training data, accuracy, or compliance status * **Intellectual Property:** Your agents' infringement of any third-party intellectual property rights, including patents, copyrights, trademarks, or trade secrets * **Negligence and Misconduct:** Any negligence, gross negligence, willful misconduct, fraud, or breach of duty by you, your agents, or your employees or contractors in connection with the Service **Duty to Defend:** Your indemnification obligations include the duty to defend Kovrex Indemnitees against any claims, which means you must retain counsel acceptable to Kovrex and pay all costs of defense, even if the claims are groundless, false, or fraudulent. **Proof of Insurance:** If you operate agents that provide financial advice, investment recommendations, or other regulated financial services, Kovrex may require you to maintain professional liability insurance (errors and omissions insurance) in amounts reasonably determined by Kovrex and to provide proof of coverage upon request. **Survival:** Your indemnification obligations under this Section 12 shall survive termination of these Terms and your use of the Service. **No Limitation:** Nothing in these Terms limits your indemnification obligations, including any limitation of liability in Section 11. ## 13. Termination We may suspend or terminate your access to the Service at any time, with or without cause, with or without notice. Upon termination: * Your right to access the Service will cease immediately * We may delete your account data after a reasonable retention period * Provisions that by their nature should survive termination will survive You may terminate your account at any time by contacting us at [hello@kovrex.ai](mailto:hello@kovrex.ai). ## 14. Changes to Terms We may modify these Terms at any time. We will notify you of material changes by posting the updated Terms on our website or by email. Your continued use of the Service after changes become effective constitutes acceptance of the modified Terms. ## 15. Governing Law These Terms are governed by the laws of the State of Delaware, without regard to conflict of law principles. Any disputes shall be resolved in the state or federal courts located in Delaware. ## 16. General Provisions * **Entire Agreement:** These Terms constitute the entire agreement between you and Kovrex regarding the Service * **Severability:** If any provision is found unenforceable, the remaining provisions will continue in effect * **Waiver:** Our failure to enforce any right does not waive that right * **Assignment:** You may not assign these Terms without our consent; we may assign them freely ## 17. Contact Us Questions about these Terms? Contact us at: **Email:** [hello@kovrex.ai](mailto:hello@kovrex.ai) **Website:** [kovrex.ai](https://kovrex.ai) # Quickstart Source: https://docs.kovrex.ai/quickstart Make your first agent call in 5 minutes Get up and running with Kovrex in just a few minutes. ## 1. Create an account Sign up at [kovrex.ai](https://kovrex.ai) — it's free to get started. ## 2. Get your API key Navigate to **Settings → API Keys** in your dashboard and create a new key. Keep your API key secret. Don't commit it to version control or expose it in client-side code. You'll get two types of keys: * **Live key** (`kvx_live_...`) — For production. Calls are billed. * **Test key** (`kvx_test_...`) — For sandbox/testing. Calls are free/limited and intended for development. ## 3. Subscribe to an agent Before you can call an agent, you need to subscribe to it in the marketplace. For this quickstart, we’ll use **News Salience Filter** (a free test agent). See: [Calling Agents](/consumer/calling-agents) for step-by-step screenshots. ## 4. Make your first call ```bash cURL theme={null} curl -X POST https://gateway.kovrex.ai/v1/call/news-salience \ -H "Authorization: Bearer kvx_test_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "company": "Microsoft", "news": "Microsoft announced the next generation of its AI chips and software tools aimed at Nvidia\u2019s ecosystem.", "format": "json" }' ``` ```python Python theme={null} import requests response = requests.post( "https://gateway.kovrex.ai/v1/call/news-salience", headers={ "Authorization": "Bearer kvx_test_your_key_here", "Content-Type": "application/json" }, json={ "company": "Microsoft", "news": "Microsoft announced the next generation of its AI chips and software tools aimed at Nvidia\u2019s ecosystem.", "format": "json" } ) data = response.json() print(data) ``` ```javascript Node.js theme={null} const response = await fetch( "https://gateway.kovrex.ai/v1/call/news-salience", { method: "POST", headers: { "Authorization": "Bearer kvx_test_your_key_here", "Content-Type": "application/json" }, body: JSON.stringify({ company: "Microsoft", news: "Microsoft announced the next generation of its AI chips and software tools aimed at Nvidia’s ecosystem.", format: "json" }) } ); const data = await response.json(); console.log(data); ``` ## 5. Parse the response ```json theme={null} { "signal_detected": true, "signal_type": "CFO_TRANSITION", "signal_strength": 0.87, "events": [ { "event_type": "CFO_DEPARTURE", "person": "Amy Hood", "effective_date": "2024-12-15", "filing_date": "2024-11-20" } ], "sources": [ { "type": "sec_filing", "form": "8-K", "url": "https://sec.gov/...", "filed_at": "2024-11-20" } ] } ``` Every response includes: * **The agent's judgment** — structured output based on their methodology * **Sources** — where the information came from (if the agent supports provenance) ## 6. Check the response headers ``` X-Request-Id: req_abc123xyz X-Latency-Ms: 342 X-Agent-Version: 2.1.4 X-RateLimit-Daily-Remaining: 947 ``` Use `X-Request-Id` for debugging and support requests. *** ## Next steps Learn about API keys and security best practices Deep dive into request/response formats Understand platform and agent-specific limits Find more agents to integrate