Agent on DK Blog

A2A 实战：用 Go 搭一个支付诊断 MVP

Tue, 30 Jun 2026 22:56:00 +0800

A2A 实战：用 Go 搭一个支付诊断 MVP

A2A 不是单纯的聊天协议，它更像一套“任务协议”：客户端先通过 Agent Card 发现服务能力，再把用户问题作为 Task 发送给远端 Agent，最后根据 Task 状态、History 和 Artifact 把完整结果取回来。

这篇文章基于你给出的 Go 代码，整理成一个支付失败诊断 MVP。这个 Demo 的目标很明确：

客户端能自动解析 Agent Card
服务端能暴露 JSON-RPC 接口和 Agent Card
任务执行过程中能持续推送状态
结果不只返回一句话，而是带结构化 Artifact

一、MVP 框架结构

可以把这套代码拆成四层理解：

层	职责	关键对象
客户端	发现 Agent、发送消息、接收流式事件、再次拉取 Task	`a2aclient.Client`
服务端	暴露 Agent Card 和 JSON-RPC `/invoke`	`a2asrv.NewJSONRPCHandler`
业务执行层	把“诊断支付失败”拆成状态更新和 Artifact 输出	`PaymentDiagnosisExecutor`
领域模型层	生成诊断报告和结构化数据	`DiagnosisReport`

一个完整请求的路径大概是这样：

1
2
3
4
5
6
7


User
 -> Client
 -> /.well-known/agent-card.json
 -> /invoke
 -> PaymentDiagnosisExecutor
 -> Task / Status / Artifact
 -> GetTask

二、A2A 在这个 MVP 里做了什么

这份 Demo 里最关键的不是“问答”，而是“任务”。

AgentCard 用来告诉客户端：我是谁、我支持什么协议、输出什么格式
SendMessage / SendStreamingMessage 用来发起任务
Task 用来保存执行上下文、历史消息、状态和附件
Artifact 用来返回结构化结果，适合放 markdown 和 JSON
GetTask 用来在流式完成后再取回完整任务

也就是说，A2A 把“远端智能能力”从一次性回答，变成了可追踪、可回放、可扩展的业务任务。

三、服务端源码：Agent Card 和 JSON-RPC

服务端的入口很短，核心就是两个动作：挂载 Agent Card，挂载 /invoke。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66


package main

import (
	"flag"
	"fmt"
	"log"
	"net"
	"net/http"

	"example.com/a2a-go-business-demo/internal/incident"
	"github.com/a2aproject/a2a-go/v2/a2a"
	"github.com/a2aproject/a2a-go/v2/a2asrv"
)

var port = flag.Int("port", 9001, "A2A JSON-RPC server port.")

func main() {
	flag.Parse()

	invokeURL := fmt.Sprintf("http://127.0.0.1:%d/invoke", *port)

	card := &a2a.AgentCard{
		Name: "Payment Diagnosis Agent",
		Description: "Diagnoses payment failures and returns task progress plus final artifacts.",
		SupportedInterfaces: []*a2a.AgentInterface{
			a2a.NewAgentInterface(invokeURL, a2a.TransportProtocolJSONRPC),
		},
		DefaultInputModes: []string{"text/plain", "application/json"},
		DefaultOutputModes: []string{"text/markdown", "application/json"},
		Capabilities: a2a.AgentCapabilities{
			Streaming: true,
		},
		Skills: []a2a.AgentSkill{
			{
				ID: "payment_failure_diagnosis",
				Name: "Payment failure diagnosis",
				Description: "Creates a task, updates task status while collecting evidence, and returns markdown/json artifacts.",
				Tags: []string{"payment", "risk", "diagnosis", "artifact"},
				Examples: []string{"为什么 order-10086 这笔订单支付失败？"},
			},
		},
	}

	trace := func(stage string, detail string) {
		log.Printf("[server] stage=%s detail=%s", stage, detail)
	}

	requestHandler := incident.NewPaymentDiagnosisHandler(trace)

	mux := http.NewServeMux()
	mux.Handle("/invoke", a2asrv.NewJSONRPCHandler(requestHandler))
	mux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(card))

	listener, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))
	if err != nil {
		log.Fatalf("bind server port: %v", err)
	}

	log.Printf("A2A server listening on http://127.0.0.1:%d", *port)
	log.Printf("Agent card: http://127.0.0.1:%d%s", *port, a2asrv.WellKnownAgentCardPath)
	log.Printf("JSON-RPC endpoint: %s", invokeURL)

	if err := http.Serve(listener, mux); err != nil {
		log.Fatalf("serve: %v", err)
	}
}

这里有三个点最重要：

SupportedInterfaces 把 JSON-RPC 地址写进 Agent Card
Capabilities.Streaming = true 表示这个 Agent 支持流式事件
Skills 描述这个 Agent 会做什么，客户端不需要预先硬编码能力

四、业务执行层：把一个问题变成 Task 流程

真正的业务逻辑在 incident 包里。它不是“直接返回诊断结论”，而是一步步把执行过程变成 A2A 事件。

1
2
3
4
5


type PaymentDiagnosisExecutor struct{ trace ServerTrace }

func NewPaymentDiagnosisHandler(trace ServerTrace) a2asrv.RequestHandler {
	return a2asrv.NewHandler(&PaymentDiagnosisExecutor{trace: trace})
}

执行流程如下：

第一次进来先创建 SubmittedTask
把任务状态改成 Working
分阶段写入进度消息
生成 Artifact
最后改成 Completed

核心 Execute 逻辑可以这样看：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


func (e *PaymentDiagnosisExecutor) Execute(_ context.Context, execCtx *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
	return func(yield func(a2a.Event, error) bool) {
		e.record("server.receive_send_message", "a2asrv handler parsed SendMessage and built ExecutorContext")

		if execCtx.StoredTask == nil {
			e.record("task.create_submitted", "create Task with initial user message in history")
			if !yield(a2a.NewSubmittedTask(execCtx, execCtx.Message), nil) {
				return
			}
		}

		if !e.status(yield, execCtx, "task.status_working", a2a.TaskStateWorking, "已创建支付失败诊断任务，正在查询订单、支付网关和风控证据。") {
			return
		}

		report, err := DiagnoseQuestion(messageText(execCtx.Message))
		if err != nil {
			e.fail(yield, execCtx, "诊断失败："+err.Error())
			return
		}

		if !e.status(yield, execCtx, "task.progress_order_loaded", a2a.TaskStateWorking, "订单服务已返回：订单已创建，支付单为 "+report.PaymentID+"。") {
			return
		}
		if !e.status(yield, execCtx, "task.progress_gateway_loaded", a2a.TaskStateWorking, "支付网关已返回：RISK_REJECT，支付被风控拒绝。") {
			return
		}
		if !e.status(yield, execCtx, "task.progress_risk_loaded", a2a.TaskStateWorking, "风控服务已返回：高风险设备指纹规则命中。") {
			return
		}

		e.sleep("task.artifact_create")
		e.record("task.artifact_create", "append final markdown and json result parts to task artifacts")

		if !yield(newPaymentArtifact(execCtx, report), nil) {
			return
		}

		e.status(yield, execCtx, "task.status_completed", a2a.TaskStateCompleted, "诊断完成："+report.RootCause)
	}
}

这段代码体现了 A2A 的核心价值：不是“立刻吐一个答案”，而是让任务状态可见、过程可追踪、结果可落盘。

五、诊断报告：Markdown + JSON 双输出

业务模型层把诊断结果组织成两种视图：人类可读的 markdown 和机器可读的 JSON。

1
2
3
4
5
6
7
8


type DiagnosisReport struct {
	OrderID string `json:"orderId"`
	PaymentID string `json:"paymentId"`
	RootCause string `json:"rootCause"`
	Summary string `json:"summary"`
	Evidence []Evidence `json:"evidence"`
	Suggestions []string `json:"suggestions"`
}

生成 Artifact 时，两个 part 会一起挂到任务上：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func newPaymentArtifact(execCtx *a2asrv.ExecutorContext, report DiagnosisReport) *a2a.TaskArtifactUpdateEvent {
	markdownPart := a2a.NewTextPart(report.Markdown())
	markdownPart.MediaType = "text/markdown"
	markdownPart.Filename = "payment-root-cause-report.md"

	dataPart := a2a.NewDataPart(report.StructuredData())
	dataPart.MediaType = "application/json"
	dataPart.Filename = "payment-root-cause-report.json"

	event := a2a.NewArtifactEvent(execCtx, markdownPart, dataPart)
	event.LastChunk = true
	event.Artifact.Name = "payment-root-cause-report"
	event.Artifact.Description = "订单支付失败根因诊断报告"
	event.Artifact.SetMeta("business.orderId", report.OrderID)
	event.Artifact.SetMeta("business.paymentId", report.PaymentID)
	return event
}

这个设计很实用：

markdown 给人看
JSON 给后续系统接
LastChunk = true 表示这个 Artifact 已经写完

六、客户端源码：发现能力、发送消息、回收任务

客户端做三件事：解析 Agent Card、发消息、再取完整 Task。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


card, err := agentcard.DefaultResolver.Resolve(ctx, *cardURL)
if err != nil {
	log.Fatalf("resolve agent card: %v", err)
}

client, err := a2aclient.NewFromCard(ctx, card)
if err != nil {
	log.Fatalf("create A2A client: %v", err)
}
defer client.Destroy()

然后按 stream 参数决定走流式还是非流式：

1
2
3
4
5


if *stream {
	taskID = runStreamingQuestion(ctx, client, *question)
} else {
	taskID = runNonStreamingQuestion(ctx, client, *question)
}

流式版本会实时打印事件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


for event, err := range incident.StreamPaymentQuestion(ctx, client, question) {
	if err != nil {
		log.Fatalf("stream payment question: %v", err)
	}
	if event == nil {
		continue
	}

	info := event.TaskInfo()
	if info.TaskID != "" {
		taskID = info.TaskID
	}

	fmt.Printf(" [%s] %s\n", time.Now().Format("15:04:05.000"), incident.DescribeStreamEvent(event))
}

最后再拉一次完整任务：

1
2
3
4


storedTask, err := incident.FetchTask(ctx, client, taskID)
if err != nil {
	log.Fatalf("get task: %v", err)
}

这一步很关键，因为流式事件适合看进度，GetTask 适合拿完整上下文、History 和 Artifacts。

七、示例业务：为什么 `order-10086` 支付失败

这里的示例诊断逻辑非常明确：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


func DiagnoseQuestion(question string) (DiagnosisReport, error) {
	if !strings.Contains(question, "order-10086") {
		return DiagnosisReport{}, errors.New("question must contain an order id like order-10086")
	}

	return DiagnosisReport{
		OrderID: "order-10086",
		PaymentID: "pay-7788",
		RootCause: "支付网关返回 RISK_REJECT，订单命中高风险设备指纹规则",
		Summary: "订单已创建成功，但支付阶段被风控拒绝。",
		Evidence: []Evidence{
			{Source: "order-service", Detail: "订单已创建，金额 1299.00 CNY"},
			{Source: "payment-gateway", Detail: "支付网关返回 RISK_REJECT"},
			{Source: "risk-engine", Detail: "设备 device-risk-9 风控分 97，超过拒绝阈值 90"},
		},
		Suggestions: []string{
			"提示用户更换支付方式或完成身份校验",
			"风控平台核验 device-risk-9 是否误杀",
		},
	}, nil
}

这说明一个 MVP 不一定要连真实系统，但必须把业务边界说清楚。A2A 负责承载任务流转，业务函数负责给出稳定、可解释的结论。

八、一次请求的完整流程

如果用户问：

为什么 order-10086 这笔订单支付失败？

整个链路会是：

客户端解析 Agent Card
客户端发送 SendStreamingMessage
服务端创建 SubmittedTask
服务端持续发 Working 状态
服务端生成 Artifact
服务端发 Completed
客户端通过 GetTask 拉回完整结果

这套流程的价值在于，前端、网关、外部系统都能按 Task ID 继续追踪，而不是只拿到一次性文本。

九、总结

这份 A2A MVP 的重点不是“做了一个问答接口”，而是把一个远端 Agent 做成了可发现、可流转、可追踪的任务系统。

如果你要把它继续往下做，最值得补的三块是：

把 DiagnoseQuestion 换成真实订单、支付、风控查询
把 Artifact 接到对象存储或知识库
把 trace 日志接到统一观测平台

A2A 的落点很清楚：让 Agent 不只是会回答，而是能真正进入业务流程。

Codex 的 Main Agent 和 Subagent 是怎么通信的

Thu, 25 Jun 2026 19:20:00 +0800

很多人第一次看 Codex 的多 agent 机制时，会下意识把 subagent 理解成 “main agent 调了一个内部函数”。这个理解不对。

在 Codex 里，subagent 更接近于：主线程之外又开了一个独立聊天线程。它有自己的 thread id、上下文、工具调用过程、执行状态和 mailbox。main agent 和 subagent 不共享完整上下文，它们靠 Codex runtime 转发内部消息协作。

这篇文章不讲 Rust 语法，只讲一条闭环：

1
2
3
4
5


main agent 怎么派任务
-> runtime 怎么投递消息
-> subagent 怎么独立执行
-> 结果怎么回到 main agent
-> main agent 怎么继续往下走

先看总览图：

先记住一个模型

可以先把 Codex 的 subagent 理解成下面这个结构：

1
2
3


main agent 所在主聊天线程
 另外开了一个独立聊天线程
 这个独立线程就是 subagent

所以 subagent 不是 main agent 内部的一个函数。它有自己的：

thread id
上下文
工具调用过程
执行状态
mailbox

这件事决定了 main agent 和 subagent 的关系不是同步函数调用，而是多个独立线程之间通过内部信件协作。

先看通信闭环

main agent 能控制 subagent 的方式，不是直接读写它的内存，而是调用一组协作工具：

1
2
3
4
5
6


spawn_agent 创建子 agent，并给第一条任务
send_message 给已有 agent 发消息，但不强制它马上跑
followup_task 给已有 agent 发后续任务，并在空闲时触发它继续跑
wait_agent 等待有 agent 消息或状态变化
interrupt_agent 打断某个 agent 当前执行
list_agents 查看当前有哪些 agent

这些工具本质上都是 function call。模型输出 function call，Codex runtime 收到后执行内部逻辑。

把完整流程压成一条主链路，大致就是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


用户提问
 -> main agent 决定拆任务
 -> main agent 调 spawn_agent
 -> runtime 创建 child thread
 -> 第一条任务进入 child thread
 -> child agent 独立执行
 -> main agent 调 wait_agent
 -> child agent 调 send_message(target=root)
 -> root mailbox 收到结果
 -> wait_agent 被唤醒
 -> main agent 下一轮读到这条消息
 -> main agent 汇总后回答用户

这里最重要的三点是：

subagent 是真的独立 thread，不是内部函数。
send_message 和 followup_task 都是在投递内部消息，只是后者会顺带触发目标 agent 开始下一轮执行。
wait_agent 等的是 mailbox 活动，不是同步拿子函数返回值。

例如 main agent 创建 subagent 时，可能只是发出这样一个调用：

1
2
3
4


spawn_agent({
 task_name: "research",
 message: "你去分析 app-server 里的 subagent 通信逻辑"
})

但 runtime 真正做的是：

1
2
3
4
5


创建 child thread
记录 parent_thread_id
记录 task_name
投递第一条任务
启动 child agent 独立执行

而 subagent 回结果时，走的也不是“返回值”，而是再发一封内部信：

1
2
3
4


send_message({
 target: "root",
 message: "我查完了。结论是：Codex 通过 InterAgentCommunication 和 mailbox 通信。"
})

所以从运行时视角看，Codex 的多 agent 更像：

1
2


多个独立聊天线程
 通过 runtime 维护的内部邮箱互相发消息

wait_agent 为什么经常被误解

wait_agent 最容易被误解成“同步等待 subagent 返回值”，其实它更像：

`1`	`main agent 暂停一下，等 mailbox 有没有新消息`

比如：

1
2
3


wait_agent({
 timeout_ms: 30000
})

它的意思是：

1
2
3


最多等 30 秒
如果收到 agent 消息或相关活动，就返回
如果 30 秒没有，就返回 timed_out

超时返回类似：

1
2
3
4


{
 "message": "Wait timed out.",
 "timed_out": true
}

这里一定要分清：

1
2
3


wait_agent 超时
!=
subagent 被杀掉

子 agent 可能还在继续跑。runtime 不会自动替 main agent 做决策，它不会自动：

kill 子 agent
interrupt 子 agent
判定子 agent 失败
自动重派任务

它只是把 timed_out=true 交还给 main agent。接下来 main agent 自己决定下一步：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


继续等:
 wait_agent({ timeout_ms: 30000 })

打断:
 interrupt_agent({ target: "research" })

催促:
 followup_task({ target: "research", message: "收敛一下，直接给结论" })

先回答用户:
 基于已有信息组织答案

所以 main agent 在这套机制里，本质上更像调度者。

这条闭环在源码里怎么落地

如果只看一张源码总览图，可以先记住这条链：

1
2
3
4
5
6
7


模型看到工具定义
 -> 模型发起 function call
 -> tool handler 接住 function call
 -> AgentControl 负责创建 / 发消息 / 等待 / 中断
 -> session handlers 和 InputQueue 负责 mailbox
 -> turn loop 把 mailbox 消息放进模型上下文
 -> app-server / TUI 把事件展示给客户端

按这个链路往下看，源码可以分成 6 个位置。

第一层：工具暴露给模型

文件：

1
2


codex-rs/core/src/tools/spec_plan.rs
codex-rs/core/src/tools/handlers/multi_agents_spec.rs

这里分别负责两件事：

spec_plan.rs 决定当前 turn 要不要把多 agent 工具暴露给模型
multi_agents_spec.rs 定义这些 function call 的参数 schema

也就是说，main agent 能不能调用 spawn_agent、send_message、wait_agent，第一步先看这里。

第二层：main agent 的控制入口

文件：

1
2
3
4
5
6
7


codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs
codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs
codex-rs/core/src/tools/handlers/multi_agents_v2/wait.rs
codex-rs/core/src/tools/handlers/multi_agents_v2/interrupt_agent.rs
codex-rs/core/src/agent/control.rs
codex-rs/core/src/agent/control/spawn.rs
codex-rs/core/src/agent/registry.rs

这层可以理解成 “main agent 的控制台”：

spawn.rs 负责接住 spawn_agent
message_tool.rs 负责接住 send_message 和 followup_task
wait.rs 负责 wait_agent
interrupt_agent.rs 负责打断入口
AgentControl 是统一控制中心
spawn_agent_internal(...) 真正创建 child thread
AgentRegistry 记住有哪些 agent、各自的 thread id 和 path

所以“main agent 怎么找到 subagent、怎么把任务发过去”，主要都在这层。

第三层：内部消息的数据结构

文件：

`1`	`codex-rs/protocol/src/protocol.rs`

关键结构：

`1`	`InterAgentCommunication`

它可以直接理解成一封内部信，里面最关键的是：

author
recipient
content
trigger_turn

例如：

1
2
3
4


from: root
to: research
content: 继续查一下 thread_history.rs
trigger_turn: true

第四层：消息如何进入 mailbox

文件：

1
2


codex-rs/core/src/session/handlers.rs
codex-rs/core/src/session/input_queue.rs

这里是真正的 mailbox 落点：

handlers.rs 里的 inter_agent_communication(...) 收到 Op::InterAgentCommunication
input_queue.rs 里的 enqueue_mailbox_communication(...) 把消息放进 mailbox
如果 trigger_turn=true，runtime 会尝试启动目标 agent 的新一轮 turn

所以 send_message 和 followup_task 的本质区别，就落在 trigger_turn 上。

第五层：mailbox 怎么进入模型上下文

文件：

1
2


codex-rs/core/src/session/turn.rs
codex-rs/core/src/session/mod.rs

这里负责两件事：

turn.rs 在每轮请求模型前，从 InputQueue 取 pending input
mod.rs 里的 record_inter_agent_communication(...) 把消息写进历史和 rollout

也就是说，agent 间消息不只是内存里短暂经过，它还会：

进入下一轮模型上下文
写入会话历史
被客户端看到

第六层：状态和展示

文件：

1
2
3
4
5


codex-rs/core/src/agent/status.rs
codex-rs/app-server-protocol/src/protocol/thread_history.rs
codex-rs/tui/src/app/loaded_threads.rs
codex-rs/tui/src/app/agent_navigation.rs
codex-rs/tui/src/app/thread_routing.rs

这层负责把运行中的事实变成用户能看到的东西：

status.rs 把事件映射成 Running、Completed、Errored 等状态
thread_history.rs 把协作事件转成客户端能展示的 ThreadItem
TUI 相关文件负责找出主线程下有哪些 subagent，以及怎么在界面里切换和缓存它们

所以你在 app-server 或 TUI 里看到的“创建了哪个 agent”“谁给谁发了消息”“wait 有没有超时”，最终都依赖这层映射和展示。

最短源码定位表

你想看什么	看哪个文件
工具怎么暴露给模型	`codex-rs/core/src/tools/spec_plan.rs`
function call 参数怎么定义	`codex-rs/core/src/tools/handlers/multi_agents_spec.rs`
`spawn_agent` 入口	`codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs`
创建 child thread	`codex-rs/core/src/agent/control/spawn.rs`
main 如何控制 agent	`codex-rs/core/src/agent/control.rs`
agent 列表和 metadata	`codex-rs/core/src/agent/registry.rs`
`send_message` / `followup_task`	`codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs`
内部信件结构	`codex-rs/protocol/src/protocol.rs`
mailbox 队列	`codex-rs/core/src/session/input_queue.rs`
mailbox 进入模型上下文	`codex-rs/core/src/session/turn.rs`
通信记录进历史	`codex-rs/core/src/session/mod.rs`
`wait_agent` 超时逻辑	`codex-rs/core/src/tools/handlers/multi_agents_v2/wait.rs`
agent 状态	`codex-rs/core/src/agent/status.rs`
app-server 展示	`codex-rs/app-server-protocol/src/protocol/thread_history.rs`
TUI subagent 导航	`codex-rs/tui/src/app/agent_navigation.rs`

最后收一句

如果只记一句话，我建议记这句：

`1`	`Codex 的 main agent 和 subagent 不是同步函数调用，而是多个独立 thread 通过 runtime 维护的 mailbox 互相发消息`

从原理上看，这是一个“多线程聊天 + 内部邮箱”的协作模型；从源码上看，这条链路则落在 tool handler、AgentControl、session mailbox、turn loop、app-server 和 TUI 几层里，刚好首尾闭环。

Multica 初体验：把 Codex、Claude Code 这类 coding agent 当成队友来管理

Thu, 28 May 2026 22:16:00 +0800

最近看了一下 Multica，感觉它解决的不是“让 AI 写代码”这个问题，而是另一个更实际的问题：当你同时用 Codex、Claude Code、Copilot CLI、OpenCode 这类 coding agent 时，怎么管理它们干活。

以前我的用法比较粗糙：开几个终端窗口，每个窗口一个 agent，谁在跑什么、结果有没有回来、上下文有没有断，全靠自己记。任务少的时候还行，一旦同时丢两三个问题，比如一个查 bug、一个写测试、一个做文档，很快就乱了。

Multica 的思路是把 agent 放进一个协作空间里。它有 workspace、issue、comment、agent 这些概念。你可以把一个 issue 分配给某个 agent，也可以在评论里 @ 它。这个体验更像是在给同事派活，而不是在终端里继续补 prompt。

我当时顺手记了一个很小的判断：如果一个工具只是在网页里多开几个聊天窗口，那它对 coding agent 的帮助有限；如果它能回答“谁在跑、跑到哪、改了什么、失败后能不能复盘”，它才像是在管理执行单元。Multica 比较接近后者。

我比较在意的点

我比较在意的一点是：Multica 并不是简单把所有东西都丢到云端跑。官方文档里说，真正执行任务的是本地 daemon。Multica server 负责 workspace、issue、成员、任务队列这些数据；daemon 跑在你自己的机器上，去调用本地安装的 Claude Code、Codex、Copilot CLI 等工具。

这个设计对我来说挺关键。coding agent 最敏感的地方不是“问答内容”，而是它会读代码、跑命令、改文件。如果一个平台只是提供任务面板，但实际执行仍然在本地，那接受成本会低很多。

当然这不代表完全没有风险。agent 能做什么、工具权限怎么给、仓库怎么隔离，还是要自己控制。

从 provider matrix 看，Multica 对不同 coding tool 的支持不是完全一样的。Claude Code、Codex、OpenCode 在 MCP 支持、skill 注入路径、session resumption 上都有差异。这个地方我觉得文档写得比较实在，没有假装所有工具都能做到同一个水平。

我会特别看这些差异，而不是只看“支持多少 agent”：

能力	我为什么关心
session resumption	agent 中途断了以后能不能接着跑，不然长任务很容易废掉
MCP support	能不能接公司内部工具，而不是只靠本地 shell
skill injection	能不能把团队约定、代码规范、常用命令放进 agent 上下文
task history	失败任务能不能复盘，而不是只剩一句“没做好”

如果我要试

如果要在项目里试，我大概会先按这个方式用：

1
2
3


multica daemon start

multica setup self-host

然后给不同 agent 分清职责，而不是所有任务都丢给一个“全能助手”：

1
2
3


codex-fixer 小范围代码修复和测试
claude-reviewer review、解释设计风险
opencode-docs 文档草稿和命令整理

我现在对这类工具的看法是：不要指望它让 agent 变聪明。它真正有价值的地方是让 agent 的工作可排队、可观察、可追溯。

终端里跑 agent 最大的问题是过程容易丢。Multica 把一次运行抽象成 task，有 queued、dispatched、running、completed、failed 这类状态，也有重试和历史记录。这样你至少知道它是没开始、跑挂了，还是已经完成只是结果不理想。

我不会一上来就接正式仓库

更合理的方式是先拿一个 side project 或内部工具试：

只给只读或低风险仓库。
agent 默认不要有生产凭证。
每个任务只允许小范围修改。
输出必须经过人工 review。
不要把“能跑起来”误认为“能放心用”。

Multica 这类项目让我感觉到一个趋势：coding agent 正在从“单次对话工具”变成“可管理的执行单元”。以前我们关心的是 prompt 怎么写，现在更关心任务怎么派、权限怎么控、结果怎么验收。

这篇先记到这里。它不是那种看完文档就能断言成熟的工具，但方向我觉得值得关注。尤其是团队里已经有人混用 Codex、Claude Code、Copilot CLI 的时候，与其每个人各玩各的，不如有一个地方把任务和 agent 统一管起来。

我暂时不会把它写成“推荐大家马上上”。更准确的评价是：如果你的团队还没有稳定使用 coding agent，它不是第一优先级；如果已经有人同时开好几个 agent 做修复、review、文档和测试，它解决的就是混乱本身。

参考资料

MCP 工具接入后的 Agent 设计：别只会调工具，还要能兜底

Thu, 19 Feb 2026 23:08:00 +0800

最近接 MCP 工具时有个感受：让 agent 能调工具其实不难，难的是工具出错以后它怎么收场。

很多 demo 都停在“模型发现工具，然后调用工具，最后返回结果”。这个流程当然重要，但一到真实项目里，问题马上会变多：

工具参数不完整。
MCP server 连不上。
工具返回了业务错误。
工具返回内容太长。
工具结果里混了不该给模型看的内容。
用户问的是高风险操作，但 agent 没有停下来确认。

所以我现在更愿意把 MCP 看成一个工具协议，而不是完整的 agent 方案。MCP 解决的是“工具怎么暴露、怎么发现、怎么调用”。但 agent 怎么规划、怎么重试、怎么审批、怎么记录，这些还是应用自己要设计。

我踩到的第一个误区就是：工具列表一多，agent 看起来就“能力很强”。但真实情况是，工具越多，出错路径也越多。尤其是工具之间有依赖的时候，模型一次错误调用可能会把后面的上下文都带偏。

失败要分类

MCP 官方规范里，tool 是 server 暴露给模型调用的能力。每个 tool 有 name、description、inputSchema，新版本里还可以有 outputSchema。client 可以通过 tools/list 发现工具，通过 tools/call 调用工具。

工具失败不能都当成一种失败。我比较喜欢分成四类：

1
2
3
4


1. 参数错误：模型传错了，应该让模型修正参数后重试
2. 临时错误：网络、限流、超时，可以做有限重试
3. 权限错误：不要重试，直接提示需要授权或人工处理
4. 业务错误：工具正常执行了，但结果不满足条件，需要解释给用户

如果不分这些类型，agent 很容易出现两种问题：要么无限重试，要么一失败就胡编。

一个比较朴素的工具调用兜底逻辑可以这样设计：

1
2
3
4
5
6
7
8


用户请求
 -> 判断是否需要工具
 -> 检查工具是否允许在当前场景使用
 -> 调用工具
 -> 校验结果结构
 -> 如果失败，按失败类型处理
 -> 如果是敏感操作，等待人工确认
 -> 汇总结果，明确哪些是工具返回，哪些是推断

这里我会强制 agent 在最终回答里暴露两类信息：

1
2


已确认：来自工具返回、日志、数据库或 API 的事实
推测：根据事实做出的判断，需要继续验证

这个写法有点啰嗦，但对排障类 agent 很有用。最怕的是模型把推测写成事实，用户再拿这个“事实”去改线上配置。

敏感工具不要让模型自己决定

这里面最容易被忽略的是“工具是否允许在当前场景使用”。MCP 规范也强调了 trust & safety：客户端应该让用户知道哪些工具暴露给了模型，敏感操作前应该有确认。

我自己的倾向是把 MCP 工具分级：

1
2
3
4


read_only 只读查询，比如查文档、查资源、查状态
low_risk 可写但影响小，比如创建草稿、生成 issue
dangerous 可能改配置、删数据、执行命令
external 会访问外部系统或带来数据外发风险

然后给 agent 一个硬规则：dangerous 和 external 默认必须人工确认，不能让模型自己判断“应该没事”。

我还会给工具加一个“是否可回滚”的维度。比如创建一条草稿 issue 是低风险，因为删掉就行；修改线上 ConfigMap 也许看起来只是一个字段，但一旦触发 rollout，影响就不是工具自己能兜住的。

trace 比想象中重要

如果用 OpenAI Agents SDK，它本身也提供了不少跟工程化有关的东西，比如 MCP servers、guardrails、handoffs、tracing。这里我觉得 tracing 很重要，因为 agent 一旦开始多步调用工具，事后没有 trace 基本没法排查。

一次完整 trace 至少要能回答几个问题：

1
2
3
4
5
6


用户原始输入是什么？
模型决定调用哪个工具？
传给工具的参数是什么？
工具原始返回是什么？
中间有没有 guardrail 拦截？
最终答案里哪些来自工具，哪些是模型总结？

另外，MCP transport 也要注意。stdio 适合本地工具，client 拉起子进程，通过 stdin/stdout 通信；Streamable HTTP 适合远程或服务化工具。HTTP 场景下要考虑认证、Origin 校验和服务绑定地址。

我现在更愿意把 MCP server 写得“笨”一点：输入严格校验，输出结构稳定，错误信息清楚，不在工具里偷偷做太多推理。推理留给 agent，工具只负责可靠地拿数据或执行动作。

比如一个查询 Kubernetes pod 的 MCP tool，返回最好是这种结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "namespace": "default",
 "pods": [
 {
 "name": "api-7f8d7c9b8d-abcde",
 "phase": "Running",
 "restartCount": 3,
 "node": "worker-1"
 }
 ],
 "warnings": [
 "restartCount > 0, check container logs"
 ]
}

不要直接返回一大段混杂的自然语言。自然语言看起来顺，但后续不好校验，也不好让 agent 做稳定判断。

小结

接 MCP 以后我会重点看这些东西：

工具有没有清晰的 inputSchema 和 outputSchema。
工具失败有没有分类型。
是否设置超时、限流和审计日志。
敏感工具有没有人工确认。
工具结果进模型前有没有校验和脱敏。
有没有 trace 能复盘每一步。
agent 最终回答有没有区分事实和推断。

MCP 的价值是把工具接入标准化，但它不会自动让 agent 变可靠。真正影响线上可用性的，往往是这些不太显眼的兜底逻辑。

Agent on DK Blog

A2A 实战：用 Go 搭一个支付诊断 MVP

A2A 实战：用 Go 搭一个支付诊断 MVP

一、MVP 框架结构

二、A2A 在这个 MVP 里做了什么

三、服务端源码：Agent Card 和 JSON-RPC

四、业务执行层：把一个问题变成 Task 流程

五、诊断报告：Markdown + JSON 双输出

六、客户端源码：发现能力、发送消息、回收任务

七、示例业务：为什么 order-10086 支付失败

八、一次请求的完整流程

九、总结

Codex 的 Main Agent 和 Subagent 是怎么通信的

先记住一个模型

先看通信闭环

wait_agent 为什么经常被误解

这条闭环在源码里怎么落地

最短源码定位表

最后收一句

Multica 初体验：把 Codex、Claude Code 这类 coding agent 当成队友来管理

我比较在意的点

如果我要试

我不会一上来就接正式仓库

参考资料

MCP 工具接入后的 Agent 设计：别只会调工具，还要能兜底

失败要分类

敏感工具不要让模型自己决定

trace 比想象中重要

小结

参考资料

七、示例业务：为什么 `order-10086` 支付失败