Fidacy
Open console

Concepts

A2A Protocol

Fidacy is a first-class citizen of Agent2Agent (A2A) v1.0. Send any assessment with an A2A-Versionheader 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 on the response. 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_…

An unsupported version returns a structured A2A error:

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

The request

Add an a2ablock to bind the assessment to a Task's lifecycle. Every field is optional.

FieldMeaning
a2a.task_idThe A2A Task this assessment belongs to.
a2a.context_idThe conversation / context the Task runs in.
a2a.agent_card_refReference to the calling agent's Agent Card (for verification).
a2a.a2a_versionProtocol version, if not sent as a header.
idempotency_keyEchoed 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 assessment 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

Fidacy maps the verdict to the official A2A task states, it never invents a state.

DecisionRecommended task stateMeaning
approveTASK_STATE_WORKINGThe Task proceeds.
reviewTASK_STATE_AUTH_REQUIREDStep up, require stronger auth or human approval.
denyTASK_STATE_REJECTEDBlocked, 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, it gets no trust boost and no Fidacy assertion (a 202 with agent-issuer-untrusted), preventing a forged card from earning trust.

Trust-Verdict Extension

Carrying a verdict over A2A is a formal, declarable Fidacy Trust-Verdict Extension. An agent advertises it in its Agent Card (capabilities.extensions[]) and clients opt in. The verdict still rides in Task.metadata (or AP2 risk_data), the extension names it and pins where to find and verify the signed JWS. Mirrors how the x402 and AP2 extensions are declared.

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 (MCP, a future card-network agent standard, or an A2A v2) is one adapter and one line, the verdict engine never changes.

Next →API Reference