heimdall systems.

Learn · Multi-tenant agents

Ten-Grd: guard your agent's data

Agents read prompts, and prompts can say anything. Five lessons cover why tenant identity must stay out of the model's reach, how to guard memory and retrieval, and where the guarantee stops.

Free, no sign-up. Needs Python 3.10+. No API key or model needed. Written for ten-grd 0.3.2.

About this guide

In a multi-tenant AI product, one vector store, memory service and cache can hold every customer's data, with only application logic keeping them apart. If a tool takes a tenant ID as an argument, that boundary is only as strong as the model's judgement. If every query needs a tenant filter, it is only as strong as your memory.

Ten-Grd keeps the authenticated tenant attached to each protected operation. The guarded client adds the restriction, checks the selector with Z3 before running it, and validates complete result batches before returning them. When isolation can't be established, the operation is denied. This guide is for developers building tools, memory, retrieval or caching for agents.

You'll be able to

  • Explain why tenant identity shouldn't be a tool argument
  • Guard an agent memory tool in a few lines
  • Predict how a selector will be judged, and why anything but proven is denied
  • Connect Qdrant or another supported backend, and find the Claude Agent SDK examples
  • State what the SDK trusts and what it leaves to you

1. Where the boundary lives

The protected property is simple: a tenant-facing operation may only access resources owned by its authenticated active tenant. Missing identity, unknown ownership, unsupported semantics and inconclusive verification all deny.

The design follows from assuming an attacker controls prompt text, request fields, tool arguments, record IDs and selector expressions supplied to a tool. So the tenant can't come from any of those. Your host authenticates the user and checks membership first, then enters a scope. Guarded methods have no tenant parameter at all.

2. Guard a memory tool

python -m pip install ten-grd

The distribution is ten-grd, and the import is ten_grd.

from ten_grd import InMemoryAdapter, TenantContext, TenantGuard, tenant_scope

memory = TenantGuard(InMemoryAdapter())

# Your host authenticates the subject and validates tenant membership first.
with tenant_scope(TenantContext("acme", "alice", "request-1")):
    memory.put("plan", {"text": "Acme's private plan"}, metadata={"kind": "plan"})
    print(memory.get("plan").data["text"])

with tenant_scope(TenantContext("other", "bob", "request-2")):
    print(memory.get("plan"))
Acme's private plan
None

Both tenants asked for the same record ID. The second gets nothing. Constructing TenantContext only validates identifier format. It doesn't authenticate anyone, so never build one from a prompt, tool argument or unchecked request field.

3. Selectors and formal checks

from ten_grd import Eq, Or, TenantContext, Z3InvariantEngine

engine = Z3InvariantEngine(timeout_ms=1000)
context = TenantContext("acme", "alice", "request-3")

print(engine.verify_selector(context, Eq("tenant_id", "acme")).status)
print(engine.verify_selector(
    context, Or((Eq("tenant_id", "acme"), Eq("tenant_id", "other")))
).status)
VerificationStatus.PROVEN
VerificationStatus.VIOLATION

The selector language supports Eq, And, Or and Not over string metadata. Only PROVEN permits execution. A violation, a timed-out or inconclusive solver, an unsupported expression or an error all deny, and there is no soft-fail option.

4. Real backends and agents

Backends install as extras. See the integrations guide for PostgreSQL, SQLite, Qdrant, Redis and LangChain.

python -m pip install "ten-grd[qdrant]"
from qdrant_client import QdrantClient
from ten_grd import Eq, TenantContext, tenant_scope
from ten_grd.integrations.qdrant import QdrantRetriever

client = QdrantClient(location=":memory:")
docs = QdrantRetriever(client, "policies", 3, create=True)

with tenant_scope(TenantContext("acme", "alice", "request-4")):
    docs.put("refund-policy", {"text": "Refunds within 30 days."},
             [0.99, 0.01, 0.0], metadata={"topic": "refunds"})
    hits = docs.search([1.0, 0.0, 0.0], predicate=Eq("topic", "refunds"), limit=3)
    print([hit.record.data["text"] for hit in hits])
['Refunds within 30 days.']

You write only your own filter. The tenant filter you can't forget shows the same search with and without the restriction. For agents, Claude agents and tenant isolation walks through runnable examples that work offline first.

5. Where the guarantee stops

PROVEN applies to the supported selector logic under the trusted adapter contract. It isn't a proof of agent behaviour, infrastructure, backend internals or authentication. In practice:

  • You must authenticate tenant membership before entering a scope, and enforce permissions within a tenant. Tenant equality isn't complete authorization.
  • Raw access bypasses it. An in-process SDK can't stop code that uses raw credentials, so protect every data path.
  • Custom adapters are security-critical code. A buggy write adapter can do damage before result validation notices.
  • Workers need care. Propagate and revalidate context for jobs, and avoid long-lived tasks carrying stale context.
  • It doesn't prevent prompt injection, and a supported adapter isn't a certification of that backend.

Read the threat model before deploying. To find the paths you didn't guard, continue with the leak probe guide.