Orchestrator A2A

The meta-agent for multi-agent orchestration. Discovers, routes, and coordinates tasks across all Craftpipe A2A agents — agent discovery, task routing, workflow execution, escalation chains, smart TF-IDF routing, health monitoring, and incident response.

Unlike other A2A products that expose domain-specific capabilities, the Orchestrator is the central coordinator that ties the entire agent fleet together.

Architecture

graph LR
    Client[AI Client] --> Orch[Orchestrator A2A<br/>Port 3010]
    Orch -->|discover| TF[TestForge A2A]
    Orch -->|route| DF[DocForge A2A]
    Orch -->|workflow| CG[ComplianceGuard A2A]
    Orch -->|health| SF[SchemaForge A2A]
    Orch -->|escalate| FO[FinanceOps A2A]
    Orch -->|smart-route| DP[DevPilot A2A]
    Orch -->|incident| CB[CRM Bridge A2A]
    Orch -.->|+ more| CV[CloudVault A2A]
    Orch -.->|+ more| LL[LogLens A2A]
    Orch -.->|+ more| SS[ShipStack A2A]

    style Orch fill:#4338ca,stroke:#6366f1,color:#f0f0ff
    style Client fill:#1e293b,stroke:#6366f1,color:#e2e8f0

Workflow Execution

sequenceDiagram
    participant C as Client
    participant O as Orchestrator
    participant A1 as Agent 1
    participant A2 as Agent 2

    C->>O: workflow-execute
    O->>A1: Step 1 (skill: test-scan)
    A1-->>O: output: {coverage: 85}
    O->>A2: Step 2 (input: $previous)
    A2-->>O: output: {readme: "..."}
    O-->>C: workflow completed (2/2 steps)

Quick Start

# Install globally
npm install -g orchestrator-a2a

# Start the orchestrator
orchestrator-a2a

# Or with initial agents
AGENT_URLS=http://localhost:3001,http://localhost:3002 orchestrator-a2a

Skills

| Skill | Description | Tier | |:------|:-----------|:-----| | agent-register | Register an A2A agent by URL, discover its capabilities | Free | | discover-agents | List registered agents with optional tag/name filtering | Free | | agent-health | Health check agents — ping /health, measure response time | Free | | route-task | Route a task to the correct agent by exact skill ID match | Free | | workflow-status | Get status of a workflow execution by ID | Free | | task-history | Query history of tasks routed through the orchestrator | Free | | capability-search | Search for capabilities across all agents by keyword | Free | | workflow-execute | Execute multi-step workflows with $previous data passing | Pro | | escalation-chain | Try agents in sequence with automatic fallback | Pro | | scheduled-workflow | Schedule workflows for future or recurring execution | Pro | | cross-agent-report | Aggregated report: health, capabilities, task history | Pro | | smart-routing | TF-IDF semantic matching — route by natural language | Pro | | incident-response | Automated incident analysis with severity-based workflows | Pro |

Usage Examples

Register an Agent

curl -X POST http://localhost:3010/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "agent-register",
    "params": { "url": "http://localhost:3001" }
  }'

Route a Task

curl -X POST http://localhost:3010/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 2,
    "method": "route-task",
    "params": {
      "skill_id": "pii-scan",
      "input": { "project_path": "/app" }
    }
  }'

Execute a Workflow (Pro)

curl -X POST http://localhost:3010/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 3,
    "method": "workflow-execute",
    "params": {
      "name": "Test & Document",
      "steps": [
        { "agent": "TestForge A2A", "skill": "test-scan", "input": { "project_path": "/app" }, "on_failure": "abort" },
        { "agent": "DocForge A2A", "skill": "generate-readme", "input": "$previous", "on_failure": "abort" }
      ]
    }
  }'

Smart Routing (Pro)

curl -X POST http://localhost:3010/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 4,
    "method": "smart-routing",
    "params": {
      "description": "scan my code for privacy and PII violations",
      "input": { "project_path": "/app" }
    }
  }'

Agent Card

curl http://localhost:3010/.well-known/agent.json

Health Check

curl http://localhost:3010/health

Environment Variables

| Variable | Description | Default | |:---------|:-----------|:--------| | PORT | Server port | 3010 | | AGENT_URLS | Comma-separated agent URLs to auto-register on startup | — | | PRO_LICENSE | License key for Pro skills | — |

How Smart Routing Works

The smart-routing skill uses TF-IDF (Term Frequency-Inverse Document Frequency) combined with cosine similarity to match natural language task descriptions to agent capabilities:

1. Tokenize the task description — lowercase, remove stop words, split on punctuation
2. Build corpus — one document per skill (name + description + tags) across all agents
3. Compute TF-IDF vectors for query and each skill document
4. Cosine similarity between query vector and each skill vector
5. Rank and route to the highest-scoring skill above the confidence threshold

No external LLM calls required — runs entirely in-process with zero latency overhead.

License

MIT