Eigenoid Core

Governed communication for multi-agent AI -- every agent interaction traced, scoped, and approved.

Status	alpha
Version	0.1.0
Python	>=3.10
Repo	eigenoid/eigenoid
License	Business Source License 1.1

Overview

Eigenoid Core is a Python framework that provides the runtime for governed agent-to-agent communication. It ensures that every interaction between AI agents is authenticated, authorized, audited, and -- when required -- approved by a human.

Key capabilities:

• SPIFFE/SPIRE identity -- cryptographic workload identity for every agent, using X.509 SVIDs issued by SPIRE.
• A2A protocol -- interoperability between agents using the Agent-to-Agent protocol, with built-in server and executor.
• Delegation chains -- scoped permission propagation across agent hops, with automatic permission reduction at each step.
• Approval workflows -- human-in-the-loop approval for sensitive operations, with configurable policies and tracking.
• Audit trails -- every agent interaction is logged to pluggable backends (SQLite, JSONL, or custom).
• Orchestration -- supervisor-based multi-agent orchestration with YAML-driven stack configuration and LLM agent support.
• Agent discovery -- pluggable discovery providers (static, agent card, chained) for locating agents at runtime.

Architecture

Module breakdown

Module	Purpose
eigenoid.agent	Simplified Agent class with @skill decorator
eigenoid.core	Low-level agent, config, identity, TLS, peer cert middleware
eigenoid.delegation	Delegation chain management and permission reduction
eigenoid.permissions	Permission sets, inheritance strategies, filesystem permissions
eigenoid.approval	Approval server, tracker, policies, and request lifecycle
eigenoid.audit	Audit store with pluggable backends (SQLite, JSONL)
eigenoid.auth	OIDC, token resolver, credential storage
eigenoid.a2a	Agent Card, SPIFFE executor, A2A server
eigenoid.orchestration	Supervisor, LLM agent, YAML stack config
eigenoid.spire	SPIRE process supervisor, binary resolver, config generator
eigenoid.conversation	Governed conversation store, BM25 search, skill routing
eigenoid.cli	Command-line interface (eigenoid command)

Installation

Eigenoid Core is distributed as compiled Cython wheels via GCP Artifact Registry. Production wheels ship compiled .so extensions for critical modules instead of plain .py source.

Prerequisites

• Python 3.10 or higher
• Access to the private Artifact Registry repository
• GCP credentials with Artifact Registry Reader permissions

Install the keyring helper

pip install keyrings.google-artifactregistry-auth

bash

Basic install

pip install --extra-index-url \
  https://us-central1-python.pkg.dev/eigenoid-prd/eigenoid-python/simple/ \
  eigenoid==0.1.0

bash

With dev dependencies

pip install --extra-index-url \
  https://us-central1-python.pkg.dev/eigenoid-prd/eigenoid-python/simple/ \
  "eigenoid[dev]==0.1.0"

bash

In requirements.txt

--extra-index-url https://us-central1-python.pkg.dev/eigenoid-prd/eigenoid-python/simple/
eigenoid==0.1.0

text

Verify

eigenoid --help

bash

Quick start

Define an agent with a skill and run it:

from eigenoid import Agent, skill, context

class MyAgent(Agent):
    name = "my-agent"
    description = "A simple example agent"

    @skill("greet")
    async def greet(self, name: str):
        caller = context.caller_spiffe_id
        return {"message": f"Hello {name}!", "from": caller}

if __name__ == "__main__":
    MyAgent().run(port=9100)

python

This starts an A2A-compatible agent server on port 9100, with SPIFFE identity, delegation chain enforcement, and audit logging enabled by default.

Multi-agent orchestration

For multi-agent systems, define a stack in YAML and let the supervisor manage the agents:

from eigenoid import load_stack_config, AgentSupervisor

config = load_stack_config("eigenoid.yaml")
supervisor = AgentSupervisor(config)
supervisor.run()

python

Distribution model

Eigenoid Core uses a dual-mode build:

• Developer mode -- standard source installs for local development and editable installs.
• Release mode -- when EIGENOID_COMPILE=1 is set, critical internal modules are compiled with Cython and packaged as native extensions. The .py and .c source files are stripped from the published wheel.

This provides practical IP protection for orchestration, governance, and delegation logic while preserving a normal Python developer workflow. CI builds are driven by .github/workflows/build-and-publish.yml and published to GCP Artifact Registry at us-central1-python.pkg.dev/eigenoid-prd/eigenoid-python/.