manifest · capabilities · run modes

The QuickAgent format

A QuickAgent is a single-purpose AI agent in a small package you can review: a manifest that declares what it may touch, and an instruction that says what it does. It ships no tool code. When it runs, the tools it declares are the only tools it has.

The QuickAgent template (github.com/blaktron/agentry-template) runs as it stands: it reads the files you give it and writes a report. Its agent.yaml shows every other manifest option, commented, with its limits.

Repository layout

The template ships this shape:

my-quickagent/
├── agent.yaml          # the manifest (required)
├── AGENT.md            # the instruction (frontmatter allowed, so a SKILL.md works)
├── README.md           # shown on the QuickAgent's page; required to publish publicly
├── LICENSE             # required to publish publicly
├── output.schema.json  # optional: the run must return JSON that matches it
└── knowledge/…         # optional: knowledge packs the release ships

The manifest

agent.yaml is the security contract. The registry scans each release against it, an install asks for consent to it, and the runner enforces it. A capability the manifest does not declare is a tool the QuickAgent does not have.

schemaVersion: "2"
name: incident-summarizer
namespace: acme
version: 1.4.2              # strict semver; matches the git tag
summary: "Turns an incident's timeline and alerts into a postmortem draft"
license: Apache-2.0

modes: [autonomous, interactive]   # one or both

entrypoints:
  instruction: AGENT.md     # the default

guide:                      # what a person reads before a run; never the agent
  overview: "Reads the incident's export and writes a postmortem draft."
  files: "Add the incident export and any chat log."
  connect:
    PAGERDUTY_TOKEN: "A **read-only** PagerDuty API key."

inputs:                     # what files it takes; grants nothing
  kinds: [documents, data]
  view: text

intake:                     # questions asked before a run
  - id: incident
    prompt: "The incident id"
    required: true

interactive:
  opening: "Which incident, and who is the draft for?"

capabilities:               # the contract: a closed vocabulary
  network:
    egress: [api.pagerduty.com]   # exact hosts, or none
  filesystem:
    read: none                    # files arrive as inputs, without a grant
    write: none
  exec: none                      # or commands: [jq, …]
  secrets: [PAGERDUTY_TOKEN]      # names, never values
  dataAccess: [tickets]
  # optionalSecrets: [...]        # declared secrets a run can do without
  # targetHosts: [server]         # a machine the person names at run time
  # browser:                      # a headless browser the run drives
  #   sites: [site]               # url questions: the person names the site
  #   hosts: [fonts.googleapis.com]   # fixed hosts its pages need
  # mcpServers:                   # installed with this release, pinned
  #   - npm: github-mcp-server-js
  #     version: 0.1.7            # exact; ranges are refused
  #     secrets: [GITHUB_TOKEN]
  #     egress: [api.github.com]
  #   - url: https://mcp.linear.app/mcp   # a vendor's remote server
  #     auth: oauth                       # signs the person in at the vendor

publish:
  include: [agent.yaml, AGENT.md, README.md, LICENSE]  # the archive's allowlist

autonomous

Runs from its task and files, after any questions it asks first, writes its result and reports, and ends.

interactive

The same plan and controls, as a conversation: the agent can ask, you can answer and add files, and nothing you say widens what the manifest allows.

MCP servers

Declared under capabilities.mcpServers: a package pinned to an exact version, or a vendor's remote server by its address. They are tools a QuickAgent uses, not packages of their own.

From template to running QuickAgent

# start from the QuickAgent template, then:
agentry validate .                                # the registry's checks, offline
agentry run --local . --dry-run --allow-unsigned  # the compiled run plan
agentry run --local . --allow-unsigned --file incident.json
agentry review .                                  # the built-in Examiner, before you submit
agentry publish                                   # scanned, signed, immutable
agentry run acme/incident-summarizer@^1 --file incident.json

agentry run runs one QuickAgent once, in an isolated container. Its tools come through a per-run MCP gateway, the files you give it are read-only under /inputs, and its reports land in an output folder. Before the first agentry publish, create the QuickAgent at New QuickAgent. Installed into a coding agent instead (agentry install), the same contract maps onto that application's own tools. To start without a repository, use the QuickAgent Builder: describe the QuickAgent and AI writes a draft (signed in, for credits), or fill in the form yourself and download the package or submit it.

Every manifest option, and everything the runner enforces, is documented field by field in the QuickAgents documentation.