AgentKey SDK

AgentKey is an authorization and evidence layer for AI agents. Before an agent takes an action, the SDK asks the AgentKey API whether it is allowed, denied, or requires human approval. Both the decision and what the agent actually did are recorded as hash-chained evidence events you can inspect in a dashboard.

Installation

Python (3.8+, zero dependencies):

pip install agentkey

JavaScript / TypeScript (Node 18+, zero dependencies, ESM):

npm install agentkey

Get an API key

1. Sign up at the AgentKey dashboard: https://agentkey.base44.app
2. Open the Connect wizard (or Agents, then create an agent).
3. Generate an API key. It is shown once; store it as an environment variable and do not hard-code it.

First authorization (Python)

from agentkey import AgentKeyClient

ak = AgentKeyClient(api_key="agent_live_xxxxx")  # production API by default

result = ak.check_permission(action="send_email", resource="gmail", arguments={"to": "x@company.com"})
if result["allowed"]:
    send_email(...)  # your code
else:
    print("Blocked:", result["reason"], "approval_required:", result.get("approval_required", False))

First authorization (JavaScript / TypeScript)

import { AgentKeyClient } from "agentkey";

const ak = new AgentKeyClient({ apiKey: "agent_live_xxxxx" }); // production API by default

const result = await ak.checkPermission({
  action: "send_email",
  resource: "gmail",
  arguments: { to: "x@company.com" },
});
if (result.allowed) {
  await sendEmail(); // your code
} else {
  console.log("Blocked:", result.reason, "approval_required:", result.approval_required ?? false);
}

Decisions: allow, deny, ask

check_permission / checkPermission evaluates the permissions you configured for the agent:

• allow: allowed: true. Run the action, then record the execution (below).
• deny: allowed: false with the server's reason. Do not run the action.
• ask (human approval): allowed: false, approval_required: true. The request appears on the Approvals page in the dashboard, where a human approves or denies it. Do not run the action until it is approved.

Fail-closed: if the service cannot return a valid decision within 5 seconds, the SDK returns:

{ "allowed": false, "reason": "agentkey_unreachable", "fail_closed": true }

Treat fail_closed: true as an infrastructure failure and allowed: false without it as an authorization decision. Either way the agent must not proceed.

wrap(): authorize every tool call in one line

agent = ak.wrap(my_agent)                   # observe (default): records, blocks nothing
agent = ak.wrap(my_agent, mode="enforce")   # raises AgentKeyDenied on a denial

const agent = ak.wrap(myAgent);                    // observe (default)
const agent = ak.wrap(myAgent, { mode: "enforce" }); // raises AgentKeyDenied on a denial

wrap() detects an MCP client (callTool / call_tool), a LangChain agent or tool list, a plain object or dict of functions, or a single function. Observe mode records every call and blocks nothing, so you can see what AgentKey would have caught before trusting it with enforcement. Enforce mode raises AgentKeyDenied and does not run the tool. If no session id is passed, a session is started automatically and ended best-effort at process exit.

Sessions

Every decision and execution is recorded as an evidence event on the session's hash chain. Group a task into one session:

s = ak.start_session()
# ... checks and actions ...
ak.end_session(s["session_id"])

const s = await ak.startSession();
// ... checks and actions ...
await ak.endSession({ sessionId: s.session_id });

Recording what the agent actually did

After an allowed action runs, record the execution, linked back to its decision by authorization_id:

auth = ak.check_permission(action="send_email", resource="gmail", session_id=sid)
if auth["allowed"]:
    send_email(...)
    ak.record_action(session_id=sid, authorization_id=auth["event_id"], tool="gmail",
                     action="send_email", resource="gmail", result_status="success")

record_action never refuses to record, so evidence is not lost for billing reasons. Actions that run without any authorization decision are surfaced on the dashboard as findings (executions_without_authorization), because the SDK is self-reported: an agent that bypasses the wrapped functions produces no evidence.

guard(): authorize, run, record in one call

out = ak.guard(sid, "gmail", "send_email", lambda: send_email(...), arguments={"to": "x@company.com"})

const out = await ak.guard({ sessionId: sid, resource: "gmail", action: "send_email" }, async () => sendEmail());

If authorize denies, guard returns the denial and does not run the function.

Delegated authorization

A parent agent can delegate a scoped subset of its permissions to a child agent. Scopes are resource:action strings, must be a subset of the parent's own permissions, and chains are depth-limited. See delegate() in the source docstrings.

Production API

Base URL: https://agentkey.base44.app (the SDK default). Override it with base_url (Python) or baseUrl (JavaScript) if you self-host.

All endpoints are POST with a Bearer API key, under /api/functions/:

• authorize
• record_action
• start_session
• end_session
• delegate
• validate_api_key (GET)

Raw HTTP:

curl -X POST https://agentkey.base44.app/api/functions/authorize \
  -H "Authorization: Bearer agent_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"action":"send_email","resource":"gmail","arguments":{"to":"x@company.com"}}'

Dashboard

Sessions, evidence events, approvals, findings and permission settings: https://agentkey.base44.app

Security limitations (current, accurate)

• Evidence events are hash-chained per session, and session Merkle roots are attested with HMAC-SHA256 under a server-side key. This detects altered or missing events in stored evidence. It is not an asymmetric digital signature scheme, it does not make records forgery-proof against a compromised server, and it is not a non-repudiation guarantee.
• SDK instrumentation is self-reported. wrap() and record_action record what the agent reports; an agent that calls tools outside the SDK produces no evidence. This is reported as an executions_without_authorization finding, but not prevented.
• Checks fail closed on network errors and timeouts. In observe mode the SDK still lets the call run; only enforce mode blocks it.
• No SOC 2 or other third-party compliance audit has been completed.

License: MIT.