Field-by-Field Reference

This page documents every field in the Agent Format schema with its type, constraints, authoring role, and rationale.

`schema_version` (required)

Property	Value
Type	`string` (semver pattern: `^\d+\.\d+\.\d+$`)
Required	Yes
Authored by	Agent Owner
Purpose	Declares which version of the Agent Format schema this file targets. Conforming parsers MUST reject files without a `schema_version`.
Example	`schema_version: "1.0.0"`

`metadata` (required)

The metadata section defines the agent's identity. It is used for discovery, registry listing, and governance policy matching.

Field	Type	Required	Description
`id`	`string` (pattern: `^[a-z0-9][a-z0-9_\-]*$`)	Yes	Machine-readable identifier. Must start with a lowercase alphanumeric character, followed by lowercase alphanumeric, underscores, or hyphens.
`name`	`string`	Yes	Human-readable display name.
`version`	`string`	Yes	Agent version. Semantic versioning (e.g., `1.0.0`) is RECOMMENDED per Semver 2.0.0. Free-form values are accepted for compatibility with existing versioning schemes.
`description`	`string`	Yes	What this agent does.
`authors`	`string[]`	No	List of author names or emails.
`license`	`string`	No	License identifier (e.g., `MIT`, `Apache-2.0`, `proprietary`).
`labels`	`map[string -> string]`	No	Kubernetes-style key-value labels for selection, filtering, and governance policy matching.
`annotations`	`map[string -> string]`	No	Opaque key-value pairs for SDK/runtime pass-through data. Not used for selection or policy matching.
`homepage`	`string` (URI)	No	URL linking to the agent's documentation or homepage.
`data_classification`	`string`	No	Sensitivity level of data this agent handles. Common values: `public`, `internal`, `confidential`, `restricted`. Used by governance tools for policy matching.
`namespace`	`string` (pattern: `^[a-z0-9][a-z0-9_.\-]*$`)	No	Organizational scope (e.g., `globex.finance`). Used by registries for namespace isolation and governance policy matching.

Example:

metadata:
  id: financial_analyst
  name: Financial Analyst
  version: "2.1.0"
  description: Analyzes financial data and generates reports
  authors: [alice@example.com, bob@example.com]
  license: Apache-2.0
  labels:
    domain: finance
    tier: production
    team: analytics
  annotations:
    internal.example.com/cost-center: "CC-4521"
  homepage: https://docs.example.com/agents/financial-analyst
  data_classification: confidential
  namespace: globex.finance

`interface` (required)

The interface section defines the agent's input/output contract -- what data it accepts and what it returns.

Field	Type	Required	Description
`input`	`SchemaRef`	Yes	Input data schema.
`output`	`SchemaRef`	Yes	Output data schema.

SchemaRef is a JSON Schema definition. The root type can be object, string, number, integer, boolean, or array. Schemas without an explicit type (using enum, anyOf, or $ref) are also valid. For shared or large schemas, use JSON Schema's built-in $ref mechanism to reference external definitions by URL.

Object schema (structured input/output)

interface:
  input:
    type: object
    properties:
      query:
        type: string
        description: User query
    required: [query]
  output:
    type: object
    properties:
      response:
        type: string
    required: [response]

Primitive schemas (simple input/output)

interface:
  input:
    type: string
    description: User message
  output:
    type: string
    description: Agent response

Numeric output (e.g., scorer)

interface:
  input:
    type: object
    properties:
      text: { type: string }
    required: [text]
  output:
    type: number
    minimum: 0
    maximum: 1
    description: Sentiment score

Array output (e.g., list generator)

interface:
  input:
    type: object
    properties:
      topic: { type: string }
    required: [topic]
  output:
    type: array
    items:
      type: string

Enum output (e.g., classifier)

interface:
  input:
    type: string
  output:
    type: string
    enum: [positive, negative, neutral]

External reference via JSON Schema `$ref`

interface:
  input:
    $ref: "https://schemas.example.com/financial-query.v2.json"
  output:
    type: object
    properties:
      report:
        type: string
    required: [report]

`memory`

The memory section declares the agent's memory requirements. Memory allows agents to retain and recall information across turns within a conversation or across separate runs.

Field	Type	Required	Default	Description
`required`	`boolean`	No	`false`	If `true`, the runtime MUST provide a stable memory context and the Agent User MUST supply a MemoryScope. The agent MUST NOT execute without memory. If `false` or absent, the runtime MAY execute statelessly or with best-effort memory.

Example:

memory:
  required: true

When memory.required is true, the runtime is responsible for providing a MemoryStore implementation and the Agent User must supply scope identity (e.g., userId, sessionId). The agent author does not specify how memory is stored or where -- only that it is needed.

note

For opaque pass-through data previously served by additional_context, use metadata.annotations.

`constraints`

The constraints section declares the agent's operational boundaries -- budgets, call limits, and governance policy references.

`tighten_only_invariant`

Property	Value
Type	`boolean` (default: `true`)
Purpose	When true, child agents and governance policies can only tighten constraints, never relax them.

This is a foundational safety primitive. When a parent agent delegates to a child, the child cannot exceed the parent's budget. When a governance policy applies additional constraints, it cannot remove constraints the Agent Owner declared.

`budget`

Field	Type	Min	Description
`max_token_usage`	`integer`	0	Maximum total token usage (input + output) for a single agent run.
`max_duration_seconds`	`integer`	1	Maximum wall-clock time in seconds for a single agent run.

`limits`

Field	Type	Description
`max_llm_calls`	`integer`	Maximum number of LLM API calls per run.
`max_tool_calls`	`integer`	Maximum number of tool invocations per run.
`max_delegation_depth`	`integer`	Maximum depth of sub-agent delegation.

`governance_policies`

An array of references to governance policies managed in an external Policy Registry. The Runtime Owner resolves these at execution time. Policy details are opaque to the Agent Owner (see the Governance page for the full governance model).

Each entry is a GovernancePolicyRef:

Field	Type	Required	Description
`policy_ref`	`string` (pattern: `^[a-z0-9][a-z0-9_.\-]*$`)	Yes	Unique identifier in the Policy Registry. Convention: `<org>.<team>.<policy-name>[-<version>]`.
`required`	`boolean` (default: `true`)	No	If true, the agent MUST NOT execute if this policy cannot be resolved. If false, the policy is advisory.
`description`	`string`	No	Human-readable description of why this policy is referenced.

Example:

constraints:
  tighten_only_invariant: true
  budget:
    max_token_usage: 100000
    max_duration_seconds: 600
  limits:
    max_llm_calls: 100
    max_tool_calls: 200
    max_delegation_depth: 3
  governance_policies:
    - policy_ref: org.security.pii-redaction-v2
      description: Required for all customer-facing agents
    - policy_ref: org.finance.cost-ceiling-q1
      description: Finance team quarterly budget controls
    - policy_ref: org.compliance.sox-controls
      required: false
      description: SOX compliance monitoring (advisory)

`action_space`

The action_space section declares the agent's available tools, MCP servers, local sub-agents, and remote agents. Each entry is identified by an alias that the runtime maps to an implementation.

`local_tools[]`

Local tools are functions provided by the runtime and bound to the agent at execution time.

Field	Type	Required	Description
`alias`	`string`	Yes	Unique identifier within this agent's action space.
`name`	`string`	No	Human-readable display name.
`description`	`string`	No	What this tool does.
`approval`	`Approval`	No	Approval requirement (see Human-in-the-Loop Approval).

`mcp_servers[]`

MCP (Model Context Protocol) servers expose tools over a standardized protocol.

Field	Type	Required	Description
`alias`	`string`	Yes	Unique identifier within this agent's action space.
`server_ref`	`string`	No	Portable registry or catalog identity for this MCP server (e.g., a public MCP registry ID or enterprise internal catalog entry). The Runtime Owner maps this -- along with `alias` -- to connection details (transport, URL, command, auth, routing).
`description`	`string`	No	What this MCP server provides.
`allowed_tools`	`McpToolRef[]`	No	Which tools from this server are allowed. When omitted, all tools are available.
`approval`	`Approval`	No	Blanket approval for ALL tools on this server. Per-tool approval in `allowed_tools` overrides this. See Human-in-the-Loop Approval.

McpToolRef is a union type -- either a plain tool name (string) or an object with name and optional approval:

allowed_tools:
  - read_table                      # string: no per-tool approval
  - list_tables                     # string: no per-tool approval
  - name: write_table               # object: per-tool approval
    approval:
      message_template: "Approve writing to '{{tool_args.table_name}}'?"
  - name: health_check
    approval: false                 # exempt from blanket approval

`local_agents[]`

Local agents are sub-agents whose definitions are resolved and executed by the same runtime. The source_type field declares the kind of reference, and source provides the reference value whose interpretation depends on the type.

Field	Type	Required	Description
`alias`	`string`	Yes	Unique identifier.
`source_type`	`string`	No	Declares how `source` should be resolved. Standard types: `file` (relative or absolute file path), `registry` (agent registry identifier), `db` (database key). Runtimes may define additional types. Defaults to `file`.
`source`	`string`	Yes	Reference to the sub-agent's definition. For `file`: a path (relative to the parent YAML or absolute); for `registry`: a registry identifier (e.g., `org.team.agent@version`); for `db`: a database key or path.
`description`	`string`	No	What this sub-agent does.
`approval`	`Approval`	No	Approval requirement for delegating to this agent. See Human-in-the-Loop Approval.
`memory_scope_strategy`	`string` (enum: `inherit`, `isolated`, `none`)	No	How this sub-agent's memory scope relates to the parent. `inherit` (default): child shares parent memory context. `isolated`: runtime derives a child-specific memory context. `none`: child runs with no memory context (stateless).

`remote_agents[]`

Remote agents are external agents accessible via the A2A protocol or other inter-agent communication protocols. The schema declares what the parent agent needs from the remote agent; the runtime resolves where and how to connect.

Field	Type	Required	Description
`alias`	`string`	Yes	Local alias. The runtime maps this to connection details (endpoint, auth, protocol).
`description`	`string`	No	Human-readable description.
`input_modes`	`string[]`	No	Media types (MIME) the parent expects to send (e.g., `application/json`). When omitted, uses the remote agent's defaults.
`output_modes`	`string[]`	No	Media types the parent expects to receive.
`allowed_skills`	`SkillRef[]`	No	Skills from the remote agent that the parent is allowed to invoke. Parallels `allowed_tools` on MCP servers. When omitted, all skills are available.
`approval`	`Approval`	No	Blanket approval for all interactions with this remote agent. See Human-in-the-Loop Approval.

SkillRef is a union type -- either a plain skill ID (string) or an object with id and optional approval:

remote_agents:
  - alias: payment_gateway
    description: Processes payments via external service
    approval: true
    allowed_skills:
      - id: check-balance
        approval: false                # exempt from blanket
      - id: process-payment
        approval:
          message_template: "Approve payment of ${{skill_args.amount}}?"
          condition:
            args_match:
              amount: { gt: 1000 }
      - refund-lookup                  # inherits blanket approval

`execution_policy` (required)

The execution policy tells the runtime which strategy to use when executing this agent. Policy IDs use a two-namespace convention: agf.* for standard-defined policies and x-<vendor>.* for runtime/vendor-specific policies (see Execution Policies for the full narrative).

Field	Type	Required	Description
`id`	`string`	Yes	Policy identifier. `agf.` = standard policies (e.g., `agf.react`, `agf.sequential`, `agf.parallel`, `agf.loop`, `agf.batch`, `agf.conditional`). `x-<vendor>.` = runtime/vendor policies (e.g., `x-myruntime.custom-policy`).
`config`	`object`	Yes	Policy-specific configuration. For standard (`agf.`) policies, the structure is defined by the standard (see Execution Policy Catalog). For vendor (`x-`) policies, the structure is defined by the runtime.

Example:

execution_policy:
  id: agf.react
  config:
    instructions: |
      You are a helpful assistant with access to tools.
      Use tools when needed to answer the user's question.
    provider: google
    model: gemini-2.5-pro
    temperature: 0.3
    max_steps: 10

schema_version (required)​

metadata (required)​

interface (required)​

Object schema (structured input/output)​

Primitive schemas (simple input/output)​

Numeric output (e.g., scorer)​

Array output (e.g., list generator)​

Enum output (e.g., classifier)​

External reference via JSON Schema $ref​

memory​

constraints​

tighten_only_invariant​

budget​

limits​

governance_policies​

action_space​

local_tools[]​

mcp_servers[]​

local_agents[]​

remote_agents[]​

execution_policy (required)​

`schema_version` (required)

`metadata` (required)

`interface` (required)

Object schema (structured input/output)

Primitive schemas (simple input/output)

Numeric output (e.g., scorer)

Array output (e.g., list generator)

Enum output (e.g., classifier)

External reference via JSON Schema `$ref`

`memory`

`constraints`

`tighten_only_invariant`

`budget`

`limits`

`governance_policies`

`action_space`

`local_tools[]`

`mcp_servers[]`

`local_agents[]`

`remote_agents[]`

`execution_policy` (required)