ADK Agent Development Kit智能体开发套件是 Eino 提供的一套标准化 Agent 开发抽象层不管你写什么类型智能体单 Agent、多 Agent 协作、工具调用、循环 Agent全都统一实现一套 TypedAgent 接口框架就能统一调度、流式消费、多智能体互通。所有代码基于 Go 泛型设计用泛型区分两种消息格式传统 *schema.Message / 新版结构化 *schema.AgenticMessage。一、最顶层核心TypedAgent 接口typeTypedAgent[M MessageType]interface{Name(ctx context.Context)stringDescription(ctx context.Context)stringRun(ctx context.Context,input*TypedAgentInput[M],options...AgentRunOption)*AsyncIterator[*TypedAgentEvent[M]]}typeAgentTypedAgent[*schema.Message]// 日常99%场景用这个别名三个方法分工极其清晰类比成「员工」更好理解Name()员工姓名全局唯一标识多 Agent 调度时用来区分是谁在干活Description()员工简历 / 能力介绍框架自动读取多 Agent 协作时别的 Agent 靠这段描述知道能不能把任务交给它Run()干活的入口函数最核心入参input 用户对话历史、是否开流式输出options 本次运行临时配置返回AsyncIterator 异步事件流源源不断产出执行过程事件。MessageType 泛型约束两种消息模式二选一typeMessageTypeinterface{*schema.Message|*schema.AgenticMessage}*schema.Message传统对话消息文本、工具调用、普通聊天完整兼容所有 Eino 组件ChatModel、工具、记忆日常开发首选别名 Agent 就是它*schema.AgenticMessagev0.9 新结构结构化内容块适合复杂多 Agent 分层、强结构化输出场景偏高级用法。文档里所有带 TypedXXX[M] 的结构体都有不带 Typed 的简写别名不用每次写长泛型泛型完整类型日常简写别名TypedAgent[*schema.Message]AgentTypedAgentInputAgentInputTypedAgentEventAgentEventTypedAgentOutputAgentOutputTypedMessageVariantMessageVariant二、Run 入参TypedAgentInput / AgentInput传给 Agent 的任务信息typeTypedAgentInput[M MessageType]struct{Messages[]M EnableStreamingbool}Messages []M对话上下文等价大模型 Chat 请求包含用户提问、历史聊天、工具返回结果、系统提示词。Agent 读取这段对话做推理。EnableStreaming bool流式开关true尽量分段输出打字机效果逐字返回false全部推理完一次性返回完整结果不支持流式的 Agent比如纯工具执行、静态决策 Agent会自动忽略这个字段。三、Run 返回AsyncIterator 异步事件迭代器流式结果载体3.1 作用Agent.Run 不会阻塞主线程内部开 goroutine 执行逻辑一边跑一边不断发送事件 Event外部通过迭代器循环读取实时消息、工具动作、中断、报错。3.2 标准使用模板消费 Agent 输出运行// 启动Agent拿到事件迭代器iter:agent.Run(ctx,input)// 循环读取所有运行事件for{event,ok:iter.Next()if!ok{// 迭代器关闭Agent执行完毕退出循环break}// 处理每一步事件打印文字、捕获工具调用、监听中断、处理报错}iter.Next() 是阻塞调用没有新事件就卡住直到有输出 / 执行结束。3.3 Agent 内部如何生成迭代器自定义 Agent 必写模板这个迭代器是自定义的func(m*MyAgent)Run(ctx context.Context,input*adk.AgentInput,opts...adk.AgentRunOption)*adk.AsyncIterator[*adk.AgentEvent]{// 创建一对迭代器(对外返回) 生成器(内部发事件)iter,gen:adk.NewAsyncIteratorPair[*adk.AgentEvent]()gofunc(){defergen.Close()// Agent逻辑结束自动关闭流// 业务逻辑大模型推理、循环调用工具、多Agent跳转// 产出事件发送给迭代器gen.Send(adk.AgentEvent{/*填充事件内容*/})}()returniter}简单理解gen 是「生产者」往里面塞事件iter 是「消费者」外部循环读取goroutine 实现异步不阻塞。四、核心产出物TypedAgentEvent / AgentEvent运行全流程事件Run 流里每一条数据都是 Event记录这一步发生了什么typeTypedAgentEvent[M MessageType]struct{AgentNamestring// 当前执行的Agent名字RunPath[]RunStep// 执行链路记录走了哪些Agent、步骤用于日志/追踪Output*TypedAgentOutput[M]// 本轮输出内容文字/结构化消息Action*AgentAction// 协作控制信号中断、跳转、退出循环Errerror// 运行报错}拆分两个重点子结构体TypedAgentOutput、AgentAction4.1 TypedAgentOutput本次 Agent 输出内容typeTypedAgentOutput[M MessageType]struct{MessageOutput*TypedMessageVariant[M]// 标准对话消息文字、工具返回CustomizedOutput any// 自定义业务输出任意类型结构体}MessageOutput标准聊天输出最常用CustomizedOutput扩展字段你可以塞自己业务数据比如订单 ID、检索文档框架不干涉。TypedMessageVariant统一兼容「流式 / 一次性」消息typeTypedMessageVariant[M MessageType]struct{IsStreamingboolMessage M// 非流式完整消息MessageStream*schema.StreamReader[M]// 流式分段数据流Role schema.RoleType// 传统消息角色assistant/toolAgenticRole schema.AgenticRoleType// 结构化消息专用角色ToolNamestring}核心开关 IsStreamingIsStreaming false一次性结果直接读 Message 完整对话IsStreaming true流式打字机效果从 MessageStream 循环读取分段字符Role / AgenticRole 互斥用 *schema.Message默认 Agent只看 Role、ToolName用 *schema.AgenticMessage 结构化消息只看 AgenticRole。4.2 AgentAction多 Agent 协作控制信号调度指令决定Agent的行为动作的参数Event 里的 Action 是用来控制整个智能体系统流转的不需要返回消息只发控制指令typeAgentActionstruct{Exitbool// 整个多Agent系统直接结束Interrupted*InterruptInfo// 暂停运行保存状态后续可以恢复ResumeTransferToAgent*TransferToAgentAction// 废弃方案直接转让任务给其他Agent不推荐BreakLoop*BreakLoopAction// 终止LoopAgent循环循环思考智能体CustomizedAction any// 自定义控制信号}逐个解释场景Exit true任务彻底完成所有 Agent 全部停止Interrupted中途暂停比如需要用户补充信息、人机交互保存现场外部拿到数据后可以恢复执行BreakLoop专门给循环 Agent思考 - 工具调用循环用满足条件跳出循环TransferToAgent不推荐旧方案硬编码跳转 Agent官方推荐新方案把其他 Agent 包装成工具 AgentAsTool更规范、兼容框架调度CustomizedAction自定义控制逻辑比如标记需要检索知识库、发起审批。五、AgentRunOption单次 Run 运行的临时配置作用每次调用 agent.Run() 可以传入可变参数只对本次执行生效不污染 Agent 全局配置。5.1 框架内置通用 OptionWithSessionValues(map[string]any)多 Agent 共享上下文 KV 存储所有 Agent 在同一次任务里都能读写这份数据全局会话缓存WithCallbacks(…)注册回调钩子监听 Agent 生命周期事件开始执行、输出消息、工具调用、报错WithCancel()开启取消能力ctx cancel 时可以中断 Agent 运行配套 Loop 循环、中断恢复逻辑。5.2 自定义业务 Option重点实操框架支持给你的自定义 Agent 增加专属配置示例运行// 1. 定义自定义配置结构体typemyOptionsstruct{modelNamestring}// 2. 包装成标准AgentRunOption构造函数funcWithModelName(namestring)adk.AgentRunOption{returnadk.WrapImplSpecificOptFn(func(t*myOptions){t.modelNamename})}在 Agent.Run 内部读取自定义配置运行func(m*MyAgent)Run(ctx context.Context,input*adk.AgentInput,opts...adk.AgentRunOption)*adk.AsyncIterator[*adk.AgentEvent]{// 从opts列表中提取自定义配置o:adk.GetImplSpecificOptions(myOptions{},opts...)fmt.Println(o.modelName)// 使用本次传入的模型名称}5.3 DesignateAgent给指定 Agent 单独生效的 Option同一个多 Agent 系统里多个 Agent 共享一组 opts 时可以限定某条配置只给特定 Agent 生效运行// 这个SessionKV配置只对nameagent_1的Agent生效opt:adk.WithSessionValues(map[string]any{key:val}).DesignateAgent(agent_1)六、全局语言设置 adk.SetLanguage运行 adk.SetLanguage(adk.LanguageChinese)// 默认LanguageEnglish英文作用修改 Eino ADK内置组件自带提示词的语言比如文件检索、总结、内置工具、ChatModelAgent 这些框架自带 Agent 的系统提示局限只管框架内置提示词你自己写的自定义 Instruction、提示词不会自动翻译需要自己处理中英文使用时机程序 main 初始化阶段一次性设置全局生效。七、整体的一套完整流程大致梳理下面是一个大致的流程并非详细程序启动 mainadk.SetLanguage(adk.LanguageChinese) 设置中文自定义智能体 MyAgent实现 adk.AgentTypedAgent [*schema.Message]接口实现 Name、Description实现 Run 方法内部创建 AsyncIteratorgoroutine 执行业务发起调用组装输入运行 input:adk.AgentInput{Messages:[]*schema.Message{用户提问历史对话},EnableStreaming:true,}// 传入通用自定义配置opts:[]adk.AgentRunOption{adk.WithSessionValues(map[string]any{user_id:123}),WithModelName(gpt-4o),}// 启动Agent拿到异步事件流iter:myAgent.Run(ctx,input,opts...)循环消费事件流收到 Event.Err捕获异常Event.Output.MessageOutput读取大模型输出文字流式 / 完整Event.Action判断是否中断、退出、跳出循环、切换 Agent全部事件读取完毕迭代器关闭本次 Agent 执行结束。总的来说上述内容讲的是Eino ADK如何用一套统一 Go 泛型接口标准化所有 AI 智能体的定义、入参、异步流式输出、多智能体协作控制、运行时配置是开发 Go 版 LLM Agent 的底层基础规范。