capiscio 2.0.0

The definitive A2A protocol validator with live endpoint testing, JWS signature verification, and transport protocol compliance checking

Capiscio CLI - A2A Protocol Validator

Validator & A2A Protocol Compliance CLI | The only CLI that actually tests AI agent transport protocols. Validate agent-card.json files, A2A compliance across JSONRPC, GRPC, and REST with live endpoint testing.

🌐 Learn more about Capiscio | Download Page | Web Validator

Installation

pip install capiscio

Zero dependencies required - This package contains pre-built native binaries that work without Python runtime dependencies.

Quick Start

💡 Prefer a web interface? Try our online validator at capisc.io - no installation required!

# Validate your agent (with signature verification)
capiscio validate ./agent-card.json

# Test live endpoints with cryptographic verification  
capiscio validate https://your-agent.com

# Strict validation for production deployment
capiscio validate ./agent-card.json --strict --json

# Skip signature verification when not needed
capiscio validate ./agent-card.json --skip-signature

Security & Trust 🔐

Industry-grade cryptographic validation:

• ✅ RFC 7515 compliant JWS signature verification
• ✅ HTTPS-only JWKS endpoint fetching
• ✅ Secure by default - signatures checked automatically
• ✅ Zero trust - verify before you trust any agent card
• ✅ Production ready - meets enterprise security standards

Why signature verification matters:

• Prevent tampering - Detect modified or malicious agent cards
• Establish authenticity - Cryptographically verify publisher identity
• Enable trust networks - Build secure agent ecosystems
• Regulatory compliance - Meet security audit requirements

Key Features

• 🚀 Transport Protocol Testing - Actually tests JSONRPC, GRPC, and REST endpoints
• 🔐 JWS Signature Verification - Cryptographic validation of agent cards (RFC 7515 compliant)
• 💻 Native Binaries - No Node.js or runtime dependencies required
• 🔍 Smart Discovery - Finds agent cards automatically with multiple fallbacks
• ⚡ Three Validation Modes - Progressive, strict, and conservative
• 🔧 CI/CD Ready - JSON output with proper exit codes
• 🌐 Live Endpoint Testing - Validates real connectivity, not just schemas
• 🛡️ Secure by Default - Signature verification enabled automatically

Usage Examples

Basic Commands

capiscio validate [input] [options]

# Examples
capiscio validate                              # Auto-detect in current directory
capiscio validate ./agent-card.json           # Validate local file (with signatures)
capiscio validate https://agent.com           # Test live agent (with signatures)
capiscio validate ./agent-card.json --skip-signature # Skip signature verification
capiscio validate ./agent-card.json --verbose # Detailed output
capiscio validate ./agent-card.json --registry-ready # Check registry readiness
capiscio validate https://agent.com --errors-only    # Show only problems

Key Options

Option	Description
--strict	Strict A2A protocol compliance
--json	JSON output for CI/CD
--verbose	Detailed validation steps
--timeout	Request timeout (default: 10000)
--schema-only	Skip live endpoint testing
--skip-signature	Skip JWS signature verification
--test-live	Test agent endpoint with real messages

Three-Dimensional Scoring

Capiscio CLI automatically provides detailed quality scoring across three independent dimensions:

# Scoring is shown by default
capiscio validate agent.json

Three Quality Dimensions:

• Spec Compliance (0-100) - How well does the agent conform to A2A v0.3.0?
• Trust (0-100) - How trustworthy and secure is this agent? (includes confidence multiplier)
• Availability (0-100) - Is the endpoint operational? (requires --test-live)

Each score includes a detailed breakdown showing exactly what contributed to the result. Learn more: Scoring System Documentation

Live Agent Testing

The --test-live flag tests your agent endpoint with real A2A protocol messages:

# Test agent endpoint
capiscio validate https://agent.com --test-live

# Test with custom timeout
capiscio validate ./agent-card.json --test-live --timeout 5000

# Full validation for production
capiscio validate https://agent.com --test-live --strict --json

What it validates:

• ✅ Endpoint connectivity
• ✅ JSONRPC and HTTP+JSON transport protocols
• ✅ A2A message structure (Message, Task, StatusUpdate, ArtifactUpdate)
• ✅ Response timing metrics

Exit codes for automation:

• 0 = Success
• 1 = Schema validation failed
• 2 = Network error (timeout, connection refused, DNS)
• 3 = Protocol violation (invalid A2A response)

Use cases:

• CI/CD post-deployment verification
• Cron-based health monitoring
• Pre-production testing
• Third-party agent evaluation
• Multi-environment validation

Signature Verification (New in v1.2.0)

Secure by default JWS signature verification for agent cards:

🔐 Cryptographic Validation

• RFC 7515 compliant JWS (JSON Web Signature) verification
• JWKS (JSON Web Key Set) fetching from trusted sources
• Detached signature support for agent card authentication
• HTTPS-only JWKS endpoints for security

🛡️ Security Benefits

• Authenticity - Verify agent cards haven't been tampered with
• Trust - Cryptographically confirm the publisher's identity
• Security - Prevent malicious agent card injection
• Compliance - Meet security requirements for production deployments

Why Use Capiscio CLI?

Catch Integration Issues Before Production:

• ❌ Schema validators miss broken JSONRPC endpoints
• ❌ Manual testing doesn't cover all transport protocols
• ❌ Integration failures happen at runtime
• ❌ Unsigned agent cards can't be trusted
• ✅ Capiscio tests actual connectivity and protocol compliance
• ✅ Capiscio verifies cryptographic signatures for authenticity

Real Problems This Solves:

• JSONRPC methods return wrong error codes
• GRPC services are unreachable or misconfigured
• REST endpoints don't match declared capabilities
• Agent cards validate but agents don't work
• Unsigned or tampered agent cards pose security risks

Transport Protocol Testing

Unlike basic schema validators, Capiscio CLI actually tests your agent endpoints:

• JSONRPC - Validates JSON-RPC 2.0 compliance and connectivity
• GRPC - Tests gRPC endpoint accessibility
• REST - Verifies HTTP+JSON endpoint patterns
• Consistency - Ensures equivalent functionality across protocols

Perfect for testing your own agents and evaluating third-party agents before integration.

CI/CD Integration

GitHub Actions Example:

- name: Install and Validate Agent
  run: |
    pip install capiscio
    capiscio validate ./agent-card.json --json --strict

Docker Example:

RUN pip install capiscio
COPY agent-card.json .
RUN capiscio validate ./agent-card.json --strict

Exit codes: 0 = success, 1 = validation failed

Platform Support

This package contains pre-built binaries for multiple platforms:

• Linux: x86_64, ARM64
• macOS: Intel (x64), Apple Silicon (ARM64)
• Windows: x64 (ARM64 available via direct download)
• Python: 3.7+ (no runtime dependencies required)

The Python wrapper automatically detects your platform and runs the appropriate native binary.

FAQ

Q: What is the A2A Protocol?
A: The Agent-to-Agent (A2A) protocol v0.3.0 is a standardized specification for AI agent discovery, communication, and interoperability. Learn more at capisc.io.

Q: How is this different from schema validators?
A: We actually test live JSONRPC, GRPC, and REST endpoints with transport protocol validation, not just JSON schema structure. We also verify JWS signatures for cryptographic authenticity.

Q: Do I need Node.js installed?
A: No! This Python package contains pre-built native binaries that work without any Node.js dependency.

Q: Can I validate LLM agent cards?
A: Yes! Perfect for AI/LLM developers validating agent configurations and testing third-party agents before integration.

Development

This package contains pre-built native binaries compiled for maximum performance and zero dependencies. The CLI provides the same functionality across all platforms without requiring any additional runtime installations.

Source code: https://github.com/capiscio/capiscio-cli

License

MIT License - see the main repository for details.

---

Need help? Visit capisc.io | Open an issue | Documentation | Web Validator

Keywords: A2A protocol, AI agent validation, agent-card.json validator, Python CLI, agent-to-agent protocol, LLM agent cards, AI agent discovery, transport protocol testing, JSONRPC validation, GRPC testing, JWS signature verification