Skip to main content

Schema Overview

An .agf.yaml file has the following top-level structure. Four sections are required (schema_version, metadata, interface, execution_policy); the rest are optional.

schema_version: "1.0.0"          # REQUIRED: semver string

metadata:                         # REQUIRED: agent identity
  id: my_agent
  name: My Agent
  version: "1.0.0"
  description: What this agent does

interface:                        # REQUIRED: input/output contract
  input: { ... }
  output: { ... }

memory:                           # optional: memory requirements
  required: false

constraints:                      # optional: budget, limits, governance
  budget: { ... }
  limits: { ... }
  governance_policies: [ ... ]

action_space:                     # optional: tools, agents, MCP servers
  local_tools: [ ... ]
  mcp_servers: [ ... ]
  local_agents: [ ... ]
  remote_agents: [ ... ]

execution_policy:                 # REQUIRED: how to execute
  id: agf.react
  config: { ... }

For a complete breakdown of every field, see the Field Reference.

Forward Compatibility​

The JSON Schema intentionally omits additionalProperties: false on most type definitions. This is a deliberate forward-compatibility decision that allows minor schema versions (e.g., 1.1.0) to add new optional fields without breaking existing parsers.

Normative rules for unknown fields:

  1. Conforming parsers MUST NOT reject .agf.yaml files that contain fields not recognized by their supported schema version. Unknown fields MUST be silently ignored during execution.
  2. Parsers and SDKs SHOULD emit a warning for each unknown field encountered, identifying the field name and location. This alerts authors to potential typos while maintaining compatibility.
  3. Tooling (CLI validators, IDE extensions, CI linters) SHOULD provide a strict validation mode that treats unknown fields as errors. This mode is intended for authoring-time checks where forward compatibility is not a concern and catching typos is the priority.
Rationale

The tradeoff between forward compatibility and typo safety is inherent to all extensible schemas. Rules 2 and 3 mitigate the risk of silent misconfiguration (e.g., aproval: true being ignored) while preserving the ability for older parsers to process files authored for newer schema versions.

Section Dependency​

The sections within an .agf.yaml file have the following dependency relationships:

  • schema_version, metadata, interface, and memory are standalone — they have no dependencies on other sections.
  • constraints is standalone but may reference entries from an external governance registry.
  • action_space may reference other .agf.yaml files via local_agents.
  • execution_policy may reference entries declared in action_space (e.g., sub-agent aliases used in policy steps).