Coordinate a complete Mappls A2A journey

Define the user and system contract

An application must coordinate exact offline planning or purpose-bound Mappls provider reads through A2A while retaining application-owned identity, intent, privacy purpose, recovery, review, and audit authority. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Start with the maintained application

Download A2A Solution Studio and run its credential-free zero-network fixture. Exercise the complete offline journey first; never accept a free-form prompt, file, URL, provider credential, OAuth token, provider write, or arbitrary skill name in the task model.

const nearbyPlacesTool = {
  name: "mappls_search_nearby",
  description: "Find real places near a validated Mappls Pin or coordinate.",
  inputSchema: {
    type: "object",
    required: ["location", "category"],
    properties: {
      location: { type: "string", description: "Mappls Pin or 'lat,lng'." },
      category: { type: "string" },
      radiusMeters: { type: "integer", minimum: 50, maximum: 10_000 }
    }
  }
};

Choose and pin the profile

Fetch the well-known Agent Card under a bounded response, validate A2A v1 plus JSONRPC or HTTP+JSON, require the exact structured skill, infer offline or live-read from the advertised skills, and retain the canonical card fingerprint. Keep offline as default; require the stronger mappls:a2a:live-read resource scope for protected live reads.

Use the normalized source contract below as the executable boundary. Switch tabs to compare credential-safe languages without changing the operation.

curl --request GET \
  --url 'https://ai.mappls.com/models' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Bind live-read purpose and data class

For one of the ten live commands, require the exact enumerated purpose and bounded operation fields. Record its data class and one-call authority before delegation. Keep Mappls provider credentials only in the A2A service; task payloads and the host never accept them.

Bind transport identity without broadening skill authority

Obtain a short-lived token for the exact A2A resource from an approved client store, inject it only in the Authorization header, and retain only the public scope plus a transport-authenticated boolean. Never persist or log the token, reuse a Mappls provider credential, or let a request tenant override the token-bound tenant.

Delegate with correct identities

Persist the command digest and client-owned message, context, attempt, and idempotency identities before transport. Leave task ID empty for a new A2A task, then bind the server-assigned task identity from the result.

Reconcile an unknown outcome

If the response is lost, keep the aggregate delegated. List the unique context across task states, require exactly one matching task, bind its server identity, and inspect it rather than creating a duplicate delegation.

Validate and review the artifact

Require completed state, matching context/task identity, one bounded structured artifact, the command’s exact zero-call offline or one-read live authority, no task-payload credentials or writes, and no production approval. Hash the canonical artifact and require an attributable reviewer to accept or reject that exact digest.

Operate sensitive durable state

Atomically commit snapshots, immutable events, idempotency receipts, and outbox messages; keep live provider payloads out of audit and outbox events; apply tenant authorization, encryption, minimization, expiry, and deletion before adapting the sample file store; recover reconciliation evidence after restart.

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when fixture and official sdk paths preserve one host lifecycle; all three offline and ten live command contracts are explicit; agent card, profile, skill, protocol, oauth, purpose, and authority validation fail closed; missing-token, insufficient-scope, wrong-audience, and cross-tenant reads are denied; a lost response reconciles without a second task; server-assigned task identity and artifact digest survive restart; no transport token or provider payload appears in audit evidence; human acceptance never becomes entitlement, write authority, or production approval. Capture provider request identity without logging credentials or unnecessary precise location.

Failure modes you must exercise

Definition of done

MCP production checks

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.