Kevros

Cryptographic governance for autonomous agents: precision decisioning, provenance attestation, intent binding, capability delegation, policy analysis, and compliance export.

Every decision gets a signed release token. Every action gets a hash-chained record. Every intent gets a cryptographic binding to its command. Downstream services verify independently — no callbacks, no trust assumptions.

Base URL: https://governance.taskhawktech.com

Quick Start

Get an API key (free, instant, no payment):

curl -X POST https://governance.taskhawktech.com/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id"}'

Response:

{
  "api_key": "kvrs_...",
  "tier": "free",
  "monthly_limit": 1000,
  "usage": {
    "header": "X-API-Key"
  }
}

Use the API key in all subsequent requests via the X-API-Key header.

Precision Decisioning

POST /governance/verify

Verify an action against policy bounds before execution. Returns ALLOW, CLAMP, or DENY with a cryptographic release token that any downstream service can verify independently.

Request:

{
  "action_type": "api_call",
  "action_payload": {
    "endpoint": "/deploy",
    "service": "api-v2",
    "replicas": 3
  },
  "agent_id": "your-agent-id",
  "policy_context": {
    "max_values": { "replicas": 5 },
    "forbidden_keys": ["sudo", "force"]
  }
}

Response:

{
  "decision": "ALLOW",
  "verification_id": "a1b2c3d4-...",
  "release_token": "f7a8b9c0...",
  "applied_action": {
    "endpoint": "/deploy",
    "service": "api-v2",
    "replicas": 3
  },
  "reason": "All values within policy bounds",
  "epoch": 42,
  "provenance_hash": "e3b0c442...",
  "timestamp_utc": "2026-02-26T12:00:00Z"
}

ALLOW — proceed as planned. The release_token is proof.
CLAMP — action was adjusted to safe bounds. Use applied_action instead of your original.
DENY — action rejected. Do not proceed. release_token is null.

Share the release_token with collaborating agents so they can independently verify the decision.

Provenance Attestation

POST /governance/attest

Record a completed action in a hash-chained, append-only evidence ledger. Each attestation extends your provenance chain. Your raw payload is SHA-256 hashed — actual data is never stored.

Request:

{
  "agent_id": "your-agent-id",
  "action_description": "Deployed api-v2 with 3 replicas",
  "action_payload": {
    "service": "api-v2",
    "replicas": 3,
    "status": "success"
  },
  "context": {
    "environment": "production",
    "triggered_by": "scheduled"
  }
}

Response:

{
  "attestation_id": "b2c3d4e5-...",
  "epoch": 43,
  "hash_prev": "e3b0c442...",
  "hash_curr": "a1b2c3d4...",
  "timestamp_utc": "2026-02-26T12:00:01Z",
  "chain_length": 43
}

A longer chain with consistent outcomes builds a higher trust score over time.

Intent Binding

POST /governance/bind

Bind a declared intent to a specific command. Creates a cryptographic link between what you plan to do and the command that does it. Prove later that you did exactly what you said you would.

Request:

{
  "agent_id": "your-agent-id",
  "intent_type": "MAINTENANCE",
  "intent_description": "Scale api-v2 to handle traffic spike",
  "command_payload": {
    "action": "scale",
    "service": "api-v2",
    "replicas": 5
  },
  "goal_state": {
    "replicas": 5,
    "healthy": true
  }
}

Response:

{
  "intent_id": "c3d4e5f6-...",
  "intent_hash": "d4e5f6a7...",
  "binding_id": "e5f6a7b8-...",
  "binding_hmac": "a7b8c9d0...",
  "command_hash": "b8c9d0e1...",
  "epoch": 44,
  "timestamp_utc": "2026-02-26T12:00:02Z"
}

Save intent_id and binding_id to verify outcomes later.

Verify Outcome

POST /governance/verify-outcome

Verify whether a bound intent achieved its goal state. Free when used with a prior bind() call.

Request:

{
  "agent_id": "your-agent-id",
  "intent_id": "c3d4e5f6-...",
  "binding_id": "e5f6a7b8-...",
  "actual_state": {
    "replicas": 5,
    "healthy": true
  },
  "tolerance": 0.1
}

Response:

{
  "verification_id": "f6a7b8c9-...",
  "intent_id": "c3d4e5f6-...",
  "status": "ACHIEVED",
  "achieved_percentage": 100.0,
  "discrepancy": null,
  "evidence_hash": "c9d0e1f2...",
  "timestamp_utc": "2026-02-26T12:00:03Z"
}

Status values: ACHIEVED, PARTIALLY_ACHIEVED, FAILED, BLOCKED, TIMEOUT. Free when used with a prior bind() call.

Compliance Bundle

POST /governance/bundle — $0.25 per call

Export your agent's full cryptographic trust record for compliance, auditing, or regulatory review.

Request:

{
  "agent_id": "your-agent-id",
  "time_range_start": "2026-02-25T00:00:00Z",
  "time_range_end": "2026-02-26T12:00:00Z",
  "include_intent_chains": true,
  "include_pqc_signatures": true,
  "include_verification_instructions": true
}

Response:

{
  "bundle_id": "d4e5f6a7-...",
  "agent_id": "your-agent-id",
  "record_count": 42,
  "truncated": false,
  "chain_integrity": true,
  "time_range": {"start": "2026-02-25T00:00:00Z", "end": "2026-02-26T12:00:00Z"},
  "records": ["..."],
  "intent_chains": ["..."],
  "pqc_signatures": ["..."],
  "verification_instructions": "Recompute SHA-256...",
  "bundle_hash": "e5f6a7b8...",
  "timestamp_utc": "2026-02-26T12:00:04Z"
}

Batch Operations

POST /governance/batch

Execute up to 100 governance operations (verify, attest, bind) in a single call. Each sub-operation is metered individually at standard rates. Use for bulk processing or multi-step workflows.

Request:

{
  "agent_id": "your-agent-id",
  "operations": [
    {
      "type": "verify",
      "params": {
        "action_type": "api_call",
        "action_payload": {"endpoint": "/deploy", "replicas": 3}
      }
    },
    {
      "type": "attest",
      "params": {
        "action_description": "Deployment completed",
        "action_payload": {"status": "success"}
      }
    }
  ],
  "stop_on_deny": false
}

Response:

{
  "batch_id": "g7h8i9j0-...",
  "agent_id": "your-agent-id",
  "total": 2,
  "executed": 2,
  "results": [
    {"index": 0, "type": "verify", "status": "ok", "result": {"decision": "ALLOW", "...": "..."}},
    {"index": 1, "type": "attest", "status": "ok", "result": {"attestation_id": "...", "...": "..."}}
  ],
  "summary": {"allow": 1, "clamp": 0, "deny": 0, "attest": 1, "bind": 0, "error": 0},
  "batch_hash": "a1b2c3d4..."
}

If stop_on_deny is true, processing halts on the first DENY decision.

Capability Delegation

POST /governance/delegate

Grant scoped, time-limited capabilities to another agent. The delegation is HMAC-signed and recorded in the provenance chain. Supports hierarchical sub-delegation with restrictive scope intersection.

Request:

{
  "delegator_agent_id": "your-agent-id",
  "delegatee_agent_id": "helper-agent-42",
  "scope": {
    "allowed_endpoints": ["verify", "attest"],
    "policy_overrides": {"max_values": {"replicas": 3}},
    "max_calls": 100
  },
  "ttl_seconds": 3600,
  "description": "Handle deployment verification",
  "allow_subdelegation": false
}

Response:

{
  "delegation_id": "h8i9j0k1-...",
  "delegation_token": "f7a8b9c0...",
  "delegator_agent_id": "your-agent-id",
  "delegatee_agent_id": "helper-agent-42",
  "scope": {"allowed_endpoints": ["verify", "attest"], "max_calls": 100},
  "expires_utc": "2026-02-26T13:00:00Z",
  "provenance_hash": "b8c9d0e1...",
  "chain_depth": 1
}

The delegatee passes the delegation_token as X-Delegate-Token header when acting on behalf of the delegator.

GET /governance/delegations/{agent_id} — list active delegations for an agent.

DELETE /governance/delegations/{delegation_id} — revoke an active delegation.

Reversibility Check

POST /governance/check-reversibility

Check whether an intent chain can be reversed. Pre-abort safety check for multi-step workflows.

Request:

{
  "intent_id": "c3d4e5f6-...",
  "include_children": true
}

Returns reversibility status, constraints, time elapsed, and child dependency analysis.

Policy Replay

POST /governance/replay

Replay provenance records through an alternative policy. Deterministic "what-if" analysis: "What would have happened if we'd used policy X instead?"

Request:

{
  "agent_id": "your-agent-id",
  "template_id": "strict_safety",
  "limit": 50
}

Response:

{
  "total_replayed": 50,
  "replay_policy": {"max_values": {"speed": 3.0}},
  "changes": {"upgraded": 5, "downgraded": 12, "unchanged": 33},
  "results": [
    {
      "epoch": 42,
      "agent_id": "your-agent-id",
      "action_type": "motor_command",
      "original_decision": "ALLOW",
      "replayed_decision": "CLAMP",
      "change": "more_restrictive"
    }
  ]
}

Use for policy regression testing before deploying new policies, or forensic investigation.

Counterfactual Analysis

POST /governance/counterfactual

Simulate an action against multiple policies simultaneously. Returns a decision matrix showing how each policy handles the same action.

Request:

{
  "action_payload": {"endpoint": "/deploy", "replicas": 10},
  "action_type": "api_call",
  "policies": [
    {"label": "conservative", "template_id": "strict_safety"},
    {"label": "permissive", "policy_context": {"max_values": {"replicas": 20}}},
    {"label": "deny-all", "policy_context": {"forbidden_keys": ["replicas"]}}
  ],
  "include_historical": true,
  "agent_id": "your-agent-id"
}

Response includes consensus analysis (do all policies agree?), decision distribution, and optional historical comparison.

Intent Navigation

GET /governance/intents/{intent_id}/children

Return all direct child intents of a parent intent. Audit multi-agent delegation hierarchies.

GET /governance/intents/{intent_id}/ancestry

Walk up the intent hierarchy from leaf to root. Full authorization chain for auditing.

GET /governance/intents/{intent_id}/tree

Return the full delegation tree rooted at an intent. Accepts optional max_depth query parameter (default 10).

Policy Templates

GET /governance/policy-templates — free, no API key required

List available named policy templates. Use template IDs with verify, replay, and counterfactual endpoints instead of inline policy definitions.

Export

POST /governance/export/csv — export provenance records as CSV.

POST /governance/export/sarif — export provenance in SARIF format (Static Analysis Results Interchange Format) for security tooling integration.

POST /governance/export/merkle — export provenance as a Merkle tree with root hash and leaf hashes for independent integrity verification.

All export endpoints accept optional agent_id, time_range_start, time_range_end, and limit parameters.

Health and Audit

GET /governance/health-score — overall gateway health score including agent count, healthy agent count, and chain integrity rate.

GET /governance/audit-summary — aggregate statistics across all provenance: total records, total agents, decision distribution, and chain integrity status.

GET /governance/agent-compliance/{agent_id} — compliance profile for a specific agent: compliance score, chain integrity, total decisions, and outcome success rate.

Media Attestation

POST /media/attest — $0.05 per call

Attest media files (photos, videos, audio, documents) with SHA-256 hashing and provenance chain inclusion.

Request:

{
  "agent_id": "your-agent-id",
  "media_hash": "a1b2c3d4e5f6...64-char-hex-sha256",
  "media_type": "PHOTO",
  "media_size_bytes": 2048576,
  "capture_timestamp_utc": "2026-02-26T12:00:00Z",
  "description": "Generated report screenshot"
}

Required fields: agent_id, media_hash (64-char hex SHA-256), media_type (PHOTO | VIDEO | AUDIO | DOCUMENT), media_size_bytes, capture_timestamp_utc.

Optional fields: description, tags, capture_location (lat/lng), device_info, frame_hashes (for video).

Response:

{
  "attestation_id": "e5f6a7b8-...",
  "certificate_id": "mca_abc123",
  "media_hash": "a1b2c3d4e5f6...",
  "media_type": "PHOTO",
  "epoch": 45,
  "hash_prev": "...",
  "hash_curr": "b8c9d0e1...",
  "verification_url": "https://governance.taskhawktech.com/media/verify/mca_abc123",
  "chain_length": 45,
  "timestamp_utc": "2026-02-26T12:00:05Z"
}

Media Verify

POST /media/verify — free, no API key required

Verify that media content matches a specific attestation certificate.

Request:

{
  "media_hash": "a1b2c3d4e5f6...64-char-hex-sha256",
  "certificate_id": "mca_abc123"
}

Response:

{
  "verified": true,
  "certificate_id": "mca_abc123",
  "media_hash_match": true,
  "chain_integrity": true,
  "pqc_signature_valid": true,
  "reason": "Media hash matches certificate, chain intact"
}

Media Verify Lookup

GET /media/verify/{certificate_id} — free, no API key required

Look up a specific media attestation by its certificate ID. Returns the full attestation record including attesting agent, epoch, and chain integrity.

Passport

All Passport endpoints are free and require no authentication.

GET /passport/{agent_id}

Returns an agent's trust passport including score, tier, badges, and activity stats.

{
  "agent_id": "your-agent-id",
  "trust_score": 0.95,
  "tier": "gold",
  "badges": ["verified", "consistent", "high_volume"],
  "stats": {
    "total_decisions": 1250,
    "attestations": 890,
    "bindings": 340,
    "outcomes_achieved": 310,
    "chain_intact": true,
    "active_days": 45,
    "current_streak": 12
  }
}

GET /passport/{agent_id}/badge.svg

Returns an embeddable SVG trust badge. Use in agent descriptions, documentation, or dashboards.

GET /passport/{agent_id}/history

Returns full decision history for an agent.

GET /passport/leaderboard

Returns top trusted agents by trust score. Accepts optional limit query parameter (1-200, default 50).

Response:

{
  "agents": [
    { "agent_id": "top-agent", "trust_score": 0.98, "tier": "gold" }
  ],
  "total": 150
}

POST /passport/{agent_id}/claim — requires API key

Link an agent's passport to your operator account. Must provide X-API-Key header.

Response:

{
  "agent_id": "your-agent-id",
  "claimed": true,
  "profile": { "...passport profile..." }
}

Returns 409 if already claimed by another operator, 404 if no passport exists yet.

Agent Discovery

GET /.well-known/agent.json

Returns the A2A protocol agent card. No authentication required.

curl https://governance.taskhawktech.com/.well-known/agent.json

Returns capabilities, supported skills, SDK references, and free-tier signup details.

MCP

For MCP-native agents, connect directly via streamable-http transport:

https://governance.taskhawktech.com/mcp/

360 tools, 2 resources, 2 prompts. Auto-provisions a free-tier key on first tool call if no API key is provided.

Python SDK

pip install kevros
# or
uv pip install kevros

from kevros_governance import GovernanceClient

client = GovernanceClient(agent_id="your-agent-id")
result = client.verify(
    action_type="api_call",
    action_payload={"endpoint": "/deploy"},
    agent_id="your-agent-id",
)
print(result.decision)  # ALLOW, CLAMP, or DENY

Enforcement Modes

Every operator key has an enforcement mode that controls how decisions are applied:

enforce (default) — fail-closed. DENY means DENY. Release tokens are only issued for ALLOW/CLAMP.
advisory — shadow mode. DENY decisions are logged but overridden to ALLOW. No release token is issued for would-be denials. Use for testing policies before enforcing them.
gated — human-in-the-loop. DENY decisions are held for operator approval. Poll /governance/gated/{request_id} for status.
deny — kill-switch. ALL requests are blocked regardless of policy evaluation. Use for emergency shutdown.

The enforcement_mode field is returned in every verify response. Use /enforcement to check your current mode.

Enforcement mode changes require admin-level access and are not available through the plugin. Contact your administrator or use the admin API directly.

Decision Approach

When collaborating with another agent:

Check their passport first — GET /passport/{agent_id} returns trust score, tier, and history
Embed badges — Use GET /passport/{agent_id}/badge.svg in your agent's description to show your trust level
Trust thresholds:
- Gold tier (score >= 90%) — proceed with normal collaboration
- Silver tier (score 50-89%) — verify their actions before relying on results
- Bronze tier (score < 50%) — require bound intents with outcome verification
- No history — start with small, low-risk interactions and build trust incrementally
Verify before you rely — Use /governance/verify-token to independently confirm any release token a peer shares with you

Pricing

Subscriptions:

Free tier: 1,000 calls/month, instant signup, no payment required
Scout: $29/mo — 5,000 calls
Sentinel: $149/mo — 50,000 calls
Sovereign: $499/mo — 500,000 calls

Per-call (via x402 USDC, no subscription required):

Verify: $0.01
Attest: $0.02
Bind: $0.02
Media Attest: $0.05
Compliance Bundle: $0.25
Batch: each sub-operation metered individually
Verify Outcome: free with Bind
Delegation, Replay, Counterfactual, Export, Health, Audit: metered per call
Passport, Media Verify, Reputation, Verify Token, Policy Templates: free

Subscription calls are metered against your monthly allowance. x402 per-call pricing applies when paying per-call without a subscription.

Upgrade at https://www.taskhawktech.com/pricing

kevros

Safety Notice

Copy this and send it to your AI assistant to learn

Kevros

Quick Start

Precision Decisioning

Provenance Attestation

Intent Binding

Verify Outcome

Compliance Bundle

Batch Operations

Capability Delegation

Reversibility Check

Policy Replay

Counterfactual Analysis

Intent Navigation

Policy Templates

Export

Health and Audit

Media Attestation

Media Verify

Media Verify Lookup

Passport

Agent Discovery

MCP

Python SDK

Enforcement Modes

Decision Approach

Pricing

Source Transparency

Related Skills

ZipCracker

Agentshield Audit

Safe Encryption