How relari-ai/agent-contracts works
Project Type & Purpose
• The project is a middleware/verification framework that acts as a contract-based guard for AI systems.
• Its primary purpose is to enforce formal verification (offline and runtime) and certification of AI agents by checking defined behavioral contracts.
• The README indicates that contracts are defined, verified offline (via test runs) and further processed in runtime certification scenarios, integrating tools like Docker, Relari OTEL, and Jaeger.
High-Level Components & Their Roles
• Agent Contracts Core (agent_contracts/core):
• Contains the definitions for data types (specifications, trace, and verification), configuration management, and prompt templates.
• Manages the representation of preconditions, pathconditions, and postconditions, and defines how contracts are structured and processed.
• Certification Module (agent_contracts/certification):
• Handles runtime certification and configuration for certifying the ongoing behavior of AI agents.
• Includes supporting elements like configuration and protocol definitions for runtime verification.
• CLI Interface (agent_contracts/cli.py):
• Provides command-line utilities for listing runs, triggering verifications, and other interactions with the framework.
• Integrations (agent_contracts/integrations):
• Contains adapters for external systems such as Jaeger and StackAI. These scope out how to integrate the framework with external tracing and monitoring tools.
• Prompts and TUI (agent_contracts/prompts and agent_contracts/tui):
• Jinja2 templates to generate and customize messages or prompts for verifying preconditions, pathconditions, and postconditions.
• TUI files suggest a simple text-based user interface for interacting with parts of the system.
• Configuration & Deployment:
• The configs folder and multiple docker-compose files indicate deployment scenarios and runtime configuration for both verification and certification modes.
• The Makefile and pyproject.toml show toolchain integrations and build/deployment automation.
Relationships and Interactions
• The main “core” contracts creation and verification engine make extensive use of the datatypes in the core module to structure contracts.
• The CLI (and likely the TUI) provide entry points for developers to trigger both offline verification and runtime certification.
• The integrations serve as connectors to external systems (like Jaeger) for telemetry and tracing.
• When a contract is defined (using the specifications and scenario patterns), it is then passed to the verification engine that interacts with (or simulates) an agent’s behavior, collects traces, and validates outcomes against the predefined contracts.
• The runtime certification process invoked via a separate docker-compose flow uses configurations from the certification module to check the trace data in real time.
• Utility modules assist across these components (for logging, generating IDs, telemetry, etc.).
Architectural Patterns and Design Principles
• Modular design: The separation of concerns is clear from the distinct directories for core, certification, integrations, and prompts.
• Layered architecture: Lower-level utilities support core functionalities, which then feed into higher-level services like verification and certification.
• Extensibility: The presence of clear integration points (e.g., for Jaeger and external telemetry) suggests the framework is designed to be extended with additional integrations as needed.
• Configuration-driven: Multiple configuration files and YAML/JSON support indicate that the system behavior is highly configurable via external files.