Agent Card 规范 · BossAgents 数字员工编排平台

概述

Agent Card 是 BossAgents 基于 AgentTeams 协同架构定义的智能体接入规范。任何第三方Agent只需声明一个JSON Card，即可接入 AgentTeams 的岗位编排体系，作为 Worker 节点与预置的 71 个数字员工协同工作。

规范定义

{
  "agent_id": "string",          // 全局唯一Agent标识
  "name": "string",              // Agent显示名称
  "description": "string",       // Agent能力描述
  "capabilities": ["string"],    // 能力标签列表
  "endpoint": "string",          // Agent的HTTP端点URL
  "auth": "api_key | oauth | none",  // 认证方式
  "protocol": "trace_span",      // 通信协议（固定trace_span）
  "metadata": {}                 // 扩展元数据
}

示例

BossAgents采购闭环Agent Card

{
  "agent_id": "bossagents-procurement-chain",
  "name": "BossAgents采购闭环",
  "description": "4步串行采购闭环：询价→比价→评估→审批",
  "capabilities": ["inquiry", "cost_analysis", "vendor_evaluation", "compliance_check"],
  "endpoint": "https://ylxt.chat/api/agents/dispatch",
  "auth": "api_key",
  "protocol": "trace_span"
}

外部Agent接入示例

{
  "agent_id": "exploreai-scout-001",
  "name": "ExploreAI竞品侦察兵",
  "description": "竞品分析与市场扫描",
  "capabilities": ["competitive_analysis", "market_scanning"],
  "endpoint": "https://api.exploreai.fun/agent/dispatch",
  "auth": "api_key",
  "protocol": "trace_span"
}

通信协议：trace_span

所有Agent通信基于 trace_span 协议，核心原则：

1. trace_id 全链路透传：从任务下发到结果回传，一个trace_id贯穿始终
2. span 自动记录：每个Agent的输入/输出/决策/耗时全部写入审计日志
3. customer_id 数据隔离：每个客户Agent只能访问授权范围内的数据

交互流程

平台                              外部Agent
  │                                  │
  │── POST /api/agents/dispatch ───→│  携带 customer_id + trace_id + task
  │                                  │
  │←─ POST /api/agents/callback ───│  回传 result + span数据
  │                                  │
  │── GET /api/agents/audit/:id ──→│  按trace_id查询完整审计链路

1. 任务分发

POST /api/agents/dispatch

请求：

{
  "customer_id": "exploreai",
  "task": "查询伺服电机SM-750A的市场价格趋势",
  "agent_card": {
    "agent_id": "exploreai-scout-001",
    "name": "ExploreAI竞品侦察兵",
    "capabilities": ["competitive_analysis", "market_scanning"],
    "endpoint": "https://api.exploreai.fun/agent/dispatch",
    "auth": "api_key"
  }
}

响应：

{
  "success": true,
  "trace_id": "dispatch-1786446519673",
  "status": "dispatched",
  "message": "任务已分发"
}

2. 结果回传

POST /api/agents/callback

请求：

{
  "trace_id": "dispatch-1786446519673",
  "agent_id": "exploreai-scout-001",
  "result": {
    "market_price_avg": 8500,
    "trend": "上涨5%",
    "competitors": ["A公司", "B公司"]
  },
  "span": 1
}

响应：

{
  "success": true,
  "trace_id": "dispatch-1786446519673",
  "status": "received"
}

3. 审计链路查询

GET /api/agents/audit/{trace_id}

响应：

{
  "success": true,
  "trace_id": "dispatch-1786446519673",
  "total_spans": 2,
  "spans": [
    {
      "span_index": 0,
      "timestamp": "2026-08-11T01:15:19Z",
      "agent_id": "exploreai",
      "action": "agent.dispatch",
      "input": "任务分发: 查询伺服电机SM-750A的市场价格趋势",
      "output": { "customer_id": "exploreai" },
      "decision": "任务分发: 查询伺服电机SM-750A的市场价格趋势"
    },
    {
      "span_index": 1,
      "timestamp": "2026-08-11T01:15:20Z",
      "agent_id": "exploreai-scout-001",
      "action": "agent.callback",
      "input": "结果回传: exploreai-scout-001",
      "output": { "result_summary": "{\"market_price_avg\":8500}" },
      "decision": "结果回传: exploreai-scout-001"
    }
  ]
}

Skill 接口规范

Agent Card 即 Skill 声明。每个 Agent Card 对应一个可复用的 Skill：

| Agent Card 字段 | Skill 语义 |

|----------------|-----------|

| capabilities | Skill 的能力标签，用于技能发现与匹配 |

| endpoint | Skill 的调用入口 |

| protocol | Skill 的通信协议（trace_span） |

| auth | Skill 的安全认证要求 |

Skill 的可复用性体现在：

• procurement-chain-worker 是一个"采购闭环 Skill"，可被任意岗位引用
• goai-agent-worker 是一个"GOAI 协同 Skill"，可跨场景复用
• inspect-loop-worker 是一个"巡检闭环 Skill"，可跨数据类型复用
• 外部 Agent Card 注册后同样成为可调度的 Skill 节点

错误处理

与预置员工的协同

外部Agent通过Agent Card注册后，可与BossAgents预置的71个数字员工协同工作：

1. 注册：通过 /api/agents/dispatch 提交Agent Card
2. 编排：在岗位YAML中引用外部Agent ID
3. 执行：岗位运行时，外部Agent与预置员工按编排顺序串行/并行执行
4. 审计：所有Agent的执行过程均记录到统一的trace_id/span审计链路

开源边界

• ✅ 开源（Apache License 2.0）：Agent Card规范、trace_span通信协议、dispatch/callback/audit三接口
• ✅ 开放：71个数字员工免登录体验（ylxt.chat）
• ❌ 不开源：工业知识图谱（73.9万关系）、规则引擎（2306条）、Schema-Aware增强层