Introduction#

What the manifest is, why it matters, and how the schema keeps things predictable.

What is agent.json?#

agent.json is the single source of truth for an AgentPM project. It describes:

• Kind — either an agent (composes tools) or a tool (a single runnable package).
• Behavior & interface — names, versions, entrypoint, inputs/outputs, files, env vars.
• Operational details — runtime, timeouts, auth modes, and more.

Agents and SDKs read this file to know exactly how to call your tool, ensuring consistent, language-agnostic execution in a managed subprocess.

Why it’s important#

• Determinism: Installs and executions are reproducible across machines and CI.
• Discoverability: The registry renders docs straight from the manifest.
• Safety & trust: Lint/publish validations enforce schema correctness and semantic checks.

The schema (high level)#

The manifest is validated against a JSON Schema:

https://raw.githubusercontent.com/agentpm-dev/cli/refs/heads/main/schemas/agentpm.manifest.schema.json

At a glance:

• File: agentpm.manifest.schema.json
• Kinds: agent (composed of tools) and tool (single tool package)
• Strictness: additionalProperties: false — unknown fields are rejected

Design notes#

• Strict by default: Unknown fields are rejected (additionalProperties: false).
• SemVer enforced: version must match a SemVer-compatible regex.
• Paths: files[] are repo-relative paths or globs.

Versioning & stability#

• The schema file is versioned in the repo. Breaking changes will be published under a new filename (e.g., agentpm.manifest.schema.v2.json) and reflected in docs.
• Generators should point $schema to a tag or commit for stability (e.g., a released tag).
• The CLI will validate manifests against the bundled schema version it supports as it evolves.