A minimal sandbox API for testing agent interoperability.

CONCEPTUAL FLOW

1. CREATE DEAL -- POST /api/playground/external/deals
2. RECEIVE ACCEPTANCE SPEC -- GET /api/playground/external/deals/{deal_id}
3. ACKNOWLEDGE AGREEMENT -- POST /api/playground/external/deals/{deal_id}/ack
4. EXECUTE TASK -- (off-sandbox: your own agent process does the actual work)
5. SUBMIT DELIVERY -- POST /api/playground/external/deals/{deal_id}/delivery
6. RECEIVE VERIFICATION RESULT -- GET /api/playground/external/deals/{deal_id}/verification

1. CREATE DEAL

POST /api/playground/external/deals
{
  "criteria": {
    "requiredItemCount": 3,
    "sourcesRequired": true,
    "minSourceCount": 2,
    "outputLanguage": "en"
  }
}

-> { "dealId": "...", "state": "AWAITING_ACCEPTANCE", "acceptanceSpec": { "criteria": {...}, "acceptanceSpecHash": "..." } }

Criteria are explicit, visitor/agent-chosen fields -- never guessed from free text. No LLM is involved in defining the deal.

2. READ THE DEAL

GET /api/playground/external/deals/{deal_id}
-> { "dealId": "...", "state": "...", "acceptanceSpec": {...} }

3. ACKNOWLEDGE (AcceptanceAck -- application-layer extension)

POST /api/playground/external/deals/{deal_id}/ack
{ "party": "provider", "accepted": true }

-> { "ok": true, "ack": {...signed ack...}, "dealState": "ACCEPTED" }

AcceptanceAck is an experimental application-layer extension and is explicitly NOT part of the frozen ADP v0.1.1 core specification. A delivery submitted without a valid provider ack is rejected (see Mode E below).

4. SUBMIT DELIVERY

POST /api/playground/external/deals/{deal_id}/delivery
{
  "acceptanceSpecHash": "...",   // must exactly match the deal's signed spec hash
  "items": ["item 1", "item 2", "item 3"],
  "sources": [{"name": "my-source", "url": "https://example.com/a"}, ...]
}

-> { "dealId": "...", "state": "DELIVERED", "deliveryHash": "..." }

Delivery content is treated as untrusted input: length-capped, type-checked, HTML-escaped before storage/rendering. A mismatched acceptanceSpecHash is rejected as TAMPER_DETECTED / INVALID_DEAL, not silently accepted.

5. GET VERIFICATION RESULT

GET /api/playground/external/deals/{deal_id}/verification
-> { "finalResult": "PASS"|"FAIL", "checks": [...], "settlementStatus": "ELIGIBLE"|"NOT ELIGIBLE" }

RUNNABLE EXAMPLE

A small, genuinely separate example agent process (plain Python, stdlib only, no ADP internal imports -- talks only to this HTTP API) lives at C:\mep\integration\external-agent-example\agent.py in this local development environment, demonstrating all of the above plus five deliberate failure modes (correct delivery; missing item; wrong source count; modified deal identifier; delivery without acknowledgement).