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"
export QWED_A2A_API_KEYS='{"key-abc123": "procurement-agent", "key-def456": "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	Auth	Description
`/a2a/intercept`	POST	`X-API-Key` header (required)	Primary verification gateway — accepts `AgentMessage`, returns `VerificationVerdict`
`/a2a/health`	GET	None	Service health check with version
`/a2a/metrics`	GET	None	Aggregated intercept metrics
`/.well-known/jwks.json`	GET	None	Public signing key in JWKS format for external attestation verification

Gateway authentication

POST /a2a/intercept requires a per-agent API key in the X-API-Key header. Keys are configured through QWED_A2A_API_KEYS, a JSON object mapping each API key to the agent ID it authenticates:

export QWED_A2A_API_KEYS='{"key-abc123": "procurement-agent", "key-def456": "treasury-agent"}'

curl -X POST http://localhost:8000/a2a/intercept \
  -H "Content-Type: application/json" \
  -H "X-API-Key: key-abc123" \
  -d '{
    "sender_agent_id": "procurement-agent",
    "receiver_agent_id": "treasury-agent",
    "payload_type": "financial_transaction",
    "payload": {"data": {"claimed_total": 100.00, "line_items": [{"amount": 100.00, "quantity": 1}]}}
  }'

The authentication is fail-closed:

A missing or unknown X-API-Key returns 401 Invalid or missing API key.
If QWED_A2A_API_KEYS is unset, malformed, or contains no usable entries, every request returns 401 API authentication is not configured for this service. A deployment without configured keys denies all traffic.
Agent IDs in the map are normalized to the AgentMessage contract (trimmed, max 256 characters, no control characters). Entries that violate it are dropped and their keys denied.

The key’s agent ID is the identity the gateway trusts. Trust-boundary evaluation, rate limiting, telemetry, and the attestation JWT all bind to the authenticated agent. If the body’s sender_agent_id names a different agent, the gateway logs a warning and overrides it with the authenticated identity. Key rotation. The gateway reads QWED_A2A_API_KEYS fresh on every request, so rotating keys takes effect without a restart. Update the environment variable (for example through your secrets manager) and old keys stop matching immediately.

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)
`QWED_A2A_API_KEYS`	JSON object mapping per-agent API keys to agent IDs, e.g. `{"key-abc123": "procurement-agent"}`. Read on every request, so rotation needs no restart. Required for `/a2a/intercept` — with no usable keys the endpoint returns `401` for every request.	(none — deny all)
`QWED_A2A_TRUSTED_ISSUERS`	JSON object mapping peer issuer IDs to `{"deployment_id": ..., "jwks": ...}` for cross-deployment attestation verification. Re-read on every verification, so rotation needs no restart.	(none — only self-issued tokens verify)
`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

Gateway authentication

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

​Gateway authentication

​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

Gateway authentication

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