Modei
PricingDocsBlog

Documentation

Theme
Log inSign up

Agent Autonomy Guide

How AI agents can discover, authenticate with, and operate through Modei with minimal human involvement after initial bootstrap. Covers self-issued passports, managed platform API keys, MCP integration, and agent-to-agent trust chains.

··

Architecture Overview

Your AI AgentCarries Passport · Signs Requests · Reads AuditPresents PassportGateVerifies Passport · Enforces Guardrails · Logs Every DecisionAttested DecisionProtected ResourceAPI · Tool · Data Source · Service

Ed25519 (an industry-standard elliptic curve signing algorithm)

Fast, secure, compact. The private key never leaves the agent.

Signed attestations

Every decision is signed by the gate, tamper-proof, cryptographically verifiable.

Issuer chains

Trust is established through issuer relationships, not central authorities.

The Bootstrap Problem

Every autonomous agent system has a bootstrap problem: someone has to set things up before the agent can operate autonomously. Here's the minimal human intervention required:

What a human does once

  1. Create a Modei account
  2. Create an Issuer (signing identity)
  3. Generate an API key with appropriate scopes
  4. Provide the API key to the agent (env var, secrets manager)

What the agent does forever after

  • Issue new passports for itself or sub-agents
  • Rotate credentials before expiry
  • Create and configure gates
  • Verify other agents' passports
  • Read its own audit trail
  • Self-manage permissions within bounds

Discovery via llms.txt

Modei follows the llms.txt convention for machine-readable discovery. An agent can autonomously discover how to integrate:

python
import httpx

async def discover_modei():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://modei.ai/llms.txt")
        # Returns structured document with endpoints, auth methods,
        # SDK install instructions, MCP server details
        return response.text

Path A: Self-Issued L1 Passports

No account required. No API key. Pure local trust. L1 passports can be issued entirely locally using the Modei SDK. Ideal for local agent development, air-gapped environments, and prototyping.

python
# pip install modei-python --pre
from datetime import timedelta
from modei import AgentCredentials, PassportIssuer

# Generate a local agent keypair, private key never leaves this machine.
credentials = AgentCredentials.generate()

# Self-issue a passport.
issuer = PassportIssuer(
    credentials,
    identity_claim="email-assistant@dev.local",
)

signed = issuer.self_issue(
    permissions=[
        {"permission_key": "email:read",    "constraints": {}},
        {"permission_key": "email:send",    "constraints": {}},
        {"permission_key": "calendar:read", "constraints": {}},
    ],
    expires_in=timedelta(days=30),
)

print("passport_id:", signed.envelope.passport_id)

# Save credentials for reuse, private key is never stored on Modei servers.
credentials.save("~/.config/my-agent/credentials.json")

This example uses the Modei SDK (pip install modei-python --pre) for local cryptographic operations. For managed operations, use the Modei REST API.

Critical: Save your Private Key RIGHT NOW

The private key is returned exactly once and is never stored on Modei servers. Copy it immediately and save it to a secrets manager (1Password, Bitwarden, AWS Secrets Manager). It cannot be recovered.

typescript
// npm install modei-typescript@next
import { AgentCredentials, PassportIssuer } from 'modei-typescript';

// Generate a local agent keypair.
const credentials = AgentCredentials.generate();

const passport = new PassportIssuer(credentials, {
  identityClaim: 'email-assistant@dev.local',
}).selfIssue({
  permissions: [
    { permission_key: 'email:read',    constraints: {} },
    { permission_key: 'email:send',    constraints: {} },
    { permission_key: 'calendar:read', constraints: {} },
  ],
  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
});

console.log('passport_id:', passport.envelope.passport_id);

// Save credentials for reuse — private key never leaves this machine.
credentials.save(`${process.env.HOME}/.config/my-agent/credentials.json`);

This example uses the Modei SDK (npm install modei-typescript@next) for local cryptographic operations. For managed operations, use the Modei REST API.

Rotating Before Expiry

Passports carry an absolute expires_at on the envelope's provenance. To keep an agent running continuously, call issuer.self_issue(...) again with a new expires_in before the old passport expires. The keypair itself does not change, only the passport's expiry does.

Path B: Managed Platform via API Key

For production agents. The API key (format: mod_live_xxxxxxxx) authenticates against the Modei platform. Issue passports against an existing gate with the shipped modei-python client.

bash
export MODEI_API_KEY="mod_live_xxxxxxxx"
# Optional, override for local development
export MODEI_API_URL="https://modei.ai"
python
# pip install modei-python --pre
import asyncio
import os
from modei import AsyncModeiClient

async def main():
    async with AsyncModeiClient(api_key=os.environ["MODEI_API_KEY"]) as client:
        passport = await client.issue_passport(
            "gate_research",                          # gate_id (first positional)
            agent_id="research-agent",
            agent_name="Research Agent",
            permissions=["web:read", "documents:read"],
            expires_in="24h",                         # ISO duration string
        )
        print("passport_id:", passport["passport_id"])

asyncio.run(main())

See the Python SDK reference for the full ModeiClient / AsyncModeiClient surface (gates, constraints, attestations, settlement).

Path C: MCP Server Integration

Modei ships a Model Context Protocol (MCP) server with 48 tools. Recommended for agents that support MCP natively, including Claude Desktop.

claude_desktop_config.json
{
  "mcpServers": {
    "modei": {
      "command": "npx",
      "args": ["modei-mcp"],
      "env": {
        "MODEI_API_KEY": "mod_live_xxxxxxxx"
      }
    }
  }
}

See the full MCP Integration Reference (48 tools) for all available tools.

Agent-to-Agent Trust Chains

Orchestrator agents can spawn sub-agents with scoped, delegated permissions. Sub-agents cannot have more permissions than their parent.

Orchestrator Agent (L2 Passport, permissions: *)
     │
     ├── Research Agent  (L1, permissions: web:search, web:fetch)
     ├── Writer Agent    (L1, permissions: documents:write)
     └── Reviewer Agent  (L1, permissions: documents:read)
python
# pip install modei-python --pre
import asyncio
import os
from modei import AsyncModeiClient

async def spawn_sub_agent(client, gate_id, permissions, task_name):
    """Spawn a sub-agent with a subset of parent permissions."""
    return await client.issue_passport(
        gate_id,
        agent_id=f"{task_name}-sub",
        agent_name=f"{task_name} Agent",
        permissions=permissions,           # Subset of parent's permissions.
        expires_in="1d",                   # Task-scoped.
    )

async def main():
    async with AsyncModeiClient(api_key=os.environ["MODEI_API_KEY"]) as client:
        gate_id = "gate_research"

        # Spawn a team.
        researcher = await spawn_sub_agent(
            client, gate_id, ["web:search", "web:fetch"], "researcher"
        )
        writer = await spawn_sub_agent(
            client, gate_id, ["documents:write"], "writer"
        )

        # ... run tasks ...

        # Revoke when done.
        await client.revoke_passport(gate_id, researcher["passport_id"])
        await client.revoke_passport(gate_id, writer["passport_id"])

asyncio.run(main())

Verifying another agent's passport

python
# pip install modei-python --pre
from modei import PassportVerifier

def verify_incoming_agent(envelope, signature_b64, required_permissions):
    verifier = PassportVerifier()
    result = verifier.verify(envelope, signature_b64)

    if not result.valid:
        raise ValueError(f"Invalid passport: {result.reason_code} {result.detail or ''}")

    granted = {p["permission_key"] for p in envelope["permissions"]}
    for perm in required_permissions:
        if perm not in granted:
            raise PermissionError(f"Agent lacks: {perm}")

    return result.tier.value  # "L0" for self-issued, "L1"/"L2"/etc. otherwise

This example uses the Modei SDK (pip install modei-python --pre) for local cryptographic operations. For managed operations, use the Modei REST API.

Related

For AgentsWeb Dashboard