afps-spec

Agent Flow Packaging Standard (AFPS)

AFPS is an open specification for declaring portable AI workflow packages. It standardizes how flows, skills, tools, and providers are described, versioned, and distributed. It focuses on package definition and composition, not on tool calling or agent-to-agent transport.

Ecosystem Positioning

Existing AI agent standards define capabilities — what an agent can do and how it communicates. AFPS defines goals — what the agent should accomplish, packaged with everything it needs.

                ┌───────────────────────────────┐
  Goal          │  AFPS Flow                     │  "Process my inbox and
                │  prompt.md + manifest.json    │   summarize support requests"
                ├───────────────────────────────┤
  Capability    │  Skills (SKILL.md)            │  "Rewrite in a professional tone"
                │  Tools (source + manifest)    │  "Fetch JSON from a URL"
                │  MCP Tools                    │  "Read a file, query a database"
                ├───────────────────────────────┤
  Connection    │  Providers (OAuth2, API key)  │  "Gmail, OpenAI, Slack"
                ├───────────────────────────────┤
  Transport     │  MCP / A2A                    │  Runtime protocols
                └───────────────────────────────┘

A flow’s prompt.md is the equivalent of what a user would type to give an agent its objective. Skills and tools are the capabilities the agent draws on to reach that objective. Providers are the authenticated service connections. AFPS packages all of this into a portable, versioned .afps artifact (a standard ZIP file).

• MCP defines runtime tool invocation. AFPS does not define tool-calling transport; a runtime may choose to expose AFPS tools via MCP.
• Agent Skills defines reusable capabilities (SKILL.md). AFPS skill packages are a strict superset: a valid Agent Skill directory becomes an AFPS skill when a manifest.json is added. The SKILL.md format, frontmatter fields, and optional directories (scripts/, references/, assets/) are preserved unchanged. AFPS adds identity, versioning, and dependency resolution.
• A2A defines inter-agent communication. AFPS does not compete — A2A metadata can be added via x- extension fields.

No existing standard covers the goal layer: structured workflow packages with dependency resolution, semantic versioning, provider auth metadata, and a distribution format. AFPS fills that gap.

Quick Start

Create a minimal flow package with two files:

manifest.json

{
  "name": "@my-org/hello-world",
  "version": "1.0.0",
  "type": "flow",
  "schemaVersion": "1.0",
  "displayName": "Hello World",
  "author": "My Org",
  "requires": {}
}

prompt.md

You are a helpful assistant. Greet the user and ask how you can help.

ZIP both files together (using the .afps extension by convention) — that’s a valid AFPS flow package. See examples/ for more, or read the primer for a guided introduction.

How a flow composes its dependencies

A real flow declares the skills, tools, and providers it needs:

                  ┌──────────────────────────────┐
                  │  @acme/customer-intake        │
                  │  type: flow                   │
                  │  prompt.md = the objective    │
                  └──────┬───────────────────────┘
                         │ requires
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
  ┌──────────────┐ ┌────────────┐ ┌────────────┐
  │ @acme/gmail  │ │ @acme/     │ │ @acme/     │
  │ provider     │ │ rewrite-   │ │ fetch-json │
  │ (OAuth2)     │ │ tone       │ │ tool       │
  │              │ │ skill      │ │            │
  └──────────────┘ └────────────┘ └────────────┘

The flow’s manifest lists these dependencies in requires (runtime) and registryDependencies (install-time resolution with semver ranges). See the full example.

Repository Contents

• spec.md — the AFPS v1.0 draft specification
• primer.md — non-normative introduction for newcomers
• examples/ — minimal and full package examples (flow, skill, tool, provider)
• schema/ — JSON Schema files (see schema/README)
• GOVERNANCE.md — change process and stewardship
• CONTRIBUTING.md — how to contribute
• CHANGELOG.md — specification history

Scope

AFPS defines:

• Package identity with scoped names and semantic versions
• Manifest fields for flow, skill, tool, and provider
• Registry dependencies and provider configuration
• A constrained schema system for input, output, and config
• ZIP package structure for distribution

AFPS does not define:

• Agent runtime APIs
• Prompt execution semantics
• Tool invocation transport
• Agent-to-agent messaging

Origin

AFPS was created by Appstrate and published as an independent open specification.

Implementations

See IMPLEMENTATIONS.md for known implementations.

Contributing

See GOVERNANCE.md for the change process. To propose a normative or editorial change, open an issue using the spec change template.

License

• Specification text (spec.md, GOVERNANCE.md, CHANGELOG.md): CC-BY-4.0
• Code and examples (examples/, schema/): MIT

This site is open source. Improve this page.