What is Agent Format?
Agent Format is a declarative, runtime-agnostic YAML standard for defining AI agent systems. An .agf.yaml file captures everything an agent is — its identity, interface contract, action space, safety constraints, approval requirements, and execution strategy — in a single, portable, human-readable document.
Think of Agent Format as "Kubernetes" for AI Agents. Just as a Kubernetes manifest declares what a container needs (ports, volumes, resource limits) and the cluster decides how to schedule it, an .agf.yaml declares what an agent needs and the runtime decides how to execute it.
Or, for a simpler analogy: an .agf.yaml file is like an architect's blueprint. The blueprint specifies rooms, dimensions, materials, and safety requirements — but does not dictate which construction crew builds it, which concrete supplier is used, or which crane lifts the beams. Any licensed contractor can build from the same blueprint.
Key Value Propositions
| Value | Description |
|---|---|
| Write once, run on compliant runtimes | The same .agf.yaml runs across runtimes that implement the referenced standard policies. No code changes, no vendor lock-in. |
| Declarative safety | Approval requirements, budget limits, and governance policies are declared in the YAML, not scattered across code. Auditors read YAML, not source code. |
| Enterprise governance | A two-layer constraint model lets governance teams enforce invisible, organization-wide policies on top of agent-level declarations. |
| Composable multi-agent systems | Local agents, remote agents (A2A protocol), and MCP tool servers are first-class citizens with unified approval and constraint semantics. |
| Schema-validated | Every .agf.yaml is validated against a JSON Schema. Misconfigurations are caught at authoring time, not at runtime. |
Kubernetes Analogy Mapping
| Kubernetes Concept | Agent Format Equivalent |
|---|---|
| Pod manifest | .agf.yaml |
| Resource requests/limits | constraints.budget / constraints.limits |
| Network policies | governance_policies |
| Admission controllers | Governance + approval |
| Labels/selectors | metadata.labels |
| Annotations | metadata.annotations |
| CRDs (Custom Resource Definitions) | x-<vendor>.* execution policies |
| Built-in resources (Pod, Deployment) | agf.* standard policies |
What This Documentation Covers
This documentation is the flagship specification for the Agent Format open standard. It is fully self-contained — a reader should understand the entire standard from these pages. Specifically, it covers:
- The six-role ecosystem model and how roles interact
- The WHAT/HOW design principle and the three-question litmus test for field placement
- A complete field-by-field reference for every schema element
- The execution policy model (standard
agf.*and vendorx-*namespaces) - Human-in-the-loop approval (per-tool, conditional, composable with governance)
- Enterprise governance via opaque policy references and a two-layer constraint model
- Comprehensive YAML examples at increasing complexity
- The vision for agentformat.org as the neutral home for the standard
- Integrations and ecosystem — how Agent Format works with MCP, A2A, and framework adapters
Non-Goals
Agent Format intentionally does not cover the following concerns. Recognizing these boundaries helps implementers understand where the standard ends and where runtime-specific or complementary standards begin.
| Non-Goal | Rationale |
|---|---|
| Runtime behavior specification | The standard declares WHAT an agent needs, not HOW the runtime executes it. Execution internals (event loops, threading models, streaming protocols) are runtime-specific. |
| Authentication and credentials | Credentials, OAuth flows, API keys, and mTLS certificates are deployment-specific. The runtime maps abstract references (server_ref, alias) to concrete connection details. |
| Wire protocols | Agent Format does not define how agents communicate over the network. A2A (agent-to-agent) and MCP (tool invocation) handle protocol concerns. |
| Model-specific APIs | The standard is model-agnostic. Fields like provider and model are preferences, not binding requirements. The runtime selects and configures the actual model. |
| Audit record shape | While the standard declares what requires approval and which governance policies apply, the shape of audit records, trace logs, and compliance reports is a runtime specification concern. |
| Pricing and cost modeling | Token costs vary by model, provider, and contract. The standard provides max_token_usage (portable) but not max_cost_usd (not portable). |
| UI/UX for approval workflows | The standard declares that approval is required; the runtime decides whether to deliver it via Slack, email, CLI, or a custom UI. |
| Agent discovery and registry APIs | The standard provides metadata fields (namespace, labels, data_classification) that registries can index, but does not define registry APIs. |
Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this documentation are to be interpreted as described in RFC 2119 and RFC 8174.