Skip to content

Releases: agent-matrix/a2a-validator

v0.1.0

05 Oct 09:16
@ruslanmv ruslanmv
v0.1.0
8c4c4be

Choose a tag to compare

View all tags
v0.1.0 Latest
Latest

A2A Validator v0.1.0 — Release Notes

Date: 2025-10-05
Tag: v0.1.0

This one is all about making the Validator effortless to use in the real world—whether you’re pasting a root URL that redirects to docs, running inside Docker, or testing agents that don’t ship a perfect Agent Card yet. The UI got sharper, the API got friendlier, and the networking path is far more forgiving.

Highlights

  • Smarter Agent Card resolution
    Paste a base URL and the Validator will follow redirects and probe common paths like /.well-known/agent.json and /agent.json before giving up.

  • Production-ready chat path
    Socket.IO mounts cleanly; message handling is hardened; and validation errors are surfaced in-stream (✅/⚠️).

  • HF Spaces & Docker friendly
    Better defaults behind proxies and in containerized setups; fewer surprises on localhost vs. container networking.

  • Cleaner, calmer UI
    No more “Matrix rain” bleeding through code blocks. The Agent Card and JSON modals have solid, readable backgrounds.

What’s New

  • Lenient card fetcher (/validator/agent-card and the root alias /agent-card)

    • Follows 30x redirects (e.g., a root URL that bounces to /docs).

    • Probes well-known locations automatically:

      • /.well-known/agent.json
      • /.well-known/ai-agent.json
      • /agent-card
      • /agent.json

    • Returns the resolved URL along with validation results.

  • Root alias for the UI script

    • Added server-side alias POST /agent-card → /validator/agent-card so the frontend can “just work” in embedded or proxied environments.

  • Optional A2A SDK integration

    • If a2a-sdk is present, the app uses the official resolver and streaming client.
    • If not, it gracefully falls back to HTTP fetch + local validation (card linting still works).

  • Socket.IO hardened

    • Clean mount at /socket.io.
    • Safe connect/disconnect lifecycle; resource cleanup on disconnect.

Improvements

  • UI polish

    • Solid code block backgrounds; no visual bleed from animated background.
    • Collapsible sections are consistent and accessible.
    • Agent Card section gets a proper header with toggle.
    • Debug console and Raw JSON modal are always available and more readable.

  • Safer inputs

    • Incoming user text is sanitized with bleach before being sent to agents.

  • OpenAPI & routing

    • Default landing route now redirects to /validator only (avoids FastAPI union type edge cases).
    • Health endpoints are unchanged (/healthz, /readyz) and tagged.

  • Developer experience

    • Static assets are mounted predictably at /static.
    • Clear log lines for Socket.IO mount and alias creation.

  • CI/CD

    • Multi-arch images built and published (Docker Hub + GHCR).
    • Rich OCI labels (version, commit, build date).
    • Registry-neutral Dockerfile; build cache enabled.

Bug Fixes

  • Fixed 307 Temporary Redirect crashes when users paste a base URL; we now follow redirects and probe for the actual card.
  • Eliminated “code rain” showing through JSON code blocks by using an opaque background on <pre><code>.
  • Resolved 404 /agent-card by adding an explicit alias even when the validator router is prefixed.
  • Avoided FastAPI response model errors on / by returning a single RedirectResponse (no problematic Union).

Breaking / Behavioral Changes

  • Root route / now always redirects to /validator.
    If you previously mounted a different home, update your links or add your own alias.

  • Legacy “Chat/Dev” UI pages are not shipped by default in v0.1.0.
    The focus is the A2A Validator experience (UI + endpoints). You can re-enable your own pages in your app if you need them.

Deployment Notes

  • Ports
    The app listens on $PORT (default 7860). The validator will attempt to talk to agents on whatever port their card advertises (common: 8080, 3000, 8000, 11434, 5000, 80, 443).

  • Proxies / HF Spaces
    The server runs with --proxy-headers. If your agent lives behind HTTPS and the validator is on HTTPS, you’re good. If your agent is HTTP-only, watch for browser mixed-content blocks; put a TLS proxy in front of the agent or let the validator fetch server-side (recommended).

  • Docker “localhost” gotcha
    From inside the validator container, http://localhost:8080 means the container itself, not your host. Use:

    • http://host.docker.internal:8080 (Docker Desktop), or
    • The agent’s service name on a user-defined Docker network, or
    • An externally reachable host/IP.

How to Upgrade

Docker Hub

docker pull docker.io/ruslanmv/a2a-validator:v0.1.0
docker run --rm -p 7860:7860 docker.io/ruslanmv/a2a-validator:v0.1.0

GHCR

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <you> --password-stdin
docker pull ghcr.io/<owner>/a2a-validator:v0.1.0
docker run --rm -p 7860:7860 ghcr.io/<owner>/a2a-validator:v0.1.0

Pip / source

# if you run from source
pip install -U a2a-validator
uvicorn app.main:app --host 0.0.0.0 --port 7860

Known Issues & Tips

  • HTTPS UI → HTTP agent: browsers block mixed content. Terminate TLS in front of the agent or rely on server-side fetches (the validator’s /agent-card endpoint does server-side HTTP).
  • 503 on chat in containers: almost always a networking target issue (see “Docker ‘localhost’ gotcha” above). Confirm the agent is reachable from inside the validator container.
  • No Agent Card at base URL: not all agents publish cards at /. The new resolver tries common paths; if that fails, point directly at the JSON Card URL.

If you hit a snag, include logs from the Debug Console in the UI and the backend uvicorn logs in your issue—those two together usually pinpoint the problem fast.

Happy validating 👋

Assets 2
Loading