AdminConsole
Agent2Agent Protocol · v1.0

Let agents collaborate on Mappls—with a hard authority boundary.

The Mappls A2A server turns the canonical solution, capability, and stateful-journey catalogs into discoverable tasks. It is runnable today, uses the official JavaScript SDK, and makes zero provider calls.

Run the local agent Compare MCPRead the A2A specification
ProtocolA2A 1.0
Offline skills3
Opt-in live reads10
Bindings2
Two complementary protocols

MCP equips an agent. A2A connects agents.

Use MCP inside an AI application when a model needs exact tools or catalog resources. Use A2A when one independently operated agent needs to discover another agent, submit a task, and observe its lifecycle.

MCP

An AI application invokes precise Mappls tools and reads resources.

Primitive
Tool call
Transport
Local stdio or authenticated remote HTTP
Open MCP guide
A2A

An independent agent discovers another agent and delegates a bounded task.

Primitive
Task lifecycle
Transport
JSON-RPC or HTTP+JSON
Start A2A
Exact task surface

Three skills. No prompt-shaped ambiguity.

Every request selects a published skill and exact catalog identities. Unknown fields, free-form text, files, URLs, credentials, and unrecognized identities are rejected before execution.

01

Plan a Mappls solution

Compose one source-grounded industry and platform plan from the canonical 208-plan catalog.

plan-mappls-solution16 industry outcomes × 13 platforms
02

Inspect a Mappls capability

Return one exact product-platform availability decision without promoting adjacent evidence into support.

inspect-mappls-capability130 product-platform decisions
03

Simulate a stateful Mappls journey

Execute one deterministic complete or hostile application-owned lifecycle fixture.

simulate-mappls-journey18 journeys × 5 scenarios
Structured commands

Send identity, not prose.

A message contains exactly one application/json data part. The service looks up a deterministic result in the build-time catalog snapshot and returns its source authority with the artifact.

  • 16 KiB maximum request body
  • 128 KiB maximum canonical result
  • 512 KiB bounded tenant/owner-scoped task record
  • SQLite on loopback; PostgreSQL required outside loopback
  • No provider credential or customer payload channel
command.json
{
  "skill": "plan-mappls-solution",
  "input": {
    "useCaseSlug": "last-mile-delivery",
    "platform": "Android"
  }
}
Local quickstart

Discover, delegate, inspect.

  1. Build the immutable snapshot.npm run build --workspace @mappls/a2a-server
  2. Start in loopback-only fixture mode.npm run start --workspace @mappls/a2a-server
  3. Resolve the Agent Card.GET /.well-known/agent-card.json
  4. Send one structured task.JSONRPC /a2a/jsonrpc or HTTP+JSON /a2a/rest

This page documents the deployable service; it does not claim that a production A2A endpoint is already hosted at developer.mappls.com.

agent-client
import { Role } from "@a2a-js/sdk";
import { ClientFactory } from "@a2a-js/sdk/client";

const client = await new ClientFactory().createFromUrl(
  "http://127.0.0.1:3400",
);

const result = await client.sendMessage({
  tenant: "",
  message: {
    messageId: crypto.randomUUID(),
    contextId: "",
    taskId: "",
    role: Role.ROLE_USER,
    parts: [{
      content: { $case: "data", value: {
        skill: "simulate-mappls-journey",
        input: {
          journeySlug: "connected-fleet-trip",
          scenario: "unknown-outcome",
        },
      }},
      mediaType: "application/json",
      filename: "",
      metadata: undefined,
    }],
    metadata: {}, extensions: [], referenceTaskIds: [],
  },
  configuration: {
    acceptedOutputModes: ["application/json", "text/plain"],
    taskPushNotificationConfig: undefined,
    returnImmediately: false,
  },
  metadata: {},
});

console.log(result.status, result.artifacts);
Production identity + state

Token authority becomes database isolation.

OAuth mode validates the signed access token before either protocol binding parses a task. The production store then uses only stable issuer-bound opaque tenant and owner identities in its composite key.

  • Public Agent Card with advertised OAuth metadata and scope
  • Protected-resource metadata at the resource-derived well-known path
  • PostgreSQL is mandatory for every non-loopback deployment
  • Atomic cross-instance upsert and one-snapshot list pagination
  • Process-only liveness and database-backed readiness
  • Versioned migration, bounded pool/timeouts, and verified TLS
  • Request tenant cannot override the verified token tenant
  • Missing tokens return 401; insufficient scope returns 403
a2a-oauth.env
A2A_HOST=0.0.0.0 \
A2A_BASE_URL=https://agents.example.com \
A2A_ALLOWED_HOSTS=agents.example.com \
A2A_AUTH_MODE=oauth-jwt \
A2A_OAUTH_ISSUER=https://identity.example.com/tenant \
A2A_OAUTH_RESOURCE=https://agents.example.com/a2a \
A2A_OAUTH_JWKS_URI=https://identity.example.com/tenant/jwks \
A2A_OAUTH_REQUIRED_SCOPE=mappls:a2a:offline \
A2A_TASK_STORE=postgres \
A2A_TASK_PG_HOST=tasks.internal.example \
A2A_TASK_PG_DATABASE=mappls_agents \
A2A_TASK_PG_USER=a2a_runtime \
A2A_TASK_PG_SSLMODE=verify-full \
npm run start --workspace @mappls/a2a-server
Explicit live authority

Ten provider reads. Still zero writes.

The default Agent Card stays offline. An operator must deliberately select live-read, bind the stronger OAuth scope, inject restricted Mappls credentials into the server process, and validate entitlement. Every command carries one exact purpose; URLs, tokens, keys, extra fields, oversized windows, and unsafe route locations fail before provider execution.

Search live Mappls places

Search · user-place-intent

search-mappls-placesuser-requested-place-discovery

Geocode a live Mappls address

Search · user-address

geocode-mappls-addressuser-requested-place-discovery

Reverse geocode a live coordinate

Search · precise-location

reverse-geocode-mappls-coordinateuser-requested-place-discovery

Find live nearby Mappls places

Search · precise-location

find-mappls-nearbyuser-requested-place-discovery

Plan a live Mappls route

Routes & Navigation · precise-location

plan-mappls-route-liveroute-planning

Calculate a live Mappls matrix

Routes & Navigation · precise-location

calculate-mappls-matrixroute-planning

Read live Mappls asset status

InTouch · sensitive-live-location

read-mappls-asset-statusfleet-operations

Read Mappls asset events

InTouch · sensitive-location-history

read-mappls-asset-eventssafety-investigation

Read Mappls geofence activity

InTouch · sensitive-location-history

read-mappls-geofence-activitysafety-investigation

Read live Mappls trip status

InTouch · sensitive-operational-state

read-mappls-trip-statusfleet-operations
Qualify live entitlementDesign the authority boundary
live-read-command.json
{
  "skill": "find-mappls-nearby",
  "input": {
    "purpose": "user-requested-place-discovery",
    "keywords": "hospital",
    "referenceLocation": "MMI000",
    "region": "IND",
    "radiusMeters": 1000,
    "page": 1,
    "sortBy": "dist:asc"
  }
}
Task semantics

Every journey ends visibly.

The server publishes a submitted task first, then a working update, a structured artifact, and a completed terminal status. Invalid authority or input reaches rejected; cancellation reaches canceled.

1submitted

Task identity and selected offline or live-read authority are established.

2working

The exact catalog skill or single governed provider read executes.

3completed

Data and text artifacts carry the canonical result and bounded authority.

4rejected / failed / canceled

Unsafe input, provider failure, or explicit cancellation terminates without elevated authority.

Maintained full-stack application

Run the journey around the protocol.

A2A Solution Studio exposes all 13 exact commands and owns what an A2A client library cannot: profile/scope discovery, purpose and data-class evidence, OAuth token non-persistence, durable intent, one-read authority, client message and context identity, server task binding, unknown-outcome reconciliation, artifact integrity, provider-payload-free audit, independent review, idempotency, outbox, and restart recovery.

Explore the applicationFollow the 90-minute tutorialDownload ZIP
01discover

Pin exact card, protocol, transport, skill, and authority.

02delegate

Persist intent and client identities before transport.

03reconcile

Recover one server task through its unique context.

04review

Accept or reject the exact artifact digest—never production.

Authority, stated plainly

Planning evidence is not operational authority.

A2A exposes only deterministic public-catalog planning and simulation. It does not call Mappls, accept customer data, persist operational work, grant entitlement, or authorize production.

  1. 01

    Publish an HTTPS base URL and keep both advertised transports functionally equivalent.

  2. 02

    Add gateway rate limits, concurrency limits, request deadlines, abuse telemetry, and an emergency disablement control.

  3. 03

    Deploy the implemented PostgreSQL task store on an approved highly available service and prove backup, restore, failover, migration, least-privilege role, and pool-capacity behavior.

  4. 04

    Register the implemented OAuth JWT resource boundary with the approved authorization server and prove issuer, audience, tenant, client, scope, consent, revocation, and abuse controls; never reuse a Mappls provider credential as an A2A client credential.

  5. 05

    Keep the offline profile as the public default; enable live-read only with restricted server-held Mappls credentials, exact product entitlement, purpose policy, data minimization, rate limits, and sensitive-location audit evidence.

  6. 06

    Sign the Agent Card only through an approved KMS-backed key and publish independently governed JWKS evidence.

  7. 07

    Run official client interoperability and hostile-input conformance in the release environment.

Go deeper

Protocol, implementation, and operating model.

A2A v1 specificationNormative protocol behaviorOfficial JavaScript SDKClient and server adaptersMappls MCP serverTools, resources, and promptsAgent Integration CenterGovernance and release evidenceA2A Solution StudioComplete durable host journeyA2A coordination tutorialDiscovery through recovery and review