A2A Setup Guide

Connect your AI agent to Willform via the Agent-to-Agent (A2A) protocol — JSON-RPC over HTTPS with x402 payment.

What is A2A?

The Agent-to-Agent (A2A) protocol lets AI agents interact with Willform programmatically via JSON-RPC 2.0. Unlike MCP which connects human-operated AI assistants, A2A is designed for autonomous agent-to-agent communication with built-in x402 payment.

Agent Card Discovery

Willform publishes an Agent Card at the standard well-known URL. Your agent can discover capabilities, supported skills, and payment requirements automatically:

https://agent.willform.ai/.well-known/agent.json

Key fields in the Agent Card:

skills — 11 available operations (deploy, namespace, credits, domain, agent management)
securitySchemes — x402 payment with USDC on 6 networks (Ethereum, Base, Arbitrum, Optimism, Polygon, BSC)
identity — ERC-8004 on-chain identity (Base mainnet)

Authentication via x402

A2A uses x402 payment protocol for authentication — no API keys needed. Your agent signs a payment header with its wallet.

How it works:

Send a POST request to /a2a without a PAYMENT-SIGNATURE header
Willform responds with 402 Payment Required and a payment request (minimum 0 USDC)
Your agent signs the payment request with its wallet and resends with the PAYMENT-SIGNATURE header
Willform verifies the signature, identifies the wallet, and processes the request

Zero-amount signatures: For read-only operations, you can sign a 0 USDC payment. This authenticates your wallet without spending anything.

Top-up payments: Include USDC in the payment to add credits to your Willform account. The payment is processed before the operation executes.

Endpoint

All A2A requests go to a single endpoint via POST:

https://agent.willform.ai/a2a

JSON-RPC Methods

Willform A2A supports three JSON-RPC 2.0 methods:

Method	Description
message/send	Execute an operation on the Willform platform. The message content specifies the operation and parameters.
tasks/get	Retrieve the status and result of a previously submitted task by ID.
tasks/cancel	Cancel a running task by ID.

Example: List Namespaces

Here's a minimal JSON-RPC request to list your namespaces:

POST /a2a HTTP/1.1
Host: agent.willform.ai
Content-Type: application/json
PAYMENT-SIGNATURE: <your-x402-signature>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "namespace_list" }]
    }
  }
}

Per-Namespace Agent Endpoint

Each user namespace also exposes a dedicated A2A endpoint for interacting with the Willy agent:

https://agent.willform.ai/a2a/ns/{shortId}

GET — GET — Returns the namespace-specific agent card
POST — POST — Send messages to the Willy agent (agent_chat, agent_invoke)

Per-namespace endpoints use standard SIWE authentication instead of x402.

Available Skills

The main A2A endpoint exposes 11 skills:

Skill	Description
chart_list	List available chart types for deployment
deploy_create	Deploy a container image to a namespace
deploy_preflight	Validate deployment before creating it
namespace_manage	Create, list, update, or delete namespaces
deploy_manage	Stop, restart, delete, scale, update env, view logs and events
deploy_expose	Expose or unexpose deployments with public domains
deploy_metrics	Get resource usage metrics for deployments
credits_manage	Check balance, get deposit info, verify deposits
domain_manage	Add, remove, or verify custom domains
agent_manage	Deploy, suspend, resume, or delete Willy agents
ask_willy	Get platform guidance (free, no token cost)

MCP vs A2A

Choose the right protocol for your use case:

Feature	MCP	A2A
Designed for	Human-operated AI assistants	Autonomous agent-to-agent
Authentication	OAuth 2.0 or API Key	x402 payment signature
Built-in payment	No (pre-fund account)	Yes (pay-per-request)
Protocol	MCP over Streamable HTTP	JSON-RPC 2.0 over HTTPS
Discovery	MCP tool listing	Agent Card (/.well-known/agent.json)