A2A Learnables Extension, Version 1

Extension URI: https://rsaxb.com/a2a/learnables/v1

Status: Draft. Published 2026-08-17.

Editors: RSA Cross Border.

Independent extension. Not published by, endorsed by, or affiliated with the A2A project. It is published under a URI its authors control, which the A2A extension governance permits without registration. The a2aproject URI prefixes are reserved for artifacts that have been through that project's process; this one has not.

Feedback: the reference implementation and the issue tracker are maintained by RSA Cross Border. Comments are welcome.

Paragraphs marked Rationale are non-normative and may be skipped.

1. Abstract

A2A lets an agent say what it can do, and lets it stop and ask a human. It does not let an agent say what it can be taught, and it does not say what becomes of the human's answer once the task that prompted it ends. Today that answer is spent once: a person identifies a sender, the task completes, and the next message from that sender asks the same question.

This extension defines:

1. how an agent declares its learnable surface on its Agent Card — what it recognises, how it decides today, and what shape an answer must take;
2. how an agent attaches a teachable proposal to a question, so a client can offer "remember this" without knowing the agent's internals;
3. the semantics of absorbing a lesson — refusal, idempotence, versioning, and the rule that a lesson never mutates a definition a running task is pinned to;
4. a show-back operation, so a person sees what the agent now makes of the same input instead of the word "saved".

It does not define who stores the agent's knowledge, or over what transport a lesson is written. In many deployments that party is not the agent.

2. Status of this document

This is a Draft. Field names and semantics MAY change.

A stable release of this URI is announced by setting status to stable in the extension descriptor (Appendix A). Breaking changes are published under a new URI, never by amending this one (§15).

3. Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

Three roles carry requirements:

• a conformant agent publishes a declaration under this extension's URI;
• a conformant client reads that declaration and renders questions from it;
• a conformant authority absorbs lessons into the agent's knowledge.

One implementation MAY fill more than one role.

4. Motivation

A2A specifies the moment an agent cannot decide: the task moves to input-required, a human answers, the task resumes. It does not specify the moment after. The answer was evidence about the world, and there is nowhere to put it. Implementations resolve that in one of three ways:

1. Discard it. The same question is asked again tomorrow.
2. Write it into a prompt or config, then redeploy. The knowledge reaches production days after the person who held it answered.
3. Let the agent self-modify. Fast and unauditable: nobody can say what the agent knew when it decided, and nothing can be undone.

This extension describes a fourth: the agent publishes what it can be taught, the client holding the human decides what is written, and the write produces a new immutable version carrying an author and a reason.

The agent proposes, the client decides, the authority records.

5. Terminology

Learnable — something in an agent's knowledge that a human's answer may extend. It owns its own vocabulary and its own idea of a valid answer.

Collection — the named set a learnable belongs to, e.g. customers.

Entry — one member of a collection, e.g. northgate. A lesson is written into an entry.

Lesson — one human-supplied value addressed to one entry, with an author.

Lesson field — one input a client must collect to build a usable lesson value. The agent describes these; the client renders them.

Definition — the versioned, addressable unit of agent knowledge a client resolves before starting a task. Its internal structure is out of scope.

Authority — the party holding definitions and writing lessons into them. MAY be the agent; in the reference deployment it is a separate control plane.

Show-back — read-only re-evaluation of an input under the current definition.

6. Extension declaration

6.1 The AgentExtension entry

A conformant agent MUST declare the extension in capabilities.extensions with uri set to this document's extension URI, and required set to false.

Rationale. Nothing here changes the meaning of a core A2A request, so refusing clients that do not understand it would refuse them for no reason.

The declaration is carried in params:

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://rsaxb.com/a2a/learnables/v1",
        "description": "Publishes what this agent can be taught: which customer a message belongs to, and what kind of message it is.",
        "required": false,
        "params": {
          "learnables": [
            {
              "collection": "customers",
              "entry": "customer",
              "skills": ["triage_inbound", "recheck_message"],
              "teaches": "which customer a message belongs to",
              "how": "Each customer carries marks - text that gives them away. Every mark that matches scores; the highest score wins if it clears the identification margin. Nothing matches, nothing is claimed.",
              "decidedBy": "rules",
              "lessonFields": [
                {
                  "name": "pattern",
                  "label": "Text that gives it away",
                  "kind": "text",
                  "help": "An address, a reference, a phrase. Matched without regard to case; regular expressions work if you want one."
                },
                {
                  "name": "where",
                  "label": "Where to look for it",
                  "kind": "choice",
                  "choices": ["from", "subject", "body", "attachments", "any"],
                  "default": "from",
                  "help": "Narrower is safer. 'any' matches the whole message."
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

params.learnables MUST be an array of Learnable Descriptors (§6.2). It MAY be empty, which asserts that the agent understands the extension and currently has nothing to teach.

6.2 The Learnable Descriptor object

Rationale. how is required because somebody is about to change how software decides something that matters, and is entitled to know what it does now, from the thing doing it. decidedBy is required because it changes what a client may honestly promise: under "rules" a taught mark takes effect deterministically, under "model" it is one example among many and the effect is statistical.

6.3 The LessonField object

A client that encounters an unrecognised kind MUST render the field as "text". It MUST NOT drop the field and MUST NOT fail.

Rationale. This is the load-bearing rule of the extension. A client rendering blind from lessonFields needs no change when an agent that reads spreadsheets asks to be taught a column instead of a pattern; a client that hard-codes one agent's fields must be edited and released. A dropped field, meanwhile, produces a lesson the agent will refuse at the moment somebody is trying to fix something.

7. Activation

The declaration in §6 is data-only. A client MAY read it without activating anything, and an agent MUST publish it whether or not any client activates.

The teach block (§8) and show-back (§11) are profile behaviour. A client MUST request them by including the extension URI in the A2A-Extensions request header, and a conformant agent MUST echo activated URIs in the response header.

A2A-Extensions: https://rsaxb.com/a2a/learnables/v1

An agent MUST NOT emit a teach block to a client that has not activated the extension.

Activation is not authorization; see §13.2.

8. The teach block

When an agent moves a task to input-required because it could not decide something a learnable covers, it MAY attach a teach block to the question, carried in the Message's metadata and keyed by this extension's URI:

{
  "role": "agent",
  "parts": [{ "text": "I can't tell whose shipment this is. Who should it go to?" }],
  "metadata": {
    "https://rsaxb.com/a2a/learnables/v1": {
      "teach": {
        "collection": "customers",
        "entries": ["northgate", "alhamra", "gulftrade"],
        "suggested": { "pattern": "billing@origin.example", "where": "from" },
        "suggestionLabel": "the address this message came from",
        "lessonFields": [ "...as declared on the card..." ]
      }
    }
  }
}

Keys of suggested MUST be a subset of the applicable lessonFields names.

A suggested value MUST NOT be wider in scope than the evidence it was drawn from.

Emitting a teach block MUST NOT change how the agent handles the answer to the underlying question. A client MAY ignore the block entirely, and the task MUST proceed identically.

Rationale. A suggestion is displayed for confirmation, and most people confirm, which makes its scope a correctness property rather than a convenience. The reference implementation shipped a defect here: a reference extractor matched PA-2026-0901 as PA-2026, so confirming what looked like one shipment's reference would have taught the directory to claim every reference issued that year.

9. The Lesson object

{
  "collection": "customers",
  "entry": "northgate",
  "value": { "pattern": "billing@origin\\.example", "where": "from" },
  "taughtBy": "dana@warehouse.example",
  "reason": "Northgate's billing desk sends the pre-alerts"
}

Every party between the client and the learnable MUST treat value as opaque. No transport, authority, or storage layer may read a named key out of it.

Rationale. The moment one of them reads value.pattern, adding a learnable that is not about text — a column mapping, a threshold, a unit of measure — requires a coordinated release of every component in the chain. The reference implementation enforces this by construction: its control plane contains no field named pattern, and its regression suite drives a ColumnMapping learnable, whose value has no pattern key, through the identical code path.

10. Absorption semantics

These requirements constrain the effect of a write, not its implementation.

10.1 The learnable judges the value

The authority MUST delegate validation to the learnable being taught and MUST NOT apply its own idea of a valid value. A refusal MUST carry a human-readable reason authored by the learnable:

"billing@origin\\.example(" is not a usable pattern: missing ), unterminated subpattern at position 24

and not 400 Bad Request: invalid value. The learnable compiled the value; it is the only party that knows why the value failed.

10.2 Idempotence

Absorption MUST be idempotent. A lesson duplicating knowledge the entry already holds MUST report learned: false, MUST NOT produce a new version, and MUST NOT be treated as an error.

Rationale. Two people answering the same way is the normal case, not a fault.

10.3 Versioning and pinning

A lesson that changes anything MUST produce a new immutable version of the definition, and MUST NOT modify one in place. Therefore:

• a task running against version n MUST run against version n to completion, even if n+1 is activated mid-flight;
• the new version MUST appear in an activation history carrying taughtBy and reason;
• the change MUST be undoable by the same mechanism that undoes any other activation.

Rationale. Without pinning, "the agent learns" and "the agent changes unpredictably under a running task" describe the same behaviour.

10.4 The result

{
  "learned": true,
  "describes": "matches 'billing@origin\\.example' in the from",
  "definitionVersion": 12,
  "versionId": "sha256:9f2c...",
  "previousVersionId": "sha256:41ab..."
}

describes MUST be produced by the learnable, not composed by the authority from field names.

Rationale. The authority does not know that where: "from" means "on the from-line", so it can only emit something like customers.northgate.pattern set — which nobody can audit six months later.

11. Show-back

A conformant agent SHOULD expose a read-only operation that re-evaluates a previously seen input under the currently active definition.

It MUST NOT ask a question, MUST NOT propose an action, and MUST NOT be pinned to an earlier version.

The report MUST distinguish settled from unsettled, and when unsettled SHOULD say what it saw:

{
  "customer": {
    "settled": true,
    "winner": "northgate",
    "reads": "Reads as Northgate Motors Ltd, on billing@origin.example",
    "candidates": [
      { "name": "northgate", "label": "Northgate Motors Ltd", "score": 0.333,
        "matched": ["billing@origin\\.example"] },
      { "name": "alhamra", "label": "Al Hamra Trading", "score": 0.0, "matched": [] }
    ]
  }
}

An implementation MUST NOT report the outcome of a lesson using only the success of the write.

Rationale. The case this exists for is the other one:

{ "customer": { "settled": false, "reads": "Still cannot tell whose this is." } }

A rule that is saved, valid, and does not do what its author meant. learned: true is true and useless; the unsettled reading is what lets them fix it in the next minute rather than the next shipment.

12. Writing a lesson: transport

The transport for writing a lesson is out of scope. The agent recognises, the client holds the human, and a third party may hold the definitions; specifying "POST the lesson to the agent" would exclude that topology. Two profiles are recognised.

12.1 External authority (RECOMMENDED)

The agent declares learnables and proposes teach blocks. The client sends the lesson to an authority it already talks to. The agent learns of the change by resolving the active definition on its next task.

An agent in this profile MUST NOT treat a lesson as accepted merely because it proposed it, and MUST NOT hold local state that a client's decision not to teach would leave stale.

12.2 Self-owning agent (OPTIONAL)

An agent that owns its definitions MAY expose a method extension, declaring teachMethod in params:

{
  "uri": "https://rsaxb.com/a2a/learnables/v1",
  "params": {
    "teachMethod": "rsaxb.learnables.Teach",
    "learnables": ["..."]
  }
}

The method takes a Lesson (§9) and returns a result (§10.4). A client MUST NOT call it without having activated the extension. An agent exposing it MUST still satisfy every requirement in §10, including versioning and reversibility.

13. Security considerations

A lesson is a durable, tenant-wide change to automated decision-making, submitted through a text box by somebody doing another job.

13.1 Over-broad values

The dominant risk is not a malicious lesson but a well-meant one that matches far more than its author believed: a mark on invoice, or a pattern one character from matching every reference in a year.

Implementations SHOULD evaluate a proposed lesson against a corpus before accepting it and SHOULD report the match count to the person. Implementations MUST NOT present a suggestion whose scope exceeds the evidence it was drawn from (§8).

13.2 Authorization

The A2A-Extensions header is a negotiation mechanism and carries no authority. An authority MUST authorize the writer independently and MUST scope every lesson to exactly one tenant.

Rationale. An unscoped lesson is a cross-tenant leak with extra steps: a mark taught by customer A, applied to customer B's traffic, silently routes B's shipments into A's name.

13.3 Untrusted pattern compilation

Where a learnable compiles a supplied value into an executable matcher — a regular expression, a query, a template — the implementation:

• MUST validate at absorption time and refuse with a reason, rather than at match time inside a running task;
• SHOULD bound evaluation time or use a non-backtracking engine. A regular expression accepted from a text box is a denial-of-service vector against every future message.

13.4 Attribution and reversal

Every lesson MUST be attributable to an identified human and MUST be reversible. Which rules were in force when this decision was made, and who put them there MUST be answerable from stored state, without reconstructing deploy history.

14. Privacy considerations

Lesson values routinely contain personal data: the most useful mark for identifying a customer is often an individual's work address.

Implementations:

• MUST treat a lesson value as carrying the same data classification as the content it was drawn from;
• SHOULD record taughtBy as a stable internal identifier rather than embedding personal data in an audit trail with a different retention period;
• MUST be able to deactivate and tombstone every version containing a personal identifier, where that identifier cannot be removed from a historic version.

Rationale. Content-addressed immutable versions are excellent for auditability and hostile to erasure. This document does not resolve that tension; it requires that an implementation resolve it deliberately.

15. Versioning

The extension URI is the version. Any change that would break a client reading params — a removed field, a narrowed type, a changed meaning — MUST be published under a new URI ending in a higher version segment.

The following are not breaking and MUST NOT change the URI:

• new optional fields on any object defined here;
• new kind values, since §6.3 requires unknown kinds to degrade to "text";
• new decidedBy values.

An agent MAY declare several versions simultaneously during a migration. A client SHOULD use the highest version it understands.

16. Relationship to core A2A

Nothing here changes the meaning of a core A2A message. A client ignoring this extension sees one extra entry in capabilities.extensions and one extra key in a question's metadata, both ignorable by construction — which is why required is fixed at false.

Three parts of core A2A are load-bearing and are used as specified, not redefined:

• capabilities.extensions — the declaration lives in params;
• input-required — the state in which a teach block is emitted;
• metadata — the augmentation channel, keyed by URI.

Appendix A. JSON Schema

The machine-readable descriptor and JSON Schema for the objects above are served at https://rsaxb.com/a2a/learnables/v1/extension.json, whose $defs define LearnableDescriptor, LessonField, TeachBlock, Lesson, and LessonResult.

Appendix B. Worked example

A pre-alert application, an email agent, and a control plane: three processes, no redeploy between the first step and the last.

1. The application fetches the agent's card and reads one learnable: collection customers, two lesson fields.

2. A message arrives from billing@origin.example. No mark matches. The task moves to input-required, and the question carries a teach block with suggested: { "pattern": "billing@origin.example", "where": "from" }.

3. The application renders the fields blind: a text box labelled "Text that gives it away", prefilled, and a select labelled "Where to look for it", defaulted to "from". Neither string appears in the application's source.

4. Dana answers and leaves the teach box ticked. The application posts a Lesson to the control plane. The agent is not involved.

5. The control plane hands the value to the learnable, which validates it, absorbs it, and phrases the audit line. A new version is published:

   v12  taught by dana@warehouse.example
        "northgate learned: matches 'billing@origin\.example' in the from"
        reason: Northgate's billing desk sends the pre-alerts
   

6. The application calls show-back and displays Reads as Northgate Motors Ltd, on billing@origin.example — the effect, not the word "Saved".

7. The next message from that address is never asked about. The task that asked the original question was pinned to v11 and finished on v11. Nothing was restarted; nothing was redeployed.

Appendix C. Changelog

References

• A2A Protocol Specification
• A2A Extensions
• A2A Extension & Binding Governance
• RFC 2119 / RFC 8174 — requirement keywords