本文将以我编写的一个 Go Agent Demo 为例，穿透各类框架的表层封装，回归其工程本质。我将首先分析其核心的 ReAct 循环，并展示这个看似简单的循环是如何通过模块化设计，演进为一个结构化、可扩展的软件系统。最近，我投入了一些时间学习和研究大语言模型（LLM）驱动的 Agent 技术。在对 LangChain、LlamaIndex 等主流框架进行了一番学习后，我决定自己动手，用 Go 语言编写一个 Agent Demo，以加深对底层原理的理解。本文便是我在完成这个 Demo 后，对 Agent 架构的一些复盘和思考，希望能为同样在探索这一领域的开发者提供一个清晰的视角。
摘要：本文将以我编写的一个 Go Agent Demo 为例，穿透各类框架的表层封装，回归其工程本质。我将首先分析其核心的 ReAct 循环，并展示这个看似简单的循环是如何通过模块化设计，演进为一个结构化、可扩展的软件系统。
一、Agent 的核心机制：一个状态驱动的循环
在动手编写代码前，我首先明确了 Agent 的核心运行机制：一个由 LLM 驱动、通过工具与外部交互的状态循环。这个模式通常被称为 ReAct (Reason-Act)。
其逻辑可以由以下伪代码概括：
// messages: 存储完整的对话上下文，包含系统提示
for {// 1. Reason (思考): 将上下文和可用工具列表提交给 LLM，获取行动计划thought := agent.Think(messages, available_tools)// 2. Decision (决策): 基于 LLM 的响应进行分支if thought.HasToolCalls() {// ... (行动、观察)continue} else {// ... (返回最终响应)return thought.Text // 终止循环}
}
这个循环是 Agent 工作流的基础：基于当前状态思考 -> 决策 -> 行动 -> 观察新状态 -> 进入下一轮思考。在我的 Demo 项目中，我将该循环实现于 internal/controller/controller.go 的 ProcessInput 方法内。
二、技术选型思考：为什么选择 Go？
在项目初期，我曾考虑过 Node.js 和 Python。但一个关键的用户体验需求——允许用户在任何时候通过 ESC 键中断 Agent 的长时间思考或工具执行，并立即返回交互界面——让我最终选择了 Go。
- Node.js/Python 的挑战：在单线程异步模型（如 Node.js 的事件循环或 Python 的 asyncio）中，处理这种抢占式中断相对复杂。一个长时间运行的同步I/O或CPU密集型任务可能会阻塞事件循环，使得监听用户输入（如
ESC键）的响应变得不及时。 - Go 的优势：Go 语言的
goroutine和channel提供了原生的、轻量级的并发能力。我可以轻易地将 Agent 的核心 ReAct 循环放在一个独立的goroutine中运行，同时主goroutine负责监听用户输入。通过context包，可以优雅地实现超时和取消信号的传递。当用户按下ESC时，主goroutine可以通过context.CancelFunc向正在执行任务的goroutine发送一个取消信号，使其安全地中止当前操作并退出，从而实现即时响应。
在我的项目中，Controller 的 ProcessInput 方法就接收了一个 context.Context 参数，并在循环的开始处检查其状态，这正是 Go 并发优势的具体体现。
// internal/controller/controller.go
func (c *Controller) ProcessInput(ctx context.Context, input string) (string, error) {// ...for {select {case <-ctx.Done(): // 检查取消信号return "", errors.New("operation cancelled by user")default:// 继续执行}// ...}
}
三、从循环到架构：模块化的必要性
明确了核心机制和技术栈后，下一步就是工程化。若核心只是一个 for 循环，引入多组件（如 Controller, Agent, ToolKit）的目的在于实现关注点分离 (SoC)，以保证系统的可维护性、可测试性和可扩展性。
我将我的项目结构映射为一套通用的 Agent 架构，其分层设计便一目了然：
四、代码分析：核心模块的职责与实现
以下我将分析自己编写的各模块是如何协同工作以驱动核心循环的。
1. 编排层：Controller - ReAct 循环的驱动者
Controller 负责驱动流程，不处理具体思考或执行细节。它实现了核心的 for 循环，并在循环的每个阶段调用其他组件。
// internal/controller/controller.go
func (c *Controller) ProcessInput(ctx context.Context, input string) (string, error) {c.messages = append(c.messages, models.Message{Role: "user", Content: input})for {// ... (上下文检查)// 调用思考层thought, err := c.agent.Think(ctx, c.messages)if err != nil {return "", fmt.Errorf("agent failed to think: %w", err)}if len(thought.ToolCalls) > 0 {c.messages = append(c.messages, models.Message{Role: "assistant", Content: thought.Text, ToolCalls: thought.ToolCalls})// 调用能力层for _, toolCall := range thought.ToolCalls {result, err := c.toolKit.ExecuteTool(toolCall.Name, toolCall.Arguments)// ... (处理工具执行结果)c.messages = append(c.messages, models.Message{Role: "tool", Content: result, ToolCallID: toolCall.ID})}continue // 驱动循环继续}c.messages = append(c.messages, models.Message{Role: "assistant", Content: thought.Text})return thought.Text, nil // 结束循环}
}
2. 思考层：Agent - 决策逻辑的封装
Agent 模块的核心职责是“思考”，即封装与 LLM 交互以获取行动计划的逻辑。
// internal/agent/agent.go
func (a *Agent) Think(ctx context.Context, messages []models.Message) (*models.Thought, error) {// 1. 从能力层获取工具定义tools := a.toolKit.GetTools()// 2. 调用 LLM 提供者，传入上下文和工具llmResponse, err := a.llmProvider.CallLLM(ctx, messages, tools)if err != nil { return nil, err }// 3. 将 LLM 返回的 JSON 解析为结构化的 Thought 对象var thought models.Thoughterr = json.Unmarshal([]byte(llmResponse), &thought)if err != nil {return &models.Thought{Text: llmResponse}, nil // 若解析失败，作为纯文本响应}return &thought, nil
}
我让这个模块依赖 interfaces.IToolKit 和 interfaces.ILLMProvider 接口，遵循了依赖注入（DI）原则，使底层能力可被替换。
3. 能力层：LLMProvider 和 ToolKit - 外部交互的接口
-
LLMProvider(llm/provider.go)：作为适配器，它隔离了与具体 LLM（本项目中为 OpenAI）的 API 调用细节。更换 LLM 服务时，理论上只需修改此模块。// internal/agent/llm/provider.go func (p *LLMProvider) CallLLM(...) (string, error) {// 1. 转换内部模型到 OpenAI SDK 的模型apiMessages := toOpenAIChatMessages(messages)apiTools := toOpenAITools(tools)// 2. 创建并发送请求req := openai.ChatCompletionRequest{ Model: p.cfg.Model, Messages: apiMessages, Tools: apiTools }resp, err := p.client.CreateChatCompletion(ctx, req)// 3. 将 OpenAI 的响应转换回内部的 Thought JSON 字符串// ...return string(thoughtBytes), nil } -
ToolKit(toolkit.go)：作为工具的统一管理器，它聚合了本地（LocalClient）和远程（MCPClient）工具，并提供统一的ExecuteTool接口，为系统提供扩展性。// internal/toolkit/toolkit.go func (tk *ToolKit) ExecuteTool(name string, args map[string]interface{}) (string, error) {// 优先尝试作为本地工具执行if tool, ok := tk.localClient.GetTool(name); ok {return tool.Execute(args)}// 否则，作为 MCP 远程工具执行return tk.mcpClient.ExecuteTool(name, args) }
五、结论
通过动手实现这个 Agent Demo，我总结出以下几点：
- Agent 的核心运行机制是基于 ReAct 模式的状态循环。
- 在需要处理并发和抢占式中断的场景下，Go 语言展现出了其独特的工程优势。
- 模块化架构通过关注点分离和依赖注入，将简单的循环逻辑解构为一个结构化的软件系统，提高了代码的可维护性和扩展性。
- 接口定义了组件间的契约，是实现系统灵活性的基础。
这次实践让我深刻体会到：Agent 的核心逻辑可以被精炼为一个 for 循环，但将其从一个简单的循环变为一个健壮、可扩展的工程产品，则需要依赖系统化的软件工程实践来解决并发、解耦、错误处理等一系列复杂问题。
源码：jinhan1414/go-agent: 这是一个基于Go语言构建的智能代理（Agent）框架。它利用大语言模型（LLM）的强大能力，结合可扩展的工具集，以交互或非交互的方式完成复杂任务。
写在最后
关注 【松哥ai自动化】 公众号，每周获取深度技术解析，从源码角度彻底理解各种工具的实现原理。更重要的是，遇到技术难题时，直接联系我！我会根据你的具体情况，提供最适合的解决方案和技术指导。
上期回顾：（跨平台自动化框架的OCR点击操作实现详解与思考）