Eino: v0.8.*-adk middlewares

本文档介绍 Eino ADK v0.8.* 版本的主要新功能和改进。

💡 目前尚处于 v0.8.0.Beta 版本阶段：https://github.com/cloudwego/eino/releases/tag/v0.8.0-beta.1

版本亮点

v0.8 是一个重要的功能增强版本，引入了全新的中间件接口架构，新增多个实用中间件，并提供了增强的可观测性支持。

1. ChatModelAgentMiddleware 接口

💡 核心更新: 全新的中间件接口，提供更灵活的 Agent 扩展机制

ChatModelAgentMiddleware 是 v0.8 最重要的架构更新，为 ChatModelAgent 及基于它构建的 Agent（如 DeepAgent）提供统一的扩展点。

相比 AgentMiddleware 的优势:

接口方法:

• BeforeAgent - Agent 运行前修改配置
• BeforeModelRewriteState - 模型调用前处理状态
• AfterModelRewriteState - 模型调用后处理状态
• WrapInvokableToolCall - 包装同步工具调用
• WrapStreamableToolCall - 包装流式工具调用
• WrapModel - 包装模型调用

使用方式:

agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model:    model,
    Handlers: []adk.ChatModelAgentMiddleware{mw1, mw2, mw3},
})

详见 Eino ADK: ChatModelAgentMiddleware

1.1 Summarization 中间件

💡 功能: 自动对话历史摘要，防止超出模型上下文窗口限制

📚 详细文档: Middleware: Summarization

当对话历史的 Token 数量超过阈值时，自动调用 LLM 生成摘要，压缩上下文。

核心能力:

• 可配置的触发条件（Token 阈值）
• 支持保留最近的用户消息
• 支持记录完整对话历史到文件
• 提供前后处理钩子

快速开始:

mw, err := summarization.New(ctx, &summarization.Config{
    Model: chatModel,
    Trigger: &summarization.TriggerCondition{
        ContextTokens: 100000,
    },
})

1.2 ToolReduction 中间件

💡 功能: 工具结果压缩，优化上下文使用效率

📚 详细文档: Middleware: ToolReduction

提供两阶段的工具输出管理：

快速开始:

mw, err := reduction.New(ctx, &reduction.Config{
    Backend:           fsBackend,
    MaxLengthForTrunc: 30000,
    MaxTokensForClear: 50000,
})

1.3 Filesystem 中间件

💡 功能: 文件系统操作工具集

📚 详细文档: Middleware: FileSystem

新增能力:

• Grep 功能增强: 支持完整正则表达式语法
• 新增选项: CaseInsensitive、EnableMultiline、FileType 过滤
• 自定义工具名: 所有 filesystem 工具支持自定义名称

1.4 Skill 中间件

💡 功能: 动态加载和执行 Skill

📚 详细文档: Middleware: Skill

新增能力:

• Context 模式: 支持 fork 和 isolate 两种上下文模式
• 自定义配置: 支持自定义系统提示和工具描述
• FrontMatter 扩展: 支持通过 FrontMatter 指定 agent 和 model

1.5 PlanTask 中间件

💡 功能: 任务规划和执行工具

📚 详细文档: Middleware: PlanTask

支持 Agent 创建和管理任务计划，适用于需要分步执行的复杂任务场景。

1.6 ToolSearch 中间件

💡 功能: 工具搜索，支持从大量工具中动态检索

📚 详细文档: Middleware: ToolSearch

当工具数量较多时，通过语义搜索动态选择最相关的工具，避免上下文过载。

1.7 PatchToolCalls 中间件

💡 功能: 修补悬空的工具调用，确保消息历史完整性

📚 详细文档: Middleware: PatchToolCalls

扫描消息历史，为缺少响应的工具调用插入占位符消息。适用于工具调用被中断或取消的场景。

快速开始:

mw, err := patchtoolcalls.New(ctx, nil)

2. Agent Callback 支持

💡 功能: Agent 级别的回调机制，用于观测和追踪

支持在 Agent 执行的全生命周期中注册回调，实现日志记录、追踪、监控等功能。

核心类型:

• AgentCallbackInput - 回调输入，包含 Agent 输入或恢复信息
• AgentCallbackOutput - 回调输出，包含 Agent 事件流

使用方式:

agent.Run(ctx, input, adk.WithCallbacks(
    callbacks.NewHandler(
        callbacks.WithOnStart(func(ctx context.Context, info *callbacks.RunInfo, input callbacks.CallbackInput) context.Context {
            agentInput := adk.ConvAgentCallbackInput(input)
            // 处理 Agent 启动事件
            return ctx
        }),
        callbacks.WithOnEnd(func(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
            agentOutput := adk.ConvAgentCallbackOutput(output)
            // 处理 Agent 完成事件
            return ctx
        }),
    ),
))

详见 Eino ADK: Agent Callback

3. Language Setting

💡 功能: 全局语言设置

支持全局设置 ADK 的语言偏好，影响内置提示词和消息的语言。

使用方式:

adk.SetLanguage(adk.LanguageChinese)  // 设置为中文
adk.SetLanguage(adk.LanguageEnglish)  // 设置为英文（默认）

中间件使用建议

💡 推荐组合: 以下中间件可组合使用，覆盖大部分长对话场景

handlers := []adk.ChatModelAgentMiddleware{
    patchMW,          // 1. 修补悬空工具调用
    reductionMW,      // 2. 压缩工具输出
    summarizationMW,  // 3. 摘要对话历史
}

agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model:    model,
    Handlers: handlers,
})

Breaking Changes

💡 升级到 v0.8 前，请查阅 Breaking Changes 文档了解所有不兼容变更

📚 完整文档: Eino v0.8 不兼容更新

变更概览:

ShellBackend

Shell

AgentEvent

ReadRequest.Offset

FileInfo.Path

WriteRequest

GrepRequest.Pattern

升级指南

详细的迁移步骤和代码示例请参考：Eino v0.8 不兼容更新

快速检查清单:

1. 检查是否使用了 ShellBackend / StreamingShellBackend 接口（需重命名）
2. 检查 ReadRequest.Offset 使用（0-based → 1-based）
3. 检查 GrepRequest.Pattern 使用（字面量 → 正则表达式，特殊字符需转义）
4. 检查是否依赖 WriteRequest 的"文件存在报错"行为
5. 检查是否依赖 FileInfo.Path 为绝对路径
6. 如有自定义 ChatModel/Tool Decorator/Wrapper，考虑迁移到 ChatModelAgentMiddleware
7. 运行测试验证功能正常