eino-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eino ADK Overview

Eino ADK 概述

Import:

github.com/cloudwego/eino/adk

The Agent Development Kit (ADK) provides a framework for building agents in Go. Core interface:

type Agent interface {
    Name(ctx context.Context) string
    Description(ctx context.Context) string
    Run(ctx context.Context, input *AgentInput, opts ...AgentRunOption) *AsyncIterator[*AgentEvent]
}

导入路径：

github.com/cloudwego/eino/adk

Agent开发工具包（ADK）提供了在Go中构建Agent的框架，核心接口如下：

type Agent interface {
    Name(ctx context.Context) string
    Description(ctx context.Context) string
    Run(ctx context.Context, input *AgentInput, opts ...AgentRunOption) *AsyncIterator[*AgentEvent]
}

Agent Types

Agent 类型

Type	Description	Decision
ChatModelAgent	ReAct pattern: LLM reasons, calls tools, loops until done	Dynamic (LLM)
DeepAgent	Pre-built agent with planning, filesystem, sub-agents	Dynamic (LLM)
Custom Agent	Implement the Agent interface directly	Custom

类型	描述	决策模式
ChatModelAgent	ReAct模式：LLM推理、调用工具、循环执行直到任务完成	动态（LLM驱动）
DeepAgent	内置规划、文件系统、子Agent能力的预构建Agent	动态（LLM驱动）
自定义Agent	直接实现Agent接口	自定义

ChatModelAgent Quick Start

ChatModelAgent 快速开始

import (
    "context"
    "fmt"
    "log"

    "github.com/cloudwego/eino-ext/components/model/openai"
    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/components/tool/utils"
    "github.com/cloudwego/eino/compose"
)

func main() {
    ctx := context.Background()

    // 1. Create a tool
    searchTool, _ := utils.InferTool("search_book", "Search books by genre",
        func(ctx context.Context, input *struct {
            Genre string `json:"genre" jsonschema_description:"Book genre"`
        }) (string, error) {
            return `{"books": ["The Great Gatsby"]}`, nil
        })

    // 2. Create model
    cm, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
        APIKey: "your-key", Model: "gpt-4o",
    })

    // 3. Create agent
    agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
        Name:        "BookRecommender",
        Description: "Recommends books",
        Instruction: "You recommend books using the search_book tool.",
        Model:       cm,
        ToolsConfig: adk.ToolsConfig{
            ToolsNodeConfig: compose.ToolsNodeConfig{
                Tools: []tool.BaseTool{searchTool},
            },
        },
    })

    // 4. Run with Runner
    runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
    iter := runner.Query(ctx, "recommend a fiction book")
    for {
        event, ok := iter.Next()
        if !ok {
            break
        }
        if event.Err != nil {
            log.Fatal(event.Err)
        }
        msg, _ := event.Output.MessageOutput.GetMessage()
        fmt.Printf("Agent[%s]: %v\n", event.AgentName, msg)
    }
}

import (
    "context"
    "fmt"
    "log"

    "github.com/cloudwego/eino-ext/components/model/openai"
    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/components/tool/utils"
    "github.com/cloudwego/eino/compose"
)

func main() {
    ctx := context.Background()

    // 1. 创建工具
    searchTool, _ := utils.InferTool("search_book", "Search books by genre",
        func(ctx context.Context, input *struct {
            Genre string `json:"genre" jsonschema_description:"Book genre"`
        }) (string, error) {
            return `{"books": ["The Great Gatsby"]}`, nil
        })

    // 2. 创建模型
    cm, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
        APIKey: "your-key", Model: "gpt-4o",
    })

    // 3. 创建Agent
    agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
        Name:        "BookRecommender",
        Description: "Recommends books",
        Instruction: "You recommend books using the search_book tool.",
        Model:       cm,
        ToolsConfig: adk.ToolsConfig{
            ToolsNodeConfig: compose.ToolsNodeConfig{
                Tools: []tool.BaseTool{searchTool},
            },
        },
    })

    // 4. 使用Runner执行
    runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
    iter := runner.Query(ctx, "recommend a fiction book")
    for {
        event, ok := iter.Next()
        if !ok {
            break
        }
        if event.Err != nil {
            log.Fatal(event.Err)
        }
        msg, _ := event.Output.MessageOutput.GetMessage()
        fmt.Printf("Agent[%s]: %v\n", event.AgentName, msg)
    }
}

Runner

The Runner manages agent lifecycle, context passing, and interrupt/resume:

runner := adk.NewRunner(ctx, adk.RunnerConfig{
    Agent:           myAgent,
    EnableStreaming:  true,
    CheckPointStore: myStore,  // for interrupt/resume
})

// Query (convenience for single user message)
iter := runner.Query(ctx, "hello")

// Run (full control over input messages)
iter := runner.Run(ctx, []adk.Message{schema.UserMessage("hello")})

Runner负责管理Agent生命周期、上下文传递以及中断/恢复能力：

runner := adk.NewRunner(ctx, adk.RunnerConfig{
    Agent:           myAgent,
    EnableStreaming:  true,
    CheckPointStore: myStore,  // 用于中断/恢复能力
})

// Query（单用户消息场景的便捷调用方式）
iter := runner.Query(ctx, "hello")

// Run（可完全控制输入消息的全能力调用方式）
iter := runner.Run(ctx, []adk.Message{schema.UserMessage("hello")})

Middleware System

中间件系统

Middleware extends ChatModelAgent behavior. Configure via

Handlers

field:

agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    // ...
    Handlers: []adk.ChatModelAgentMiddleware{fsMiddleware, summarizationMW},
})

Seven built-in middleware types (see reference/middleware.md for details):

Middleware	Package	Purpose
FileSystem	`adk/middlewares/filesystem`	File ops (read/write/edit/glob/grep) + shell
ToolSearch	`adk/middlewares/dynamictool/toolsearch`	Dynamic tool selection via regex search
ToolReduction	`adk/middlewares/reduction`	Truncate/clear large tool results
Summarization	`adk/middlewares/summarization`	Compress long conversation history
PlanTask	`adk/middlewares/plantask`	Task creation and progress tracking
Skill	`adk/middlewares/skill`	Skill-based progressive disclosure
PatchToolCalls	`adk/middlewares/patchtoolcalls`	Fix dangling tool calls in history

中间件可扩展ChatModelAgent的行为，通过

Handlers

字段配置：

agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    // ...
    Handlers: []adk.ChatModelAgentMiddleware{fsMiddleware, summarizationMW},
})

7个内置中间件类型（详情见reference/middleware.md）：

中间件	包路径	用途
FileSystem	`adk/middlewares/filesystem`	文件操作（读/写/编辑/glob/grep）+ shell执行
ToolSearch	`adk/middlewares/dynamictool/toolsearch`	通过正则搜索实现动态工具选择
ToolReduction	`adk/middlewares/reduction`	截断/清空过大的工具返回结果
Summarization	`adk/middlewares/summarization`	压缩过长的对话历史
PlanTask	`adk/middlewares/plantask`	任务创建与进度追踪
Skill	`adk/middlewares/skill`	基于Skill的渐进式能力披露
PatchToolCalls	`adk/middlewares/patchtoolcalls`	修复历史对话中不完整的工具调用

AgentAsTool

Wrap any Agent as a Tool for use by another agent:

subAgent := createMySubAgent()
agentTool := adk.NewAgentTool(ctx, subAgent)

parentAgent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{agentTool},
        },
    },
})

将任意Agent封装为Tool，供其他Agent调用：

subAgent := createMySubAgent()
agentTool := adk.NewAgentTool(ctx, subAgent)

parentAgent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{agentTool},
        },
    },
})

Human-in-the-Loop

人在闭环

ChatModelAgent supports interrupt and resume for human approval, clarification, and feedback. See reference/human-in-the-loop.md for details.

Key pattern: tool returns

compose.NewInterruptAndRerunErr(info)

to pause, then

runner.ResumeWithParams(ctx, checkpointID, params)

to continue.

ChatModelAgent支持中断与恢复能力，可用于人工审核、信息澄清与反馈收集，详情见reference/human-in-the-loop.md。

核心模式：工具返回

compose.NewInterruptAndRerunErr(info)

暂停执行，之后调用

runner.ResumeWithParams(ctx, checkpointID, params)

即可继续执行。

Instructions to Agent

Agent开发指引

Default to
```
ChatModelAgent
```
for most use cases (single agent with tools)
Use
```
Runner
```
to execute agents -- never call
```
agent.Run()
```
directly in production
Middleware order matters: PatchToolCalls first, then Summarization, then Reduction
Use
```
DeepAgent
```
(
```
adk/prebuilt/deep
```
) when you need built-in planning + filesystem + sub-agents
Use
```
AgentAsTool
```
or DeepAgents' SubAgents when a sub-agent needs isolated context (no shared history)

大部分场景优先使用
```
ChatModelAgent
```
（带工具的单Agent场景）
始终使用
```
Runner
```
执行Agent——生产环境切勿直接调用
```
agent.Run()
```
中间件加载顺序很重要：优先加载PatchToolCalls，然后是Summarization，最后是Reduction
当需要内置规划+文件系统+子Agent能力时，使用
```
DeepAgent
```
（
```
adk/prebuilt/deep
```
）
当子Agent需要独立上下文（无共享对话历史）时，使用
```
AgentAsTool
```
或是DeepAgents的子Agent能力

Reference Files

参考文档

Read these files on-demand for detailed API, examples, and advanced usage:

reference/chat-model-agent.md -- ChatModelAgentConfig reference, ReAct pattern, ToolsConfig, streaming example
reference/deep-agents.md -- DeepAgent concept, config, architecture, comparison with ChatModelAgent
reference/middleware.md -- All 7 middleware types with interface, config, and examples
reference/runner-and-events.md -- Runner creation, AgentEvent/AgentOutput, event iteration patterns
reference/agent-as-tool.md -- Wrapping an Agent as a Tool for use by another agent
reference/human-in-the-loop.md -- Interrupt APIs, ResumableAgent, CheckPointStore, resume patterns
reference/filesystem.md -- Filesystem Backend interface, Local and AgentKit implementations, usage with DeepAgent

按需阅读以下文件获取详细API、使用示例与高级用法：

reference/chat-model-agent.md -- ChatModelAgentConfig参考、ReAct模式、ToolsConfig、流式调用示例
reference/deep-agents.md -- DeepAgent概念、配置、架构、与ChatModelAgent的对比
reference/middleware.md -- 全部7类中间件的接口定义、配置方式与使用示例
reference/runner-and-events.md -- Runner创建、AgentEvent/AgentOutput、事件迭代模式
reference/agent-as-tool.md -- 将Agent封装为工具供其他Agent调用的方法
reference/human-in-the-loop.md -- 中断API、ResumableAgent、CheckPointStore、恢复执行模式
reference/filesystem.md -- 文件系统后端接口、本地与AgentKit实现、与DeepAgent的集成用法