View Markdown

Core

Status: Working Draft
Version: 0.1.0-draft.4

Purpose

The Core Agentfile Profile defines the minimum behavior required to parse, validate, and inspect a single-agent Agentfile.

It does not define execution.

A small, stable core is a deliberate design choice. Every directive in the core is something a second, independent implementer must build and a conformance test must cover. The core is therefore kept intentionally narrow so the format can stabilize, while richer capabilities live in clearly separated optional profiles that can evolve without breaking the core.

Required behavior

An implementation claiming this profile MUST:

1. read a text file named Agentfile or an explicitly supplied path;
2. ignore blank lines and comments;
3. parse known directives case-sensitively;
4. preserve directive order for lockfile generation and review;
5. capture POLICY ... END and SOP ... END blocks without interpreting inner lines as Agentfile directives;
6. reject unknown directives unless an extension profile is enabled;
7. produce a structured parse tree suitable for linting and package generation;
8. report line numbers for parse failures.

Core directive set

The v0.1 core directive set is deliberately minimal — the smallest set that can describe a reviewable, governed, portable single agent:

AGENT  FROM  CMD  TOOL  MOUNT  CRED  URL  POLICY  AUDIT

Directive	Concern	Why it is core
AGENT	Identity	A package needs a stable, signable identity.
FROM	Inheritance	Establishes the base and the security ceiling that inheritance tightens.
CMD	Entrypoint	The one thing every runner must know to start the agent.
TOOL	Capability	The primary capability surface that policy governs.
MOUNT	Filesystem boundary	A first-class, reviewable security boundary.
CRED	Credential boundary	Secrets-as-references is a core security guarantee.
URL	Network boundary	Deny-by-default network egress is a core security guarantee.
POLICY	Governance	Machine-evaluable boundaries that travel with the package.
AUDIT	Governance	Fail-closed auditability is a core review guarantee.

All other recognized directives belong to optional profiles (below). An implementation MAY support any number of them, but it MUST publish a support matrix rather than implying that every recognized directive is enforced.

Directive classification

Every directive defined by this specification is assigned to exactly one profile. This is what keeps the core small while leaving room to grow.

Profile	Directives	Status
Core Agentfile	AGENT FROM CMD TOOL MOUNT CRED URL POLICY AUDIT	Normative, v0.1
Capability Extensions	TOOLSET FUNCTION SKILL SERVER MCP MEMORY	Optional
Instruction Embedding	SOP	Optional (Agent SOP / Agent Skills)
Security Shorthand & Limits	ALLOW DENY RATELIMIT TIMEOUT LIMIT	Optional (lowers into the Security profile)
Placement / Run Manifest	ISOLATION IMAGE SLICE BACKEND BIND BROKER PLUGIN	Optional, non-portable (see below)
Observability	TRACE HEALTHCHECK	Optional
Framework & Experimental	SHELL OPTIMIZER	Optional / experimental

Build vs. placement (Run Manifest)

The directives in the Placement / Run Manifest group describe where and how an agent runs, not what it is or what it may do. Mixing them into the portable declaration breaks the “vet once, run anywhere, content-addressed” promise: two agents identical in capability but different in placement would otherwise produce different artifacts and different digests.

Therefore:

1. The portable, signable artifact (the Agentfile and its package) SHOULD be computed from capability and boundary directives only.
2. Placement directives (ISOLATION, IMAGE, SLICE, BACKEND, BIND, BROKER, PLUGIN) SHOULD be expressible in a separate Run Manifest chosen by the operator or runner, and SHOULD NOT contribute to the package digest.
3. For backward compatibility, current implementations MAY still accept these directives inline; when they do, a linter SHOULD warn (see below) and the package builder SHOULD exclude them from the content-addressed identity.

This mirrors the Dockerfile (build) vs. Compose/run (placement) separation and is load-bearing for reproducibility and signing.

Compatibility notes

The current agentrc implementation recognizes the full directive family above, though not every directive has full semantic enforcement. This profile defines target semantics; implementations should publish a support matrix rather than implying all recognized directives are enforced.

Validation recommendations

A linter SHOULD warn when:

1. AGENT is missing in a package intended for publication;
2. FROM uses a mutable tag such as latest;
3. a CRED contains plaintext-like material;
4. BIND lacks a mode;
5. a TOOL is declared but no policy permits it under deny-by-default mode;
6. AUDIT is absent;
7. a placement directive (ISOLATION, IMAGE, SLICE, BACKEND, BIND, BROKER, PLUGIN) couples the portable package to one runner, where a Run Manifest should be used instead.