Mcp on DK Blog

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 变可靠。真正影响线上可用性的，往往是这些不太显眼的兜底逻辑。

参考资料

kagent：在 Kubernetes 里跑一个完整的 AI Agent Case

Thu, 13 Nov 2025 21:34:00 +0800

前面看 kagent 的时候，我只把它当成一个 Kubernetes native 的 Agent 框架来理解。后来再翻官方文档，发现更值得记录的是完整落地链路：CRD 怎么装，controller 怎么起来，模型配置怎么声明，MCPServer 怎么接进来，最后 Agent 怎么引用这些东西。

这篇就按一个完整 case 记下来。目标不是让 agent 直接改生产集群，而是先做一个低风险的“集群观察 + 网页 fetch”助手：

可以调用 kagent 内置 Kubernetes 工具查资源。
可以通过一个 MCPServer 抓取网页内容。
Agent 使用显式的 ModelConfig。
所有对象都用 YAML 表达，方便放进 GitOps。

这个 case 里会出现哪些对象

先把关系画清楚：

1
2
3
4
5
6
7
8


Secret
 -> ModelConfig
 -> Agent
 -> RemoteMCPServer: kagent-tool-server
 -> MCPServer: mcp-website-fetcher

kagent CRDs + kagent controller
kmcp CRDs + kmcp controller

这里有两个容易混的对象：

RemoteMCPServer：kagent 里用来描述远程 MCP 服务的资源，内置的 kagent-tool-server 就属于这一类。
MCPServer：kmcp 管理的 MCP server 资源，可以把一个 stdio MCP server 包成 Kubernetes 里的服务。

官方文档里的 First MCP Tool 示例就是用 MCPServer 起了一个 fetch 工具，然后 Agent 通过 tools 引用它。

1. 安装 CRD 和 controller

我更偏向用 Helm 装，因为这套东西更适合放到平台环境里，不只是本地 demo。

先装 kagent CRD：

1
2
3


helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
 --namespace kagent \
 --create-namespace

再装 kagent controller 和 UI。这里用 OpenAI provider 举例，实际项目里可以换 Anthropic、Gemini、Azure OpenAI、Ollama 等。

1
2
3
4
5
6


export OPENAI_API_KEY="your-api-key"

helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
 --namespace kagent \
 --set providers.default=openAI \
 --set providers.openAI.apiKey="$OPENAI_API_KEY"

官方安装文档里提到，kagent 0.7 之后默认包含 kmcp 子项目。如果你已经单独装了 kmcp，可以通过 chart 配置关掉内置 kmcp。对第一次试用来说，先用默认就行。

确认 CRD 和 controller：

1
2
3
4


kubectl get crd | grep kagent.dev

kubectl get pods -n kagent
kubectl get svc -n kagent

如果要单独安装 kmcp controller，官方文档给的是这条线：

1
2
3
4
5
6
7
8


helm install kmcp-crds oci://ghcr.io/kagent-dev/kmcp/helm/kmcp-crds \
 --namespace kmcp-system \
 --create-namespace

kmcp install

kubectl get pods -n kmcp-system
kubectl logs -l app.kubernetes.io/name=kmcp -n kmcp-system

这里要注意：不要在同一个集群里重复装两套 kmcp controller。要么用 kagent 默认带的，要么明确自己单独安装并在 kagent chart 里关掉。

2. 准备模型 Secret 和 ModelConfig

Helm 安装时如果设置了 provider，通常会带默认配置。为了把流程讲完整，我这里单独写一个 ModelConfig，后续 Agent 明确引用它。

先创建 API key secret：

1
2


kubectl -n kagent create secret generic openai-api-key \
 --from-literal=api-key="$OPENAI_API_KEY"

然后创建 ModelConfig：

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


apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
 name: ops-openai-model
 namespace: kagent
spec:
 provider: OpenAI
 model: "<your-openai-model>"
 apiKeySecret: openai-api-key
 apiKeySecretKey: api-key
 openAI:
 temperature: "0.2"
 maxTokens: 2048
 timeout: 60

我这里把 model 写成占位符，是因为不同账号、网关或代理支持的模型可能不一样。实际落地时要改成你环境里可用的模型名。

应用并检查：

1
2
3
4


kubectl apply -f modelconfig.yaml

kubectl get modelconfig -n kagent
kubectl describe modelconfig ops-openai-model -n kagent

ModelConfig 里有几个字段比较关键：

provider：模型提供方，API 里支持 OpenAI、Anthropic、AzureOpenAI、Ollama、Gemini、Bedrock 等。
model：具体模型名。
apiKeySecret / apiKeySecretKey：引用同 namespace 里的 Secret。
openAI：OpenAI provider 的额外参数，比如 temperature、maxTokens、timeout。

这个对象的价值是把模型配置从 Agent 里拆出来。多个 Agent 可以引用同一个 ModelConfig，模型切换也更清楚。

3. 创建一个 MCPServer：网页 fetch 工具

接下来创建一个最小 MCPServer。官方 First MCP Tool 文档里用的是 mcp-server-fetch，通过 uvx 启动 stdio MCP server，再由 kmcp controller 管理它的生命周期。

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


apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
 name: mcp-website-fetcher
 namespace: kagent
spec:
 deployment:
 cmd: uvx
 args:
 - mcp-server-fetch
 port: 3000
 stdioTransport: {}
 transportType: stdio

应用：

`1`	`kubectl apply -f mcp-website-fetcher.yaml`

检查状态：

1
2
3
4


kubectl get mcpserver -n kagent
kubectl describe mcpserver mcp-website-fetcher -n kagent

kubectl get pods -n kagent | grep mcp-website-fetcher

如果 MCPServer 没起来，我会先看 kmcp controller 日志，而不是直接怀疑 Agent：

1

kubectl logs -l app.kubernetes.io/name=kmcp -n kmcp-system

如果你用的是 kagent chart 内置 kmcp，controller 的 namespace 和 label 可能跟独立安装不同，直接用下面的方式先找：

1
2


kubectl get pods -A | grep -i kmcp
kubectl get deploy -A | grep -i kmcp

4. 创建 Agent：同时引用 Kubernetes 工具和 fetch 工具

现在创建 Agent。这个 Agent 做两件事：

用内置 kagent-tool-server 查 Kubernetes 资源。
用刚才的 mcp-website-fetcher 抓网页内容。

 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


apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
 name: ops-readonly-agent
 namespace: kagent
spec:
 description: >
 A read-only Kubernetes operations assistant. It can inspect Kubernetes
 resources and fetch documentation pages, but it must not perform write
 operations.
 type: Declarative
 declarative:
 modelConfig: ops-openai-model
 stream: true
 systemMessage: |-
 You are a Kubernetes operations assistant.

 Rules:
 - Only use read-only tools.
 - Do not make up cluster state.
 - If a tool result is missing or ambiguous, say so.
 - Separate confirmed facts from guesses.
 - Never suggest deleting or modifying resources without human review.

 Response format:
 - Summary
 - Evidence from tools
 - Possible causes
 - Next checks
 tools:
 - type: McpServer
 mcpServer:
 apiGroup: kagent.dev
 kind: RemoteMCPServer
 name: kagent-tool-server
 toolNames:
 - k8s_get_available_api_resources
 - k8s_get_resources
 - type: McpServer
 mcpServer:
 kind: MCPServer
 name: mcp-website-fetcher
 toolNames:
 - fetch

应用：

`1`	`kubectl apply -f ops-readonly-agent.yaml`

检查 Agent：

1
2
3


kubectl get agent -n kagent

kubectl get agent ops-readonly-agent -n kagent -o yaml

官方示例里 Agent 的 status 会出现类似 Accepted=True、Ready=True 的 condition。如果这里不 Ready，优先看三类对象：

1
2
3


kubectl get modelconfig ops-openai-model -n kagent -o yaml
kubectl get mcpserver mcp-website-fetcher -n kagent -o yaml
kubectl get agent ops-readonly-agent -n kagent -o yaml

我会按这个顺序查：

ModelConfig 是否能读到 secret。
MCPServer 是否已经被 kmcp controller 拉起来。
Agent 引用的 tool 名称是否存在。
Agent 的 namespace 是否能引用对应 MCP server。

5. 打开 UI 验证

本地打开 kagent UI：

`1`	`kubectl port-forward -n kagent svc/kagent-ui 8080:8080`

然后访问：

`1`	`http://localhost:8080`

可以先问几个低风险问题：

`1`	`列出当前集群里可以查询的 Kubernetes API resources。`

再问一个会用到 fetch 的问题：

`1`	`帮我读取 https://kagent.dev/docs/kagent/getting-started/first-mcp-tool ，总结创建 MCPServer 和 Agent 的关键步骤。`

如果 Agent 正常，它应该会调用对应工具，而不是直接编造结果。这个时候我会重点看 UI 里有没有展示 tool call、参数和返回内容。kagent 这类工具的价值不只是回答，还在于能不能复盘它怎么回答的。

6. 权限边界：我不会一开始就给写权限

这个 case 里我故意只选了只读工具。原因很简单：Agent 最容易出事故的不是回答错，而是拿着写权限执行错。

如果未来要开放写操作，我会分三层：

1
2
3


read_only get/list/watch/logs/events
reviewed 生成 YAML、生成 patch，但不 apply
approved 人工确认后才允许执行写操作

kagent 的 Tool 配置里支持 requireApproval，可以把敏感工具列进去，让工具调用前停下来等人工确认。这个设计比“相信系统提示词不会乱来”靠谱。

比如后续某个 MCP server 有一个 restart_deployment 工具，我不会直接放开，而是会写成：

1
2
3
4
5
6
7
8
9


tools:
 - type: McpServer
 mcpServer:
 kind: MCPServer
 name: ops-actions
 toolNames:
 - restart_deployment
 requireApproval:
 - restart_deployment

这套 case 的落地判断

如果只是本地试用，kagent install --profile demo 更快。官方 quickstart 里这条命令会预装一些 demo agents 和 MCP tools：

1
2


kagent install --profile demo
kagent dashboard

但如果要往团队环境里放，我更建议走 Helm + YAML：

CRD 和 controller 由平台侧统一安装。
ModelConfig、MCPServer、Agent 放进 Git 仓库。
每个 Agent 的工具列表明确写出来。
写操作默认要求人工确认。
先把目标限定为“排查摘要”和“信息收集”，不要一上来自动修复。

kagent 这类项目让我感觉 Kubernetes 后面会多出一种新对象：不是 workload，也不是 controller，而是“会调用工具的运维助手”。但真正能不能用，不取决于它能不能聊天，而取决于工具边界、权限边界和运行记录是不是足够清楚。

参考资料

Model Context Protocol 与 OpenAI 工具调用实践

Sun, 27 Jul 2025 10:16:57 +0800

引言：从“问答机器人”到“行动型AI助手”

传统的聊天机器人大多停留在“理解-回答”的单向交互模式。而随着大模型能力的演进，我们不再满足于“知道答案”，更希望 AI 能“采取行动”——比如查询天气、发送邮件、执行数据库操作等。

这正是 Model Context Protocol (MCP) 和 OpenAI 函数调用（Function Calling） 技术的用武之地。本文将带你从零开始，用 Go 语言实现一个基于 MCP 协议与 OpenAI SDK 深度整合的 Demo，构建一个能动态发现并调用远程工具的智能对话系统。

我们将深入剖析核心架构、关键设计模式，并最终实现一个可扩展、高可用的 AI 助手原型。

核心目标：

多轮递归调用：支持 LLM 决策后多次调用工具。
上下文累积：确保每一轮工具调用的结果都能被 LLM 看到。
高效并发处理：利用 Go 的并发特性提升响应速度。
精准流程控制：正确解析 FinishReason，避免冗余请求。

一、技术选型与核心概念

1.1 OpenAI Function Calling（函数调用）

OpenAI 的 gpt-3.5-turbo 及以上模型支持“函数调用”功能。你可以向模型描述一组函数（工具）的能力，模型会根据用户输入决定是否调用、调用哪个函数，并生成符合函数签名的参数。

核心优势：将自然语言指令转化为结构化 API 调用。
参考实现：sashabaranov/go-openai

1.2 Model Context Protocol (MCP)

MCP 是一种新兴的标准化协议，用于描述和暴露 LLM 可调用的“工具”（Tools）。它允许 LLM 客户端动态发现远程服务提供的功能，并安全地执行调用。

核心价值：
- 动态发现：无需硬编码工具列表，运行时自动获取。
- 解耦架构：LLM 核心与工具提供方完全分离，便于微服务部署。
- 标准化接口：统一的 ListTools、CallTool 接口，降低集成成本。
参考实现：modelcontextprotocol/go-sdk

1.3 为什么选择 Go？

高性能：适合高并发的 API 网关场景。
强类型与并发支持：sync, errgroup 等包让并发控制更安全。
丰富的生态：go-openai, gin, grpc 等库成熟稳定。

二、系统架构设计

我们的系统由三部分组成：

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


+----------------+ +---------------------+ +------------------+
| | | | | |
| 用户请求 | --> | OpenAI LLM | --> | MCP 工具服务 |
| (DingTalk等) | | (决策与生成) | | (天气、数据库等) |
| | | | | |
+----------------+ +----------+----------+ +------------------+
 |
 v
 +------------------+
 | MCP Manager |
 | (工具发现与路由) |
 +------------------+

LLM 核心：负责理解用户意图，决定是否调用工具。
MCP Manager：管理多个 MCP 服务连接，实现工具发现与负载均衡。
MCP 服务：实际提供工具能力的微服务（如天气查询、数据库操作）。

三、核心代码解析

3.1 MCPManager：工具服务的“指挥官”

MCPManager 是整个系统的核心调度器，负责管理所有 MCP 服务的生命周期和工具映射。

1
2
3
4


type MCPManager struct {
	clients []*MCPClient // 所有 MCP 客户端
	toolMap sync.Map // 工具-服务器映射: toolName -> []*MCPClient
}

关键方法：

NewMCPManager()
从配置文件加载所有 MCP 服务地址，初始化客户端列表。
ConnectAll(ctx)
使用 errgroup 并发连接所有 MCP 服务，提升启动效率。
buildToolMap(ctx)
核心逻辑！遍历所有已连接的服务，调用 ListTools() 获取其提供的工具，并构建全局映射表 toolMap。
✅ 优势：支持多服务提供同一工具（负载均衡），自动去重。
ExecuteTool(ctx, toolName, args)
根据 toolMap 找到提供该工具的服务，尝试调用。支持失败重试，增强系统鲁棒性。

3.2 MCPClient：MCP 服务的“通信桥梁”

MCPClient 封装了与单个 MCP 服务的通信细节。

1
2
3
4
5
6


func (m *MCPClient) Connect(ctx context.Context) error {
	client := mcp.NewClient(&mcp.Implementation{...}, nil)
	session, err := client.Connect(ctx, &mcp.StreamableClientTransport{Endpoint: m.host}, nil)
	m.session = session
	return err
}

关键方法：

ListTools(ctx)
调用 MCP 的 ListTools 接口，并将返回的工具描述转换为 OpenAI 兼容的 openai.Tool 格式。这是实现协议桥接的关键一步。
ExecuteTool(ctx, toolName, args)
使用 CallTool 接口执行工具调用，并内置了3次重试机制，避免因网络抖动导致失败。

3.3 LLMClient：OpenAI 的“代言人”

封装了 sashabaranov/go-openai 客户端，提供更简洁的调用接口。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func (l *LLMClient) CreateCompletion(ctx context.Context, messages []openai.ChatCompletionMessage, tools []openai.Tool) (interface{}, error) {
	req := openai.ChatCompletionRequest{
		Model: l.model,
		Messages: messages,
		Tools: tools,
		ToolChoice: "auto",
		Stream: l.stream,
	}
	// ...
}

线程安全初始化：使用 sync.OnceFunc 确保 LLMClientO 全局单例。
灵活配置：支持自定义 baseURL（用于私有化部署的 LLM）。

3.4 ChatSession：对话状态的“管理者”

ChatSession 维护了完整的对话上下文（messages），并驱动整个交互流程。

核心流程 `HandleUserInput`：

添加用户消息 → 2. 调用 LLM → 3. 处理响应

若 LLM 返回文本，则直接回复用户。
若 LLM 返回工具调用，则执行 handleToolCalls。

`buildSystemPrompt()`：LLM 的“操作手册”

这是最精妙的设计之一！我们动态生成系统提示，将所有可用工具的描述注入给 LLM：

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


你是一个有帮助的助手，可以使用以下工具:

{
 "name": "getWeather",
 "description": "获取天气情况",
 "parameters": { ... }
}

重要提示: 当你需要使用工具时，必须只返回以下格式的JSON对象:
{
 "tool": "tool-name",
 "arguments": { ... }
}

✅ 优势：LLM 始终知道“我能做什么”，无需重新训练。

四、深入理解 `FinishReason`：LLM 的“决策信号灯”

FinishReason 是 LLM 返回响应时附带的状态码，它告诉客户端“我为什么停止生成”。正确解析它，是实现智能交互的前提。

`FinishReason`	含义	我们的处理策略
`stop`	模型自然结束，通常已生成最终答案	✅ 直接回复用户
`length`	因达到最大 token 限制而截断	⚠️ 可选择扩展上下文或警告用户
`tool_calls`	模型决定调用一个或多个工具	🔧 执行工具调用，并将结果返回给模型继续思考
`function_call`	旧版函数调用（与 `tool_calls` 类似）	🔧 兼容处理，同 `tool_calls`
`content_filter`	内容被安全策略拦截	🛡️ 向用户返回安全提示
`null`	生成未完成（流式响应中常见）	🔄 继续接收流数据

✅ 重点：tool_calls 和 function_call 是我们进行工具调用的触发信号。

五、核心交互流程的增强设计

我们对 ChatSession.HandleUserInput 方法进行了全面升级，使其支持递归式多轮工具调用。

增强版交互流程图

 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


 +------------------+
 | 用户输入问题 |
 +--------+---------+
 |
 v
 +------------------+
 | 调用 LLM 生成响应 |
 +--------+---------+
 |
 +-------------------------+-------------------------+
 | |
 v (tool_calls) v (stop / length)
+---------------------+ +---------------------+
| 执行所有工具调用 | | 直接回复用户 |
| - 并发执行（可选） | +---------------------+
| - 累积结果到 messages |
+----------+----------+
 |
 v
 +---------------------+
 | 将结果喂回 LLM |
 | 再次调用 HandleUserInput |
 +----------+----------+
 |
 +--------> (循环，直到 LLM 返回 stop)

六、实战演示：多轮工具调用

假设用户提问：

“请查询北京和杭州的天气，并告诉我哪个更热？”

系统执行流程：

第一轮 LLM 调用：

LLM 分析问题，决定需要调用 getWeather 工具两次。
返回 FinishReason: tool_calls，并包含两个 ToolCall。

执行工具调用：

MCPManager 并发调用两次 getWeather。
假设返回：
- 北京：30°C
- 杭州：25°C

将结果注入上下文：

两条 Role: tool 的消息被加入 messages。

第二轮 LLM 调用（递归调用 HandleUserInput("", ctx)）：

LLM “看到”了两个城市的天气数据。
经过推理，生成最终回复：

“北京的气温是 30°C，杭州是 25°C，因此北京更热。”
返回 FinishReason: stop。

回复用户：

系统调用 replyToUser()，将 Content 中的内容直接发送给用户。

✅ 成功实现多轮推理与决策，且在 stop 时正确终止流程！

七、设计亮点与最佳实践

动态工具发现：无需重启即可接入新服务。
高可用设计：errgroup 并发连接、工具调用重试、服务健康检查。
协议桥接：无缝整合 MCP 与 OpenAI 两种协议。
可扩展架构：轻松支持数据库查询、邮件发送、内部 API 调用等更多工具。
清晰的职责分离：MCPManager, ChatSession, LLMClient 各司其职。

结语

通过将 MCP 的动态工具发现能力与 OpenAI 强大的语言理解能力相结合，我们构建了一个真正“能做事”的 AI 助手。这不仅是一个 Demo，更是一种可落地的架构范式。

在微服务与 AI 融合的浪潮中，掌握这种“LLM + 工具调用”的模式，将为你打开通往下一代智能应用的大门。

代码已开源：GitHub 仓库链接
欢迎 Star 与贡献！

Mcp on DK Blog

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

我比较在意的点

如果我要试

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

参考资料

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

失败要分类

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

trace 比想象中重要

小结

参考资料

kagent：在 Kubernetes 里跑一个完整的 AI Agent Case

这个 case 里会出现哪些对象

1. 安装 CRD 和 controller

2. 准备模型 Secret 和 ModelConfig

3. 创建一个 MCPServer：网页 fetch 工具

4. 创建 Agent：同时引用 Kubernetes 工具和 fetch 工具

5. 打开 UI 验证

6. 权限边界：我不会一开始就给写权限

这套 case 的落地判断

参考资料

Model Context Protocol 与 OpenAI 工具调用实践

引言：从“问答机器人”到“行动型AI助手”

核心目标：

一、技术选型与核心概念

1.1 OpenAI Function Calling（函数调用）

1.2 Model Context Protocol (MCP)

1.3 为什么选择 Go？

二、系统架构设计

三、核心代码解析

3.1 MCPManager：工具服务的“指挥官”

关键方法：

3.2 MCPClient：MCP 服务的“通信桥梁”

关键方法：

3.3 LLMClient：OpenAI 的“代言人”

3.4 ChatSession：对话状态的“管理者”

核心流程 HandleUserInput：

buildSystemPrompt()：LLM 的“操作手册”

四、深入理解 FinishReason：LLM 的“决策信号灯”

五、核心交互流程的增强设计

增强版交互流程图

六、实战演示：多轮工具调用

系统执行流程：

七、设计亮点与最佳实践

结语

核心流程 `HandleUserInput`：

`buildSystemPrompt()`：LLM 的“操作手册”

四、深入理解 `FinishReason`：LLM 的“决策信号灯”