sentinel-agent-trust

Python client SDK for Sentinel AI — the identity & governance layer for AI agents: control, authorize, and audit autonomous agents before they touch your production APIs.

Sentinel is in private beta. For source access, a hosted sandbox organization key, or to collaborate: cosimo@plannest.net

Install

pip install sentinel-agent-trust

Usage

import os
from agent_trust_sdk import AgentTrustClient, AgentPermissionDeniedException

client = AgentTrustClient(
    agent_id="agt_...",
    private_key=os.environ["SENTINEL_AGENT_PRIVATE_KEY"],  # base64 Ed25519 seed
    gateway_url="https://your-gateway.example.com",
)

try:
    client.enforce_action("crm.refund.create", "crm://refunds", {"amount": 90})
    crm.create_refund(amount=90)          # authorized → do the real thing
except AgentPermissionDeniedException as exc:
    # final denial: do NOT retry — branch (degrade, escalate to a human, give up)
    escalate_to_human(exc.reason, exc.request_id)

Every request is signed with the agent's private Ed25519 key (never sent to the server) and carries a timestamp + nonce, so requests cannot be replayed. Denials carry a machine-readable code (permission_denied, behavioral_limit_exceeded, rate_limited, …) so your agent can branch instead of looping.

Proxy mode

With proxy mode the request travels through the gateway, which authorizes it, injects the upstream credential (the agent never holds it) and forwards it — enforcement the agent cannot skip:

resp = client.proxy_request("stripe", "POST", "v1/refunds",
                            payload={"charge": "ch_123", "amount": 90})
print(resp.status_code, resp.json())   # the upstream's response

Method, path, query and body are all covered by the Ed25519 signature. Denials raise the same exceptions as enforce_action; a pending human approval raises AgentApprovalPendingException — retry the identical call after approval.

Generate a keypair

python -m agent_trust_sdk.keygen

Register the public key with your Sentinel gateway (POST /v1/agents); keep the private seed in a secret store.

License

Apache 2.0 — see LICENSE and NOTICE.