feat(samples): add human-present crypto-algo scenario (AP2 v0.1 + AlgoVoi on-chain USDC extension)

[chopmob-cloud]

Adds a new human-present A2A scenario: `code/samples/python/scenarios/a2a/human-present/crypto-algo/`.

What this adds

A parallel to the existing `cards` and `x402` scenarios — settling on Algorand/VOI using on-chain USDC (aUSDC) with memo-field hash binding to link the settling transaction deterministically to the signed AP2 PaymentMandate.

Why memo-field binding matters here

For on-chain crypto settlement, there is no equivalent to a card network's transaction reference number. This scenario uses the Algorand transaction note field to commit a SHA-256 hash of the canonical CartMandate at payment time:

```
note_field = sha256(canonical_json(CartMandate))
```

The Merchant Payment Processor Agent rejects any PaymentMandate where the on-chain note does not match the stored cart hash — providing a cryptographic consistency gate without requiring round-trips to external services.

This gives:

• Deterministic tx↔mandate correlation — the MPP finds the settling tx via the cart hash
• Tamper evidence — a compromised Shopping Agent cannot substitute a different amount without invalidating the hash
• Chain-native — no separate side-channel needed; the hash travels with the funds

Scope

Minimal and additive — two files under `code/samples/python/scenarios/a2a/human-present/crypto-algo/`:

• `README.md` — full flow documentation
• `run.sh` — launcher (starts Merchant, CP, MPP agents, then Shopping Agent via ADK web)

Uses the shared role agents already in `code/samples/python/src/roles/`. No changes to existing files except adding `ALGOVOI` and `AlgoVoi` to the cspell wordlist.

Prerequisites

```
GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI=true
ALGOVOI_API_KEY # sign up at https://cloud.algovoi.co.uk
ALGORAND_RPC_URL # defaults to public Algorand mainnet if not set
```

Happy to sign the Google CLA if required.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request introduces a bash script to automate the execution of the crypto-algo AP2 example, handling environment setup, virtual environment management via uv, and the orchestration of background agent processes. The review feedback suggests refining the web interface command to target the specific shopping agent directory, removing a redundant installation step that is already covered by uv sync, and improving the robustness of the log-clearing logic by using find instead of shell wildcards.

[gemini-code-assist]

The log message on line 109 indicates that the 'Shopping Agent' is being started. However, $AGENTS_DIR points to the parent directory containing multiple agents (merchant, credentials provider, etc.). To ensure the web interface targets the shopping agent specifically, it is recommended to point adk web directly to the shopping_agent subdirectory.

Suggested change

	$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR
	$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR/shopping_agent

[gemini-code-assist]

The command uv pip install -e . is redundant because uv sync (called on line 71) already handles installing the project and its dependencies in the virtual environment. Removing this line simplifies the script and follows uv best practices.

[gemini-code-assist]

Clearing the log directory using a wildcard * can be problematic if the directory is empty (the wildcard might not expand) or contains a very large number of files. A more robust approach is to use find to delete the contents without relying on shell expansion.

Suggested change

	if [ -d "$LOG_DIR" ]; then
	rm -f "$LOG_DIR"/*
	fi
	if [ -d "$LOG_DIR" ]; then
	find "$LOG_DIR" -mindepth 1 -delete
	fi

[chopmob-cloud]

I have signed the Google CLA. @googlebot please re-check.

[chopmob-cloud]

Thanks for the review @gemini-code-assist. All three suggestions are already applied in the latest commit:

• adk web now points to $AGENTS_DIR/shopping_agent specifically
• uv pip install -e . removed (uv sync handles it)
• Log clearing uses find "$LOG_DIR" -mindepth 1 -delete for robustness

[chopmob-cloud]

Thanks for the review @gemini-code-assist — all three suggestions are already applied in the latest commit:

• adk web now targets $AGENTS_DIR/shopping_agent specifically
• uv pip install -e . removed (covered by uv sync)
• Log clearing uses find "$LOG_DIR" -mindepth 1 -delete

[gemini-code-assist]

Thanks for the update, @chopmob-cloud. The changes look good and address the points raised. I'll take another look at the PR now.

[chopmob-cloud]

Live demo: AP2 over A2A v1.0 REST + MCP

Following up on the adapter — wanted to share a working end-to-end demonstration of the protocol stack this implements:

AI Agent (Claude/Cursor/etc.)
    │  MCP tool call: send_a2a_message(agent_url, text)
    ▼
AlgoVoi MCP Server  ─────────────────────────────────────────
    │  POST https://agent.example.com/message:send
    ▼
A2A v1.0 REST server
    │  HTTP 402  X-AP2-Cart-Mandate: ...
    │            X-AP2-Payment-Required: amount=0.01,network=algorand_mainnet
    ▼
Agent pays on-chain (Algorand / VOI / Hedera / Stellar)
    │  Retry with  Authorization: Payment <tx_id>
    ▼
A2A v1.0 REST server  →  task result returned

AP2 v0.1 (CartMandate / PaymentMandate) is one of three payment challenge protocols the adapter supports over the A2A v1.0 REST transport — alongside MPP (WWW-Authenticate) and x402 (X-Payment-Required).

MCP tools (v1.2.0)

The AlgoVoi MCP Server now ships two A2A client tools that complete this flow from inside any MCP-compatible assistant:

Tool	What it does
fetch_agent_card	GET {agent_url}/.well-known/agent.json — discover capabilities + payment requirements
send_a2a_message	POST {agent_url}/message:send — call payment-gated A2A agent; returns task on 200, challenge_headers on 402 for pay-and-retry

Live smoke test results

═══════════════════════════════════════════════════════════
  MCP A2A Two-Agent Smoke Test
  Agent A: AlgoVoi MCP tools
  Agent B: https://api1.ilovechicken.co.uk
═══════════════════════════════════════════════════════════

Phase 1a — fetch_agent_card
  ✓  tool returned without exception
  ✓  agent_url matches
  ✓  error is None
  ✓  card.name present
  ✓  card.description present
  ✓  card.url present
  ✓  card has skills list
  ✓  card has securitySchemes

Phase 1b — send without payment (expect 401/402)
  ✓  tool returned without exception
  ✓  401 Unauthorized returned (auth required before payment check)

Phase 1c — generate AP2/MPP challenge (4-network)
  ✓  status_code == 402
  ✓  WWW-Authenticate set
  ✓  accepts has 4 networks

PASS  13/13 checks passed

npm: npx -y @algovoi/mcp-server
PyPI: pip install algovoi-mcp
Source + smoke test: https://github.com/chopmob-cloud/AlgoVoi-MCP-Server

[chopmob-cloud]

Update — Base chain support + ecosystem status (2026-04-22)

Since the last update AlgoVoi now supports Base (EVM) as a fifth payment network alongside Algorand, VOI, Hedera, and Stellar. The AP2 scenario in this PR can be extended to cover Base/USDC payment flows in a follow-up if useful.

Current live status:

• Agent card: https://algovoi.co.uk/.well-known/agent.json (lists base_mainnet in skills)
• Running ecosystem discovery across 22 A2A seed domains — AlgoVoi is currently the only live A2A agent card found across all chains
• AP2 + MPP + x402 all live on production with 13/13 smoke tests passing

This PR is MERGEABLE with CLA signed and all gemini-code-assist suggestions addressed. Gentle ping for human maintainer review — no changes needed on our side. 🙏