What is soul-agent-validator?

soul-agent-validator is a Python package that validates AI agent repositories against 33 compliance rules before deployment. It checks for hardcoded secrets, unsafe imports, missing governance docs, PII handling, rate limiting, and Google A2A protocol compliance — all defined as plain Markdown files you can read and edit.

How do I install soul-agent-validator?

pip install soul-agent-validator. Then run 'soul-agent-validator serve' to start the web UI on port 8080, or 'soul-agent-validator validate https://github.com/your-org/your-agent' to validate from the CLI.

What rules does soul-agent-validator check?

33 rules across 4 tiers: HARD gates (reject on fail) cover secrets, banned imports, SSRF, and A2A compliance. SOFT gates (warn) cover rate limiting, PII redaction, error handling, and data residency. QUALITY checks cover README, CHANGELOG, SOUL.md presence, and test coverage. A2A checks verify Google A2A protocol compliance.

What is Google A2A and why does it matter for agent validation?

Google's A2A (Agent-to-Agent) protocol is a standard for agent discovery and interoperability. It requires agents to serve a .well-known/agent.json card and support JSON-RPC 2.0 tasks/send. soul-agent-validator checks A2A compliance as part of its rule set, and is itself A2A compatible — orchestrators can call it as a tool.

Can I add custom rules?

Yes. Rules are plain Markdown files in the rules/ directory. Create a new .md file following the existing template — define a tier (HARD/SOFT/QUALITY), check type (regex_scan, ast_check, structure_check), parameters, and failure message. No code changes required.

How is soul-agent-validator different from other code scanners?

Most scanners (Bandit, Semgrep, Trivy) check for general code vulnerabilities. soul-agent-validator is specifically designed for AI agent repositories — it checks AI-specific risks like prompt injection patterns, tool call safety, missing SOUL.md identity files, lack of memory architecture, and A2A protocol gaps that generic scanners miss.

What is soul.py and why is it used in soul-agent-validator?

soul.py (pip install soul-agent) gives AI agents persistent identity and memory across sessions. soul-agent-validator uses it to load a governance auditor persona (SOUL.md) on startup, ensuring consistent and principled review behavior across all validations. The two packages are complementary: soul.py gives agents internal identity; soul-agent-validator validates their external compliance.

Can I use soul-agent-validator in CI/CD?

Yes. The REST API accepts a GitHub repo URL and returns a structured JSON report card. Add a step to your GitHub Actions or GitLab CI to POST to your validator instance and fail the pipeline if any HARD gate fails. See the GitHub Actions example in the documentation.

soul-agent-validator: pip install Your AI Agent Governance Pipeline

By Prahlad Menon Published 2026-04-18 3 min read

Every AI agent that ships to production today is a black box. You have no idea if it’s hardcoding API keys, calling unauthorized external services, skipping PII redaction, or missing the governance documentation that makes audits survivable. And with Google A2A becoming the standard for agent interoperability, there’s a whole new category of compliance gaps — agents that claim A2A compatibility but don’t actually serve a valid agent card.

soul-agent-validator is the pre-deployment governance pipeline for AI agents. One command, 33 rules, structured report card.

pip install soul-agent-validator

# Validate from the CLI
soul-agent-validator validate https://github.com/your-org/your-agent

# Or start the web UI
soul-agent-validator serve    # → http://localhost:8080

What It Checks

Rules are organized into four tiers. HARD failures reject the agent outright. SOFT failures warn but allow deployment. QUALITY checks are advisory.

HARD Gates — Reject on Failure

SEC-001 — Hardcoded secrets: scans for API keys, tokens, AWS/GCP/GitHub credentials embedded in source
SEC-002 — Banned imports: flags subprocess, os.system, eval with external input
SEC-003 — SSRF risk: detects unvalidated URL construction that could allow server-side request forgery
A2A-001 — Agent card: checks for .well-known/agent.json with required fields
A2A-002 — A2A endpoint: verifies tasks/send JSON-RPC 2.0 endpoint exists

SOFT Gates — Warn

Rate limiting on API endpoints
PII redaction before logging
Error handling and graceful degradation
Input validation on tool calls
Data residency controls

QUALITY — Advisory

README presence and minimum length
CHANGELOG or version history
SOUL.md for agent identity (soul.py integration)
Test coverage indicators
Dependency version pinning

The soul.py Connection

soul-agent-validator is powered by soul.py (arXiv:2604.09588). It loads a governance auditor persona from SOUL.md on startup — so the validator doesn’t just run mechanical checks, it maintains a consistent set of values and reasoning patterns across all validations.

This is the same architecture described in Persistent Identity in AI Agents: the validator itself is an AI agent with persistent identity, validating whether other AI agents meet the bar for deployment.

One of the QUALITY checks specifically looks for SOUL.md in the repo being validated. An agent that ships with a defined identity and memory architecture — that has thought through who it is and how it remembers — is a more trustworthy agent than one that doesn’t.

Google A2A Compliance Built In

As Google’s A2A protocol gains adoption, validators need to check for A2A compliance in the repos they scan and be A2A-compatible themselves. soul-agent-validator does both.

It checks:

GET /.well-known/agent.json  → required fields: name, description, skills, capabilities
POST /a2a                    → JSON-RPC 2.0, tasks/send method

It serves:

curl https://your-validator/.well-known/agent.json
# → agent card with skills: [validate-agent]

curl -X POST https://your-validator/a2a \
  -d '{"jsonrpc":"2.0","method":"tasks/send","params":{"message":{"parts":[{"text":"validate https://github.com/org/repo"}]}}}'

Orchestrators using LangGraph, CrewAI, or Google ADK can call soul-agent-validator as a tool — pass a GitHub URL, get back a report card with pass/warn/fail breakdown.

Custom Rules in Markdown

The entire rule engine is driven by Markdown files. No DSL, no YAML schema, no proprietary format. Each rule looks like this:

## RULE: CUSTOM-001 — No Direct DB Writes

**Tier:** HARD (fail = reject)
**Check type:** regex_scan
**Tags:** data-integrity

### Description
Agents must not write directly to the database.

### Parameters
```yaml
patterns:
  - "cursor\\.execute\\s*\\(.*INSERT"
file_glob: "**/*.py"

Failure Message

❌ Direct DB write detected. Use the data access layer.


Drop it in `rules/custom.md`, restart, and the rule is live. No code changes.

## CI/CD Integration

```yaml
# .github/workflows/agent-check.yml
- name: Validate agent before deploy
  run: |
    curl -X POST ${{ vars.VALIDATOR_URL }}/validate \
      -H "Content-Type: application/json" \
      -d '{"repo_url": "${{ github.server_url }}/${{ github.repository }}", "submitter": "${{ github.actor }}"}' \
      | tee result.json
    
    # Fail if any HARD gate failed
    python3 -c "
    import json, sys
    r = json.load(open('result.json'))
    hard_fails = [f for f in r.get('report', {}).get('failures', []) if f.get('tier') == 'HARD']
    if hard_fails:
        print('❌ Hard gate failures:', [f['rule_id'] for f in hard_fails])
        sys.exit(1)
    print('✅ All hard gates passed')
    "

Deploy It Yourself

Docker:

docker build -t soul-agent-validator .
docker run -p 8080:8080 soul-agent-validator

Railway / Cloud Run / Fly.io: A Dockerfile is included. Point your platform at the repo and it deploys in minutes.

Community

soul-agent-validator — I built a pre-deployment governance pipeline for AI agents (33 rules, A2A compatible, soul.py powered)
by u/the_ai_scientist in r/ollama