M12 Google ADK for Go 与 A2A 协议

        ┌─────────────────────┐         ┌─────────────────────────┐
        │   Eino (字节)        │         │  Google ADK for Go (谷歌) │
        │   ├── components     │         │  独立框架                  │
        │   ├── compose        │         │  A2A 官方参考实现          │
        │   └── adk  ←─────────┼─不是同一个─┼─►  这才是本章的 ADK       │
        │       (Eino 的子模块) │         │                          │
        └─────────────────────┘         └─────────────────────────┘

              ┌──────────────────────────────────────────────┐
              │   你的主 Agent（用某个 ADK 框架构建）            │
              │   ── Eino 或 Google ADK 都行 ──                │
              └───────┬───────────────────────────┬──────────┘
                      │ MCP（连工具/数据）           │ A2A（连别人的 Agent）
                      ▼                            ▼
            ┌──────────────────┐        ┌──────────────────────┐
            │ 数据库 MCP Server │        │ 外部物流 Agent         │
            │ 文件系统 MCP      │        │ (别家、Java写、另一台机)│
            └──────────────────┘        └──────────────────────┘

                    ┌────────────────────────────┐
                    │     Runner                 │  ← 跑 Agent 的运行时
                    │  (Query / Iterator / 事件)  │
                    └─────────────┬──────────────┘
                                  │ 跑
                                  ▼
                    ┌────────────────────────────┐
                    │      Agent                 │  ← 编排核心
                    │  llmagent.Config{...}      │
                    │  - Model                   │
                    │  - Tools                   │
                    │  - Instruction(系统提示) │
                    │  - Description(给 A2A 看) │
                    └─────────┬─────────┬────────┘
                              │         │
                              ▼         ▼
                    ┌──────────────┐  ┌──────────────┐
                    │   Model      │  │   Tool       │
                    │ (LLM 接口)   │  │ (能力接口)   │
                    │  gemini      │  │  trackingTool│
                    │  openai      │  │  搜索 / API  │
                    │  ollama      │  │  ...         │
                    └──────────────┘  └──────────────┘

ag, _ := llmagent.New(llmagent.Config{
    Name:        "logistics_agent",     // → AgentCard.name
    Description: "查询订单物流状态",     // → AgentCard.description
    Tools:       []tool.Tool{...},      // → AgentCard.skills(每个 tool 抽出一条 skill)
})

// ADK-Go 提供一个 Server 把 Agent 一键暴露为 A2A 服务
// 自动:
//   - GET /.well-known/agent-card.json  → 返回 AgentCard
//   - POST /a2a (SendMessage 等)        → 驱动 Agent 处理并返回 Task

// 在工具上要求"执行前需确认"（API 示意，以官方 pkg.go.dev 为准）：
// 注意：tool.Tool 是接口；函数工具用 functiontool.New 构造，
// 通过 functiontool.Config.RequireConfirmation 开启确认（不是 tool.New/Sensitive）。
refundTool, _ := functiontool.New(functiontool.Config{
    Name:               "refund",
    Description:        "发起退款",
    RequireConfirmation: true,        // ★ 关键标记：调用前需人工确认
}, refundHandler)

// Agent 调到该工具时（ADK-Go 的 Human-in-the-Loop 机制）:
// 1. 暂停执行,通过 tool.Context.RequestConfirmation 产出"等待确认"事件
//    （向客户端/UI 发一个 adk_request_confirmation 事件）
// 2. 状态可 checkpoint 落库
// 3. 收到 confirm 信号后,从 checkpoint 恢复执行
// 相关：tool/toolconfirmation 包；toolset 级的 tool.WithConfirmation 目前仍标 EXPERIMENTAL。

# logistics_agent.yaml
name: logistics_agent
model:
  type: gemini
  name: gemini-flash-latest
instruction: |
  你是物流查询助手,根据运单号返回物流状态。
description: 查询订单物流状态
tools:
  - track_shipment

import (
	"google.golang.org/adk/agent/llmagent"
	"google.golang.org/adk/model/gemini"
	"google.golang.org/adk/tool"
	"google.golang.org/genai"
)

model, _ := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{
	APIKey: os.Getenv("GOOGLE_API_KEY"),
})

ag, err := llmagent.New(llmagent.Config{
	Name:        "logistics_agent",
	Model:       model,
	Description: "查询订单物流状态",                  // 给别的 Agent 看的能力简介(A2A 会用到)
	Instruction: "你是物流查询助手,根据运单号返回物流状态。", // 系统提示词
	Tools:       []tool.Tool{trackingTool},
})

要做一个 Agent 项目
        │
        ├─ 内部复杂编排(多步骤、循环、并行)?
        │     │是 → Eino(编排能力最强)
        │
        ├─ 要把 Agent 对外发布给别人调用(A2A)?
        │     │是 → ADK-Go(原生支持,开箱即用)
        │
        ├─ 跨语言团队共用 Agent 定义?
        │     │是 → ADK-Go(YAML 跨语言对齐)
        │
        ├─ 已部署在 GCP / Vertex AI?
        │     │是 → ADK-Go(深度集成)
        │
        └─ 默认选项
              → Eino(国内生态最完整、生产级最成熟)

  ┌──── Agent A ────┐                    ┌──── Agent B ────┐
  │                 │  ──[SendMessage]─►│                 │
  │   Client Agent  │                    │   Server Agent  │
  │   (发起方)      │  ◄──[Task/状态]────│   (接收方)      │
  └─────────────────┘                    └─────────────────┘
         ↑↓                                       ↑↓
   也可能是别人的                              也可能反过来
   Server Agent                                Client Agent

{
  "name": "物流查询助手",
  "description": "根据运单号查询订单的实时物流状态",
  "version": "1.0.0",
  "capabilities": { "streaming": true, "pushNotifications": false },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "supportedInterfaces": [
    {
      "url": "https://logistics.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "track_shipment",
      "name": "物流跟踪",
      "description": "输入运单号，返回当前物流状态与轨迹",
      "tags": ["logistics", "tracking"]
    }
  ],
  "signatures": [
    {
      "protected": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9",
      "signature": "..."
    }
  ]
}

                 ┌───────────────► TASK_STATE_CANCELED
                 │     (被取消)
                 │
TASK_STATE_SUBMITTED ──► TASK_STATE_WORKING ──┬──► TASK_STATE_COMPLETED   (顺利完成,有 artifacts)
   (已提交)              (处理中)              │
                                              ├──► TASK_STATE_FAILED      (失败,有 error 信息)
                                              │
                                              ├──► TASK_STATE_REJECTED    (Agent 拒绝执行)
                                              │
                                              ├──► TASK_STATE_AUTH_REQUIRED (需要鉴权)
                                              │
                                              └──► TASK_STATE_INPUT_REQUIRED (需要发起方补充信息)
                                                       │
                                                       └──► (发起方补充后) 回到 TASK_STATE_WORKING

Agent 内部"暂停等确认"
       ⟷
协议上"Task 处于 input-required"
       ⟷
发起方"看到这个状态,去拿到人工输入,再回传"

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-req-01",
      "role": "ROLE_USER",
      "parts": [{ "text": "查一下运单 SF1234567890 的物流" }]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "message": {
      "messageId": "msg-aa11",
      "role": "ROLE_AGENT",
      "parts": [{ "text": "运单 SF1234567890 已签收,签收人:张三,2026-05-30 14:22" }]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "task": {
      "id": "task-789",
      "contextId": "ctx-456",
      "status": { "state": "TASK_STATE_WORKING", "timestamp": "2026-05-30T14:22:00Z" },
      "history": [{"role": "ROLE_USER", "parts": [{"text": "查一下运单..."}]}]
    }
  }
}

// 客户端 GetTask
// 响应:Task 处于 input-required 状态,带询问消息
// 注意:GetTask 的 result 直接是 Task 对象(没有 SendMessage 那种 oneof 包装)
{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "id": "task-789",
    "status": {
      "state": "TASK_STATE_INPUT_REQUIRED",
      "message": {
        "messageId": "msg-ask-01",
        "role": "ROLE_AGENT",
        "parts": [{"text": "找到 3 个匹配,请确认查哪个:[A] / [B] / [C]"}]
      }
    }
  }
}

// 客户端拿到用户选择,继续 SendMessage 同一个 task
{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-reply-01",
      "role": "ROLE_USER",
      "parts": [{"text": "查 [A]"}],
      "taskId": "task-789"     // 关联到现有 task
    }
  }
}

// 服务端：把 12.3 定义的 ag 暴露为 A2A 服务（API 示意，以官方为准）
// ADK-Go 会据 ag 的 Name/Description/Tools 自动生成 AgentCard，
// 并起一个 HTTP 服务处理 A2A 的 JSON-RPC 方法。
//   - GET  /.well-known/agent-card.json  → 返回 AgentCard
//   - POST /a2a (SendMessage 等)        → 驱动 ag 处理并返回 Task

package a2a

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/yourname/llmagent/internal/transport" // 复用 M01 的 HTTP 客户端
)

type Skill struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

// AgentInterface 是 v1.0 supportedInterfaces[] 里的一项：一个可连端点 + 它的协议绑定。
type AgentInterface struct {
	URL             string `json:"url"`
	ProtocolBinding string `json:"protocolBinding"` // JSONRPC / GRPC / HTTP+JSON
	ProtocolVersion string `json:"protocolVersion"`
}

type AgentCard struct {
	Name                string           `json:"name"`
	Description         string           `json:"description"`
	Version             string           `json:"version"`
	SupportedInterfaces []AgentInterface `json:"supportedInterfaces"`
	URL                 string           `json:"url"` // v0.x 兼容：老卡片把端点放顶层
	Skills              []Skill          `json:"skills"`
}

// JSONRPCEndpoint 从名片里挑出 JSON-RPC 绑定的端点（挑不到就回退到老的顶层 url）。
// 这正是"先取卡、再按绑定选端点、最后才发消息"流程里的一步。
func (c *AgentCard) JSONRPCEndpoint() string {
	for _, it := range c.SupportedInterfaces {
		if it.ProtocolBinding == "JSONRPC" {
			return it.URL
		}
	}
	return c.URL // 兼容 v0.x 单 url
}

// FetchAgentCard 从对方的 well-known 路径拉取名片。
func FetchAgentCard(ctx context.Context, baseURL string) (*AgentCard, error) {
	url := baseURL + "/.well-known/agent-card.json"
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}
	resp, err := transport.NewClient().Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("拉取 AgentCard 失败: 状态码 %d", resp.StatusCode)
	}
	var card AgentCard
	if err := json.NewDecoder(resp.Body).Decode(&card); err != nil {
		return nil, err
	}
	return &card, nil
}

package a2a

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/yourname/llmagent/internal/transport"
)

type TaskStatus struct {
	// PROTO 枚举名:TASK_STATE_SUBMITTED / TASK_STATE_WORKING /
	// TASK_STATE_INPUT_REQUIRED / TASK_STATE_COMPLETED / TASK_STATE_FAILED / ...
	State string `json:"state"`
}

type Task struct {
	ID     string     `json:"id"`
	Status TaskStatus `json:"status"`
	// 实际还有 artifacts、history 等，按需补充
}

// Message 是即时回复形态：短问题服务端可能直接回一条消息，而不建 Task。
type Message struct {
	MessageID string `json:"messageId"`           // A2A 1.0 必填
	Role      string `json:"role"`                // 通常是 "ROLE_AGENT"
	Parts     []struct {
		Text string `json:"text"`
	} `json:"parts"`
}

// SendResult：SendMessage 的结果可能是 Task（长任务，要跟踪状态机）或 Message（即时回复）。
// A2A 1.0 不保证永远返回 Task——两种都得能接，否则客户端只适配你假想的那种服务端。
type SendResult struct {
	Task    *Task
	Message *Message
}

// uuidNew 生成一个新 messageId（业务代码中可换成 google/uuid）。
func uuidNew() string { /* ... 略 ... */ return "msg-uuid-placeholder" }

// SendMessage 向某个 A2A Agent 的端点发送一条消息，返回结果（Task 或 Message）。
// 严格按 A2A 1.0 JSON-RPC binding 实现：messageId 必填、role 用 PROTO 枚举名、
// 必带 A2A-Version 头、result 内 oneof task/message。
func SendMessage(ctx context.Context, endpoint, text string) (*SendResult, error) {
	reqBody := map[string]any{
		"jsonrpc": "2.0",
		"id":      "1",
		"method":  "SendMessage",
		"params": map[string]any{
			"message": map[string]any{
				"messageId": uuidNew(),                                    // A2A 1.0：必填
				"role":      "ROLE_USER",                                  // 1.0 PROTO 枚举名
				"parts":     []map[string]any{{"text": text}},              // 1.0：靠成员存在区分类型，无 kind
			},
		},
	}
	data, _ := json.Marshal(reqBody)
	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(data))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("A2A-Version", "1.0") // 1.0 规范 §3.6.1：Client MUST 带该头

	resp, err := transport.NewClient().Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	// A2A 1.0 §9.4.1：result 是 SendMessageResponse，其内 oneof：task 或 message。
	var rpcResp struct {
		Result struct {
			Task    *Task    `json:"task,omitempty"`
			Message *Message `json:"message,omitempty"`
		} `json:"result"`
		Error *struct {
			Code    int    `json:"code"`
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&rpcResp); err != nil {
		return nil, err
	}
	if rpcResp.Error != nil {
		return nil, fmt.Errorf("A2A 错误 %d: %s", rpcResp.Error.Code, rpcResp.Error.Message)
	}

	switch {
	case rpcResp.Result.Task != nil:
		return &SendResult{Task: rpcResp.Result.Task}, nil
	case rpcResp.Result.Message != nil:
		return &SendResult{Message: rpcResp.Result.Message}, nil
	default:
		return nil, fmt.Errorf("A2A 响应 result 既无 task 也无 message")
	}
}

// 注:v0.3.x JSON-RPC binding 曾用 result 顶层 kind="task"|"message" 字段或靠
// "有没有 status" 这种结构差异区分;A2A 1.0 已废弃,统一为 result.task / result.message
// oneof 包装。新代码按上面 switch 写,不要再做 kind / status 探测。

func RemoteAgentTool(name, endpoint, desc string) tool.Tool {
	return tool.NewTypedTool(name, desc,
		func(ctx context.Context, a struct {
			Request string `json:"request" desc:"要委托给远程 Agent 处理的请求"`
		}) (string, error) {
			res, err := SendMessage(ctx, endpoint, a.Request)
			if err != nil {
				return "", err
			}
			switch {
			case res.Message != nil: // 即时回复：拼出文本直接返回
				text := ""
				for _, p := range res.Message.Parts {
					text += p.Text
				}
				return text, nil
			case res.Task != nil:
				// 简化：真实实现要按 res.Task.Status.State 处理
				// TASK_STATE_INPUT_REQUIRED / 轮询 TASK_STATE_WORKING / 终态 TASK_STATE_COMPLETED 等
				return fmt.Sprintf("远程任务 %s 状态: %s", res.Task.ID, res.Task.Status.State), nil
			default:
				return "", fmt.Errorf("A2A: 空结果")
			}
		})
}

要对接一个外部依赖
        │
        ├─ 它是"被动的能力"吗？（给输入→拿输出，无自主性、无多轮状态）
        │        │是
        │        └─► 用 MCP（当工具）。例：数据库、文件系统、搜索 API
        │
        └─ 它是"主动的 Agent"吗？（有自主决策、可能多轮/中途要信息/长时异步）
                 │是
                 └─► 用 A2A（当对等 Agent）。例：外部物流 Agent、风控 Agent