Skip to content
BranchesTags

Repository files navigation

🪪 Agent Passport

Agent Passport Logo

Define Once. Travel Anywhere. Prove It.

A framework-independent infrastructure platform for building portable, interoperable, and verifiable AI agents.

Python FastAPI TypeScript Next.js PostgreSQL Docker License: MIT

Live Demo • Documentation • Architecture • Contributing

🎯 The Problem

AI agents are increasingly coupled to the frameworks in which they are created. An agent implemented in one runtime may use different tool definitions, memory models, execution semantics, and permission models. Simply recreating an agent in another framework doesn't prove it's still the same agent.

✨ The Solution

Agent Passport separates the agent definition from its runtime, providing a portable specification and infrastructure to:

  • 📦 Package agents into a portable, framework-independent specification
  • 🔄 Compile to different agent runtimes
  • 🏃 Execute in isolated sandbox environments
  • 📊 Normalize execution traces across runtimes
  • ✅ Verify contracts, tools, permissions, and behavior
  • 🚀 Migrate agents between runtimes seamlessly
  • 🔍 Detect behavioral or contractual drift
  • 📋 Generate tamper-evident verification evidence

🏗️ Architecture Overview

graph TB
    A["🎫 Agent Passport<br/>Identity | Capabilities | Tools<br/>Contracts | Behavior | Permissions"]

    B["📦 Portable Intermediate<br/>Representation<br/>PIR"]

    C1["Lyzr<br/>Adapter"]
    C2["OpenAI<br/>Adapter"]
    C3["CrewAI<br/>Adapter"]

    D1["Runtime A"]
    D2["Runtime B"]
    D3["Runtime C"]

    E["🔒 Sandbox<br/>Runner"]
    F["📝 Canonical<br/>Trace"]
    G["✅ Verification<br/>Engine"]
    H["🔍 Compatibility<br/>& Drift Analysis"]
    I["📊 Evidence<br/>+ Signing"]
    J["📚 Agent<br/>Registry"]

    A --> B
    B --> C1
    B --> C2
    B --> C3

    C1 --> D1
    C2 --> D2
    C3 --> D3

    D1 --> E
    D2 --> E
    D3 --> E

    E --> F
    F --> G
    G --> H
    H --> I
    I --> J

    style A fill:#6366f1,stroke:#4f46e5,color:#fff
    style B fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style E fill:#ec4899,stroke:#db2777,color:#fff
    style F fill:#f59e0b,stroke:#d97706,color:#fff
    style G fill:#10b981,stroke:#059669,color:#fff
    style J fill:#3b82f6,stroke:#2563eb,color:#fff
Loading

🔑 Key Concepts

1. Portable Agent Definition

Define your agent once in a framework-agnostic Passport specification:

spec_version: "1.0"

passport:
  id: "urn:agentpassport:research-agent"
  version: "1.0.0"

identity:
  name: "Evidence Research Agent"
  description: "Produces structured research from approved sources."

capabilities:
  - information_retrieval
  - evidence_synthesis
  - structured_reporting

tools:
  - id: web_search
    name: web_search
    side_effect_class: READ_ONLY

contracts:
  input:
    schema: { /* ... */ }
  output:
    schema: { /* ... */ }
  behavior:
    required:
      - cite_external_claims
      - validate_output_schema

permissions:
  shell: denied
  filesystem: read_only
  network: allowlist

2. Portable Intermediate Representation (PIR)

The Passport is normalized into a framework-independent intermediate representation:

graph LR
    A["Passport<br/>YAML/JSON"] --> B["Parser"]
    B --> C["Semantic<br/>Validation"]
    C --> D["PIR<br/>Canonical Form"]

    style A fill:#6366f1,color:#fff
    style D fill:#10b981,color:#fff
Loading

3. Runtime Adapters

Seamlessly compile and execute on any supported runtime:

graph TB
    PIR["📦 Portable Agent<br/>Definition"]

    PIR --> Lyzr["Lyzr<br/>Adapter"]
    PIR --> OpenAI["OpenAI<br/>Adapter"]
    PIR --> CrewAI["CrewAI<br/>Adapter"]

    Lyzr --> LR["Lyzr<br/>Runtime"]
    OpenAI --> OR["OpenAI<br/>Runtime"]
    CrewAI --> CR["CrewAI<br/>Runtime"]

    style PIR fill:#6366f1,color:#fff
    style LR fill:#10b981,color:#fff
    style OR fill:#10b981,color:#fff
    style CR fill:#10b981,color:#fff
Loading

4. Canonical Execution Trace

Different frameworks produce different execution events. Agent Passport normalizes them:

sequenceDiagram
    participant Agent
    participant Model
    participant Tool

    Agent->>Agent: Start
    Agent->>Model: Initialize Model Call
    Model->>Model: Process
    Model->>Tool: Invoke Tool
    Tool->>Tool: Execute
    Tool->>Model: Return Result
    Model->>Agent: Complete Call
    Agent->>Agent: End

    Note over Agent,Tool: Canonical Trace Format
Loading

🔐 Verification Layers

Agent Passport verifies eight distinct layers of agent properties:

graph TB
    A["🏗️ Structural<br/>Schema & Semantics"]
    B["🆔 Identity<br/>Preservation"]
    C["📋 Contracts<br/>Input/Output/Tools"]
    D["🔧 Tools<br/>Availability & Invocation"]
    E["🎭 Behavior<br/>Invariants & Requirements"]
    F["🔐 Permissions<br/>Runtime Boundaries"]
    G["⚙️ Runtime<br/>Execution & Errors"]
    H["🛡️ Security<br/>Isolation & Policy"]

    A --> I["✅ Verification<br/>Result"]
    B --> I
    C --> I
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I

    style I fill:#10b981,color:#fff,stroke:#059669
    style A fill:#6366f1,color:#fff
    style B fill:#6366f1,color:#fff
    style C fill:#6366f1,color:#fff
    style D fill:#6366f1,color:#fff
    style E fill:#ec4899,color:#fff
    style F fill:#f59e0b,color:#fff
    style G fill:#f59e0b,color:#fff
    style H fill:#ef4444,color:#fff
Loading

🎯 Behavioral Verification

LLM outputs are not byte-for-byte deterministic. Agent Passport uses a Behavior Envelope to distinguish semantic equivalence from behavioral drift:

graph LR
    A["Agent<br/>Execution"] --> B["Behavior<br/>Envelope"]

    B --> C["✅ Required<br/>Valid Struct Output<br/>Citations Present<br/>Approved Tools Only"]
    B --> D["~ Allowed Variation<br/>Wording<br/>Explanation Length<br/>Ordering"]

    C --> E["✓ Pass"]
    D --> E

    style B fill:#f59e0b,color:#fff
    style C fill:#10b981,color:#fff
    style D fill:#3b82f6,color:#fff
    style E fill:#10b981,color:#fff
Loading

🚀 Migration & Drift Detection

Migrate agents between runtimes with automatic behavioral drift detection:

graph TB
    Passport["🎫 Portable<br/>Passport"]

    Passport --> RA["Runtime A<br/>Execution"]
    Passport --> RB["Runtime B<br/>Execution"]

    RA --> TA["Trace A"]
    RB --> TB["Trace B"]

    TA --> C["Compatibility<br/>Engine"]
    TB --> C

    C --> R1["✅ Full<br/>Compatibility"]
    C --> R2["⚠️ Behavior<br/>Drift"]
    C --> R3["❌ Migration<br/>Failed"]

    style Passport fill:#6366f1,color:#fff
    style C fill:#f59e0b,color:#fff
    style R1 fill:#10b981,color:#fff
    style R2 fill:#f59e0b,color:#fff
    style R3 fill:#ef4444,color:#fff
Loading

Example: Citation Drift Detection

Runtime A:
Search → Summarize → Cite Sources ✓ PASS

Runtime B:
Search → Summarize → (Missing Citations) ✗ FAIL

Classification: BEHAVIOR_DRIFT

📦 Evidence Bundles

Every verification produces a tamper-evident evidence bundle:

evidence/run-001/
├── manifest.json          # Bundle metadata
├── passport.json          # Original specification
├── passport.sha256        # Hash verification
├── pir.json              # Portable IR
├── runtime.json          # Runtime info
├── adapter.json          # Adapter metadata
├── environment.json      # Execution environment
├── test-suite.json       # Verification suites
├── results.json          # Check results
├── compatibility.json    # Migration analysis
├── trace.ndjson         # Execution trace
├── outputs/             # Agent outputs
├── reports/             # Human-readable reports
└── signature.sig        # Ed25519 signature

🛡️ Security Model

Agent Passport executes agents in isolated sandboxes with defense-in-depth:

graph TB
    A["Agent<br/>Execution"]

    A --> B["Docker<br/>Isolation"]
    B --> C["Non-root<br/>User"]
    C --> D["CPU/Memory<br/>Limits"]
    D --> E["Timeout<br/>Protection"]
    E --> F["Isolated<br/>Filesystem"]
    F --> G["Network<br/>Policies"]
    G --> H["Secret<br/>Isolation"]
    H --> I["Deny-by-Default<br/>Permissions"]

    I --> J["✅ Sandboxed<br/>Execution"]

    style A fill:#6366f1,color:#fff
    style J fill:#10b981,color:#fff
    style B fill:#ef4444,color:#fff
    style C fill:#ef4444,color:#fff
    style D fill:#ef4444,color:#fff
    style E fill:#ef4444,color:#fff
Loading

📊 Tech Stack

Category Technology
Backend Python, FastAPI, Pydantic, SQLAlchemy
Database PostgreSQL, Redis, MinIO (S3-compatible)
Frontend Next.js, React, TypeScript, Tailwind CSS
Agent Runtimes OpenAI, Lyzr, CrewAI, Virtual
Security Docker, SHA-256, Ed25519
Infrastructure Docker Compose, Alembic
Tooling Pytest, pnpm, Turbo

🚀 Quick Start

Prerequisites

  • Python 3.12+
  • Node.js 18+
  • Docker & Docker Compose
  • Git

1. Clone and Setup

git clone https://github.com/JayeshJadhav28/agent-passport.git
cd agent-passport

# Setup Python virtualenv
python3.12 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -e .[dev]

# Copy environment template
cp .env.example .env

2. Start Infrastructure

docker-compose up -d postgres redis minio

3. Initialize Database

alembic upgrade head

4. Run API Server

uvicorn apps.api.main:app --reload --host 0.0.0.0 --port 8000

API docs available at: http://localhost:8000/docs

5. Start Web UI

In a new terminal:

cd apps/web
pnpm install
pnpm dev

Frontend available at: http://localhost:3000

💻 CLI Usage

Validate a Passport

python -m apps.cli validate agents/reference-research-agent/passport.yaml --json

Normalize to PIR

python -m apps.cli normalize agents/reference-research-agent/passport.yaml --json

Compile for Runtime

# OpenAI runtime
python -m apps.cli compile agents/reference-research-agent/passport.yaml \
  --runtime openai \
  --json

# Virtual runtime (no external APIs)
python -m apps.cli compile agents/migration-demo/passport.yaml \
  --runtime virtual-policy-a \
  --json

Run & Verify

echo '{"question": "What is the capital of France?"}' > input.json

python -m apps.cli run agents/reference-research-agent/passport.yaml \
  --runtime openai \
  --input-file input.json \
  --json

Detect Behavioral Drift

# Destructive confirmation drift
python -m apps.cli migrate agents/migration-demo/passport.yaml \
  --from-runtime virtual-policy-a \
  --to-runtime virtual-policy-b \
  --input-file destructive_input.json \
  --json

# Citation drift
python -m apps.cli migrate agents/reference-research-agent/passport.yaml \
  --from-runtime openai \
  --to-runtime openai-drift \
  --input-file research_input.json \
  --json

Publish to Registry

python -m apps.cli publish agents/reference-research-agent/passport.yaml \
  --evidence-dir evidence/run-<run_id> \
  --api-url http://localhost:8000 \
  --json

📁 Project Structure

agent-passport/
├── agents/                          # Reference agent definitions
│   ├── migration-demo/
│   │   └── passport.yaml           # Destructive-action confirmation demo
│   └── reference-research-agent/
│       └── passport.yaml           # Evidence Research Agent
│
├── apps/                            # Applications
│   ├── api/                         # FastAPI backend
│   │   ├── main.py
│   │   ├── routers/               # API endpoints
│   │   └── config.py
│   ├── cli/                         # Command-line interface
│   │   └── __main__.py
│   ├── verifier-worker/             # Async verification jobs
│   │   └── worker.py
│   └── web/                         # Next.js frontend
│       ├── app/
│       ├── lib/
│       └── package.json
│
├── packages/                        # Core libraries
│   ├── passport_schema/             # JSON Schema definitions
│   ├── passport_core/               # Domain models & validation
│   ├── pir/                         # Portable Intermediate Representation
│   ├── adapter_sdk/                 # Runtime adapter interfaces
│   ├── adapters/                    # Runtime implementations
│   │   ├── openai/
│   │   ├── lyzr/
│   │   └── crewai/
│   ├── trace_model/                 # Canonical execution traces
│   ├── verification_engine/         # Verification logic
│   ├── compatibility/               # Migration analysis
│   ├── evidence/                    # Evidence bundling
│   ├── security/                    # Sandbox & crypto
│   ├── tools/                       # Virtual tool implementations
│   ├── test_vectors/                # Test harness
│   └── sdk/                         # TypeScript SDK
│
├── database/                        # SQLAlchemy models & migrations
├── docs/                            # Documentation
├── examples/                        # Example Passports
├── infra/                           # Docker configurations
├── docker-compose.yml               # Local development stack
├── pyproject.toml                   # Python dependencies
├── package.json                     # JS monorepo
└── README.md                        # This file

🌐 Web Platform Features

Passport Studio

Create and validate Passport definitions with syntax highlighting and inline validation.

Runtime Matrix

View which runtimes support which agent capabilities and verification coverage.

Verification Console

Monitor verification suites and individual assertion results in real-time.

Trace Explorer

Inspect normalized agent execution traces with detailed event sequencing.

Migration Report

Compare source and target runtime behavior with drift analysis.

Evidence Explorer

Inspect artifact hashes, reports, and signatures for complete transparency.

Agent Registry

Discover published, versioned agents and their verification history.

🧪 Verification Workflow

graph LR
    A["Define<br/>Passport"] --> B["Compile<br/>PIR"]
    B --> C["Execute<br/>Sandbox"]
    C --> D["Collect<br/>Trace"]
    D --> E["Verify<br/>Checks"]
    E --> F["Generate<br/>Evidence"]
    F --> G["Sign &<br/>Publish"]

    style A fill:#6366f1,color:#fff
    style B fill:#8b5cf6,color:#fff
    style C fill:#ec4899,color:#fff
    style D fill:#f59e0b,color:#fff
    style E fill:#10b981,color:#fff
    style F fill:#3b82f6,color:#fff
    style G fill:#06b6d4,color:#fff
Loading

🔄 Migration Workflow

graph TB
    A["Source<br/>Passport"]
    B["Target<br/>Passport"]

    A --> C["Compile<br/>Runtime A"]
    B --> D["Compile<br/>Runtime B"]

    C --> E["Execute"]
    D --> F["Execute"]

    E --> G["Trace A"]
    F --> H["Trace B"]

    G --> I["Compare<br/>Traces"]
    H --> I

    I --> J["Behavioral<br/>Compatibility<br/>Analysis"]

    J --> K["✅ Compatible"]
    J --> L["⚠️ Drift"]
    J --> M["❌ Incompatible"]

    style A fill:#6366f1,color:#fff
    style B fill:#6366f1,color:#fff
    style K fill:#10b981,color:#fff
    style L fill:#f59e0b,color:#fff
    style M fill:#ef4444,color:#fff
Loading

🎓 Philosophy

Agent Passport follows five core principles:

1. Portable by Design

The canonical agent definition is independent of its runtime.

2. Contract Driven

Agent behavior, tools, inputs, outputs, and permissions are explicit and verified.

3. Verified, Not Assumed

Execution success is not equivalent to behavioral compatibility.

4. Evidence First

Every verification result is backed by inspectable, tamper-evident artifacts.

5. Open by Default

The Passport format, adapters, verification suites, and evidence format are designed for an extensible ecosystem.

📚 Documentation

🤝 Contributing

We welcome contributions! Areas for enhancement include:

  • 🔌 New runtime adapters (e.g., LangChain, AutoGPT)
  • ✅ New verification suites and invariants
  • 🧪 Additional test vectors
  • 📖 Documentation improvements
  • 🎨 UI/UX enhancements
  • 🐛 Bug fixes and optimizations

See CONTRIBUTING.md for detailed guidelines.

📋 Roadmap

  • Passport Specification v1
  • Portable Intermediate Representation
  • Passport Compiler
  • Adapter SDK
  • Runtime Adapters (OpenAI ✓, Lyzr, CrewAI, Custom)
  • Canonical Trace Model
  • Verification Engine
  • Behavior Contracts
  • Permission Enforcement
  • Migration Engine
  • Behavioral Drift Detection
  • Evidence Bundles
  • Cryptographic Signing
  • CLI
  • Web Platform
  • Agent Registry
  • CI/CD Conformance Pipeline
  • Production Deployment

🔐 Security

Agent Passport implements defense-in-depth security measures. For security considerations, vulnerability reporting, and sandbox limitations, see SECURITY.md.

Key Security Features:

  • Docker-based isolated execution
  • Non-root sandboxed processes
  • Resource limits (CPU, memory, timeouts)
  • Network policies and secret isolation
  • Cryptographically signed evidence
  • Deny-by-default permission model

📜 License

This project is licensed under the MIT License. See LICENSE for details.

👤 Author

Created by Jayesh Jadhav

⭐ Support

If you find Agent Passport useful, please consider:

  • ⭐ Starring the repository
  • 📢 Sharing with the community
  • 🤝 Contributing improvements
  • 🐛 Reporting issues and bugs
  • 💡 Suggesting enhancements

🎯 The Core Idea

DEFINE → COMPILE → MIGRATE → EXECUTE → OBSERVE → VERIFY → COMPARE → PROVE

Agent Passport makes AI-agent portability measurable.

Define Once. Travel Anywhere. Prove It.

Made with ❤️ by Jayesh Jadhav

⬆ back to top

About

Framework-independent infrastructure for building, migrating, and verifying portable AI agents across runtimes.

Topics

agent-interoperabilityagent-migrationagent-portabilityagent-verificationai-agentsai-infrastructureportable-agent

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages