FAFA: A Declarative Agent Capability Format
draft-wolfe-faf-agent-01

Independent Submission                                          J. Wolfe
Internet-Draft                                            FAF Foundation
Intended status: Informational                            16 August 2026
Expires: 17 February 2027

              FAFA: A Declarative Agent Capability Format
                        draft-wolfe-faf-agent-01

Abstract

   This document specifies the FAF Agent Format (.fafa): a declarative,
   YAML-based format for an agent's identity, the capabilities it
   exposes, and the endpoints through which it is reached.  A .fafa
   document describes an agent; it never instructs one.

   .fafa (application/vnd.fafa+yaml, IANA-registered June 2026 in the
   vendor tree) is the agent member of the FAF family, alongside .faf
   (project context) and .fafm (agent memory).  It functions as a
   portable passport that answers four questions: who the agent is, what
   it may do, where it is reached, and what it must never do.  Protocol-
   native cards (for example A2A Agent Cards and MCP Server Cards)
   remain useful wire formats; repository instruction files such as
   AGENTS.md remain the ops briefing; .fafa complements them as a house-
   neutral source of truth that can be projected into those formats; it
   does not replace them.

   This document documents the existing IANA vendor-tree registration.
   No standards-tree registration is requested.  A companion white
   paper, "Why Agents Need a Passport," provides the production
   rationale and lifecycle framing.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 17 February 2027.

Wolfe                   Expires 17 February 2027                [Page 1]
Internet-Draft                    FAFA                       August 2026

Copyright Notice

   Copyright (c) 2026 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Problem Statement . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Solution Overview . . . . . . . . . . . . . . . . . . . .   3
     1.3.  Design Goals  . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  The Agent Format (.fafa)  . . . . . . . . . . . . . . . . . .   5
     3.1.  Format Overview . . . . . . . . . . . . . . . . . . . . .   5
     3.2.  Media Type  . . . . . . . . . . . . . . . . . . . . . . .   5
     3.3.  Document Structure  . . . . . . . . . . . . . . . . . . .   5
     3.4.  Agent Section . . . . . . . . . . . . . . . . . . . . . .   7
     3.5.  Capabilities Section  . . . . . . . . . . . . . . . . . .   7
     3.6.  Endpoints Section . . . . . . . . . . . . . . . . . . . .   7
     3.7.  Attachment Section (Optional) . . . . . . . . . . . . . .   8
     3.8.  Provenance Section (Optional) . . . . . . . . . . . . . .   8
     3.9.  Parser Requirements . . . . . . . . . . . . . . . . . . .   8
     3.10. File Conventions  . . . . . . . . . . . . . . . . . . . .   8
     3.11. Versioning  . . . . . . . . . . . . . . . . . . . . . . .   8
   4.  Relationship to Protocol-Native Cards and the FAF Family  . .   9
     4.1.  Projection, Not Replacement . . . . . . . . . . . . . . .   9
     4.2.  A2A Agent Cards . . . . . . . . . . . . . . . . . . . . .   9
     4.3.  MCP Server Cards and Tool Surfaces  . . . . . . . . . . .  10
     4.4.  Repository Instruction Files  . . . . . . . . . . . . . .  10
     4.5.  Relationship within the FAF Family  . . . . . . . . . . .  10
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
     5.1.  Active or Executable Content  . . . . . . . . . . . . . .  11
     5.2.  YAML-Specific Vulnerabilities . . . . . . . . . . . . . .  11
     5.3.  Untrusted Input and Prompt Injection  . . . . . . . . . .  11
     5.4.  Identity, Endpoints, and Least Privilege  . . . . . . . .  11
     5.5.  Prohibited Content  . . . . . . . . . . . . . . . . . . .  11
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  11
     6.1.  Media Type (Documentation Only) . . . . . . . . . . . . .  11
     6.2.  Relationship to the Existing Vendor-Tree Registration . .  12
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  12
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  12
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  12

Wolfe                   Expires 17 February 2027                [Page 2]
Internet-Draft                    FAFA                       August 2026

   Appendix A.  Additional Example . . . . . . . . . . . . . . . . .  13
   Appendix B.  Document History . . . . . . . . . . . . . . . . . .  14
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  15

1.  Introduction

1.1.  Problem Statement

   Agent-interaction work consistently defines an object model for agent
   identity, capability, and endpoint, and then defers the serialization
   to "some JSON" or an unspecified schema.  The object model is
   specified repeatedly; the on-the-wire, in-the-registry, in-the-
   repository _format_ — the document an agent publishes about itself —
   is left unspecified.

   In production that identity is usually inferred from system prompts,
   product settings, and protocol-native cards that do not travel
   cleanly across hosts.  The result is seam rewrites when an agent
   moves between environments, repeated inference cost, and trust
   surfaces that cannot be diffed or reviewed as data.

1.2.  Solution Overview

   .fafa specifies the missing document: a vendor-neutral, YAML-native
   declaration of what an agent is, what it can do, and how it is
   reached.  It functions as a portable passport that answers four
   questions:

   *  who the agent is,

   *  what it may do,

   *  where it is reached, and

   *  what it must never do.

   A .fafa document describes an agent; it never instructs, authorizes,
   or executes one.  It defines the document that protocols and hosts
   carry, reference, or resolve; it does not define discovery,
   transport, authorization, or orchestration.

   .fafa is complementary by design.  It composes with existing and
   future agent-interaction protocols and repository instruction
   conventions and competes with none of them.  Protocol-native cards
   (A2A Agent Cards, MCP Server Cards, and similar) remain useful wire
   formats; files such as AGENTS.md remain the repository ops briefing.
   A .fafa document is the house-neutral source of truth that can be
   projected into those formats (see Section 4).

Wolfe                   Expires 17 February 2027                [Page 3]
Internet-Draft                    FAFA                       August 2026

   A companion paper provides extended motivation, worked examples, and
   further detail on the projection model summarized in Section 4
   [FAFA-PAPER].

1.3.  Design Goals

   1.  *Declarative, never executable* — a .fafa document describes an
       agent; it never instructs, authorizes, or executes one.

   2.  *Vendor-neutral* — no dependency on any single agent-interaction
       protocol.

   3.  *Composable* — sits at the format layer beneath protocols, not in
       competition with them.

   4.  *Forward-compatible* — unknown fields are preserved as
       extensions; documents remain valid across minor revisions.

   5.  *Family-coherent* — extends .faf [FAF-FORMAT]; shares YAML 1.2
       [RFC9512] as base syntax and MIT-licensed distribution.

   6.  *Portable source of truth* — intended to be authored once and
       projected into the protocol- or host-specific cards that
       different environments require.

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   The following terms are used throughout this document:

   *  *Agent* — An autonomous or semi-autonomous software entity that
      exposes capabilities and accepts invocation.

   *  *Capability* — A named, addressable function the agent can
      perform.

   *  *Endpoint* — A reachable address plus protocol binding for
      invoking the agent.

   *  *Attachment* — Optional infrastructure context within which the
      agent operates (gateway, domain, policy scope).

Wolfe                   Expires 17 February 2027                [Page 4]
Internet-Draft                    FAFA                       August 2026

   *  *Provenance* — Optional context substrate the agent reads from,
      most commonly a .faf reference.

   *  *Passport* (informal) — A .fafa document when emphasizing its role
      as a portable, projectable identity declaration.

   *  *Projection* (informal) — The process of deriving a protocol- or
      host-specific card or instruction fragment from a .fafa source
      document.

3.  The Agent Format (.fafa)

3.1.  Format Overview

   A .fafa file MUST be a valid YAML 1.2 document [RFC9512] [YAML].  It
   is declarative: it carries identity, capability declarations, and
   endpoint references, and MUST NOT contain executable content, code,
   or instructions to a model.

3.2.  Media Type

   The agent format is identified by application/vnd.fafa+yaml,
   registered in the IANA vendor tree on 2026-06-26 [IANA-FAFA].  This
   document documents that vendor-tree registration.  No standards-tree
   registration is requested.  The canonical specification is
   [AGENT-FORMAT].  The file extension is .fafa.

3.3.  Document Structure

   A .fafa document is a single YAML mapping.

   *Required top-level fields:* version; agent (with at least name and
   id); capabilities (array, MAY be empty); endpoints (array, MUST be
   non-empty).

   *Optional top-level fields:* attachment, provenance, signature,
   metadata (free-form vendor extensions).

   Primary example:

Wolfe                   Expires 17 February 2027                [Page 5]
Internet-Draft                    FAFA                       August 2026

   version: "1.0"

   agent:                       # REQUIRED -- identity
     name: faf-agent
     id: "did:web:faf.one:agent"
     vendor: WolfeJAM
     version: "1.0.0"
     description: "Cites the spec or refuses out of scope"

   capabilities:                # REQUIRED -- MAY be empty
     - name: validate
       type: tool
       description: "Validate .faf documents against the specification"
       tags: [validation, faf, spec]
       cites_spec: "application/vnd.faf+yaml"

     - name: score
       type: tool
       description: "Compute AI-readiness score for a .faf document"
       tags: [scoring, faf]

     - name: answer
       type: tool
       description: "Answer questions about the FAF family of formats"
       tags: [documentation, faf]
       apophatic: true
       cites_spec: "application/vnd.faf+yaml"

   endpoints:                   # REQUIRED -- MUST be non-empty
     - protocol: mcp
       transport: stdio
       location: faf-agent-mcp

     - protocol: mcp
       transport: http
       location: "https://mcp.faf.one/faf-agent"

   provenance:                  # OPTIONAL -- context substrate
     faf: "https://faf.one/.well-known/faf"
     spec: "application/vnd.faf+yaml"

   Minimal valid example:

Wolfe                   Expires 17 February 2027                [Page 6]
Internet-Draft                    FAFA                       August 2026

   version: "1.0"

   agent:
     name: example-agent
     id: "did:web:example.com:agent"

   capabilities: []

   endpoints:
     - protocol: mcp
       transport: stdio
       location: example-agent

3.4.  Agent Section

   Declares identity.

   *  *Required:* name (string, unique within the issuing vendor
      namespace); id (globally unique identifier — DID, URI, or vendor-
      scoped UUID).

   *  *Optional:* vendor; version (semantic version of the agent, NOT of
      this specification); description; homepage; license (SPDX
      identifier).

3.5.  Capabilities Section

   Each capability is a structured object.

   *  *Required:* name (unique within the document); type (tool,
      resource, prompt, event, or other).

   *  *Optional:* description, input_schema, output_schema, tags,
      apophatic (boolean; if true, the capability refuses out-of-scope
      invocation rather than attempting best effort), cites_spec (the
      format or specification the capability operates against).

   The capabilities array MAY be empty.  Declaration is not
   authorization (see Section 5).

3.6.  Endpoints Section

   Each endpoint declares a protocol binding.

   *  *Required:* protocol (mcp, a2a, grpc, http, or other); transport
      (stdio, http, websocket, quic); location (reachable address — URI,
      package name, or transport-specific locator).

Wolfe                   Expires 17 February 2027                [Page 7]
Internet-Draft                    FAFA                       August 2026

   *  *Optional:* version, auth, region, health.

   Multiple endpoints MAY declare the same protocol with different
   transports.

3.7.  Attachment Section (Optional)

   Describes the infrastructure context within which the agent operates,
   without requiring any particular gateway protocol.  Optional fields:
   gateway, domain, policy, attachment_point.

3.8.  Provenance Section (Optional)

   Cites the context substrate the agent operates from — the FAF-family
   integration point.  A .fafa agent SHOULD declare which .faf it reads.
   Optional fields: faf (reference to a .faf document), fafm (reference
   to a .fafm document), spec (media type of the substrate), version.

3.9.  Parser Requirements

   *  Consumers MUST use YAML safe-load (no custom type construction).

   *  Consumers MUST treat unknown top-level fields, and unknown
      subfields within agent, capabilities, and endpoints, as forward-
      compatible extensions.

   *  Consumers SHOULD use UTF-8 encoding and SHOULD keep documents
      within common registry storage budgets (RECOMMENDED: < 64 KB).

3.10.  File Conventions

   *  *Standard filename:* agent.fafa (alongside project.faf at the
      project layer), or served via the /.well-known/faf discovery
      anchor defined in [FAF-FORMAT].

   *  *File extension:* .fafa. *Encoding:* UTF-8.

   *  Multiple .fafa documents per scope are permitted, distinguished by
      agent.id.

3.11.  Versioning

   The top-level version field declares the version of this
   specification to which the document conforms.  Versioning is
   semantic: 1.x revisions are backward-compatible; a new major version
   is reserved for breaking changes made only with strong cause.
   Consumers MUST accept documents whose version shares their supported
   major version, and MUST apply forward-compatible extension handling

Wolfe                   Expires 17 February 2027                [Page 8]
Internet-Draft                    FAFA                       August 2026

   for unknown fields.  This separates the _agent's_ version
   (agent.version) from the _format's_ version (top-level version), so
   an agent may revise independently of the specification.

4.  Relationship to Protocol-Native Cards and the FAF Family

4.1.  Projection, Not Replacement

   .fafa is not a replacement for protocol-native identity and
   capability documents; it is a source of truth those documents MAY be
   projected from.  Existing wire formats remain useful and unaffected:

     +=================================+=============================+
     | Protocol-native document        | Relationship to .fafa       |
     +=================================+=============================+
     | Agent-to-Agent (A2A) Agent Card | MAY be projected from .fafa |
     +---------------------------------+-----------------------------+
     | Model Context Protocol server-  | MAY be projected from .fafa |
     | card / tool list                |                             |
     +---------------------------------+-----------------------------+
     | Framework-native agent          | MAY be projected from .fafa |
     | configuration                   |                             |
     +---------------------------------+-----------------------------+
     | Repository instruction files    | Orthogonal (ops briefing)   |
     | (AGENTS.md and siblings)        |                             |
     +---------------------------------+-----------------------------+

                                  Table 1

   The preferred pattern is one .fafa passport with many projections,
   rather than multiple hand-maintained, independently drifting cards
   describing the same agent.  A publisher MAY maintain .fafa as the
   authoring source and generate protocol-native documents from it; this
   document does not require or standardize that generation process.

4.2.  A2A Agent Cards

   The Agent-to-Agent (A2A) protocol defines an Agent Card as a JSON
   metadata document, conventionally published at /.well-known/agent-
   card.json.  An A2A Agent Card describes identity, skills, supported
   interfaces, security schemes, and related metadata, and MAY be
   signed.

Wolfe                   Expires 17 February 2027                [Page 9]
Internet-Draft                    FAFA                       August 2026

   A .fafa document can be projected into an A2A Agent Card.  Typical
   mappings include agent.name / agent.id → identity fields,
   capabilities[] → skills, endpoints[] → supportedInterfaces, and
   agent.description → card description.  The .fafa document remains the
   upstream source; the Agent Card is the protocol-specific
   advertisement derived from it.

4.3.  MCP Server Cards and Tool Surfaces

   The Model Context Protocol (MCP) is evolving discovery mechanisms,
   including Server Cards that describe a server's identity, transports,
   and protocol versions prior to connection.  Tool, resource, and
   prompt surfaces remain runtime concerns (for example via tools/list).

   A .fafa document can serve as the upstream source that is projected
   into an MCP Server Card or used to seed the tool surface an MCP host
   advertises; .fafa does not replace MCP Server Cards or the runtime
   tool list.

4.4.  Repository Instruction Files

   Files such as AGENTS.md, CLAUDE.md, GEMINI.md, and .cursorrules
   provide project-level operational guidance.  They are instruction
   surfaces, not structured identity or capability declarations.

   .fafa and these files address orthogonal questions: .fafa answers who
   the agent is and what it may do; AGENTS.md answers how to work in
   this repository.  The two coexist cleanly.

4.5.  Relationship within the FAF Family

   .fafa is the agent member of the FAF family [FAF-FORMAT]:

   .faf   -> Context Layer   (project IS -- static, read once)
   .fafm  -> Memory Layer    (agent REMEMBERS -- mutating)
   .fafa  -> Agent Format    (agent IS -- declarative identity)

   The .fafa schema extends application/vnd.faf+yaml additively.  A
   consumer that understands only .faf parses a .fafa file as valid YAML
   and extracts top-level identity; a .fafa-aware consumer gains the
   full agent declaration.

5.  Security Considerations

   This section addresses the IANA media-type security-considerations
   checklist for application/vnd.fafa+yaml.

Wolfe                   Expires 17 February 2027               [Page 10]
Internet-Draft                    FAFA                       August 2026

5.1.  Active or Executable Content

   None.  A .fafa document is YAML data with no scripts, code, or active
   markup.  Implementations MUST treat .fafa content as data, never as
   instructions or commands. *Declaration is not authorization:* an
   implementation MUST NOT invoke or auto-execute a capability solely
   because it is declared.

   Projection of a .fafa document into a signed protocol card does not
   transfer authorization; the receiving system must still apply its own
   policy and least-privilege controls.

5.2.  YAML-Specific Vulnerabilities

   .fafa is built on YAML 1.2; the YAML security considerations of
   [RFC9512] apply.  Parsers MUST disable custom type construction
   (e.g., !!python/object, !ruby/object), MUST enforce alias-expansion
   limits to mitigate entity-expansion ("billion laughs") attacks, and
   MUST enforce nesting-depth limits to prevent stack overflow.

5.3.  Untrusted Input and Prompt Injection

   .fafa documents originate from agents and third parties and MUST be
   treated as untrusted input.  Consumers MUST NOT elevate .fafa content
   to "system" or "developer" tiers within prompt hierarchies; it
   occupies the user-data tier.  Capability declarations are a
   documented vector for over-trust and prompt injection.

5.4.  Identity, Endpoints, and Least Privilege

   Identity claims, capability declarations, and endpoints are self-
   asserted.  Consumers MUST treat endpoints as untrusted until verified
   (against signature where present), MUST scope capability consumption
   to the declaring agent's _verified_ identity, and MUST apply least
   privilege when acting on declared capabilities.

5.5.  Prohibited Content

   .fafa documents MUST NOT contain secrets, API keys, or credentials;
   MUST NOT contain user-personal data (use .fafm for memory of that
   kind); and MUST NOT contain executable code.

6.  IANA Considerations

6.1.  Media Type (Documentation Only)

   The agent format is already registered in the IANA "Media Types"
   registry, vendor tree:

Wolfe                   Expires 17 February 2027               [Page 11]
Internet-Draft                    FAFA                       August 2026

   *  application/vnd.fafa+yaml — registered 2026-06-26 [IANA-FAFA].
      File extension .fafa.  Published specification: [AGENT-FORMAT].

   This document documents that registration.  No new media-type
   registration is requested.

6.2.  Relationship to the Existing Vendor-Tree Registration

   The vendor-tree registration remains valid.  This document does not
   request promotion to the standards tree.

7.  References

7.1.  Normative References

   [AGENT-FORMAT]
              Wolfe, J., ".fafa — FAF Agent Format Specification,
              Version 1.0", August 2026, <https://github.com/Wolfe-
              Jam/faf/blob/main/AGENT-FORMAT.md>.

   [IANA-FAFA]
              IANA, "Media Type: application/vnd.fafa+yaml", June 2026,
              <https://www.iana.org/assignments/media-types/application/
              vnd.fafa+yaml>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [RFC9512]  Polli, R., Wilde, E., and E. Aro, "YAML Media Type",
              RFC 9512, DOI 10.17487/RFC9512, February 2024,
              <https://www.rfc-editor.org/rfc/rfc9512>.

   [YAML]     Ben-Kiki, O., Evans, C., and I. döt Net, "YAML Ain't
              Markup Language Version 1.2", October 2009,
              <https://yaml.org/spec/1.2/>.

7.2.  Informative References

Wolfe                   Expires 17 February 2027               [Page 12]
Internet-Draft                    FAFA                       August 2026

   [FAF-FORMAT]
              Wolfe, J., "FAF: YAML Media Types for AI Project Context
              and Persistent Memory", Work in Progress, Internet-Draft,
              draft-wolfe-faf-format, 2026,
              <https://datatracker.ietf.org/doc/html/draft-wolfe-faf-
              format>.

   [FAFA-PAPER]
              Wolfe, J., "Why Agents Need a Passport: .fafa — Portable
              Identity for the Agentic Era", Zenodo,
              DOI 10.5281/zenodo.21951641, 15 August 2026,
              <https://doi.org/10.5281/zenodo.21951641>.

Appendix A.  Additional Example

Wolfe                   Expires 17 February 2027               [Page 13]
Internet-Draft                    FAFA                       August 2026

   version: "1.0"

   agent:
     name: docs-helper
     id: "did:web:example.com:docs-helper"
     vendor: ExampleCorp
     version: "2.1.0"
     description: "Searches and cites public documentation"
     homepage: "https://example.com/agents/docs-helper"
     license: "MIT"

   capabilities:
     - name: search_docs
       type: tool
       description: "Search the public documentation index"
       tags: [docs, search]

     - name: cite
       type: tool
       description: "Return a documentation URL for a topic"
       tags: [docs, citation]
       apophatic: true
       cites_spec: "application/vnd.faf+yaml"

   endpoints:
     - protocol: mcp
       transport: stdio
       location: docs-helper-mcp

     - protocol: http
       transport: http
       location: "https://example.com/agents/docs-helper"

   provenance:
     faf: "./project.faf"
     spec: "application/vnd.faf+yaml"

Appendix B.  Document History

   -00  29 June 2026 -- Initial version.

   -01  16 August 2026 -- Clarified positioning as portable passport;
      expanded problem statement with production motivation; added
      relationship to A2A Agent Cards, MCP Server Cards, and AGENTS.md;
      synchronized examples with AGENT-FORMAT.md (including apophatic
      and cites_spec); added companion white paper reference; minor
      security clarification regarding projection.

Wolfe                   Expires 17 February 2027               [Page 14]
Internet-Draft                    FAFA                       August 2026

Author's Address

   James Wolfe
   FAF Foundation
   United States of America
   Email: team@faf.one
   URI:   https://foundation.faf.one

Wolfe                   Expires 17 February 2027               [Page 15]