Ai on DK Blog

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、文档和测试，它解决的就是混乱本身。

参考资料

Codex CLI 交互斜杠命令全集（含作用与使用场景）

Thu, 05 Mar 2026 23:40:00 +0800

来源：OpenAI 官方文档（Codex CLI Slash Commands）
更新时间：2026-03-05
说明：以下是 codex 交互界面（TUI）内输入的 /xxx 命令，不是 PowerShell 系统命令。

最近在高频用 Codex CLI，发现很多同学刚上手时，会把 /xxx 斜杠命令和系统命令混在一起，导致操作路径有点乱。
所以我把官方文档里这部分命令做了一次“能直接抄着用”的整理：每个命令不只写功能，还配了一个真实使用场景，方便你在实战里快速判断“现在该敲哪个”。

使用方式

启动 codex
在输入框输入 / 打开命令列表
选择命令或手动输入完整命令

命令清单（作用 + 场景）

命令	具体作用	典型使用场景
`/permissions`	设置当前会话的审批/权限策略	你要从“手动审批”切到“自动执行优先”时
`/sandbox-add-read-dir`	给沙箱追加可读目录（Windows 原生 CLI）	需要读取工作区外的配置目录或共享代码目录
`/agent`	切换当前活跃 agent 线程	同时跑了多个任务，想切回另一个线程继续
`/apps`	浏览并插入可用 connectors/apps	需要接入外部系统数据（如任务系统、文档系统）
`/clear`	清屏并开启新会话	当前对话太长，想从干净上下文重新提问
`/compact`	压缩并总结长对话，减少上下文占用	会话很长导致响应变慢或上下文接近上限
`/copy`	复制最近一次已完成输出	要把刚生成的命令/代码粘贴到别处使用
`/diff`	查看当前 Git diff（含未跟踪文件）	让模型改完代码后，先人工快速过一遍改动
`/exit`	退出 CLI（等价 `/quit`）	结束当前工作会话
`/experimental`	开关实验功能	想试新能力或排查某实验特性的影响
`/feedback`	提交日志/反馈	发现异常行为，需要把现场信息反馈给官方
`/init`	在当前目录生成 `AGENTS.md` 模板	新仓库首次使用 Codex，先定义协作规则
`/logout`	退出登录并清理本地凭据	切账号、交接机器或做安全清理
`/mcp`	查看已配置 MCP 工具	检查某工具是否已接入、当前可不可用
`/mention`	把文件/目录加入当前对话上下文	只想让模型关注某几个目录而不是全仓库
`/model`	切换模型（可含推理强度）	先用快模型探索，再切强模型做最终修复
`/plan`	切到 Plan 模式并提出规划请求	任务复杂，先要分步骤方案再执行
`/personality`	切换回答风格（friendly/pragmatic/none）	团队希望输出更简洁或更工程化
`/ps`	查看实验性的后台终端及输出	排查后台执行任务卡住或失败原因
`/fork`	从当前会话分叉新线程	保留原思路，同时探索另一种实现路径
`/resume`	恢复历史会话	第二天继续昨天做到一半的任务
`/new`	在同一 CLI 中新开对话	当前问题做完，开始另一个独立任务
`/quit`	退出 CLI	同 `/exit`，用于结束会话
`/review`	让 Codex 审查当前改动	提交 PR 前先自动扫一轮风险点
`/status`	查看会话配置与 token 使用	想确认当前模型、沙箱、审批和消耗情况
`/debug-config`	输出配置层与策略诊断信息	配置不生效时定位是被哪一层覆盖
`/statusline`	配置 TUI 状态栏显示项	想在界面上实时看到模型/审批等状态

兼容与别名

/approvals：仍可用，但通常不在 slash 列表里显示；建议改用 /permissions。
/exit 与 /quit：功能等价，都是退出 CLI。

两个高频命令

/init：初始化仓库级协作规则（生成 AGENTS.md）。
/model：任务中途切模型，平衡速度和质量。

版本差异说明

不同 codex-cli 版本会新增/隐藏命令。以你本机实际可见列表为准：在交互界面输入 / 即可查看当前版本完整命令。

写在最后

如果你是第一次系统使用 Codex CLI，我建议先记住这几个高频命令：/model、/permissions、/diff、/review、/status。
这几个覆盖了日常最常见的流程：选模型 -> 管权限 -> 看改动 -> 做审查 -> 查会话状态。

另外一个实用习惯是：遇到“感觉命令不见了”或者“和别人截图不一致”时，先在当前会话里输入 / 看本机版本实际列表，再决定下一步。
这样能避免把时间花在“文档有，但你当前版本没开”这类问题上。

官方链接

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，而是“会调用工具的运维助手”。但真正能不能用，不取决于它能不能聊天，而取决于工具边界、权限边界和运行记录是不是足够清楚。

参考资料

用 Go 打造多轮工具调用 AI Agent：从代码到实战

Mon, 04 Aug 2025 14:57:57 +0800

用Go打造多轮工具调用AI Agent：从代码到实战

在大模型时代，单纯的文本生成已无法满足复杂需求，能调用工具的AI Agent才是主流。本文将基于Go语言和go-openai库，带你从零构建一个支持天气查询、数学计算、时区时间查询的多轮工具调用Agent，完整覆盖工具定义、参数校验、递归调用全流程。

核心原理：AI Agent为何能调用工具？

AI Agent实现工具调用的核心逻辑，本质是“模型决策+工具执行+上下文管理”的闭环：

模型决策：通过向大模型传递工具定义（名称、参数、功能），让模型自主判断是否需要调用工具，以及调用哪个工具。
工具执行：解析模型返回的工具调用指令，调用对应的本地/第三方工具，获取执行结果。
上下文管理：将工具执行结果回传给模型，作为下一轮决策的依据，实现多轮调用的连贯性。

本文的Agent正是基于此逻辑，通过递归调用实现多步骤工具串联（如“查天气→算温差平均值→查时区时间”）。

项目结构：模块化设计拆解

整个项目按功能划分为6个核心模块，每个模块职责单一，便于维护和扩展：

模块	核心功能	关键代码文件
工具参数结构体	定义各工具的输入参数格式，用于解析模型返回的调用指令	`WeatherParams`/`CalcParams`/`TimeParams`
工具实现逻辑	封装具体工具的业务逻辑（模拟第三方API调用）	`getWeather`/`calculate`/`getCurrentTime`
工具定义（核心）	用`jsonschema`标准化工具参数，传递给大模型	`getOpenAITools()`
工具调用执行器	解析模型指令，分发并执行对应工具	`executeToolCall()`
递归多轮调用	管理上下文，控制调用流程，处理模型终止逻辑	`recursiveAgent()`
入口函数	初始化客户端，构造测试用例，启动Agent	`main()`

关键实现：从工具定义到多轮调用

1. 工具参数标准化：用jsonschema约束输入

大模型调用工具的前提，是明确“工具需要什么参数”。通过go-openai/jsonschema库，我们可以标准化参数定义，让模型更精准地生成调用指令。

以天气查询工具为例，参数定义需包含3个核心信息：

参数类型：明确是字符串、数字还是对象。
参数描述：告知模型参数的含义和格式（如“城市名称，仅支持国内主流城市”）。
必传字段：标记哪些参数是必须的，避免模型漏传。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 天气工具参数定义（jsonschema）
weatherCityParam := jsonschema.Definition{
 Type: jsonschema.String, // 参数类型：字符串
 Description: "城市名称（如北京、上海，仅支持国内主流城市）", // 参数描述
}
// 天气工具整体参数Schema
weatherParamsSchema := jsonschema.Definition{
 Type: jsonschema.Object,
 Properties: map[string]jsonschema.Definition{"city": weatherCityParam},
 Required: []string{"city"}, // 必传字段：city
}

同理，数学计算工具需定义expr（表达式）参数，时间查询工具需定义timezone（时区）参数，最终通过getOpenAITools()函数组装成工具列表，传递给大模型。

2. 工具逻辑封装：模拟真实API调用

工具实现需考虑3个关键点：超时控制、业务逻辑、异常处理，确保工具调用稳定可靠。

以天气查询工具getWeather()为例：

超时控制：用context.WithTimeout设置3秒超时，避免工具调用阻塞。
业务逻辑：模拟网络延迟（500ms），用预定义的weatherMap返回天气数据。
异常处理：未查询到城市时，返回明确的支持城市列表，提升用户体验。

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


func getWeather(ctx context.Context, city string) (string, error) {
 // 3秒超时控制
 ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
 defer cancel()

 // 模拟网络延迟
 select {
 case <-ctx.Done():
 return "", fmt.Errorf("查询超时：%v", ctx.Err())
 case <-time.After(500 * time.Millisecond):
 }

 // 模拟天气数据
 weatherMap := map[string]string{
 "北京": "晴，20-28℃，微风",
 "上海": "多云，18-25℃，东北风3级",
 // 更多城市...
 }

 if weather, ok := weatherMap[city]; ok {
 return fmt.Sprintf("[天气工具结果] 城市：%s → %s", city, weather), nil
 }
 return fmt.Sprintf("[天气工具结果] 未查询到「%s」的天气数据（支持城市：北京、上海、广州、深圳、杭州）", city), nil
}

3. 多轮调用核心：递归Agent的实现

递归是实现多轮工具调用的关键，recursiveAgent()函数通过以下步骤控制流程：

步骤1：递归深度限制

设置maxRecursionDepth（本文设为5），避免模型逻辑异常导致无限循环。

步骤2：调用大模型

向模型传递上下文消息和工具定义，让模型判断是否调用工具。这里需注意2个参数：

ToolChoice: openai.ChunkingStrategyTypeAuto：让模型自主决定是否调用工具。
Temperature: 0.3：降低随机性，确保工具调用逻辑稳定。

步骤3：处理模型终止原因（FinishReason）

模型返回的FinishReason决定了下一步操作，这是多轮调用的核心分支逻辑：

FinishReason	含义	处理方式
`stop`	模型无需调用工具，直接返回答案	终止递归，返回最终结果
`tool_calls`	模型需要调用工具	执行工具，将结果加入上下文，继续递归
`length`	响应因Token不足被截断	提示增大`MaxTokens`
`content_filter`	内容被过滤	告知用户无法处理

步骤4：上下文管理

每次模型响应（无论是文本还是工具调用指令）、工具执行结果，都需加入上下文消息列表，确保模型能追溯历史交互，实现多轮连贯性。

4. 工具调用执行器：解析与分发

executeToolCall()函数负责解析模型返回的工具调用指令，分发到对应工具执行：

参数解析：将模型返回的JSON格式参数，反序列化为对应的结构体（如WeatherParams）。
参数校验：兜底校验必传参数（如城市名称不能为空），避免工具执行异常。
工具调用：根据工具名称（get_weather/calculate/get_current_time）调用对应函数，返回执行结果。

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


func executeToolCall(ctx context.Context, toolCall openai.ToolCall) (string, error) {
 switch toolCall.Function.Name {
 case "get_weather":
 // 解析天气参数
 var params WeatherParams
 if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &params); err != nil {
 return "", fmt.Errorf("参数解析失败：%v（请检查是否传入 city 字段）", err)
 }
 return getWeather(ctx, params.City)
 
 // 数学计算、时间查询工具的解析逻辑类似...
 }
}

实战测试：复杂多轮场景验证

为验证Agent的多轮调用能力，我们设计一个复杂测试用例：

“查询上海的天气，计算其最高温与最低温的平均值，再查询 UTC 时区的当前时间”

测试流程拆解

第一轮：模型判断需先调用get_weather工具，查询上海天气（返回“多云，18-25℃，东北风3级”）。
第二轮：模型提取气温数据（18℃和25℃），调用calculate工具计算平均值（(18+25)/2=21.5℃）。
第三轮：模型调用get_current_time工具，查询UTC时区时间。
第四轮：模型整合所有工具结果，用自然语言生成最终答案。

最终输出示例

1
2
3
4
5


===========================================
最终答案：
上海当前天气为多云，气温18-25℃，东北风3级；其最高温与最低温的平均值为21.5℃。
UTC时区的当前时间为2025-11-04 07:23:15。
===========================================

扩展与优化建议

增加更多工具：按现有模式，可轻松扩展股票查询、快递跟踪等工具，只需新增参数结构体、工具实现和jsonschema定义。
参数校验增强：引入go-playground/validator库，实现更复杂的参数校验（如城市名称合法性、数学表达式格式）。
日志与监控：增加结构化日志（如用zap库），记录工具调用耗时、结果状态，便于问题排查。
并发工具调用：当前工具执行是串行的，可通过goroutine实现多工具并行调用，提升效率。
模型切换：本文使用Qwen3-Next-80B-A3B-Instruct模型，可替换为gpt-4o/claude-3等支持工具调用的模型，只需调整客户端配置。

完整代码获取

本文的完整代码已整理，包含工具定义、递归Agent、测试用例全流程，可直接运行（需替换API Key和BaseURL）。

 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
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373


package main

import (
	"context"
	"encoding/json"
	"fmt"
	"math"
	"time"

	"github.com/sashabaranov/go-openai"
	"github.com/sashabaranov/go-openai/jsonschema"
)

// ========================== 1. 工具参数结构体（用于解析工具调用结果） ==========================
// 天气查询参数（仅用于解析模型返回的工具调用参数，无需额外标签）
type WeatherParams struct {
	City string `json:"city"`
}

// 数学计算参数
type CalcParams struct {
	Expr string `json:"expr"`
}

// 时间查询参数
type TimeParams struct {
	Timezone string `json:"timezone"`
}

// ========================== 2. 工具实现逻辑（无修改） ==========================
// 天气查询工具（模拟第三方 API 调用）
func getWeather(ctx context.Context, city string) (string, error) {
	// 超时控制（3秒）
	ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
	defer cancel()

	// 模拟 API 网络延迟
	select {
	case <-ctx.Done():
		return "", fmt.Errorf("查询超时：%v", ctx.Err())
	case <-time.After(500 * time.Millisecond):
	}

	// 模拟天气数据
	weatherMap := map[string]string{
		"北京": "晴，20-28℃，微风",
		"上海": "多云，18-25℃，东北风3级",
		"广州": "雷阵雨，22-26℃，南风2级",
		"深圳": "阴，23-27℃，东风2级",
		"杭州": "晴转多云，19-26℃，西北风2级",
	}

	if weather, ok := weatherMap[city]; ok {
		return fmt.Sprintf("[天气工具结果] 城市：%s → %s", city, weather), nil
	}
	return fmt.Sprintf("[天气工具结果] 未查询到「%s」的天气数据（支持城市：北京、上海、广州、深圳、杭州）", city), nil
}

// 数学计算工具（支持基础运算）
func calculate(ctx context.Context, expr string) (string, error) {
	// 超时控制（2秒）
	ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
	defer cancel()

	// 模拟计算延迟
	select {
	case <-ctx.Done():
		return "", fmt.Errorf("计算超时：%v", ctx.Err())
	case <-time.After(300 * time.Millisecond):
	}

	// 支持的表达式逻辑
	switch expr {
	case "100*200":
		return fmt.Sprintf("[计算工具结果] %s = %d", expr, 100*200), nil
	case "sqrt(16)":
		return fmt.Sprintf("[计算工具结果] %s = %.2f", expr, math.Sqrt(16)), nil
	case "(25+18)/2":
		return fmt.Sprintf("[计算工具结果] %s = %d", expr, (25+18)/2), nil
	case "200/5":
		return fmt.Sprintf("[计算工具结果] %s = %d", expr, 200/5), nil
	case "(18+25)/2":
		return fmt.Sprintf("[计算工具结果] %s = %.1f", expr, (18+25)/2.0), nil
	default:
		return fmt.Sprintf("[计算工具结果] 暂不支持表达式：%s（当前支持：100*200、sqrt(16)、(a+b)/2、a/b）", expr), nil
	}
}

// 时间查询工具（支持多时区）
func getCurrentTime(ctx context.Context, timezone string) (string, error) {
	// 超时控制（1秒）
	ctx, cancel := context.WithTimeout(ctx, 1*time.Second)
	defer cancel()

	// 模拟查询延迟
	select {
	case <-ctx.Done():
		return "", fmt.Errorf("时间查询超时：%v", ctx.Err())
	case <-time.After(200 * time.Millisecond):
	}

	// 默认时区处理（未传时区时用上海时区）
	if timezone == "" {
		timezone = "Asia/Shanghai"
	}

	// 加载时区并格式化时间
	loc, err := time.LoadLocation(timezone)
	if err != nil {
		return fmt.Sprintf("[时间工具结果] 无效时区：%s（示例有效时区：Asia/Shanghai、UTC、America/New_York）", timezone), nil
	}
	currentTime := time.Now().In(loc).Format("2006-01-02 15:04:05")
	return fmt.Sprintf("[时间工具结果] 时区「%s」的当前时间：%s", timezone, currentTime), nil
}

// ========================== 3. 核心修改：用 go-openai/jsonschema 定义工具参数 ==========================
// getOpenAITools：通过 jsonschema.Definition 构建 OpenAI 工具定义
func getOpenAITools() []openai.Tool {
	// -------------------------- 3.1 天气工具参数（jsonschema 定义） --------------------------
	weatherCityParam := jsonschema.Definition{
		Type: jsonschema.String, // 参数类型：字符串
		Description: "城市名称（如北京、上海，仅支持国内主流城市）", // 参数描述
	}
	// 天气工具的整体参数 Schema（对象类型，包含 city 字段）
	weatherParamsSchema := jsonschema.Definition{
		Type: jsonschema.Object,
		Properties: map[string]jsonschema.Definition{"city": weatherCityParam},
		Required: []string{"city"}, // 明确必传字段列表
	}

	// -------------------------- 3.2 计算工具参数（jsonschema 定义） --------------------------
	calcExprParam := jsonschema.Definition{
		Type: jsonschema.String,
		Description: "数学表达式（支持乘法*、除法/、开方sqrt()、两数平均值(a+b)/2）",
	}
	calcParamsSchema := jsonschema.Definition{
		Type: jsonschema.Object,
		Properties: map[string]jsonschema.Definition{"expr": calcExprParam},
		Required: []string{"expr"},
	}

	// -------------------------- 3.3 时间工具参数（jsonschema 定义） --------------------------
	timezoneParam := jsonschema.Definition{
		Type: jsonschema.String,
		Description: "时区（如 Asia/Shanghai 表示上海时区，UTC 表示世界协调时间）",
	}
	timeParamsSchema := jsonschema.Definition{
		Type: jsonschema.Object,
		Properties: map[string]jsonschema.Definition{"timezone": timezoneParam},
		Required: []string{}, // 无必传字段
	}

	// -------------------------- 3.4 组装 OpenAI 工具列表 --------------------------
	return []openai.Tool{
		{
			Type: openai.ToolTypeFunction,
			Function: &openai.FunctionDefinition{
				Name: "get_weather", // 工具名称（模型调用时使用）
				Description: "查询指定城市的实时天气（包含气温、天气状况、风力信息）", // 工具描述（帮助模型判断是否需要调用）
				Parameters: weatherParamsSchema, // 绑定上述定义的参数 Schema
			},
		},
		{
			Type: openai.ToolTypeFunction,
			Function: &openai.FunctionDefinition{
				Name: "calculate",
				Description: "执行基础数学计算（支持四则运算和简单函数，不支持复杂公式）",
				Parameters: calcParamsSchema,
			},
		},
		{
			Type: openai.ToolTypeFunction,
			Function: &openai.FunctionDefinition{
				Name: "get_current_time",
				Description: "查询指定时区的当前时间（默认返回上海时区时间，支持全球主流时区）",
				Parameters: timeParamsSchema,
			},
		},
	}
}

// ========================== 4. 工具调用执行器（解析+执行） ==========================
func executeToolCall(ctx context.Context, toolCall openai.ToolCall) (string, error) {
	fmt.Printf("\n[工具调用] 名称：%s，参数：%s\n", toolCall.Function.Name, toolCall.Function.Arguments)

	// 根据工具名称分发执行
	switch toolCall.Function.Name {
	case "get_weather":
		// 解析工具参数（绑定到 WeatherParams 结构体）
		var params WeatherParams
		if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &params); err != nil {
			return "", fmt.Errorf("参数解析失败：%v（请检查是否传入 city 字段）", err)
		}
		// 参数校验（兜底，防止模型未传必传参数）
		if params.City == "" {
			return "", fmt.Errorf("城市名称不能为空（工具要求必传 city 参数）")
		}
		return getWeather(ctx, params.City)

	case "calculate":
		var params CalcParams
		if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &params); err != nil {
			return "", fmt.Errorf("参数解析失败：%v（请检查是否传入 expr 字段）", err)
		}
		if params.Expr == "" {
			return "", fmt.Errorf("数学表达式不能为空（工具要求必传 expr 参数）")
		}
		return calculate(ctx, params.Expr)

	case "get_current_time":
		var params TimeParams
		if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &params); err != nil {
			return "", fmt.Errorf("参数解析失败：%v（请检查 timezone 字段格式）", err)
		}
		// 未传时区时使用默认值（工具定义中已声明，此处兜底）
		if params.Timezone == "" {
			params.Timezone = "Asia/Shanghai"
		}
		return getCurrentTime(ctx, params.Timezone)

	default:
		return "", fmt.Errorf("未知工具：%s（当前支持工具：get_weather、calculate、get_current_time）", toolCall.Function.Name)
	}
}

// ========================== 5. 递归多轮工具调用逻辑（FinishReason 校验） ==========================
const maxRecursionDepth = 5 // 最大递归深度（防止无限循环）

func recursiveAgent(ctx context.Context, client *openai.Client, messages []openai.ChatCompletionMessage, depth int) (string, error) {
	// 1. 递归深度限制：超过阈值直接终止（避免模型逻辑异常导致循环）
	if depth > maxRecursionDepth {
		errMsg := fmt.Sprintf("递归深度超过阈值（最大 %d 轮），可能存在工具调用循环或模型逻辑异常", maxRecursionDepth)
		fmt.Println("[错误]", errMsg)
		return "", fmt.Errorf(errMsg)
	}

	// 2. 调用 OpenAI 模型（传入工具定义，让模型判断是否调用工具）
	resp, err := client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
		Model: "Qwen3-Next-80B-A3B-Instruct", // 必须使用支持函数调用的模型（gpt-4o 更优）
		Messages: messages, // 上下文消息（包含历史交互记录）
		Tools: getOpenAITools(), // 传入用 jsonschema 定义的工具列表
		ToolChoice: openai.ChunkingStrategyTypeAuto, // 模型自主判断是否调用工具
		Temperature: 0.3, // 降低随机性，确保工具调用逻辑稳定
		MaxTokens: 1024, // 限制单轮响应长度，避免 token 不足
	})
	if err != nil {
		return "", fmt.Errorf("模型请求失败：%v（请检查 API Key 和网络连接）", err)
	}

	// 提取模型响应核心信息
	choice := resp.Choices[0]
	modelMsg := choice.Message
	finishReason := choice.FinishReason

	// 打印调试日志（便于跟踪调用流程）
	fmt.Printf("\n[模型响应] 深度：%d | FinishReason：%s | 角色：%s | 内容：%s\n",
		depth, finishReason, modelMsg.Role, modelMsg.Content)

	// 3. 将模型响应加入上下文（关键：保存所有交互历史，让模型追溯前序步骤）
	messages = append(messages, modelMsg)

	// 4. 根据 FinishReason 分支处理（核心逻辑：判断是否继续调用工具）
	switch finishReason {
	case openai.FinishReasonStop:
		// 场景1：模型正常终止（无需工具）→ 返回最终答案
		fmt.Println("[递归终止] FinishReason=stop，模型无需调用工具，直接返回最终答案")
		return modelMsg.Content, nil

	case openai.FinishReasonToolCalls:
		// 场景2：模型明确需要调用工具 → 执行工具并递归
		if len(modelMsg.ToolCalls) == 0 {
			errMsg := "异常：FinishReason=function_call，但模型未返回任何工具调用指令（可能是模型响应不完整）"
			fmt.Println("[错误]", errMsg)
			return "", fmt.Errorf(errMsg)
		}

		// 执行所有工具调用（支持单次多工具并行调用）
		for _, toolCall := range modelMsg.ToolCalls {
			toolResult, err := executeToolCall(ctx, toolCall)
			if err != nil {
				// 工具执行失败：将错误信息加入上下文，让模型决定是否重试或告知用户
				errorMsg := fmt.Sprintf("[工具调用失败] 工具：%s | 错误：%v", toolCall.Function.Name, err)
				fmt.Println(errorMsg)
				messages = append(messages, openai.ChatCompletionMessage{
					Role: openai.ChatMessageRoleTool,
					Name: toolCall.Function.Name,
					Content: errorMsg,
					ToolCallID: toolCall.ID, // 必须关联工具调用 ID，模型才能对应上下文
				})
				continue
			}

			// 工具执行成功：将结果加入上下文，供模型后续整理答案
			fmt.Printf("[工具结果] %s\n", toolResult)
			messages = append(messages, openai.ChatCompletionMessage{
				Role: openai.ChatMessageRoleTool,
				Name: toolCall.Function.Name,
				Content: toolResult,
				ToolCallID: toolCall.ID,
			})
		}

		// 递归继续：传入更新后的上下文，发起下一轮模型请求（深度+1）
		fmt.Printf("\n[递归继续] 第 %d 轮工具调用完成，发起下一轮模型请求\n", depth+1)
		return recursiveAgent(ctx, client, messages, depth+1)

	case openai.FinishReasonLength:
		// 场景3：token 不足导致响应截断 → 提示用户增大 MaxTokens
		errMsg := "模型响应因 token 长度限制被截断 → 解决方案：将 MaxTokens 参数从 1024 增大（如 2048）"
		fmt.Println("[错误]", errMsg)
		return "", fmt.Errorf(errMsg)

	case openai.FinishReasonContentFilter:
		// 场景4：内容被过滤 → 告知用户无法处理
		errMsg := "模型响应因内容过滤政策被截断（可能包含敏感信息），无法继续处理"
		fmt.Println("[错误]", errMsg)
		return "", fmt.Errorf(errMsg)

	case openai.FinishReasonNull:
		// 场景5：响应不完整（如流式响应未结束）→ 提示网络异常
		errMsg := "模型响应不完整，可能是网络波动或 API 服务临时故障"
		fmt.Println("[错误]", errMsg)
		return "", fmt.Errorf(errMsg)

	default:
		// 场景6：未知 FinishReason → 降级终止
		errMsg := fmt.Sprintf("未知的 FinishReason：%s，为避免异常终止递归调用", finishReason)
		fmt.Println("[错误]", errMsg)
		return "", fmt.Errorf(errMsg)
	}
}

// ========================== 6. 完整的 main 方法 ==========================
func main() {
	// 1. 校验 OpenAI API Key（必须设置环境变量）
	//apiKey := os.Getenv("OPENAI_API_KEY")
	config := openai.DefaultConfig("xxx")
	config.BaseURL = "xxx"
	client := openai.NewClientWithConfig(config)
	ctx := context.Background()
	
	userQuery := "查询上海的天气，计算其最高温与最低温的平均值，再查询 UTC 时区的当前时间"
	fmt.Printf("===========================================\n")
	fmt.Printf("用户提问：%s\n", userQuery)
	fmt.Printf("===========================================\n")
	
	initMessages := []openai.ChatCompletionMessage{
		{
			Role: openai.ChatMessageRoleSystem,
			Content: `你是一个智能 AI Agent，严格按照以下规则工作：
1. 必须根据用户问题，自主判断是否需要调用工具（天气、计算、时间）；
2. 若需要多步工具调用，需逐步执行，直到获取所有必要信息后再整理答案；
3. 工具返回结果后，用自然语言清晰、简洁地回复用户，无需额外冗余信息；
4. 若工具调用失败，需告知用户失败原因，无需继续重试。`,
		},
		{
			Role: openai.ChatMessageRoleUser,
			Content: userQuery,
		},
	}
	
	finalAnswer, err := recursiveAgent(ctx, client, initMessages, 0)
	if err != nil {
		fmt.Printf("\n===========================================\n")
		fmt.Printf("执行失败：%v\n", err)
		fmt.Printf("===========================================\n")
		return
	}
	
	fmt.Printf("\n===========================================\n")
	fmt.Printf("最终答案：\n%s\n", finalAnswer)
	fmt.Printf("===========================================\n")
}

代码执行Logs

通过本文的实践，你可以掌握了Go语言实现 AI Agent 的核心逻辑，更理解了多轮工具调用的底层原理。

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 与贡献！

Ai on DK Blog

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

先记住一个模型

先看通信闭环

wait_agent 为什么经常被误解

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

最短源码定位表

最后收一句

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

我比较在意的点

如果我要试

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

参考资料

Codex CLI 交互斜杠命令全集（含作用与使用场景）

使用方式

命令清单（作用 + 场景）

兼容与别名

两个高频命令

版本差异说明

写在最后

官方链接

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 的落地判断

参考资料

用 Go 打造多轮工具调用 AI Agent：从代码到实战

用Go打造多轮工具调用AI Agent：从代码到实战

核心原理：AI Agent为何能调用工具？

项目结构：模块化设计拆解

关键实现：从工具定义到多轮调用

1. 工具参数标准化：用jsonschema约束输入

2. 工具逻辑封装：模拟真实API调用

3. 多轮调用核心：递归Agent的实现

步骤1：递归深度限制

步骤2：调用大模型

步骤3：处理模型终止原因（FinishReason）

步骤4：上下文管理

4. 工具调用执行器：解析与分发

实战测试：复杂多轮场景验证

测试流程拆解

最终输出示例

扩展与优化建议

完整代码获取

代码执行Logs

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 的“决策信号灯”