va-agent-protocol

English README

AI 智能体的 USB 接口 — 调度、验证、编排。

┌─────────────────────────────────────────┐
│  Orchestrator                           │
│  (dispatch, schedule, monitor, retry)   │
└──────────────────┬──────────────────────┘
                   │  ← va-agent-protocol
┌──────────────────┴──────────────────────┐
│  ┌───────────┐ ┌──────────┐ ┌─────────┐│
│  │ Claude    │ │ Codex    │ │ Your    ││
│  │ Code      │ │          │ │ Agent   ││
│  └───────────┘ └──────────┘ └─────────┘│
│          Any CLI agent                   │
└──────────────────────────────────────────┘

立即体验

npx va-orchestrate agents --project-root .

协议对比

va-agent-protocol 与 MCP 和 A2A 的关系如何？它们是互补的，而非竞争关系：

| 维度 | MCP (Anthropic) | A2A (Google) | va-agent-protocol | |------|----------------|-------------|-------------------| | 关注点 | 工具级上下文 | 智能体发现 + 协调 | 长任务执行 + 证据验证 | | 任务类型 | 短同步工具调用 | 发现 + 路由 | 长任务 + 自动拓扑 + 调度器 | | 时间模型 | 同步 | 异步（推送） | 异步（轮询；v0.2 推送） | | 验证 | 返回值 = 结果 | 弱验证 | CLI 关卡 + 模型评估 + 陷阱机制 | | 编排 | 无 | 基本路由 | 拓扑排序 + 能力匹配 + 并发控制 | | 失败学习 | 无 | 无 | 陷阱积累 | | 互操作 | — | 兼容 MCP | 与 MCP 和 A2A 互补 |

一句话总结 — MCP 将模型连接到工具。A2A 将智能体连接到智能体。va-agent-protocol 确保工作真正被正确完成。

为什么需要它

AI 智能体可以自主编写代码、审查代码和测试代码。但每个智能体都有自己的接口。目前没有标准方法来：

• 调度任务给智能体，附带目标和约束条件
• 监控智能体工作时的实时进度
• 收集证据证明任务确实完成了（而不仅仅是自我认证）
• 重试并附带先前失败的上下文
• 组合具有不同能力的多个智能体

va-agent-protocol 通过基于 JSON Schema 的契约解决了这个问题 — 遵循规范，你的智能体就能接入任何编排器。

前沿模型为何需要它

2026 年的前沿模型（Claude Opus 4.6、GPT-5.3-codex 或同等模型）带来了非凡的能力：自主多步推理、百万 token 上下文窗口和原生工具调用。va-agent-protocol 旨在放大这些优势并防范遗留的弱点。

放大优势

• 目标驱动的委派 — 任务定义要实现什么（WHAT），而不是如何实现（HOW）。模型的推理能力得到充分释放。
• 并行任务调度 — 编排器并发调度独立任务，充分利用前沿模型原生的并行工具编排能力。
• 长上下文感知 — 任务契约、陷阱指南和证据载荷专为能够在上下文中容纳整个项目的模型而设计。

防范弱点

• 证据关卡防止幻觉 — 智能体无法自我认证完成。CLI 命令和模型评估关卡产生客观的通过/失败信号。"我认为完成了"不等于"确实完成了"。
• 陷阱积累防止重复犯错 — 来自过去尝试的结构化失败元数据被作为硬约束注入重试。系统随时间推移变得越来越难以欺骗。
• 模型评估关卡 — 对于主观质量（代码风格、内容语调），AI 评审者使用分数阈值和三级决策（通过 / 阻塞待人工审核 / 失败+重试）。

一句话： 信任模型的推理能力；使用确定性机制捕捉其盲点。

设计原则

继承自 va-auto-pilot：

1. 目标驱动，而非步骤驱动 — 任务定义要实现什么（WHAT），而不是如何实现（HOW）
2. CLI 优先 — 智能体通过子进程调用，而非库导入
3. 基于证据的完成 — 用关卡结果和产出物"证明完成"，而非"相信我"
4. 约定优于配置 — 遵循 JSON Schema，即可兼容
5. 失败知识积累 — 每次重试都会收到先前失败的陷阱信息

快速开始

npm install va-agent-protocol

1. 定义任务

import type { TaskUnit } from "va-agent-protocol";

const task: TaskUnit = {
  id: "TASK-001",
  objective: "Implement user authentication with JWT",
  constraints: [
    "Use bcrypt for password hashing",
    "Tokens expire in 24 hours",
  ],
  acceptanceCriteria: [
    "npm run typecheck passes",
    "npm test passes with all auth tests",
    "No CRITICAL findings in code review",
  ],
  priority: "P1",
};

2. 实现适配器（或使用内置适配器）

适配器是"USB 插头" — 它在协议和你的智能体 CLI 之间进行转换：

import type {
  AgentAdapter,
  AgentCapability,
  DispatchResult,
  PollResult,
  TaskUnit,
} from "va-agent-protocol";
import { generateCorrelationId } from "va-agent-protocol";

class MyAgentAdapter implements AgentAdapter {
  readonly id = "my-agent";

  capabilities(): AgentCapability {
    return {
      agentId: this.id,
      name: "My Custom Agent",
      version: "1.0.0",
      capabilities: ["code-generation", "testing"],
      modelRequirement: "frontier",
      interface: {
        type: "cli",
        command: "my-agent-cli",
      },
      constraints: {
        maxConcurrent: 2,
        maxRetries: 3,
      },
    };
  }

  async dispatch(task: TaskUnit): Promise<DispatchResult> {
    const correlationId = generateCorrelationId();
    // Spawn your agent process here
    return { correlationId, accepted: true };
  }

  async poll(correlationId: string): Promise<PollResult> {
    // Check your agent's state
    return {
      correlationId,
      state: "running",
      progress: {
        taskId: "TASK-001",
        phase: "implementing",
        summary: "Writing authentication middleware...",
        completionEstimate: 0.4,
        logs: [{
          timestamp: new Date().toISOString(),
          level: "info",
          message: "Created src/auth/middleware.ts",
        }],
        data: { linesWritten: 87 },
      },
    };
  }

  async cancel(correlationId: string): Promise<void> {
    // Kill the agent process
  }
}

3. 编排

import {
  AgentRegistry,
  Orchestrator,
} from "va-agent-protocol";

const registry = new AgentRegistry();
registry.register(new MyAgentAdapter());

const orchestrator = new Orchestrator(registry, {
  pollIntervalMs: 3000,
  maxRetries: 3,

  onProgress: (taskId, progress) => {
    console.log(`${taskId}: ${progress.phase} (${Math.round((progress.completionEstimate ?? 0) * 100)}%)`);
  },

  onCompleted: (taskId, evidence) => {
    console.log(`${taskId} completed!`);
    for (const gate of evidence.gateResults ?? []) {
      console.log(`  ${gate.passed ? "✓" : "✗"} ${gate.gate}`);
    }
  },

  onFailed: (taskId, evidence) => {
    console.error(`${taskId} failed: ${evidence.failureDetail?.hypothesis}`);
  },

  onBlocked: (taskId, reason) => {
    console.log(`${taskId} needs human input: ${reason}`);
  },
});

orchestrator.enqueue(task);
orchestrator.start();

协议 Schema

协议由 schemas/ 目录中的 5 个 JSON Schema 定义：

| Schema | 用途 | |--------|------| | task-unit.schema.json | 通用任务契约（目标 + 约束 + 验收标准） | | agent-capability.schema.json | 智能体自描述（能力、接口、约束） | | lifecycle.schema.json | 任务状态机和有效转换 | | evidence.schema.json | 完成证明（关卡结果、产出物、失败详情） | | message.schema.json | 编排器与智能体之间的通信信封 |

任务生命周期

pending → running → completed
            ↓
          blocked → running (after human input)
            ↓
          failed → running (retry with pitfall context)

基于证据的完成

任务不能自我认证完成。它们必须提供证据：

{
  "taskId": "TASK-001",
  "status": "completed",
  "gateResults": [
    {
      "gate": "typecheck",
      "command": "npm run typecheck",
      "exitCode": 0,
      "passed": true,
      "durationMs": 1200
    },
    {
      "gate": "unit-tests",
      "command": "npm test",
      "exitCode": 0,
      "passed": true,
      "output": "42 tests passed, 0 failed"
    }
  ],
  "artifacts": [
    { "type": "commit", "path": "a1b2c3d", "description": "Implement JWT auth" }
  ],
  "verification": "All 3 quality gates passed."
}

模型评估关卡

并非所有质量关卡都是 CLI 命令。对于主观或 AI 评判的评估（风格一致性、代码质量评分、内容审查），关卡支持 model-evaluation 类型：

{
  "gate": "style-consistency",
  "type": "model-evaluation",
  "evaluator": "style-similarity-agent",
  "score": 0.85,
  "threshold": 0.8,
  "softThreshold": 0.65,
  "passed": true,
  "rationale": "Sentence rhythm and vocabulary match. Tone slightly more formal."
}

当 passed: false 时，severity 字段控制响应：

• "error" — 硬失败（编排器重试）
• "warning" — 软失败（编排器可能路由到 blocked 状态以供人工审核）

softThreshold 启用三级决策：低于软阈值 = 失败+重试，介于软阈值和硬阈值之间 = 阻塞待人工审核，高于硬阈值 = 通过。

任务输入/输出

任务可以声明类型化的输入和输出。编排器自动解析依赖任务之间的数据引用：

const extractSchema: TaskUnit = {
  id: "SCHEMA-001",
  objective: "Extract API schema definitions",
  outputContract: { keys: ["apiSchema"] },  // Declares what this task produces
  // ...
};

const generateClient: TaskUnit = {
  id: "CLIENT-001",
  dependsOn: ["SCHEMA-001"],
  inputs: {
    schema: { fromTask: "SCHEMA-001", outputKey: "apiSchema" },  // Resolved by orchestrator
    language: "typescript",  // Static input
  },
  // ...
};

失败 → 陷阱 → 重试

当任务失败时，编排器捕获结构化的失败元数据，并将其作为 pitfalls 注入重试上下文：

Attempt 1: Agent implements feature → tests fail on edge case
    ↓ failureDetail captured
Attempt 2: Agent receives pitfall context →
    "Previous attempt failed: missing null check for empty array input"
    → Agent handles edge case → tests pass

进度报告

智能体通过 ProgressPayload 报告进度：

{
  taskId: "TASK-001",
  phase: "implementing",           // Current execution phase
  summary: "Writing auth module",  // Human-readable status
  completionEstimate: 0.4,         // 0.0 → 1.0
  logs: [{                         // Structured log entries
    timestamp: "2026-02-24T...",
    level: "info",
    message: "Created src/auth/middleware.ts"
  }],
  data: {                          // Arbitrary structured data
    linesWritten: 87,
    currentFile: "src/auth/middleware.ts"
  }
}

多智能体调度

注册具有不同能力的智能体。调度器将任务匹配到最合适的智能体：

registry.register(codeAgent);     // capabilities: ["code-generation", "testing"]
registry.register(reviewAgent);   // capabilities: ["code-review", "security-audit"]

// Scheduler auto-routes:
// "Implement feature X" → codeAgent (matched "code-generation")
// "Audit API security"  → reviewAgent (matched "security-audit")

并发限制会被遵守。如果智能体达到最大容量，任务会排队等待空位。

任务依赖

任务可以声明依赖关系。编排器按拓扑顺序调度它们：

const tasks = [
  { id: "TASK-001", objective: "Build core module", ... },
  { id: "TASK-002", objective: "Add tests", dependsOn: ["TASK-001"], ... },
  { id: "TASK-003", objective: "Write docs", ... }, // No deps, runs in parallel
];

orchestrator.enqueue(...tasks);
// TASK-001 and TASK-003 dispatch immediately (parallel)
// TASK-002 waits for TASK-001 to complete

内置适配器：va-auto-pilot

第一个适配器封装了 va-auto-pilot 的 sprint-board CLI：

import { VaAutoPilotAdapter, AgentRegistry, Orchestrator } from "va-agent-protocol";

const adapter = new VaAutoPilotAdapter({
  projectRoot: "/path/to/your/project",
});

const registry = new AgentRegistry();
registry.register(adapter);

CLI

# List registered agents
npx va-orchestrate agents --project-root ./my-project

# Dispatch a task from JSON file
npx va-orchestrate dispatch --task task.json --project-root ./my-project

运行示例

npm run example

这将展示多智能体注册、能力匹配、任务依赖排序、实时进度、质量关卡证据、失败 → 陷阱 → 重试、阻塞状态上报以及实时终端仪表板。

实现你自己的适配器

适配器是"USB 插头" — 是你为使智能体兼容协议而编写的唯一代码。实现 AgentAdapter 接口：

import type {
  AgentAdapter,
  AgentCapability,
  DispatchResult,
  PollResult,
  TaskUnit,
} from "va-agent-protocol";
import { generateCorrelationId } from "va-agent-protocol";

class MyAgentAdapter implements AgentAdapter {
  readonly id = "my-agent";

  capabilities(): AgentCapability {
    return {
      agentId: this.id,
      name: "My Agent",
      version: "1.0.0",
      capabilities: ["code-generation"],
      interface: { type: "cli", command: "my-agent-cli" },
      constraints: { maxConcurrent: 2 },
    };
  }

  async dispatch(task: TaskUnit): Promise<DispatchResult> {
    const correlationId = generateCorrelationId();
    return { correlationId, accepted: true };
  }

  async poll(correlationId: string): Promise<PollResult> {
    return { correlationId, state: "running" };
  }

  async cancel(correlationId: string): Promise<void> {}
}

完整的实际示例请参见 src/adapter/codex-adapter.ts。

架构

va-agent-protocol/
├── schemas/                    # JSON Schema definitions (THE SPEC)
│   ├── task-unit.schema.json
│   ├── agent-capability.schema.json
│   ├── lifecycle.schema.json
│   ├── evidence.schema.json
│   └── message.schema.json
├── src/
│   ├── types/                  # TypeScript types (mirror schemas)
│   ├── adapter/                # Agent adapter interface + implementations
│   │   ├── agent-adapter.ts        # The "USB plug shape"
│   │   ├── codex-adapter.ts        # OpenAI Codex CLI adapter
│   │   └── va-auto-pilot-adapter.ts
│   ├── orchestrator/           # Dispatch loop + scheduling
│   │   ├── registry.ts             # Agent discovery
│   │   ├── scheduler.ts            # Task → agent matching
│   │   └── orchestrator.ts         # Core loop
│   └── utils/
│       └── logger.ts               # Configurable logger interface
├── examples/
│   └── full-lifecycle.ts       # Comprehensive demo
└── bin/
    └── va-orchestrate.mjs      # CLI entry point

路线图

v0.2

• MCP 服务器适配器 — 将 va-agent-protocol 作为 MCP 工具服务器暴露
• 持久化 — 基于 SQLite 的编排器状态，支持崩溃恢复
• 推送式进度 — 智能体通过 stdio/WebSocket 主动推送进度，替代轮询
• 子编排 — 智能体可以生成子任务，反馈回编排器
• Web 仪表板 — 实时任务可视化和监控
• 扩展点 — 更多 Schema 对象上的 metadata 字段，放宽 additionalProperties

v0.3

• REST / gRPC 适配器，用于非 CLI 集成
• 治理 — 成本护栏 + 权限范围控制
• A2A 桥接 — 与 Google A2A 的双向智能体发现和任务委派

未来

• 多语言 SDK — Python、Go 协议实现
• 分布式编排 — 多个编排器实例共享状态
• 适配器生态系统 — Claude Code、Cursor、Aider 及其他 CLI 智能体适配器
• Agentic AI Foundation 贡献

v0.1 已知限制

这些是 v0.1 的有意范围约束，不是 bug：

• 仅内存状态 — 持久化/恢复计划在 v0.2 实现
• 基于轮询的进度 — 智能体主动推送计划在 v0.2+ 实现
• 严格 Schema — additionalProperties: false；v0.2 将引入扩展点
• 无子编排 — v0.2+ 功能
• 单一调度启发式 — 能力匹配使用关键词推断；生产部署应提供显式能力标签

许可证

MIT