Understanding the Agent Companies Protocol

The open standard for defining AI agent organizations. Learn what the Agent Companies protocol is, why it matters, and how Paperclip implements it.

What is the Agent Companies Protocol?

The Agent Companies protocol is a vendor-neutral specification for describing AI agent organizations using portable markdown files. It defines how to structure:

  • Companies — Top-level organizational units
  • Teams — Hierarchical groupings of agents
  • Agents — Individual AI workers with roles and capabilities
  • Projects — Work initiatives with tasks and goals
  • Tasks — Specific units of work assigned to agents
  • Skills — Reusable capabilities via SKILL.md files

Key insight: Instead of writing code to configure your AI agents, you write markdown files that any compatible platform can understand.

Why a Protocol Matters

The Problem It Solves

Before Agent Companies, every AI agent framework used its own proprietary format:

  • CrewAI → Python code
  • AutoGen → Python classes
  • LangChain → Chains and agents in code
  • Microsoft Semantic Kernel → C#/Python

The result: Vendor lock-in. Your agent configuration is trapped in code that's hard to migrate, version control, or share.

What the Protocol Enables

1. Portability Your company definition works across any platform that supports the protocol:

  • Self-hosted Paperclip
  • Managed cloud services
  • Future platforms not yet built

2. Version Control Since it's markdown in Git:

  • Track changes to your AI organization
  • Code review agent configurations
  • Roll back to previous versions
  • Branch and experiment safely

3. Collaboration Non-technical team members can:

  • Read and understand the structure
  • Propose changes via pull requests
  • Review agent behavior without reading code

4. Auditability Every change to your AI company is:

  • Documented in Git history
  • Reviewable before deployment
  • Attributable to specific authors

The File Structure

An Agent Companies package follows this convention:

my-ai-company/
├── COMPANY.md          # Company manifest
├── AGENTS.md           # Agent definitions
├── TEAM.md             # Organization structure
├── PROJECT.md          # Active projects and tasks
├── GOVERNANCE.md       # Policies and controls
└── skills/
    ├── web-search.md   # Reusable skills
    ├── code-review.md
    └── email-send.md

Each file has a specific purpose and format.

COMPANY.md — The Manifest

Defines the top-level company:

# Acme AI Solutions

## Description
A full-service AI agency providing content, code, and consulting.

## Mission
Deliver high-quality AI-powered services while maintaining strict cost controls and ethical governance.

## Governance
- Budget: $500/month maximum
- All code execution requires approval
- Audit log retention: 90 days

## Contacts
- Human oversight: ops@acme.com
- Emergency contact: +1-555-0123

Key fields:

  • Company identity and description
  • Mission and values
  • Governance policies
  • Contact information

AGENTS.md — The Workforce

Defines each agent's role and capabilities:

# Agent Definitions

## CEO Agent
**Role:** Chief Executive Officer
**Goal:** Set company direction and oversee operations

**Description:**
You are the CEO of Acme AI Solutions. You set strategic direction, 
delegate tasks to department heads, and ensure company goals are met.

**Capabilities:**
- Strategic planning
- Task delegation
- Progress monitoring

**Adapter:**
- Type: anthropic
- Model: claude-3-opus
- Budget: $100/month

**Reports to:** Human oversight

---

## CTO Agent
**Role:** Chief Technology Officer
**Goal:** Oversee technical implementation

**Description:**
You manage the technical team and review all code and architecture decisions.

**Capabilities:**
- Architecture design
- Code review
- Technical debt management

**Skills:**
- code-review
- architecture-planning
- security-audit

**Adapter:**
- Type: anthropic
- Model: claude-3-sonnet
- Budget: $75/month

**Reports to:** CEO Agent

Key fields:

  • Role and goal
  • System prompt (description)
  • Skills and capabilities
  • LLM adapter configuration
  • Budget limits
  • Reporting structure

TEAM.md — The Org Chart

Defines hierarchical relationships:

# Team Structure

## Executive Team

### CEO (Sarah)
- **Role:** Chief Executive
- **Reports to:** Human oversight

### CTO (Mike)
- **Role:** Chief Technology Officer  
- **Reports to:** CEO

### CMO (Alex)
- **Role:** Chief Marketing Officer
- **Reports to:** CEO

## Development Team

### Senior Engineer (Jordan)
- **Role:** Lead Developer
- **Reports to:** CTO

### Junior Engineer (Taylor)
- **Role:** Developer
- **Reports to:** Senior Engineer

### QA Engineer (Casey)
- **Role:** Quality Assurance
- **Reports to:** CTO

## Marketing Team

### Content Lead (Riley)
- **Role:** Content Strategist
- **Reports to:** CMO

### Social Media Manager (Quinn)
- **Role:** Community Manager
- **Reports to:** CMO

Key concept: Hierarchical reporting enables automatic task delegation. When the CEO assigns work, it flows down the org chart.

PROJECT.md — The Work

Defines active projects and their tasks:

# Active Projects

## Website Redesign

**Goal:** Launch new company website by March 1
**Priority:** High
**Budget:** $200

### Tasks

#### 1. Research Competitors
**Assigned to:** CMO
**Description:** Analyze 5 competitor websites and identify best practices
**Deliverable:** Competitor analysis report
**Budget:** $25

#### 2. Design Wireframes
**Assigned to:** CMO
**Depends on:** Research Competitors
**Description:** Create wireframes for homepage, about, and services pages
**Deliverable:** Figma wireframe files
**Budget:** $50

#### 3. Implement Frontend
**Assigned to:** Senior Engineer
**Depends on:** Design Wireframes
**Description:** Build responsive frontend using React and Tailwind
**Deliverable:** Deployed website code
**Budget:** $100

#### 4. Content Writing
**Assigned to:** Content Lead
**Depends on:** Research Competitors
**Description:** Write copy for all website pages
**Deliverable:** Website copy document
**Budget:** $25

Key features:

  • Dependencies between tasks
  • Budget allocation per task
  • Clear deliverables
  • Assignment to specific agents

GOVERNANCE.md — The Rules

Defines policies and controls:

# Governance Policies

## Budget Controls

### Company-wide
- Monthly maximum: $500
- Alert at 80% ($400)
- Hard stop at 100%

### Per-agent defaults
- Default monthly: $50
- Can be overridden in AGENTS.md

### Per-task defaults
- Maximum per task: $25
- Can be overridden per task

## Approval Gates

### Require approval:
- Code execution on production systems
- Database schema changes
- External API calls (non-sandbox)
- File deletion
- Spending over $20 in single operation

### Auto-approved:
- Research and analysis
- Content writing
- Internal file operations
- Testing in sandbox environment

## Escalation

### Escalate to human when:
- Budget exceeded
- Task fails 3 times
- Agent reports stuck/confused
- Ethical concerns flagged
- Security alert triggered

### Escalation contacts:
- Primary: ops@acme.com
- Emergency: +1-555-0123

Key concept: Governance prevents runaway costs and ensures safety.

How Paperclip Implements the Protocol

Paperclip is a reference implementation of the Agent Companies protocol. It:

1. Parses the markdown files

  • Reads COMPANY.md, AGENTS.md, TEAM.md, etc.
  • Validates structure against protocol schema
  • Loads configuration into runtime

2. Creates the agent runtime

  • Instantiates agents with configured adapters
  • Sets up communication channels between agents
  • Implements heartbeat scheduling

3. Enforces governance

  • Monitors budgets in real-time
  • Implements approval gates
  • Logs all actions for audit

4. Provides the dashboard

  • Visualizes company structure
  • Shows task progress
  • Displays budget usage
  • Enables manual overrides

Protocol vs Implementation

The Protocol (Agent Companies):

  • Vendor-neutral specification
  • Markdown file formats
  • Behavioral contracts
  • Interoperability standard

The Implementation (Paperclip):

  • One specific runtime
  • Could be self-hosted or managed
  • Adds features beyond protocol
  • Competing implementations possible

Analogy:

  • Protocol = HTML/CSS specification
  • Paperclip = Chrome browser
  • Other implementations = Firefox, Safari, Edge

Benefits of Using the Protocol

For Users

No vendor lock-in Your company definition works with any compatible platform. Switch providers or go self-hosted anytime.

Future-proof As the protocol evolves, your configuration remains valid. New features are additive.

Collaborative Technical and non-technical team members can both read and contribute to the company definition.

Auditable Git history shows exactly how your AI organization has changed over time.

For Developers

Build compatible tools Create agents, dashboards, or integrations that work with any Agent Companies-compatible platform.

Extend the ecosystem Add new skills, adapters, or governance modules that others can use.

Compete on implementation Focus on runtime performance, UX, or pricing while using the standard configuration format.

Who Created the Protocol?

The Agent Companies protocol emerged from the Paperclip project but is designed to be vendor-neutral. The specification is:

  • Open source: Available on GitHub
  • Community-driven: Accepts contributions via pull requests
  • Versioned: Changes follow semantic versioning
  • Documented: Full specification at agentcompanies.io

Key contributors:

  • Paperclip core team
  • Early adopters and power users
  • Framework developers (CrewAI, AutoGen communities)
  • Enterprise users with compliance needs

Related Protocols

Agent Companies extends Agent Skills:

  • Agent Skills defines individual capabilities (SKILL.md format)
  • Agent Companies adds organizational structure around those skills

Complementary protocols:

  • Model Context Protocol (MCP): Standard for tool/context sharing
  • A2A (Agent-to-Agent): Communication between agents from different vendors

Getting Started

1. Read the full specification: agentcompanies.io/specification

2. Try Paperclip: The reference implementation that supports Agent Companies

3. Join the community: GitHub Discussions for protocol questions

4. Build something: Create your first COMPANY.md and see how it works

Summary

Agent Companies protocol = markdown-based standard for AI agent organizations

Key benefits:

  • Portable across platforms
  • Version controlled in Git
  • Readable by technical and non-technical people
  • Auditable and reviewable

Paperclip = reference implementation

  • First platform to support the protocol
  • Available self-hosted or managed cloud
  • Can import/export Agent Companies packages

The future: Multiple implementations competing on features, performance, and price while using the same standard configuration format.

Learn more: Agent Companies Specification | Paperclip GitHub

← Back to Home