Agent Format: A Declarative Standard for AI Agents

Agent Format is our proposed answer to the definition layer — a vendor-neutral way to describe what an agent is, independent of the framework that runs it. We'd love for this specification to grow with input from the broader community.

Check out the full specification, the JSON Schema, and the interactive playground — or join the conversation on GitHub Discussions.

Define once. Run anywhere. Audit by design.

Kubernetes taught us to go declarative. The next question was: what should the declarative artifact actually contain?

Many agent platforms already offer declarative definitions — the most common being the graph model of nodes and edges, which is powerful for expressing complex execution flows with branching, merging, and cycles. However, graph-based definitions can be hard to understand without a visualization tool, especially as agent complexity grows. More fundamentally, graphs emphasize the execution flow — how steps connect — rather than the agent itself.

We wanted to start from a different question: what is an agent?

This question has been studied for decades in the field of decision-making under uncertainty. The established answer is the Partially Observable Markov Decision Process (POMDP) — a mathematical framework for agents that observe partial information, maintain beliefs about their state, take actions, and receive feedback. A POMDP defines the core structure of any agent: its action space (what it can do), its observations (what it can see), its policy (how it decides), and its reward/cost model (what it optimizes for). Every modern agent framework — ReAct loops, sequential pipelines, parallel tool calls — can be understood as a specialization of this model, whether they name it or not.

We used the POMDP formalism as the starting point for our schema design, then extended it with the practical concerns that production agents need: identity, versioning, governance, and approval gates. The result is a schema where each section maps to a well-defined concern:

That's the core idea behind Agent Format — an open, vendor-neutral standard for defining AI agents. Think of it as an Interface Definition Language (IDL) for AI agents: human-readable documentation and machine-readable configuration in one artifact.

The spec is backed by a JSON Schema, so definitions can be expressed as YAML, JSON, stored in a database, or generated programmatically.

We started this blog with three pain points — no portability, no shared tooling, and no standardized governance. The adapter model solves portability. A common schema solves shared tooling. Now let's talk about governance.

When agent definitions are declarative, constraints become part of the definition itself — easy to review, easy to enforce uniformly. The constraints section of an .agf.yaml declares exactly what the agent is allowed to do:

Because these constraints live in a structured, machine-readable file, the runtime can enforce them before the agent acts — not after. This is governance by construction, not by inspection.

When an orchestrator agent delegates to a sub-agent, the sub-agent cannot exceed the orchestrator's constraints. Ever. Governance boundaries can only become more restrictive as task delegation goes deeper — never more relaxed

This is enforced at multiple levels. At parse time, a sub-agent that declares less restrictive constraints than its orchestrator can fail validation before it ever runs. At runtime, the system automatically applies the stricter of the two constraints — so even if a delegated agent doesn't explicitly declare limits, the orchestrator's boundaries are never exceeded.

Agent Format separates what the agent owner declares from what the organization requires. Agent owners set base constraints in the .agf.yaml. The organization defines platform-wide governance policies independently. Neither touches the other's config. Any compliant runtime composes both layers at execution time, always taking the stricter of the two.

Constraints are declared in the .agf.yaml and enforced by the runtime — which means auditing what an agent can do is as simple as reading its definition. Because agent capabilities and constraints are structured and machine-readable, teams can automate compliance checks, track capability changes over time in version control, and answer governance questions without reading source code.

Requirements for human review can be set within Agent Format. Approval gates are first-class — per-tool, conditional, and composable. For example, consider a hypothetical trading agent:

Small trades go through automatically. Large trades pause for human review. The definition declares what needs approval. The runtime decides how — Slack notification, email, CLI prompt, or a custom UI. Same definition, any delivery mechanism.

Agent Format defines six built-in execution policies — composable building blocks that cover most real-world patterns:

Production systems hit edge cases. Agent Format supports vendor-specific policies via the x-<vendor>.* namespace:

Custom policies are first-class citizens. They go through the same validation and governance layer as built-in policies. The x-myorg. prefix makes it immediately clear this is an extension, and other organizations can define their own without collisions.