CONCEPTS

A2A Protocol

Fidacy is a first-class citizen of Agent2Agent (A2A) v1.0. Send any assessment with an A2A-Version header and the engine negotiates the protocol, verifies the calling agent’s Agent Card, and returns the verdict the A2A way — inside Task.metadata, with the correct recommended task state. No new fields, no rewrites.

A2A support is an additive overlay. A plain /v1/assess call behaves exactly as before; A2A semantics only engage when you opt in via the header or the a2a block. The verdict core is protocol-blind — the same decision powers AP2 and A2A.

Version negotiation

Declare the protocol version you speak with the A2A-Version header. The engine speaks 1.0 and echoes it back. An unsupported version is rejected before any work is done.

POST /v1/assess
A2A-Version: 1.0
Content-Type: application/json
Authorization: Bearer fky_live_…

→ 400
{ "errors": [
  { "type": "VersionNotSupportedError",
    "message": "A2A version 2.0 not supported (this engine speaks 1.0)." }
]}

The request

Add an a2a block to bind the assessment to a Task’s lifecycle. Every field is optional.

a2a.task_id

The A2A Task this assessment belongs to.

a2a.context_id

The conversation / context the Task runs in.

a2a.agent_card_ref

Reference to the calling agent’s Agent Card (for verification).

a2a.a2a_version

Protocol version, if not sent as a header.

idempotency_key

Echoed back; the mandate content_hash governs idempotency.

{
  "mandate": { "vct": "mandate.payment.1", … },
  "a2a": { "task_id": "task-9", "context_id": "ctx-2" }
}

The verdict, A2A-shaped

With A2A engaged, the response carries an a2a block. The rich outcome is placed under task_metadata — the A2A-correct location — and a recommended Task state is derived from the decision.

→ 200
A2A-Version: 1.0
{
  "decision": "review",
  "riskPayloadJws": "eyJ…",
  "a2a": {
    "a2a_version": "1.0",
    "task_id": "task-9",
    "context_id": "ctx-2",
    "recommended_task_state": "TASK_STATE_AUTH_REQUIRED",
    "task_metadata": { "fidacy_assessment": { /* the full outcome */ } },
    "idempotency_key": null
  }
}

Decision → Task state

approve

TASK_STATE_WORKING — the Task proceeds.

review

TASK_STATE_AUTH_REQUIRED — step up, require stronger auth or human approval.

deny

TASK_STATE_REJECTED — blocked, do not proceed.

The receiving client copies fidacy_assessment into Task.metadata — never into a new top-level field. This keeps you spec-compliant with A2A.

Agent Card verification

POST/v1/agents/verify-card

Verify a calling agent’s A2A Agent Card and its key binding before you trust it. A card whose key is embedded but unverified is treated as self-asserted — no trust boost, no Fidacy assertion (a 202 with agent-issuer-untrusted), preventing a forged card from earning trust.

Pluggable by design

A2A and AP2 differ only at the protocol edge — version negotiation and verdict packaging. Internally they dispatch through a single adapter registry over a protocol-blind core. A new protocol is one adapter and one line — the verdict engine never changes.

← PREVIOUS
How Fidacy Works NEXT →
API Reference