🦔 SmartDelegate

Delegate, don't hand over the keys. An agent never holds more than the human's role for the task.

IAIso §10 · Delegation · SmartTasks.cloud · the Smart* family

Your agent is running on your API key. What exactly can it do right now?

Usually: everything you can, on every record, until someone rotates the key. SmartDelegate is identity and access management for LLM agents. A human lends an agent one role they hold, for one task. The agent gets a short-lived token that can never carry more than that role allows, a sub-agent can only get less, every tool call is checked, fields the human's role may not see are removed before they reach the model, and every decision lands in a hash-chained audit log.

pip install sf-smartdelegate    # from a clone: pip install .
sf-smartdelegate --demo         # nine steps against the bundled example, no setup

Lines from its output (shortened):

1. Alice (support) lends support-bot her support-agent role for ticket-7
2. The bot reads customer c-1: DELEGATE-POLICY-PERMIT
   removed before it reached the model: ['card.number', 'notes', 'ssn']
4. A second 60.00 EUR refund on the same task: DELEGATE-BUDGET-EXCEEDED (...)
5. Alice asks for more than her role allows (a 500 EUR budget)
   refused: DELEGATE-ROLE-EXCEEDED (...)
6. The bot hands a read-only slice to a sub-agent
   and cannot widen it again: DELEGATE-WIDENING
8. The identity provider says Alice left the support group five minutes ago
   refused: DELEGATE-ROLE-NOT-HELD (live membership replaces the stored one)

Status: 0.3.0. No independent security review. Built and tested on Linux only. Read docs/LIMITATIONS.md before relying on it.

Run it in your stack

Thirty seconds of code

from sf_smartdelegate import core

iam = core.open_engine("bundle", "state")

# the human lends the agent a role they hold, for one task
grant = core.delegate(iam, user="alice", agent="support-bot", role="support-agent", task="ticket-7")

# every tool call is checked; the data comes back already masked
d = core.check(iam, grant.token, "read", "crm.customer", "c-1", data=record)
if d.allowed:
    give_to_model(d.data)          # no ssn, no internal notes
else:
    print(d.rule, d.detail)        # e.g. DELEGATE-CAPABILITY-ACTION

# a sub-agent gets less, never more
child = core.narrow(iam, grant, actor="summarizer", capability={"actions": ["read"], "resources": ["crm.customer/c-1"]})

More in examples/usage.md.

Install

python -m pip install sf-smartdelegate
sf-smartdelegate --demo

sf-smartdelegate on PyPI is published only by this repository's release workflow (.github/workflows/release.yml, PyPI trusted publishing, with provenance attestations). Version 0.3.0 is the first release under this name. If pip cannot find it yet, that release has not finished: install from a clone instead (Python 3.10 or later):

git clone https://github.com/SmartTasksOrg/sf-smartdelegate
cd sf-smartdelegate
python -m venv .venv
. .venv/bin/activate          # Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install .

A package called smartdelegate (without sf-) on any registry is not ours. The ports in ports/ are not published on any registry; build them from this repository (ports/README.md).

Status

• Version 0.3.0, experimental. An authorization engine for LLM agents (Python reference with REST daemon, HTTP and MCP proxies) and native ports in five other languages, held to shared conformance vectors.
• Published: PyPI sf-smartdelegate (see Install). Nothing else is published.
• Tested: the tests in tests/, the scenario harness (python -m harness run) and the skills check on Python 3.10 and 3.12, Linux, on every push to master and every pull request (.github/workflows/ci.yml). The ports, the live suites (live/) and the cross-port matrix are run by hand (./bootstrap.sh --full, docs/BUILD.md).
• Not tested: Windows and macOS on GitHub runners; the ports and live suites in CI; Docker images; identity providers and clouds other than Keycloak (the bridges are tested against fakes).
• Ports: Rust, Go, Java, Node and PHP engines and a JavaScript REST client in ports/; none is published on a registry.
• Security review: none independent. Report vulnerabilities as described in SECURITY.md.

What's in this repo

• Specification: spec/: the operations (API.md), roles (ROLES.md), byte formats and porting guide (PORTING.md), the portable Cedar subset, and the conformance vectors every implementation must pass.
• Reference engine: src/sf_smartdelegate/: Python, one dependency (cryptography).
• Language ports: ports/: Java, Node, Go, PHP and Rust engines; a JS REST client. See the table of ports.
• IAM bridges: directory sync, claim mapping, role ceilings from cloud permissions, and down-scoped cloud credentials. docs/BRIDGES.md.
• Integrations: integrations/.
• Adopter interfaces: interfaces/: the eight contracts a company implements to plug SmartDelegate into its IAM and agent systems, reference implementations, and a contract test kit (python -m interfaces.contract). Start at docs/INTEGRATE.md.
• For agents: AGENTS.md, skills/, agents/ and llms.txt. How this control fits a governance framework, IAIso or your own: docs/FRAMEWORK.md.
• Example company and scenario harness: examples/company/ is a bundle for a company of seven business units, 35 people and 18 roles. harness/ plays six business scenarios of that company against an engine, in process or against any port's daemon, and checks each step: expected outcome, no denied field in data, spend within budget, revoked tokens refused, an audit record per decision. python -m harness run. It is a small harness; the larger one behind the simulation results below is not in this repository.
• Also included: a runnable demo/, examples/, the IAIso mapping spec/iaiso-map.json, a browser site/playground.html, the scope, coverage, threat model and limitations.

How it works

Three bounds apply at once, and the narrowest wins:

The token records the whole chain (human → agent → sub-agent), the role and the task. Each hop can only narrow. Then every request goes through the same checks, first failure wins:

At issuance: DELEGATE-ROLE-NOT-HELD, DELEGATE-ROLE-EXCEEDED, DELEGATE-UNKNOWN-ROLE, DELEGATE-ROLE-REQUIRED, DELEGATE-DELEGATION-DENIED, DELEGATE-WIDENING, DELEGATE-DEPTH-EXCEEDED. Rule IDs are namespaced DELEGATE-* so output reads kin to the rest of the family (SmartPangolin's SEC-*, SmartRoute's ROUTE-*).

In-process checks bind an agent that cooperates. The boundary an agent cannot skip is a proxy that holds the real credential: sf-smartdelegate http-proxy and sf-smartdelegate mcp-proxy. docs/LIMITATIONS.md says exactly when that holds.

The data objects (UML)

These are real dataclasses in src/sf_smartdelegate/models.py:

classDiagram
    class Role {
      +name: str
      +members: list
      +ceiling: Capability
      +max_ttl: int
      +tasks: list[str]
      +agents: list[str]
      +bindings: dict
    }
    class Capability {
      +actions: list[str]
      +resources: list[str]
      +deny_labels: list[str]
      +deny_fields: list[str]
      +budget: dict
    }
    class Grant {
      +token: str
      +token_id: str
      +user: str
      +chain: list[str]
      +role: str
      +task: str
      +capability: Capability
      +expires_at: int
    }
    class Principal {
      +user: str
      +agent: str
      +chain: list[str]
      +role: str
      +task: str
      +tenant: str
      +token_id: str
    }
    class Decision {
      +allowed: bool
      +reason: str
      +rule: str
      +policies: list[str]
      +principal: Principal
      +obligations: Obligations
      +data: object
      +masked: list[str]
    }
    class Obligations {
      +fields_allow: list[str]
      +fields_deny: list[str]
      +fields_redact: list[str]
      +row_filter: list
      +rate_limit: dict
    }
    class AuditRecord {
      +seq: int
      +ts: int
      +event: str
      +prev: str
      +hash: str
    }
    Role "1" *-- "1" Capability : ceiling
    Grant "1" *-- "1" Capability : never wider than the role
    Decision "1" *-- "1" Principal
    Decision "1" *-- "1" Obligations
    Decision ..> AuditRecord : appended as

Bridges to the IAM you already run

SmartDelegate does not replace your identity provider or cloud IAM. It extends them to agents, in both directions:

graph LR
    IdP[Identity provider<br/>Entra · Okta · Keycloak · Google · AWS Identity Center]:::ext
    Human((Human))
    Roles[roles.json<br/>ceiling per role]:::sd
    Token[Task token<br/>role + task + chain]:::sd
    Agent[Agent / sub-agents]
    PEP[SmartDelegate proxy<br/>policy · fields · budget · audit]:::sd
    Cloud[AWS · GCP · Azure APIs]:::ext
    Human -->|signs in| IdP
    IdP -->|groups in the ID token, or directory sync| Token
    IdP -.->|what the human may do in the cloud| Roles
    Roles -->|caps| Token
    Token --> Agent
    Agent --> PEP
    Agent -->|down-scoped credential, never wider than the token| Cloud
    IdP -->|offboarding: revoke user| Token
    classDef sd fill:#1c232d,stroke:#f5b83d,color:#efe9f5;
    classDef ext fill:#04121f,stroke:#46d6c8,color:#46d6c8;

sf-smartdelegate bridge sync-okta ... --revoke rewrites entities.json from the directory and ends the live tokens of everyone who was removed or lost a group.

Keycloak is verified against a real server (26.0.7 and 26.8.0: sign-in, group claims, directory sync, key rotation, and the whole loop from "removed from a group in Keycloak" to "the agent's tokens are dead": live/idp). Every other bridge was written from the provider's public documentation and tested against fakes only: none has been run against a real AWS, Azure, Google or Okta account. docs/BRIDGES.md lists what is unverified.

How it is tested

One command from a fresh clone builds and checks everything that has a toolchain installed: ./bootstrap.sh (Linux, macOS) or .\bootstrap.ps1 (Windows); add --full / -Full for every suite. docs/BUILD.md has the details, the Docker files and the CI layout. A missing toolchain is reported as SKIP, never as PASS.

Not run anywhere yet: Windows and macOS themselves (the PowerShell scripts were executed with PowerShell 7 on Linux only), any Docker image, the GitHub workflows, and any identity provider or cloud other than Keycloak.

Where it sits in the architecture

graph LR
    IAIso([IAIso standard]):::std
    Cloud([SmartTasks.cloud]):::cloud
    SmartDelegate[SmartDelegate]:::tool
    SmartRoute[SmartRoute]:::tool
    SmartSeal[SmartSeal]:::tool
    SmartPangolin[SmartPangolin]:::tool
    SmartStandard[SmartStandard]:::tool
    SmartRoute -->|asks who the agent acts for| SmartDelegate
    SmartDelegate -->|audit records can be sealed by| SmartSeal
    SmartPangolin -->|keeps keys and state out of shares of| SmartDelegate
    SmartStandard -->|supplies conventions to| SmartDelegate
    SmartDelegate -.conforms.-> IAIso
    SmartDelegate -.shares IAIso with.-> Cloud
    IAIso -.governs.-> Cloud
    classDef tool fill:#1c232d,stroke:#f5b83d,color:#efe9f5;
    classDef std fill:#04121f,stroke:#46d6c8,color:#46d6c8;
    classDef cloud fill:#1a1327,stroke:#a78bfa,color:#a78bfa;
    style SmartDelegate stroke-width:3px,stroke:#ff6b6b;

• SmartRoute scores whether a call looks trustworthy; SmartDelegate decides what authority the agent holds. Use both.
• The arrows to SmartSeal, SmartPangolin and SmartStandard describe how the tools fit together; no code in this repository calls them.

Open site/playground.html to try the delegation rules in a browser, and site/flows/ to watch three scenarios replayed step by step from real engine runs, offline.

Part of the Smart* family

Same mascot, same manifesto voice, same rule-ID style, all aligned to the IAIso standard. Each is an independent, open-source, single-purpose tool:

Aligned to the standard: SmartDelegate is built to the IAIso principles as the family's delegation control. "§10 · Delegation" is our working label, not a section the standard has assigned; docs/FRAMEWORK.md says what is implemented and what is only proposed. Open-source edition: this repo is the single-purpose version, built for any org to integrate into its own architecture. SmartTasks' desktop app and SmartTasks.cloud run a more advanced, deeply-integrated implementation of the same IAIso governance — a separate product, not this code bundled.

Who's behind this

• Roen Branham — CEO & AI Strategy Architect · CISSP-certified AI, security & governance architect; author of IAIso and sole inventor of the Z4 Semantic Fabric patent application. LinkedIn
• Le Vu Tanh — CTO & Core Engineering Lead · Chief architect of the Cortex engine; large-scale system reliability and low-latency infrastructure — the engineer who ships what gets architected. LinkedIn

Runs on governed local models

An agent on a local model needs the same bounds as one on a hosted model: SmartDelegate works the same with either, and makes no call to any model.

SmartTasks publishes governance-validated GGUF builds on Hugging Face, each with a machine-readable scorecard (capability tiers, IAIso conformance invariants, OWASP-mapped red-team results, per-file SHA-256).

→ SmartTasks on Hugging Face

Get in touch

• Companies & enterprises: enterprise@smarttasks.cloud — we help teams integrate SmartDelegate + IAIso into their architecture.
• The standard: IAIso · iaiso.org
• The product: SmartTasks.cloud

Built by SmartTasks Lab. Apache-2.0 (LICENSE). Contributions welcome: to add a language, start at spec/PORTING.md.