Accord — Contract-First Multi-Service Orchestration

 █████╗  ██████╗ ██████╗ ██████╗ ██████╗ ██████╗
██╔══██╗██╔════╝██╔════╝██╔═══██╗██╔══██╗██╔══██╗
███████║██║     ██║     ██║   ██║██████╔╝██║  ██║
██╔══██║██║     ██║     ██║   ██║██╔══██╗██║  ██║
██║  ██║╚██████╗╚██████╗╚██████╔╝██║  ██║██████╔╝
╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚═════╝

Contract-First Multi-Service Orchestration

One hub. Many services. AI agents that
respect boundaries.

Accord coordinates AI agents across microservices using contracts as the source of truth. The Hub dispatches work, agents execute in their own repos, and Git tracks every change.

$ npm install -g @aion0/accord

$ accord-server start

✓ hub: http://localhost:3000 · 4 services discovered█

════════════════════════════════════════════════════════════════

# THE PROBLEM

You have 5 microservices, 3 AI agents, and 2 humans maintaining them. One team needs an API change that affects three services. Who coordinates? How do you track what changed? How do you make sure agents don't break each other's contracts?

Accord makes contracts the source of truth. Every service declares its API contract. Every change request is tracked. Every agent works within its service boundary.

────────────────────────────────────────────────────────────────

# HOW IT WORKS

  ┌─────────────────────────────────────────────────────────┐
  │  A C C O R D   H U B                                    │
  │                                                         │
  │  Dashboard · Dispatcher · Contract Registry · Audit     │
  └──────┬──────────────────┬─────────────────────┬─────────┘
         │                  │                     │
         ▼                  ▼                     ▼
  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
  │ demo-engine  │   │ device-mgr   │   │  frontend    │
  │              │   │              │   │              │
  │ maintainer:  │   │ maintainer:  │   │ maintainer:  │
  │ ai           │   │ ai           │   │ human        │
  │              │   │              │   │              │
  │ OpenAPI      │   │ OpenAPI      │   │ Internal     │
  │ contract     │   │ contract     │   │ contract     │
  │              │   │              │   │              │
  │ Claude Code  │   │ Claude Code  │   │ zhang@co.    │
  └──────────────┘   └──────────────┘   └──────────────┘

────────────────────────────────────────────────────────────────

# CORE CONCEPTS

📜 Contracts

Every service declares its API boundary via OpenAPI (external) and markdown (internal) contracts. Contracts live in Git. Changes are tracked, validated, and propagated to dependents.

OpenAPI for external APIs · Markdown for internal conventions · Git as source of truth

🔀 Dispatcher

The Hub receives change requests and routes them to the right service based on maintainer type. AI services get automated execution. Human services get notifications. Hybrid services need approval first.

dependency checking · exclusivity (one task per service) · priority sorting

🤖 Maintainer Types

Each service declares who maintains it. The dispatcher routes accordingly.

Fully automated. Agent receives task, executes, commits code, updates contract.

human

Developer gets notified (Slack/UI). Completes work manually, marks done.

hybrid

Agent prepares a plan. Human approves. Agent executes.

external

Cross-team. Request routed to another team's Hub.

📊 Dashboard

Real-time view of all services, pending requests, agent execution streams, contract diffs, and cost tracking. Approve or reject hybrid requests from the UI.

🔗 A2A Protocol

Built on the Agent-to-Agent protocol (Linux Foundation). Standard service discovery via Agent Cards, streaming execution via SSE, async notifications via webhooks. Any A2A-compatible agent can participate.

────────────────────────────────────────────────────────────────

# REQUEST LIFECYCLE

  Create Request          "Add GET /api/v1/policies to demo-engine"
       │
       ▼
  Dispatcher              check dependencies → check exclusivity → route
       │
       ├── maintainer: ai ──────────► Agent executes → commits → done
       │
       ├── maintainer: hybrid ──────► Agent plans → human approves → executes
       │
       └── maintainer: human ───────► Notification → human works → marks done
       │
       ▼
  Contract Update         OpenAPI patch validated → Git commit → notify dependents

────────────────────────────────────────────────────────────────

# SERVICE SETUP

  accord init --hub my-accord --team nac-team --service auth-service

  Creates:
    .accord/
    ├── service.yaml           # Service config
    ├── agent-card.json        # A2A Agent Card
    ├── contracts/
    │   ├── auth-service.yaml  # External API (OpenAPI)
    │   └── internal/
    │       └── token-api.md   # Internal contract
    └── a2a-server.ts          # A2A Server entry point

────────────────────────────────────────────────────────────────

# USE CASE

Accord was designed for a real project: re-architecting a network access control platform (FortiNAC) with 6 Java microservices, maintained by a mix of AI agents and human developers.

6 microservices (Java Spring Boot)

4 maintained by AI agents (Claude Code)

2 maintained by human developers

15+ OpenAPI contracts defining service boundaries

1 Hub coordinating all requests, contracts, and audit trails

════════════════════════════════════════════════════════════════

Contracts define boundaries. Agents respect them.

[ github ] [ npm ] [ blog ]