.fafa — FAF Agent Format Specification#
Version: 1.0.1
Status: Stable
MIME Type: application/vnd.fafa+yaml
File Extension: .fafa
IANA Registration: Registered 2026-06-26 (vendor tree)
DOI: 10.5281/zenodo.21951641
Last Updated: 2026-11-17
1. Purpose#
.fafa is the Agent Card format of the FAF family. It is a structured, vendor-neutral declaration of what an agent is: its identity, the capabilities it exposes, and the endpoints through which it is reached.
It is the agent-specific sibling of the IANA-registered .faf format (application/vnd.faf+yaml) and the IANA-registered .fafm format (application/vnd.fafm+yaml).
A .fafa document describes an agent; it never instructs one.
2. Scope#
.fafa defines the document that describes an agent. It does not define discovery, transport, authorization, or orchestration.
3. Core Concepts#
| Term | Definition |
|---|---|
| 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) The infrastructure context within which the agent operates — gateway, domain, policy scope |
| Provenance | (Optional) The context substrate the agent reads from — most commonly a .faf reference |
4. File Structure#
A .fafa file is a single YAML document:
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).
5. Agent Section#
Declares identity.
Required: name (Unicode string, unique within the issuing vendor namespace), id (globally unique identifier — DID, URI, or vendor-scoped UUID).
Optional: displayName (human-readable name, distinct from the machine name and id), vendor, version (semantic version of the agent, NOT of this spec), description, homepage, license (SPDX identifier).
6. Capabilities Section#
Each capability is a structured object.
Required: name (unique within the document), type (tool | resource | prompt | event | other).
Optional: description, input_schema, output_schema, tags, apophatic (boolean — if true, the capability refuses a request outside its declared scope rather than attempting best-effort), cites_spec (the format/spec the capability operates against, e.g. application/vnd.faf+yaml).
apophatic and cites_spec are FAF-family conventions.
7. 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).
Optional: version, auth, region, health.
Multiple endpoints MAY declare the same protocol with different transports.
8. Attachment Section (Optional)#
Describes the infrastructure context within which the agent operates. It does not require any particular gateway protocol.
Optional: gateway, domain, policy, attachment_point.
9. Provenance Section (Optional)#
Cites the context substrate the agent operates from. This is the FAF-family integration point: a .fafa agent SHOULD declare which .faf it reads.
Optional: faf (reference to a .faf document — path, URL, or namepoint), fafm (reference to a .fafm document), mediaType (media type of the substrate), version.
10. Minimal Valid Example#
11. Relationship to the FAF Family#
| Format | Media type | Describes |
|---|---|---|
.faf | application/vnd.faf+yaml | a project’s context |
.fafm | application/vnd.fafm+yaml | memory |
.fafa | application/vnd.fafa+yaml | an agent’s identity, capabilities and endpoints |
.fafa extends the .faf family: it adds an agent card alongside a project’s facts. It is its own YAML document type with its own schema and shares no fields with .faf, so a .faf parser does not read it. All three formats use the YAML 1.2 / RFC 9512 baseline and the MIT license.
.fafa is format-level, not protocol-level. A protocol carries, references, or resolves a .fafa document; the document declares the agent the protocol acts upon. A protocol that needs an agent-identity-and-capability document MAY use .fafa without adopting any other part of the FAF family.
12. Security & Privacy Considerations#
Active or executable content#
None. A .fafa document is YAML data. It contains no scripts, code, or active markup. Implementations MUST treat .fafa content as data, never as instructions, commands, or code. Declaration is not authorization: an implementation MUST NOT auto-execute a capability purely because it is declared.
Privacy and integrity needs#
.fafa carries identity claims and capability declarations. It is not intended to carry personal data. Integrity of endpoints and signature is required where present; confidentiality is generally not required for the declaration itself, but transport SHOULD be authenticated and encrypted.
Privacy and integrity services#
The format does not itself provide cryptographic services. Where present, signature carries provenance/integrity material; verification is the consumer’s responsibility. Implementations MUST treat endpoints as untrusted until verified against signature if present, and MUST apply least privilege when consuming declared capabilities.
YAML format considerations#
.fafa is built on YAML 1.2; all YAML 1.2 / RFC 9512 §6 security considerations apply. Specifically, parsers MUST disable custom type construction (no !!python/object, !ruby/object, or equivalent), MUST enforce alias-expansion limits to mitigate entity-expansion (“billion-laughs”) attacks, and MUST enforce nesting-depth limits to prevent stack overflow.
Untrusted input / context poisoning / prompt injection#
.fafa documents originate from agents and third parties and MUST be treated as untrusted input by consumers. Implementations MUST NOT elevate .fafa content to “system instructions” or “developer directives” within prompt hierarchies. Capability declarations are a documented vector for over-trust and prompt injection.
Cross-context isolation#
Implementations SHOULD scope capability consumption to the declaring agent’s verified identity to prevent unintended cross-agent or cross-domain influence.
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. The format is declarative, not executable.
13. Interoperability Considerations#
.fafa is YAML 1.2 / RFC 9512 compliant. Consumers:
- MUST use YAML safe-load (no custom type construction)
- MUST treat unknown top-level fields, and unknown subfields within
agent,capabilities, andendpoints, as forward-compatible extensions - SHOULD use UTF-8 encoding
- SHOULD keep documents within common registry storage budgets (recommended < 64 KB)
14. Versioning#
- Semantic versioning in the
versionfield 0.x— draft, format may change, not for production1.0— stable; backwards-compatible changes only within1.x
The top-level version field declares which version of this specification the document conforms to. It is major.minor (e.g. "1.0"); a patch release of this document (e.g. 1.0.1) corrects the text and does not change what documents declare.
15. File Conventions#
- File extension:
.fafa - Encoding: UTF-8
- Standard filename:
agent.fafa(alongsideproject.fafwhen used at the project layer) - Multiple
.fafadocuments per scope are permitted, distinguished byagent.id
16. IANA Registration Notes#
Type name: application
Subtype name: vnd.fafa+yaml
Required parameters: N/A
Optional parameters: N/A (versioning is in-band, in the document’s version field)
Encoding considerations: 8bit (UTF-8; binary content, if any, base64-encoded inside YAML)
Security considerations: See §12
Interoperability considerations: See §13
Published specification: This document, canonical at https://github.com/Wolfe-Jam/faf/blob/main/AGENT-FORMAT.md
Applications that use this media type: See IMPLEMENTATIONS.md
Fragment identifier considerations: N/A
Additional information — File extension: .fafa
Person & email address for further information: James Wolfe, team@faf.one
Intended usage: COMMON
Restrictions on usage: None
Author: James Wolfe
Change controller: FAF Foundation
17. Change History#
| Version | Date | Changes |
|---|---|---|
| 0.1 | 2026-05-11 | Initial draft |
| 1.0 | 2026-05-18 | Stable release for IANA registration |
| 1.0.1 | 2026-11-17 | Corrections to match the schema, which is unchanged: the provenance media-type field is mediaType (the text said spec); agent.displayName listed; §16 aligned with the IANA registration (no optional parameters, versioning in-band); .fafa shares no fields with .faf. Editorial: neutral examples, plain text |
End of Specification.