Agent Card Specification · BossAgents Digital Employee Orchestration Platform

Overview

The Agent Card is an agent access specification defined by BossAgents based on the AgentTeams collaborative architecture. Any third-party Agent can integrate into the AgentTeams role orchestration system by declaring a JSON Card, enabling it to work as a Worker node alongside 71 pre-built digital employees.

Specification Definition

{
  "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 Full-Link Transmission: A single trace_id persists from task assignment to result return.
2. span Automatic Recording: Input/output/decision/duration of each Agent is logged into the audit trail.
3. customer_id Data Isolation: Each customer's Agent can only access data within its authorized scope.

Interaction Flow

平台                              外部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

Request:

{
  "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

Request:

{
  "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}

Response:

{
  "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 Field | Skill Semantics |

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

| capabilities | Skill capability tags for skill discovery and matching |

| endpoint | Skill invocation endpoint |

| protocol | Skill communication protocol (trace_span) |

| auth | Skill security authentication requirements |

Skill reusability is demonstrated in:

• procurement-chain-worker is a "Procurement Closed-Loop Skill" that can be referenced by any role.
• goai-agent-worker is a "GOAI Collaborative Skill" reusable across scenarios.
• inspect-loop-worker is an "Inspection Closed-Loop Skill" reusable across data types.
• External Agent Cards, once registered, also become dispatchable Skill nodes.

Error Handling

Collaboration with Pre-built Digital Employees

After external Agents are registered via Agent Cards, they can collaborate with the 71 pre-built digital employees in BossAgents:

1. Registration: Submit Agent Card via /api/agents/dispatch
2. Orchestration: Reference the external Agent ID in the role YAML
3. Execution: During role runtime, external Agents and pre-built employees execute sequentially or in parallel according to the orchestration.
4. Audit: Execution processes of all Agents are recorded in a unified trace_id/span audit trail.

Open Source Boundaries

• ✅ Open Source (Apache License 2.0): Agent Card specification, trace_span communication protocol, three interfaces (dispatch/callback/audit).
• ✅ Open Access: 71 digital employees available for trial without login (ylxt.chat).
• ❌ Not Open Source: Industrial knowledge graph (739k relations), rule engine (2306 rules), Schema-Aware enhancement layer.