Skip to main content

Universal Agent Interface (UAI)

📖 中文文档 / Chinese README

Cross-vendor agent collaboration with acceptance governance: agents from different runtimes (Codex, Claude Code, DeepSeek Harness, any CLI) work under one hub — with enforced acceptance gates so that "an agent says DONE" is never trusted until a third-party verifier signs off.

Honest scope: proven in a real multi-agent delivery pipeline (4 seats, 3,000+ ledger records, 7 fabricated-completion incidents caught). Single-developer small tasks don't need this — deploy cost > benefit.

Why

LLM agents fabricate completions. Prompting can't fix it; mechanisms can. UAI separates execution state from acceptance verdicts:

  • SUCCEEDED only means "stopped and submitted a claim" — externally projected as "pending verification" until a VERDICT lands.
  • Verifier seat is never the implementer (ENFORCED, tested).
  • Evidence levels E1–E4; self-reported evidence cannot impersonate independent verification.

Quickstart (30 minutes, Linux/macOS/WSL)

git clone https://github.com/3338902669-ops/universal-agent-interface.git
cd universal-agent-interface

# 1. deps
pip install nats-py jsonschema cryptography

# 2. NATS (any server ≥2.9)
nats-server -c prototype/nats-test.conf        # listens 127.0.0.1:43321

# 3. hub
python prototype/hub.py --base prototype --nats-url nats://127.0.0.1:43321

# 4. verify acceptance gate projection (read-only, no deps on runtime)
python stage2/test_projection.py               # 10/10
python stage2/test_a2a_server.py               # 12/12

Full suite (24 suites, 300+ cases) and a real-lab end-to-end (A2A request → envelope → hub → real runtime → ledger) live in stage2/DEVELOPMENT.md.

What's inside

Layer Path What it does
Contract protocol/contract-v1.md, schemas/ v1 envelope (11 required fields), canonical verdict vocabulary, JSON Schema, conformance suite
Prototype prototype/ NATS hub: idempotency, leases+fencing, single-writer resources, ledger hash-chain
Governance (stage2) stage2/ A2A projection (AgentCard/Task/events), inbound message/send, SSE stream, webhook push (HMAC), OIDC/Ed25519 verifiers, unified cross-repo model
Bridges stage2/paseo_uai_bridge.py Paseo daemon orchestration ↔ UAI acceptance

Architecture in one picture

runtime seats (codex / claude / dsh / yours)
        │  provider CLI
   Paseo daemon (or any orchestrator)
        │  envelope (contract v1)
   UAI hub — ledger (append-only, hash-chained) + verdicts
        │  projection (AgentCard / Task / SSE / webhook)
   external A2A consumers

Design rule: reuse A2A semantics (AgentCard, task states), replace the transport; acceptance/verdict logic is internal and never outsourced.

Key invariants (ENFORCED, each with a test)

  • SUCCEEDED ≠ passed — projection writes "pending verification" without a verdict
  • idempotency treats loss only; fabrication is handled by the verdict seat
  • verifier ≠ implementer; unknown side-effect state forbids auto-retry
  • no verifier configured → identity stays asserted, never upgraded
  • experimental_test_only gate on event_bridge until a real cross-vendor consumer exists

Status / honest gaps

  • Cross-vendor identity: OIDC verifier ready (production JWKS verified against Microsoft), real IdP issuance is account-side work
  • A2A streaming: SSE done; push notifications done (webhook, HMAC); gRPC binding not planned
  • event_bridge v1/v2 remain behind experimental_test_only until a real external consumer exists

License: see LICENSE. Paseo bridge operates under AGPL-3.0 constraints of the upstream project.

Metadata

Release files for uai-governance 0.15.4.post1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uai-governance 0.15.4.post1
File Size Uploaded Provenance Actions
uai_governance-0.15.4.post1.tar.gz 58.5 kB Without provenance Details for uai_governance-0.15.4.post1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for uai-governance 0.15.4.post1
File Interpreter ABI Platform Actions
uai_governance-0.15.4.post1-py3-none-any.whl Python 3 none any Details for uai_governance-0.15.4.post1-py3-none-any.whl

Total release size: 126.0 kB

Release files / uai_governance-0.15.4.post1.tar.gz

Download URL uai_governance-0.15.4.post1.tar.gz
Size 58.5 kB
Tags Source
SHA-256 checksum
How to use checksums
645af200084a80c12c8c5db790091302938cfc84a35bc20184fb0f1ea2eeac0f
BLAKE2b-256 checksum
How to use checksums
f47387148b91e54520cb148e43c78bf2ae45264f5a0e58f35e862ea56a547b94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / uai_governance-0.15.4.post1-py3-none-any.whl

Download URL uai_governance-0.15.4.post1-py3-none-any.whl
Size 67.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4656fa9ea1ab0a2801ae37bd312a357394f7e2c15d6bfa56cdd9f22ce2d98f5c
BLAKE2b-256 checksum
How to use checksums
d2beb9d349e15b11251e1e14dc55743f0ca1f247d3af42de1c203715da50a6f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Security for uai-governance 0.15.4.post1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.15.4.post1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page