AgentLair
Give your AI agent an email address, encrypted vault, and a behavioral trust score — one API, no OAuth required.
Try it in 30 seconds
No signup. See what a live trust score response looks like:
# Healthy agent — high trust (score 84, principal level)
curl https://agentlair.dev/v1/demo
{
"agentId": "acc_demo_healthy_XXXXXXXXXX",
"score": 84,
"confidence": 0.91,
"atfLevel": "principal",
"trend": "stable",
"dimensions": {
"consistency": { "score": 0.82 },
"restraint": { "score": 0.87 },
"transparency": { "score": 0.80 }
},
"observationCount": 1847
}
# Suspicious agent — score 31, declining trend
curl 'https://agentlair.dev/v1/demo?scenario=suspicious'
# New agent — only 11 observations, wide confidence interval
curl 'https://agentlair.dev/v1/demo?scenario=new'
Rate limited to 10 requests/minute per IP. Response shape matches the live /v1/trust/:agentId endpoint.
Full interactive demo — register a real agent, submit observations, get a live trust score (curl + jq, ~60 seconds):
curl -sL https://raw.githubusercontent.com/piiiico/agentlair/main/examples/quickstart.sh | bash
Register an agent
curl -X POST https://agentlair.dev/v1/auth/agent-register \
-H "Content-Type: application/json" \
-d '{"name": "my-research-agent"}'
{
"api_key": "al_live_...",
"account_id": "acc_...",
"email_address": "[email protected]",
"tier": "free",
"limits": { "emails_per_day": 10, "requests_per_day": 100 },
"warning": "Save your API key — it will not be shown again."
}
From here, the agent authenticates with api_key to send email, store credentials, and emit signed audit events.
Quickstart: Add AgentLair to your agent
1. Install
pip install agentlair # Python
npm install @agentlair/sdk # TypeScript / Node
2. Set env vars
export AGENTLAIR_API_KEY=al_live_...
export [email protected]
3. Wire lifecycle hooks
# Python — three integration points
import os, agentlair
lair = agentlair.AgentLair(os.environ["AGENTLAIR_API_KEY"])
addr = os.environ["AGENTLAIR_EMAIL"]
async def on_session_start(ctx):
result = await lair.email.inbox(addr)
if result["messages"]:
ctx.prepend(f"Inbox: {len(result['messages'])} unread")
async def send_message(to, subject, text): # expose as LLM tool
await lair.email.send(from_address=addr, to=to, subject=subject, text=text)
async def on_session_end(ctx): # advance cursor so messages aren't re-delivered
if ctx.last_message_id:
await lair.vault.store("inbox_cursor", ctx.last_message_id)
// TypeScript
import { AgentLair } from '@agentlair/sdk';
const lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);
const addr = process.env.AGENTLAIR_EMAIL!;
// Session start — drain inbox before planning
const { messages } = await lair.email.inbox(addr);
if (messages.length) context.prepend(`Inbox: ${messages.length} pending`);
// Expose as tool — let the LLM send replies
const sendMessage = (to: string, subject: string, text: string) =>
lair.email.send({ from: addr, to, subject, text });
Messages accumulate while offline and drain at next session start. For a complete plugin example (peek+ack, crash-safe delivery): hermes-agentlair.
MCP server
npx @agentlair/mcp@latest
Adds 9 tools to your MCP client: agent registration, email send/receive, vault store/get, audit event emission, and trust score queries.
Agent memory needs a trust layer
Agent memory is real infrastructure. 4-tier memory hierarchies, multi-agent leases, 51+ MCP tools for storing and retrieving across agent sessions. When multiple agents share a memory pool, the category works.
The gap: any agent can write anything to shared memory. No verification of who wrote what, no way to audit contested state, no trust gating on destructive writes. A shared memory pool without identity is a notepad anyone can scribble on.
Every write should be attributable. AgentLair's Agent Attestation Token (AAT) is a short-lived EdDSA JWT carrying the agent's did:web identity and behavioral trust score. Present it as the Authorization header in a memory write — the write is now cryptographically signed and auditable:
import { AgentLair } from '@agentlair/sdk';
const lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);
// Issue a short-lived AAT (5 min) scoped to the memory server
const { token } = await lair.tokens.issue({
audience: 'memory.internal',
ttl: 300,
scopes: ['memory:write'],
});
// Write to shared memory — this write is now attributed and trust-gated
await fetch('https://memory.internal/mcp/memory/write', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`, // signed agent identity
'Content-Type': 'application/json',
},
body: JSON.stringify({
key: 'research/competitor-analysis',
value: { /* ... */ },
}),
});
The memory server verifies the AAT via standard JWKS — no AgentLair SDK required on the receiving side. The al_trust claim lets it gate writes by behavioral trust level (e.g., reject writes from agents below junior).
Without AATs: shared memory = shared notepad. Any agent writes anything, contested state has no provenance.
With AATs: shared memory = trust graph. Every write is signed, attributed, and auditable.
SDK
npm install @agentlair/sdk
TypeScript client for the AgentLair API. See agentlair.dev/getting-started.
Free tier
- 10 emails/day
- 100 API requests/day
- 10 email addresses
Pro: $5/stack/month for higher limits.
Architecture
- API: Cloudflare Workers — edge-deployed, low latency
- State: Cloudflare KV
- Vault encryption: Client-side AES-GCM via
@agentlair/vault-crypto. The server stores ciphertext only — no plaintext credentials at rest. - Audit trail: Ed25519-signed event chains. Each event is independently verifiable without trusting the server.
We've been running our own agent infrastructure on AgentLair in production. Notes on what broke and what we learned building behavioral trust scoring: agentlair.dev/blog/from-0-to-41-building-behavioral-trust-in-production
Documentation
AAT × APS boundary (cross-protocol reference)
AgentLair AAT is session identity inside the issuer. AEOESS APS is delegation chains and bilateral receipts after handoff. Three claims bridge the two layers: jti (session anchor on the APS receipt), al_nid (one Ed25519 key signs AATs and APS receipts), and al_trust (issuer-attested behavioral snapshot at iat, available for downgrade-on-import on the APS verifier side).
Jointly maintained reference:
- agentlair.dev/docs/aps-boundary (this side)
- agent-passport.org/aat-aps-boundary.html (AEOESS side, canonical)
Repository structure
packages/
worker/ — Core API worker (Cloudflare Workers)
sdk/ — @agentlair/sdk client library
mcp-server/ — @agentlair/mcp MCP server
vault-crypto/ — @agentlair/vault-crypto end-to-end encryption
verify/ — @agentlair/verify AAT token verification
email-worker/ — Email processing worker
apps/
dashboard/ — Agent dashboard UI
email-channel/ — Email MCP channel
Development
bun install # install all dependencies
bun run typecheck # type-check all packages
License
MIT