go-micro 官方示例指南：从服务、Agent 到工作流的完整生命周期路线图-北京尧图网络

go-micro 官方示例指南从服务、Agent 到工作流的完整生命周期路线图【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro本指南基于 examples/README.md 及其配套索引 examples/INDEX.md系统梳理 go-microGo Agent harness and service framework示例集的完整路线图。你将掌握服务 → Agent → 工作流 → MCP 集成的推荐学习路径、每个示例的定位与运行方式以及如何从零开始贡献一个新的可运行示例。示例集概览一条贯穿服务生命周期的学习路线examples/目录是 go-micro 的可运行示例集合其设计目标是用真实可执行的代码带开发者走完整个 go-micro 生命周期先写一个服务Service——掌握运行时基础把服务暴露成 Agent 可用的能力tool——让 AI Agent 通过工具调用使用服务用工作流Workflow协调更长周期的任务——把多个步骤组织成可检查点、可恢复的流程。每个示例都可用go run .在其目录下直接运行除非对应 README 另有说明。示例的编排逻辑与配套文档如 examples/INDEX.md以及 CLI 输出保持同步保证新开发者能沿着一条被持续验证的路径进入项目。快速上手两种推荐的进入方式对于刚接触仓库的开发者不建议按字母顺序通读目录而应选择以下两种方式之一方式一推荐先阅读 examples/INDEX.mdwayfinding 索引它按目标组织直接给出最短路径方式二跟随下面这张首个 Agent 推荐路径表它是仓库维护者认定的 canonical 路线。步骤起点你将学到下一步1. 第一个服务hello-world0→1 服务构建路径创建并注册基础 RPC 服务、添加 handler、用 client 调用、暴露健康检查转向agent-demo看服务如何被 Agent 使用2. 第一个 Agentfirst-agent运行最小的服务型 Agent使用确定性 mock 模型无需任何 provider key对比agent-demo或维护中的 0-to-hero 路径support3. 第一个工作流support跟随类型化服务进入 Agent 聊天循环、事件驱动的intake流程与审批门approval gate用flow-durable加深对工作流模型的理解此外最短的 AI 工具桥接路径MCP 方向为mcp/hello→mcp/crud→mcp/workflow调试与生产加固则就近参考agent-wrap-tool、agent-durable和deployment。所有命令默认都不需要 provider key无需模型厂商 API Key除非对应示例 README 另有说明。生命周期第 1 阶段Services——学习运行时基础hello-world0→1 的 RPC 服务最小示例hello-world 是入门第一站演示了 go-micro 服务的四个核心概念服务创建与注册micro.NewService(greeter, micro.Address(:8080))Handler 实现Hello方法客户端调用健康检查。其核心代码非常精简见 examples/hello-world/main.go定义Request/Response类型与Greeterhandlermain中依次完成服务创建、service.Init()、service.Handle(new(Greeter))注册、service.Run()启动。运行后即可用 curl 直接验证 RPC 端点cd hello-world go run . # 另一终端验证 curl -XPOST \ -H Content-Type: application/json \ -H Micro-Endpoint: Greeter.Hello \ -d {name: Alice} \ http://localhost:8080web-service带服务发现的 HTTP Web 服务web-service 在 hello-world 的基础上增加了 HTTP 层HTTP handlers服务注册健康检查JSON REST API。cd web-service go run .multi-service模块化单体模式multi-service 演示如何在单个二进制内运行多个服务。从源码看examples/multi-service/main.go关键设计是每个服务拥有独立隔离的 server、client、store 和 cache多个服务共享registry、broker 和 transport因此能在同一进程内互相发现与调用通过micro.NewGroup(users, orders)协调生命周期——由service.Group统一处理信号一个服务退出时停止全部服务。cd multi-service go run .这种先单体后拆分的模式适合在需要独立扩容前保持部署简单。deploymentDocker Compose 生产化部署deployment 提供一个接近生产的架构一条命令即可拉起docker-compose up其架构包含 MCP 网关:3001、Consul 注册中心:8500、Jaeger 分布式追踪:16686与业务服务:9090Agent如 Claude通过 MCP 协议发现并调用服务。对应端点与验证方式服务URLMCP Toolshttp://localhost:3001/mcp/toolsConsul UIhttp://localhost:8500Jaeger UIhttp://localhost:16686Service RPChttp://localhost:9090# 列出 MCP 工具 curl http://localhost:3001/mcp/tools | jq # 调用工具 curl -X POST http://localhost:3001/mcp/call \ -H Content-Type: application/json \ -d {tool: myservice.Handler.Method, arguments: {key: value}}自定义时将app服务的 build context 替换为你的服务目录新增服务只需配置MICRO_REGISTRY: consul与MICRO_REGISTRY_ADDRESS: consul:8500环境变量即可被 MCP 网关自动发现如需 Redis 缓存追加redis:7-alpine服务并设置MICRO_CACHE_ADDRESSredis:6379即可。生产化建议包括为每个服务加健康检查、Consul 数据用命名卷持久化、网关配置限流、服务间启用 TLS 以及用 secrets 管理 API Key。生命周期第 2 阶段Agents——把服务变成会使用工具的队友first-agent无密钥运行的最小服务型 Agentfirst-agent 是仓库内最小的可运行服务型 Agent位于micro new helloworld与完整 0-to-hero 参考support之间。它使用确定性 mock 模型因此不需要ANTHROPIC_API_KEY、OPENAI_API_KEY或任何 provider secretgo run ./examples/first-agent预期输出First agent (provider: mock, no API key) Summarize my next steps [notes] listed starter notes assistant: Your first agent read the notes service and found three steps: install the CLI, run a service, then chat with an agent. ✓ service-backed agent completed without provider secrets从源码examples/first-agent/main.go可以看到完整的服务→Agent 链路是如何被装配起来的notes是一个普通 go-micro 服务只有一个 RPC 方法Listassistant通过agent.Services(notes)把作用域限定到该服务mock 模型通过正常的 agent tool handler 请求服务工具m.opts.ToolHandler一次assistant.Ask即完成模型请求工具 → 服务执行 → 返回最终答复的闭环。这段链路可归纳为服务暴露工具 → Agent 发现服务 → 模型请求调用工具 → Agent 返回最终答案。CI 用go test ./examples/first-agent持续保证该路径可运行。脱离这个最小转录、进入长驻 Agent 后可用以下 CLI 命令继续调试详见 first-agent/README.mdmicro run micro chat assistant --prompt Summarize my next steps micro inspect agent assistant micro agent doctor assistantagent-demo多服务项目管理应用 MCP 集成agent-demo 是一个单进程内注册三个服务的项目管理系统ProjectServiceCreate/Get/List、TaskServiceCreate/List/Update、TeamServiceAdd/List/Get自带种子数据2 个项目、7 个任务、4 名团队成员并集成了 agent playground。go run main.go运行后暴露的端点MCP Gateway 位于http://localhost:3000MCP Tools 位于http://localhost:3000/mcp/toolsWebSocket 位于ws://localhost:3000/mcp/ws。它演示了五件事零配置 MCP——服务从 doc comments 自动变成 AI 工具跨服务编排——Agent 在一次对话中同时查询项目、任务和团队富工具描述——description结构体 tag 与example注释引导 Agent鉴权作用域——读、写操作拥有独立 scopeWithMCP一行式——一个选项即可启动 MCP 网关。与 Claude Code 集成时只需在其 MCP 配置中声明{ mcpServers: { demo: { command: go, args: [run, main.go], cwd: examples/agent-demo } } }agent-plan-delegate两大内置 Agent 能力agent-plan-delegate 在一个小型多 Agent 系统中演示 go-micro 的两个内置能力——规划plan与委派delegate能力工具行为规划plan指挥 Agentconductor在完成多步工作前记录有序步骤列表计划保存在其 store 支持的 memory 中后续轮次会回显给它委派delegate指挥 Agent 把通知步骤交给独立的commsAgent因为comms是已注册 Agent交接通过 RPC 完成而非进程内调用两者的关键设计是plan和delegate自动附加到每个 Agent 上无需配置 harness 或 graph——它们就是模型可以调用的普通工具与任何服务端点无异。运行需要 provider key示例会自动检测 providerexport ANTHROPIC_API_KEYsk-ant-... # 或 OPENAI_API_KEY, GEMINI_API_KEY, ... go run main.go也可用MICRO_AI_PROVIDER/MICRO_AI_API_KEY强制指定。delegate是混合式的若to指向拥有相关服务的已注册 Agent则通过 RPCAgent.Chat发送子任务否则创建一个聚焦的临时子 Agentfresh 隔离上下文完成任务后销毁且无内置工具、无法再次委派。agent-wrap-toolAgent 工具执行中间件agent-wrap-tool 是client.CallWrapper/server.HandlerWrapper的工具侧对应物——围绕 Agent 工具执行的中间件。Agent 的每次工具调用都会流经ai.ToolHandlertype ToolHandler func(ctx context.Context, call ai.ToolCall) ai.ToolResult type ToolWrapper func(ai.ToolHandler) ai.ToolHandlerWrapTool对外暴露为micro.AgentWrapTool注册一个包装器它接收下一个 handler 并返回新 handlernext(...)之前的代码在工具执行前运行、之后的代码在执行后运行这一个接缝即可覆盖完整生命周期——before/after 钩子、计时、指标、重试、结果检查。示例包含一个易抖动的weather服务和一个带两个包装器的 Agentobserve——为每次调用计时并记录 per-tool 计数携带 provider 传下来的关联 IDcall.ID只观察、不改变行为retry——当调用结果出错时重试最多 3 次weather 服务首次必失败、随后成功于是重试把一次瞬时故障变成模型永远看不到的成功。包装器按最外层优先组合observe先注册因此它包裹retry即使 retry 实际执行了两次工具observe 也只看到一次逻辑调用。micro.NewAgent(forecaster, micro.AgentServices(weather), micro.AgentProvider(provider), micro.AgentAPIKey(apiKey), micro.AgentWrapTool(m.observe, retry(3)), )与 guardrails 的关系开发者包装器运行在内置 guardrailsMaxSteps、LoopLimit、ApproveTool之外能看到每次调用及其结果包括 guardrail 的拒绝但 retry 包装器的next是完整的 guardrail 栈因此每次重试也会被循环检测计数。建议让LoopLimit≥ 重试次数或当包装器自己负责重复时设置AgentLoopLimit(0)。agent-durable可检查点、可恢复的 Agent 运行agent-durable 是flow-durable的 Agent 侧对应物Agent 运行使用与 flow 相同的Checkpoint接口进行检查点保存中断后可恢复且不重复已完成副作用go run ./examples/agent-durable示例中 mock 模型调用inventory.reserve后模拟进程崩溃。micro.AgentPending找到未完成运行micro.AgentResume从保存的检查点继续关键验证行是最后的tool executions: 1——恢复期间reserve工具没有被二次调用。何时用 durable flow 而非可检查点 Agent流程已知时有序服务调用、重试、定时器、补偿、精确恢复阶段如reserve/charge用 durable flow路径开放、由模型动态选择工具时用可检查点 Agent 运行。二者可组合确定性业务过程留在flow-durable判断密集步骤交给可检查点 Agent两者共用同一Checkpoint后端检查与恢复可共享同一个运行历史存储。在服务启动时同样可用此模式恢复pending, _ : micro.AgentPending(ctx, agent) for _, run : range pending { _, _ micro.AgentResume(ctx, agent, run.ID) }注意context.Context的取消与 deadline 在检查点加载/保存、模型调用、工具调用中依然生效状态为done、canceled、expired的终结运行不会被AgentPending返回。在检查点保存前已成功的副作用仍可能重复详见持久化契约文档。agent-human-input 与 agent-ollamaagent-human-input人机协同human-in-the-loop示例用于需要在运行继续前得到明确人工决策的场景。agent-ollama本地模型接线示例适合用 Ollama 承载模型调用的开发者实验。生命周期第 3 阶段Workflows——协调更长周期的任务support0-to-hero 维护中的参考路径examples/support 是 go-micro 生命周期的维护中 0-to-hero 参考一个可运行文件一个 CI 冒烟测试保证参考路径随框架演进始终诚实可用。其路径为Scaffold 服务——customers、tickets、notify是普通类型化 go-micro 服务其请求/响应结构体与方法注释成为 Agent 看到的工具契约运行 harness——进程内启动内存版 registry、broker、client、store、服务、Agent 和 flow默认运行无需外部依赖或 API Key通过 Agent 聊天——supportAgent 把工单事件作为 prompt 接收调用服务工具查询客户、分流工单、起草回复检查工作流——intakeflow 记录事件驱动运行并打印 Agent 结果展示 service → agent → workflow 在一个运行时内的完整生命周期。场景客户提交工单ticket.created事件触发 support Agent(1) 查询客户customers(2) 设置工单优先级tickets(3) 起草并发送邮件回复notify——但必须通过审批门 event: events.ticket.created {customer:aliceacme.com,id:ticket-1,subject:Cant log in} [customers] looked up Alice (pro plan) [tickets] ticket-1 → priorityhigh statusin_progress ▣ approval gate notify_NotifyService_Send(aliceacme.com) — approved [notify] toaliceacme.com: Hi Alice — thanks for reaching out. Weve bumped this to high priority and are on it. support agent: Triaged ticket-1 for Alice and sent a reply. inspect transcript: micro inspect flow intake flow: intake runs1 latest.replyTriaged ticket-1 for Alice and sent a reply. micro agent history support agent: support runs1 latest.statuscompleted ✓ ticket triaged and the customer was replied to — triggered by an event四大组成服务customers/tickets/notify——普通 go-micro 服务Agent 自动将其端点发现为工具Agentsupport——micro.NewAgent关联这三个服务推理工单并调用工具Flowintake——由events.ticket.created触发并把事件交给 Agent事件即 prompt无需人工输入GuardrailApproveTool——Agent 可自由读取与分流但给客户发邮件notify.Send必须经过门控返回false则挂起等待人工或策略示例中选择批准并记录。运行与验证mock 模型确定性执行无需 API Keygo run main.go # mock 模型 — 确定性无 API Key go test ./examples/support连接真实模型时Agent 将自行推理工单而非跟随脚本export ANTHROPIC_API_KEYsk-ant-... # 或 OPENAI_API_KEY, GEMINI_API_KEY, ... go run main.go -provider anthropic后续演化方向让ApproveTool对计费动作返回false或转人工用agent.WithA2A(:4000)将 Agent 暴露给其他团队的 Agent新增kb知识库服务让 Agent 回复前先检索。flow-durable崩溃后从断点恢复的工作流flow-durable 演示flow 是有序步骤列表带阶段的任务而非单次 LLM 轮次。每一步通过可插拔的Checkpoint默认 store 支持在前后持久化进程中途死亡后从停止的步骤恢复不重跑已成功检查点的步骤。核心代码examples/flow-durablef : micro.NewFlow(checkout, micro.FlowSteps( micro.FlowStep{Name: reserve, Run: reserve}, micro.FlowStep{Name: charge, Run: charge}, micro.FlowStep{Name: confirm, Run: confirm}, ), micro.FlowWithCheckpoint(micro.StoreCheckpoint(nil, checkout)), // nil store 默认checkout key scope ) f.Execute(ctx, {}) // 运行在 charge 处崩溃 pending, _ : f.Pending(ctx) // 运行被检查点在 charge f.Resume(ctx, pending[0].ID) // 从 charge 继续到结束State携带类型化 payloadSet/Scan与Stage标记恢复点Checkpoint持久化每次Run内置实现以 store 为后端通过store.Scope把每个 flow 的运行放进独立 store 表数据库flow、表checkout不同 flow 之间、以及 flow 与 agent/service 状态之间互不共享表。真实的步骤可以是flow.Call(service, endpoint)RPC、flow.Dispatch(agent)交给 Agent或flow.LLM(prompt)一次模型轮次此处用普通函数仅为单独展示持久化。go run main.go无需 LLM Key。注意Checkpoint本身不提供外部引擎适配器或 exactly-once 执行默认文件 store 在文件保留的前提下可跨进程重启存活。flow-loop循环工作流flow-loop 用于重复工作流步骤的循环型 flow 示例适合需要反复执行固定步骤的场景。第 4 阶段MCP 与 Agent 集成示例MCPModel Context Protocol示例目录 examples/mcp/ 提供五个递进式示例示例定位hello最小 MCP 服务从这里开始crudCRUD 联系人簿含完整 Agent 文档workflow经 AI Agent 的跨服务编排Inventory/Orders/Notifications一次自然语言请求完成搜索→查库存→预留→下单→发确认documented全部 MCP 特性鉴权 scopeGetUser/CreateUser、server.WithEndpointScopes()、预置测试数据platform平台化 MCP 服务示例Users/Posts/Comments/Mail现有微服务零代码改动即可被 Agent 访问MCP 接入只需三步examples/mcp/README.md1. 为 handler 方法写 Go doc 注释自动抽取为工具描述// SayHello greets a person by name. Returns a friendly greeting message. // // example {name: Alice} func (g *Greeter) SayHello(ctx context.Context, req *HelloRequest, rsp *HelloResponse) error { rsp.Message Hello req.Name ! return nil } type HelloRequest struct { Name string json:name description:Persons name to greet }2. 注册 handler自动抽取文档handler : service.Server().NewHandler(new(Greeter)) service.Server().Handle(handler)3. 启动 MCP 网关go mcp.ListenAndServe(:3000, mcp.Options{ Registry: service.Options().Registry, })特性包括自动文档抽取Go doc 注释→工具描述、exampletag→示例输入、struct tag→参数描述、多传输Stdio 用于 Claude Code、HTTP/SSE 用于 Web 端 Agent、零配置无需手动注册工具、无需 API wrapper、无需代码生成、per-tool 鉴权 scope以及网关层的限流与审计日志mcp.Serve(mcp.Options{ Registry: reg, Auth: authProvider, RateLimit: mcp.RateLimitConfig{ RequestsPerSecond: 10, Burst: 20, }, AuditFunc: func(r mcp.AuditRecord) { log.Printf([audit] trace%s tool%s account%s allowed%v, r.TraceID, r.Tool, r.AccountID, r.Allowed) }, })MCP 命令行同样完整micro mcp serve启动 Stdio/HTTP 服务、micro mcp list列出工具、micro mcp test tool {k:v}测试工具、micro mcp docs生成文档、micro mcp export langchain|openapi|json导出不同格式。网关侧实现细节可继续阅读 gateway/mcp/。其他示例auth认证与授权示例含 client、server 与 proto 定义。graceful-stop长驻服务的优雅停机行为。grpcgo-micro v6 作为标准 gRPC 兼容服务器开启反射可用 grpcurl 或任意标准 gRPC 客户端调用grpcurl -plaintext localhost:8080 list grpcurl -plaintext -d {name:World} localhost:8080 helloworld.Say.Hellogrpc-interopgRPC 互操作性示例client/server 双端。外部依赖与前置条件部分示例需要外部基础设施按需用 Docker 启动# NATS事件/消息 docker run -p 4222:4222 nats:latest # Consul服务注册 docker run -p 8500:8500 consul:latest agent -dev -ui -client0.0.0.0 # Redis缓存 docker run -p 6379:6379 redis:latest例如broker/nats、registry/consul相关的示例均依赖上述服务而first-agent、support等示例使用内存版 registry/broker/store无需任何外部依赖。即将推出pubsub-events——基于 NATS 的事件驱动架构示例。贡献新示例的规范若你希望向示例集贡献新示例examples/README.md 给出了明确流程创建新目录添加带说明的 README.md包含带注释的可运行代码按其支持的生命周期阶段加入 examples/README.md 索引或 examples/INDEX.md 的目标表格确保能通过go run .运行。保持 README、示例索引与micro examplesCLI 输出三者同步是新开发者能从一个文档化入口找到examples/first-agent与examples/support的前提。CLI 侧同样打印这条路径micro examples micro agent demo micro zero-to-hero小结go-micro 的示例集按服务 → Agent → 工作流的生命周期精心编排hello-world教你写第一个 RPC 服务first-agent用无密钥的 mock 模型打通服务到 Agent 的闭环support把类型化服务、Agent 聊天循环、事件驱动 flow 与审批门整合成一个维护中的 0-to-hero 参考flow-durable与agent-durable则提供可检查点、可恢复的长周期执行能力。无论你是想跑通第一个 Agent、把既有微服务暴露给 AI 客户端还是构建带审批门控的持久化工作流都可以从这张路线图出发逐级深入对应源码与测试。【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

go-micro 官方示例指南：从服务、Agent 到工作流的完整生命周期路线图

相关推荐

汽车安全RTOS深度解析：SAFERTOS、OSEK与ISO 26262实战

ChatTTS-ui完整指南：三步从文字到语音

Autocut完整上手：用文本编辑器剪视频

更多资讯

AssetRipper：免费提取 Unity 游戏文件的工具，3.5.0 到 6000.5.X 全覆盖

纯HTML+Canvas实现高性能大屏动态地图看板

LifeOS Cortex 本地记忆 CLI：如何把文件型记忆做到可验证、隐私优先（完整指南）

SOME/IP抓包实战：从服务发现到序列化的故障定位指南

AI编程工具选型指南：Claude Code、TRAE、Cursor、Codex CLI对比

CODESYS连接EPEC控制器：CANopen通信配置与故障排查指南

今日更新

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？