多Agent協作入門：基于A2A協議的Agent通信（中）

本文介紹了A2A的三個主要角色（User、Client 和 Remote Agent）和四個核心對象（Agent Card、Task、Artifact 和 Message），并通過簡單的例子介紹了A2A協議的典型工作流程，相信對于你加深了解A2A協議會有幫助。

大家好，我是Edison。

上一篇，我們了解了A2A協議的基本概念，還通過A2A組件實現了一個Hello World的Demo，有了一個快速的感性認識。這一篇，我們來了解下A2A協議的三大角色、四大對象以及工作流程，有了這些基礎的認知后會對我們全面認識A2A有所幫助。

A2A協議的三大角色

A2A 即 Agent-to-Agent，它定義了三個關鍵的角色，它們各司其職+互相配合，支撐多個Agent的運行。

那么，都是哪幾個角色呢？下面告訴你：

角色1：用戶（User）

即終端用戶（可能是人類或服務），需要使用Agent來完成某個任務。

角色2：客戶端（Client）

一個代表用戶向遠程Agent 發送請求的實體，它發送的請求是嚴格按照A2A協議的。它的表現形式可以是一個應用程序、服務或一個Agent。

例如，我們在上一篇的Demo中開發的一個控制臺應用程序通過引用A2A包來向遠端的Agent發送請求。

角色3：遠程Agent（Remote Agent）

一個執行實際任務的Agent（部署在某個遠端Server上），對于客戶端來說是“黑盒”一樣的存在，僅僅通過Agent Card聲明自己提供的接口或技能，但內部實現細節或工作機制是不透明的，即一個“黑盒”。

例如，我們在上一篇的Demo中開發的一個WebAPI項目EchoAgent，提供了一個ProcessMessage的技能以及聲明了一個AgentCard公開了一些元數據。

A2A的四大對象

A2A中定義了一套完整的對象體系，其中最核心的就是下面這四個核心對象：

第一個對象：Agent Card（又稱Agent名片）

每個A2A的遠程Agent都需要發布一個JSON格式的名片，被稱為“Agent Card”，用于描述這個Agent具有哪些技能及其認證機制，便于Client可以獲得這些信息并選擇合適的Agent來完成任務。

其實，它就和我們在做后端服務開發中的服務注冊和發現的機制差不多，只不過這個注冊的信息被標準化了，下面我們可以看看一個典型的Agent Card的JSON格式：

{
  "name": "Google Maps Agent",
  "description": "Plan routes, remember places, and generate directions",
  "url": "https://maps-agent.google.com",
  "provider": {
    "organization": "Google",
    "url": "https://google.com"
  },
  "version": "1.0.0",
  "authentication": {
    "schemes": "OAuth2"
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/html"],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "route-planner",
      "name": "Route planning",
      "description": "Helps plan routing between two locations",
      "tags": ["maps", "routing", "navigation"],
      "examples": [
        "plan my route from Sunnyvale to Mountain View",
        "what's the commute time from Sunnyvale to San Francisco at 9AM"
      ],
      "outputModes": ["application/html", "video/mp4"]
    }
  ]
}

這個JSON數據簡要描述了一個名為"Google Maps Agent"的Agent定義。這個Agent的主要功能是規劃路線、記住地點和生成導航指示。這個應用由Google提供，版本號是1.0.0，采用OAuth2身份驗證。它支持文本和HTML格式的輸入和輸出，具有流媒體功能，但不支持推送通知。它的一個核心技能是"route-planner"，可以幫助用戶規劃兩個地點之間的路線，并輸出HTML和視頻格式的內容。

在A2A .NET SDK中，AgentCard的定義如下：

public class AgentCard
{
    public string Name { get; set; }                    // 代理名稱

    public string Description { get; set; }            // 代理描述

    public string Url { get; set; }                     // 代理 URL

    public AgentProvider? Provider { get; set; }        // 提供商信息

    public string Version { get; set; }                 // 版本信息

    public AgentCapabilities Capabilities { get; set; } // 代理能力

    public List<AgentSkill> Skills { get; set; }        // 代理技能

    public List<string> DefaultInputModes { get; set; } // 默認輸入模式

    public List<string> DefaultOutputModes { get; set; }// 默認輸出模式
}

在上一篇的Demo中，我們在定義EchoAgent時，就實現了一個GetAgentCard方法，并將其注冊到服務發現中最終被Client探索發現時就會以JSON格式輸出給到Client：

public class EchoAgent
{
    public void Attach(ITaskManager taskManager)
    {
        taskManager.OnMessageReceived = ProcessMessageAsync;
        taskManager.OnAgentCardQuery = GetAgentCardAsync;
    }
    private Task<Message> ProcessMessageAsync(MessageSendParams messageSendParams, CancellationToken cancellationToken)
    {
        ......
    }
    private Task<AgentCard> GetAgentCardAsync(string agentUrl, CancellationToken cancellationToken)
    {
        return Task.FromResult(new AgentCard
        {
            Name = "Echo Agent",
            Description = "Echoes messages back to the user",
            Url = agentUrl,
            Version = "1.0.0",
            DefaultInputModes = ["text"],
            DefaultOutputModes = ["text"],
            Capabilities = new AgentCapabilities { Streaming = true }
        });
    }
}

與此同時，在Client中也可以主動進行服務發現，例如上一篇Demo中的Client示例代碼：

// Discover agent and create client
var cardResolver = new A2ACardResolver(new Uri("https://localhost:7243/"));
var agentCard = await cardResolver.GetAgentCardAsync();
var client = new A2AClient(new Uri(agentCard.Url));

第二個對象：Task （任務）

Task 是 Client 和遠程Agent 之間協作的一個概念，很好理解，一個Task代表一個需要完成的任務，每個Task都有一個唯一的ID號，它通常包含了任務狀態、歷史記錄和執行結果等信息。

Task的主要具體狀態有：submitted, working, completed, canceled, failed 等，下圖展示了Task的狀態機轉換流。

在A2A .NET SDK中，AgentTask的定義如下：

public class AgentTask : A2AResponse
{
    public string Id { get; set; }                      // 任務 ID
    public string? ContextId { get; set; }              // 上下文 ID
    public AgentTaskStatus Status { get; set; }         // 任務狀態
    public List<Artifact>? Artifacts { get; set; }      // 任務產出物
    public List<Message>? History { get; set; }         // 消息歷史
    public Dictionary<string, JsonElement>? Metadata { get; set; } // 元數據
}

第三個對象：Artifact（工件或成果）

Artifact 和我們在DevOps CI/CD流水線中的Artifact（即工件）的概念類似，它是遠程Agent執行完某個任務后生成輸出的結果（即遠程Agent返回的結果通過一個Artifact對象輸出給Client），每個任務的結果可能都不一樣。

一個Artifact可以包含多個部分（parts），每個部分（part）可以是：文本、文檔、圖像等，涉及純文本、文件和結構化數據。

第四個對象：Message（消息）

Message 也很好理解，它就是 Client 和遠程Agent 之間通信的一個消息對象，它通常包含了指令和狀態更新等內容。

同樣的，一個Message對象也可以包含多個parts，用于傳遞如文本、文件或結構化等不同類型的內容。每個Message都有發送方設置的一個唯一的messageId，且通過一些關鍵詞如"user"（代表Client發送的）或“agent”（代表服務端發送的）來區分角色。

在A2A .NET SDK中，Message的定義如下：

public class Message : A2AResponse
{
    public MessageRole Role { get; set; }               // 消息角色 (User/Agent)
    public List<Part> Parts { get; set; }               // 消息部分
    public string? MessageId { get; set; }              // 消息 ID
    public string? TaskId { get; set; }                 // 關聯任務 ID
    public string? ContextId { get; set; }              // 上下文 ID
    public Dictionary<string, JsonElement>? Metadata { get; set; } // 元數據
}

A2A協議的工作流程

這里我們來通過一個簡單的例子看看A2A協議的請求-響應工作流程是怎么樣的。

例如，有這樣一個場景“招聘XX崗位候選人搜尋”：

Step1，用戶在統一界面下向Client（假設它也是一個Agent）發送一個請求消息“請幫我尋找一個XX崗位的候選人”。

Step2，Client將用戶的請求消息進行封裝，并根據崗位需求依次調用一些遠程Agent如簡歷檢索Agent、技能篩選Agent 等等。

例如，下面的請求示例展示了Client在檢索了5位候選人簡歷之后通過A2A協議向遠端技能篩選Agent發送的任務請求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tasks/send",
  "params": {
    "id": "de38c76d-d54c-436c-8b9f-4c2703648d64",
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "請分析下面5位候選人是否符合崗位需求，并推薦最佳面試人選。"
        }
      ]
    },
    "metadata": {}
  }
}

Step3，各個遠端Agent執行各自的任務，并返回給Client對應的Artifact對象結果（如候選人名單等），然后再由Client進行匯總和展示。

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId": "c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status": {
      "state": "completed"
    },
    "artifacts": [
      {
        "name": "result",
        "parts": [
          {
            "type": "text",
            "text": "第三位候選人最符合你的需求!建議安排面試。"
          }
        ]
      }
    ],
    "metadata": {}
  }
}