A2A 协议实战：Python 与 Go Agent 跨语言协作

A2A 协议实战：Python 与 Go Agent 跨语言协作 | 前端进阶之旅

Full translation

完整中文译文

Python Agent 与 Go Agent 如何使用 Agent2Agent 协议协作完成合同合规审查

你的合同合规流水线遇到了一个问题。数据科学团队用 Python 编写了一个出色的提取 Agent。它使用 Gemini 解析法律合同，并提取其中的每一项关键条款。安全工程团队则用 Go 构建了一个速度极快的合规验证器，完全采用确定性逻辑，不使用 LLM。这两个系统各自独立运行时都表现完美。但现在，你需要让它们协同工作，形成一条统一编排的流水线，而两个团队都不愿意使用另一种语言重写自己的服务。

这就是生产级 AI 系统的现实：不同的团队、不同的语言、不同的部署目标。问题不在于你是否会遇到这种情况，而在于你将如何解决它。

本文将构建一条合同合规多 Agent 流水线：Python Agent 使用 Gemini 提取合同条款，Go Agent 根据公司政策验证这些条款。两个服务通过 Agent2Agent（A2A）协议连接，并由 Google 的 Agent Development Kit（ADK）进行编排。

在这个过程中，你将学到三种架构模式。正是这些模式，将生产级多 Agent 系统与单语言演示项目区分开来：

使用 A2A 协议实现跨语言 Agent 协作，让团队能够针对具体任务选择最适合的语言来构建 Agent，无需重写代码。
使用 ADK 的 RemoteA2aAgent 抽象，只需几行代码，就能将任意远程、兼容 A2A 的服务转换为本地子 Agent。
使用多 Agent 流水线编排，让职责单一的专业 Agent 取代试图包办一切的单体 prompt。

完整源代码可在 GitHub 上获取。

一个 Agent 不够用时

大多数 AI 项目的起点都一样：一个庞大的 Agent、一段巨型 prompt，以及塞进同一个上下文窗口的所有工具。演示时，它确实能跑起来；但到了生产环境，它会因为三个关键原因迅速崩溃：

上下文退化： 当工具数量增加到 10～15 个以上时，模型就会开始遗漏指令、调用错误的工具，或者臆造参数。每增加一个工具，模型的注意力就会被分散到更大的范围。一个既要负责合同提取，又要处理翻译、摘要和邮件起草的 Agent，最终一定会搞不清楚什么时候该调用哪个工具。

爆炸半径： 一个次要功能中未处理的异常，就可能导致整个 Agent 回合崩溃。翻译 API 遭遇限流，本不应该让整套工作流停摆。但在单体 Agent 中，任何局部故障都会演变成全局故障。

无法测试： 你无法对一个纠缠着 50 项职责的系统进行清晰的单元测试。只要每次修改 prompt 都可能影响所有下游行为，回归评估就只能靠猜。

解决方案与十年前改变后端工程的模式相同：把单体系统拆解成专业化的微服务。每个 Agent 只负责一项工作，使用聚焦的 prompt 和最精简的工具集。

A2A 协议：Agent 如何发现彼此并进行通信

Agent-to-Agent（A2A）协议是一项开放标准，它使使用任意语言或框架构建的 Agent 都能相互协作。可以把它看作 Agent 世界里的 HTTP：一份共享契约，让任意两个 Agent 都能通信，而不必关心对方内部是如何构建的。

A2A 解决了三个基础问题：

发现： Agent 通过 Agent Card 对外声明自己的能力。Agent Card 是由 /.well-known/agent.json 提供的 JSON 元数据。它与 REST API 的 OpenAPI 规范类似，声明了 Agent 的名称、URL、版本、技能，以及支持的输入和输出格式。调用方 Agent 会先获取这张卡片，以了解远程 Agent 能做什么。

通信： 所有数据交换都通过 JSON-RPC 2.0 完成，并经由单一端点路由。Agent 通信的核心方法是 message/send，我们的实现使用它提交合同数据并同步接收结果。此外，协议还提供了 tasks/send 和 tasks/get 等方法，用于提交和获取任务。数据封装在带类型的 Message Part 中传输：自然语言使用 TextPart，结构化 JSON 使用 DataPart。

任务生命周期： 每次交互都会封装在一个 Task 中，并在一组定义明确的状态之间流转：submitted、working、completed 或 failed。借助这个状态机，Agent 可以使用同一套协议处理同步工作流（立即检查这份合同）和异步工作流（在 48 小时内核验这份文档）。

这种方法的妙处在于，任何一个 Agent 都不需要了解另一个 Agent 的实现细节。Python Agent 不需要导入 Go package，Go Agent 也不需要运行 Python 代码。它们只需通过 HTTP 使用共同的协议交流。

Agent Card 实际长什么样

下面是 Go 合规服务通过 /.well-known/agent.json 暴露的 Agent Card：

// go-compliance-agent/internal/agentcard/card.go
func GetCard() AgentCard {
	agentURL := os.Getenv("AGENT_URL")
	if agentURL == "" {
		agentURL = "http://localhost:8888"
	}

	return AgentCard{
		Name:        "Security Compliance Validator",
		Description: "Go-based validation engine that checks vendor contracts against corporate compliance policy rules.",
		Version:     "1.0.0",
		SupportedInterfaces: []AgentInterface{
			{
				URL:             agentURL,
				ProtocolBinding: "JSONRPC",
				ProtocolVersion: "1.0",
			},
		},
		Capabilities: Capabilities{
			ExtendedAgentCard: false,
		},
		DefaultInputModes:  []string{"application/json"},
		DefaultOutputModes: []string{"application/json"},
		Skills: []Skill{
			{
				ID:          "contract_compliance_check",
				Name:        "Contract Compliance Check",
				Description: "Validates extracted contract fields against corporate policy rules.",
				Tags:        []string{"compliance", "contract", "validation"},
				Examples: []string{
					"Check this contract for compliance violations",
					"Validate vendor agreement terms against policy",
				},
			},
		},
	}
}

URL 从环境变量中读取，因此同一份代码既能在本地环境（localhost:8888）运行，也能在容器中（go-compliance-agent:8888）运行。Skills 数组意味着单个 Agent 可以声明多项能力。

代码实现详解

下面来看看，如何使用 Python 中的 ADK 和 Go 中的标准 HTTP 服务器，轻松组建这个跨语言团队。

共享状态：Agent 之间的数据总线

在深入了解各个 Agent 之前，需要先弄清楚它们如何通信。ADK 的 ToolContext.state 提供了一个共享字典，流水线中的所有子 Agent 都可以读写它。Agent 不需要通过函数参数或返回值来传递数据，而是通过共享的 session state 进行通信。

合规流水线中的每个步骤都对应一个明确的检查点：

class ComplianceStep(str, Enum):
    INGESTED = "INGESTED"                     # Contract uploaded, awaiting extraction
    EXTRACTED = "EXTRACTED"                    # Fields parsed by Gemini
    COMPLIANCE_PENDING = "COMPLIANCE_PENDING"  # Sent to Go agent, awaiting result
    COMPLIANCE_COMPLETE = "COMPLIANCE_COMPLETE"# Go agent returned verdict
    MANUAL_REVIEW = "MANUAL_REVIEW"           # Timeout or error, routed to human
    REVIEW_READY = "REVIEW_READY"             # Report generated, violations found
    APPROVED = "APPROVED"                      # All checks passed

MANUAL_REVIEW 状态尤其值得关注。如果 Go 合规 Agent 因服务器崩溃、网络超时、容器尚未启动等原因而无法访问，流水线不会直接失败。它会转换到 MANUAL_REVIEW 状态，将该案例交给人工法律审核人员处理。这种故障安全模式对于生产系统至关重要，因为下游服务随时可能间歇性不可用。

1. 完整的多 Agent 流水线：在 Python 中封装 Go Agent

使用 ADK，你可以通过 RemoteA2aAgent，在本地定义一个兼容 A2A 的远程 Agent。SDK 会在幕后自动处理 Agent Card 握手、参数序列化和 JSON-RPC 网络请求。

# python-extraction-agent/app/agent.py
from google.adk.agents import Agent, SequentialAgent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
from google.adk.models import Gemini

# Sub-Agent 1: Ingests & extracts details using LLM reasoning
extractor_agent = Agent(
   name="extractor_agent",
   model=Gemini(model="gemini-3.5-flash"),
   instruction="You are a Legal Data Extraction Agent. Extract contract fields: value, contractor, dates, insurance...",
   tools=[read_contract_text, save_extracted_fields, classify_risk_level]
)

# Sub-Agent 2: Go A2A Compliance Service wrapped as a local agent
compliance_agent = RemoteA2aAgent(
   name="compliance_agent",
   agent_card=GO_AGENT_CARD_URL,
   description="Validates extracted contract fields against corporate policies."
)

# Sub-Agent 3: Generates the final audit summary report
report_agent = Agent(
   name="report_agent",
   model=Gemini(model="gemini-3.5-flash"),
   instruction="Generate the final compliance report and Markdown summary.",
   tools=[generate_summary_report]
)

# Coordinator: Chains them together sequentially
root_agent = SequentialAgent(
   name="contract_compliance_coordinator",
    description="Orchestrates contract parsing, A2A compliance validation, and final reporting in sequence.",
   sub_agents=[extractor_agent, compliance_agent, report_agent],
)

2. Go 合规端点

在 Go 端，合规 Agent 是一个实现了 A2A 协议的标准 HTTP 服务器。它对外暴露 Agent Card 以供发现，同时提供一个 JSON-RPC 端点。该端点接收 message/send 请求，针对提取出的合同字段执行确定性的政策检查，然后返回通过或不通过的结论。不需要任何 AI 框架或 SDK，只需使用 Go 标准库。

下面是简化后的流程，完整实现可在代码仓库中查看：

// Simplified pseudo-code — see GitHub repository for full implementation

func HandleJSONRPC(w http.ResponseWriter, r *http.Request) {
    var req JSONRPCRequest
    json.NewDecoder(r.Body).Decode(&req)

    // Extract contract details from the A2A message
    var details compliance.ContractDetails
    extractContractFromMessage(req.Params, &details)

    // Run deterministic policy checks
    result := compliance.CheckCompliance(details, policy)

    // Return verdict as a JSON-RPC response
    writeJSONRPCResult(w, req.ID, result)
}

开源应用：合同合规引擎

完整流水线以开源应用的形式发布，你可以部署并扩展它。代码仓库中包含一个功能完整的运维驾驶舱，由 FastAPI 服务提供。

三面板运维驾驶舱： 左侧面板供操作人员选择或上传合同。中间面板显示实时结果：通过合规检查的合同会显示合规证书，未通过的合同会显示违规报告。右侧面板是开发者控制台，其中包括政策控制、网络模拟，以及两个 Agent 之间数据流动情况的实时视图。

网络故障模拟： 通过一个切换开关，可以让 Go Agent 在 Normal、Delayed 和 Crashed 三种状态之间切换。将其设置为 Crashed，就能看到故障安全机制如何运作：Python Agent 检测到服务中断后，会停止流水线，并将合同转交人工审核，而不是悄无声息地失败。

实时 Agent 交接检查器： 右侧面板会显示从 Python 发送到 Go 的确切请求，以及 Go 返回的响应，让你能够实时观察结构化合同数据如何跨越语言边界。

ADK 与 A2A 方案的优势

技术选择自由： 数据科学团队可以使用 Python 编写复杂的认知型 Agent，系统团队则可以使用 Go、Rust 或 C++ 编写高性能且安全的合规验证器。

简化集成： Python 编排器与 Go Agent 通信时，就像在调用一个本地 class。你不需要编写自定义 HTTP 客户端，也不需要手动封装 JSON-RPC payload。

弹性： 由于 Agent 彼此解耦，你可以配置细粒度的超时和重试逻辑。如果 Go 验证器宕机，Python Agent 会保存当前的状态检查点，并等待人工批准。

隔离审计： Go 合规验证器是完全确定性的。为了满足审计要求，你可以传入相同的输入，并验证它们是否会产生完全相同的政策判定结果，从而绕过 LLM 的非确定性。

多 Agent 编排不只是把多段 prompt 串联起来，而是在构建稳健的跨语言分布式系统。

通过 Google ADK 和开放的 A2A 协议，将 Python 的 AI 生态与 Go 的运行时可靠性连接起来，你就能兼得二者之长：在存在模糊性的地方使用认知推理，在涉及政策的地方执行确定性约束。

准备好亲自运行了吗？

克隆 contract-compliance-engine，在本地运行实时演示。
查看 ADK 文档，了解 session 管理、多 Agent 模式和评估框架。
查看 Agent2Agent Protocol 文档，了解更多详细信息。