Day 40 Theory — A2A Interoperability and Learning New Frameworks from Docs

Lesson goal

Today you will implement and inspect a small Agent-to-Agent (A2A) v1 interaction for the Service Desk.

By the end of the lesson you should be able to:

• explain when A2A is a better boundary than MCP,
• discover an agent through /.well-known/agent-card.json,
• read the v1 supportedInterfaces structure,
• distinguish core operations from capability flags,
• construct a valid message shape for a selected binding,
• explain task lifecycle and status updates,
• treat Agent Card signatures as optional trust evidence rather than automatic trust,
• identify which parts of the workflow still belong to application security.

What changed in the Service Desk today?

Until now, specialist behavior lived inside our own application/runtime.

Today we introduce a remote specialist boundary:

Service Desk Agent
      |
      | A2A
      v
Remote Security Specialist
      |
      | may use its own tools/runtime internally
      v
Task status + artifacts

The remote specialist does not need to use the same agent framework as the Service Desk. The shared contract is the A2A protocol.

Architecture walkthrough

graph LR
    SD[Service Desk Agent]
    Card[/.well-known/agent-card.json]
    Remote[Remote Security Specialist]
    Task[A2A Task]
    Artifact[Result Artifact]

    SD -->|1. Discover| Card
    Card -->|2. Agent Card| SD
    SD -->|3. Select supported interface| Remote
    SD -->|4. SendMessage| Remote
    Remote -->|5. Task status| Task
    Task -->|6. Completed result| Artifact
    Artifact --> SD

Notice the separation:

1. Discovery tells us what the remote service claims to support.
2. Interface selection chooses a compatible binding/version.
3. Authentication/trust policy decides whether we should communicate with it.
4. Message/task operations perform the actual interaction.

Step 1 — Read the Agent Card

A simplified A2A v1 Agent Card for our specialist can look like:

agent_card = {
    "version": "1.0.0",
    "name": "ServiceDeskSecuritySpecialist",
    "description": "Remote IT security specialist for enterprise certificate incidents",
    "supportedInterfaces": [
        {
            "url": "https://api.servicedesk.internal/a2a/v1",
            "protocolBinding": "JSONRPC",
            "protocolVersion": "1.0",
        }
    ],
    "capabilities": {
        "streaming": True,
        "pushNotifications": False,
        "extensions": [],
        "extendedAgentCard": False,
    },
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/plain", "application/json"],
    "skills": [
        {
            "id": "skill_renew_cert",
            "name": "Renew certificate",
            "description": "Handles approved SSL/SAML certificate-renewal workflows",
            "tags": ["security", "certificates", "saml"],
        }
    ],
}

What each important field means

version : Version of the agent/service description, not a top-level A2A protocol version.

supportedInterfaces : Ordered communication options. Each entry says where the interface lives, which binding it uses, and which A2A protocol version that interface implements.

capabilities : Optional runtime capabilities defined by the protocol. Do not put operation names such as SendMessage or GetTask here.

defaultInputModes / defaultOutputModes : Media types the agent accepts/produces by default.

skills : Descriptive capability metadata. A skill description is not authorization.

Step 2 — Select a compatible interface

A client should choose a supported interface it understands.

def choose_jsonrpc_interface(card: dict) -> dict:
    for interface in card["supportedInterfaces"]:
        if (
            interface["protocolBinding"] == "JSONRPC"
            and interface["protocolVersion"].startswith("1.")
        ):
            return interface
    raise ValueError("No compatible A2A v1 JSON-RPC interface")

This is a useful place for deterministic validation.

The model should not invent an endpoint or protocol binding when the Agent Card already provides the contract.

Step 3 — Treat discovery as untrusted input

Before using the card, validate it and apply trust policy.

Questions include:

• Is the endpoint in an allowed domain/network?
• Does the declared binding/version match what our client supports?
• Does the card require a security scheme we can satisfy?
• Is this remote agent approved for the current tenant/use case?
• If signatures are present, do we require and successfully verify them?

A valid JSON document is not automatically a trusted remote agent.

Optional Agent Card signatures

A card may contain optional JWS-style signatures:

signed_card_fragment = {
    "signatures": [
        {
            "protected": "<base64url protected JWS header>",
            "signature": "<base64url signature>",
        }
    ]
}

Correct handling is conceptually:

signature absent
   -> apply policy for unsigned cards

signature present
   -> canonicalize according to protocol rules
   -> verify with trusted key material
   -> apply trust policy

Do not write:

if card.get("signatures"):
    trusted = True

Presence is not verification.

Step 4 — Construct a message

A2A messages have protocol-defined fields. For a v1 JSON-RPC interaction, a simplified request shape can be:

send_message_payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
        "message": {
            "messageId": "msg_cert_001",
            "role": "ROLE_USER",
            "parts": [
                {"text": "Investigate renewal of the SAML certificate for auth.example.internal"}
            ],
        }
    },
}

Important details:

• messageId identifies the message.
• role uses the protocol-defined role representation.
• a text Part uses member-presence form ({"text": ...}) rather than an invented type: "text" discriminator.
• do not invent root-level fields that are not in the selected binding's request schema.

If continuing work that is already associated with a task, use the task association exactly where the current message schema defines it.

Step 5 — Send through the selected binding

The Agent Card tells us which endpoint/binding to use.

import httpx

async def send_message(endpoint: str, payload: dict) -> dict:
    async with httpx.AsyncClient(timeout=20.0) as client:
        response = await client.post(endpoint, json=payload)
        response.raise_for_status()
        return response.json()

This HTTP call is transport/binding plumbing. Production code also needs:

• authentication required by the remote agent,
• TLS verification,
• retry policy appropriate to operation semantics,
• response schema validation,
• tracing and redaction,
• tenant/user policy checks.

Do not hide those responsibilities behind “A2A handles it.”

Step 6 — Understand task lifecycle

A remote agent may return or create task-oriented work rather than completing everything immediately.

A useful mental model is:

message sent
   |
   v
TASK_STATE_SUBMITTED / working state
   |
   +-- input required
   |
   +-- completed
   |
   +-- failed
   |
   +-- cancelled

Use the actual protocol-defined TASK_STATE_* values supported by the current schema/binding.

Application code should never turn arbitrary strings such as "almost_done" into pretend protocol states.

Step 7 — Expose progress without exposing private reasoning

A remote specialist can send useful operational progress such as:

Certificate inventory loaded
Approval required
CSR generated
Renewal completed

That is enough for UX and monitoring.

Do not expose private chain-of-thought in protocol messages or public progress events.

A2A versus MCP: apply the boundary correctly

Use this decision question:

Am I connecting my host/agent to a capability server, or am I communicating with another independently operated agent service?

For our Service Desk:

MCP
Service Desk -> ticket/search/certificate capability server

A2A
Service Desk Agent -> remote Security Specialist Agent

The remote Security Specialist may itself use MCP internally.

That is completely valid.

Failure walkthrough

Failure 1 — unsupported interface

Agent Card contains only a binding/version our client cannot speak.

Correct behavior:

• do not guess,
• return an explicit interoperability error,
• optionally select another declared compatible interface if one exists.

Failure 2 — signature verification fails

Correct behavior depends on trust policy, but for a card that must be signed:

• reject the card,
• record a security event,
• do not dispatch task data to that endpoint.

Failure 3 — task needs additional input

Do not invent a final answer. Surface the protocol-defined input-required state and obtain the missing user/application input through the correct workflow.

Failure 4 — remote specialist returns sensitive data

The Service Desk still owns output filtering/data policy before showing or persisting the result.

Remote interoperability does not create a trusted-data exemption.

Common mistakes

1. Using an old Agent Card schema that puts protocolVersion or primary url at the top level instead of supportedInterfaces.
2. Treating capabilities as a list of core operation names.
3. Inventing Part fields from older versions/examples.
4. Trusting every discovered endpoint. Discovery is not authorization.
5. Treating signature presence as successful verification.
6. Calling A2A “remote MCP.” They represent different integration boundaries.
7. Streaming hidden model reasoning instead of safe operational status/artifacts.

Practical lab

Work in:

service-desk-day-40/

Task A — inspect the existing implementation

Locate the A2A-related implementation and identify:

• Agent Card representation,
• interface selection,
• request/message construction,
• task state handling,
• trust/security checks.

Write down which pieces are protocol logic and which pieces are Service Desk application policy.

Task B — validate interface selection

Add or inspect tests covering:

1. valid JSON-RPC v1 interface,
2. unsupported binding,
3. incompatible protocol version,
4. multiple interfaces where the first compatible option should be selected.

Task C — validate message shape

Ensure the request uses:

• a valid messageId,
• protocol-defined role,
• member-based text Part,
• task association only where the current schema defines it.

Task D — exercise trust failure

Simulate a card that violates your trust policy—for example an unapproved endpoint or failed required signature verification.

Expected behavior:

No remote task is dispatched.
A structured failure is returned/logged.

Task E — run the automated tests

cd service-desk-day-40
PYTHONPATH=. pytest

Do not stop at “pytest is green.” Be able to explain which protocol invariant each important test protects.

Knowledge check

1. Why did A2A v1 move protocol endpoint information into supportedInterfaces?

It allows an Agent Card to advertise ordered, versioned communication interfaces/bindings instead of assuming one top-level endpoint/transport.

2. Why is SendMessage not a boolean inside capabilities?

Because it is a core protocol operation; AgentCapabilities describes optional supported behavior defined by the protocol.

3. What does a valid Agent Card signature prove?

After correct verification against trusted key material and canonicalization rules, it can provide integrity/authenticity evidence for the card. It does not by itself grant authorization to use the agent.

4. When would MCP and A2A appear together?

A Service Desk agent may communicate with a remote specialist through A2A while either agent uses MCP to access tools/resources internally.

5. Why should task progress avoid chain-of-thought?

Operational status and artifacts are sufficient for users and systems; hidden model reasoning is not required for interoperability and can create privacy/security risks.

Scenario

Your Service Desk discovers an Agent Card for security-specialist.example.com. The JSON is structurally valid and the card advertises certificate-renewal skills, but the endpoint domain is not on the approved enterprise allowlist.

What should happen?

Answer: Do not dispatch the task. Schema validity only proves the data matches the expected structure. Application trust/authorization policy must still approve the remote agent and endpoint.

Key takeaways

1. Be able to explain Why we need another protocol after MCP and point to its implementation/evidence in Day 40.
2. Be able to explain Protocol boundary versus implementation framework and point to its implementation/evidence in Day 40.
3. Be able to explain Agent discovery with the Agent Card and point to its implementation/evidence in Day 40.

Official references

• A2A Protocol Specification: https://a2a-protocol.org/latest/specification/
• A2A v1 changes: https://a2a-protocol.org/latest/whats-new-v1/
• RFC 7515 — JSON Web Signature (JWS): https://datatracker.ietf.org/doc/html/rfc7515
• RFC 8785 — JSON Canonicalization Scheme (JCS): https://datatracker.ietf.org/doc/html/rfc8785