QWED A2A deployment for zero-trust agent gateways

Deployment architecture

Prerequisites

Before starting the gateway, generate a persistent ECDSA P-256 signing key and expose it as QWED_A2A_SIGNING_KEY_PEM. Attestation JWTs are signed with this key; without it the gateway fails closed (HTTP 503) on every request.

openssl ecparam -name prime256v1 -genkey -noout \
  | openssl pkcs8 -topk8 -nocrypt \
  > qwed_a2a_signing_key.pem

export QWED_A2A_SIGNING_KEY_PEM="$(cat qwed_a2a_signing_key.pem)"
export QWED_A2A_DEPLOYMENT_ID="prod-us-east-1"
export QWED_A2A_TRUSTED_AGENTS="procurement-agent,treasury-agent"

Every replica in the same logical deployment must load the same PEM. Different keys across replicas would produce different kids, and attestations issued by one instance would fail verification on another. Store the PEM in your secrets manager and inject it at runtime.

FastAPI application

Create your production entrypoint:

# main.py
from fastapi import FastAPI
from qwed_a2a.protocol.endpoints import router, wellknown_router

app = FastAPI(
    title="QWED A2A Gateway",
    description="Zero-trust verification interceptor for A2A communication",
    version="0.1.0",
)

app.include_router(router)
app.include_router(wellknown_router)  # Exposes /.well-known/jwks.json

@app.on_event("startup")
async def startup():
    """Initialize interceptor on startup."""
    from qwed_a2a.protocol.endpoints import configure_interceptor
    from qwed_a2a.protocol.schema import InterceptorConfig

    config = InterceptorConfig(
        enable_financial_verification=True,
        enable_code_verification=True,
        enable_logic_verification=True,
        block_on_error=True,
    )
    configure_interceptor(config)

Docker

# Dockerfile
FROM python:3.12-slim

WORKDIR /app

COPY pyproject.toml .
COPY src/ src/

RUN pip install --no-cache-dir .
RUN pip install --no-cache-dir uvicorn

COPY main.py .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t qwed-a2a-gateway .
docker run -p 8000:8000 qwed-a2a-gateway

# docker-compose.yml
services:
  qwed-a2a:
    build: .
    ports:
      - "8000:8000"
    environment:
      - SENTRY_DSN=${SENTRY_DSN}
      - QWED_LOG_LEVEL=INFO
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/.well-known/jwks.json"]
      interval: 30s
      timeout: 5s
      retries: 3

Available endpoints

Endpoint	Method	Description
`/a2a/intercept`	POST	Primary verification gateway — accepts `AgentMessage`, returns `VerificationVerdict`
`/a2a/health`	GET	Service health check with version
`/a2a/metrics`	GET	Aggregated intercept metrics
`/.well-known/jwks.json`	GET	Public signing key in JWKS format for external attestation verification

Health check response

{
  "status": "healthy",
  "service": "qwed-a2a",
  "version": "0.1.0"
}

Metrics response

{
  "total_intercepts": 15420,
  "forwarded": 15200,
  "blocked": 180,
  "errors": 40,
  "avg_latency_ms": 12.5,
  "engines": {
    "finance_guard": 5000,
    "code_guard": 3200,
    "logic_guard": 1800,
    "passthrough": 5420
  }
}

JWKS endpoint

GET /.well-known/jwks.json returns the current signing public key so downstream services can verify attestation JWTs without an out-of-band key exchange.

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "…base64url…",
      "y": "…base64url…",
      "kid": "did:qwed:a2a:local#key-<sha256-fingerprint>",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}

The kid is derived from a SHA-256 fingerprint of the public key, so it remains stable across restarts as long as QWED_A2A_SIGNING_KEY_PEM is unchanged. When the PEM is missing or invalid, the endpoint responds with HTTP 503 Signing key unavailable — use this as a readiness signal for orchestrators and load balancers. See Crypto attestations for the full JWT structure and verification flow.

Environment variables

Variable	Description	Default
`QWED_A2A_SIGNING_KEY_PEM`	Unencrypted PKCS#8 EC P-256 private key used to sign attestation JWTs. Required — the service fails closed if unset.	(none)
`QWED_A2A_DEPLOYMENT_ID`	Stable identifier shared by all replicas in the same logical deployment. Required — import fails without it.	(none)
`QWED_A2A_TRUSTED_AGENTS`	Trust allowlist. Comma-separated agent IDs (unrestricted) or a JSON array of scoped trust entries with `allowed_receivers`, `allowed_payload_types`, and `valid_until`.	(none — deny all)
`SENTRY_DSN`	Sentry error tracking DSN	(disabled)
`QWED_LOG_LEVEL`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`
`QWED_A2A_BLOCK_ON_ERROR`	Block on internal errors (`true`/`false`)	`true`

Monitoring

Sentry integration

QWED A2A includes built-in Sentry integration for error tracking:

import sentry_sdk

sentry_sdk.init(
    dsn="https://your-dsn@sentry.io/project",
    traces_sample_rate=0.1,
    environment="production",
)

Structured logging

All intercepts are logged with structured fields:

INFO  A2A Intercept [a2a_trace_001] FORWARDED -> engine=finance_guard (12.3ms)
INFO  A2A Intercept [a2a_trace_002] BLOCKED -> engine=code_guard (3.1ms)
WARN  Trust boundary violation: Sender 'rogue-agent' is globally blocked

CI/CD integration

GitHub Actions

# .github/workflows/a2a-tests.yml
name: A2A Verification Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -e ".[dev]"
      - run: pytest tests/ -v --tb=short

Mergify auto-merge

# .mergify.yml
pull_request_rules:
  - name: Auto-merge when CI passes
    conditions:
      - check-success=test
      - check-success=CodeQL
    actions:
      merge:
        method: squash

Integration with QWED ecosystem

QWED Core

A2A uses the same verification principles as the core QWED engine — deterministic, symbolic, and provable.

QWED MCP

MCP provides tool-level verification. A2A provides agent-to-agent communication verification. They complement each other.

QWED Finance

The A2A finance guard uses the same Decimal arithmetic patterns as QWED Finance, adapted for inter-agent payloads.

Agent Specification

The QWED-Agent spec defines trust levels and budget enforcement. A2A implements the verification gateway described in the spec.

Overview

Core Components

Guides

QWED A2A deployment for zero-trust agent gateways

Deployment architecture

Prerequisites

FastAPI application

Docker

Available endpoints

Health check response

Metrics response

JWKS endpoint

Environment variables

Monitoring

Sentry integration

Structured logging

CI/CD integration

GitHub Actions

Mergify auto-merge

Integration with QWED ecosystem

QWED Core

QWED MCP

QWED Finance

Agent Specification

​Deployment architecture

​Prerequisites

​FastAPI application

​Docker

​Available endpoints

​Health check response

​Metrics response

​JWKS endpoint

​Environment variables

​Monitoring

​Sentry integration

​Structured logging

​CI/CD integration

​GitHub Actions

​Mergify auto-merge

​Integration with QWED ecosystem

QWED Core

QWED MCP

QWED Finance

Agent Specification

Deployment architecture

Prerequisites

FastAPI application

Docker

Available endpoints

Health check response

Metrics response

JWKS endpoint

Environment variables

Monitoring

Sentry integration

Structured logging

CI/CD integration

GitHub Actions

Mergify auto-merge

Integration with QWED ecosystem