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, . [IANA-FAFA] IANA, "Media Type: application/vnd.fafa+yaml", June 2026, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9512] Polli, R., Wilde, E., and E. Aro, "YAML Media Type", RFC 9512, DOI 10.17487/RFC9512, February 2024, . [YAML] Ben-Kiki, O., Evans, C., and I. döt Net, "YAML Ain't Markup Language Version 1.2", October 2009, . 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, . [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, . 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]