Import

DeepAgent is a pre-built agent on top of ChatModelAgent that provides planning, filesystem access, shell execution, and sub-agent delegation out of the box.

Import

Requires eino >= v0.5.14:

import "github.com/cloudwego/eino/adk/prebuilt/deep"

When to Use

Use DeepAgent instead of plain ChatModelAgent when you need:

• Built-in task planning (WriteTodos tool)
• File system operations (read/write/edit/glob/grep)
• Shell command execution
• Sub-agent delegation with context isolation
• Auto-summarization for long conversations

Use plain ChatModelAgent when:

• You need fine-grained control over tools and prompts
• The task is simple (single tool, no planning needed)
• You want to minimize token cost (DeepAgent's planning adds overhead)

Architecture

MainAgent (ChatModelAgent + built-in tools + prompt)
    |
    +-- WriteTodos tool (task planning)
    +-- Built-in tools (read_file, write_file, edit_file, glob, grep, execute)
    +-- TaskTool -> SubAgents
            |
            +-- GeneralPurpose (same tools as main, no TaskTool)
            +-- Custom SubAgents

• MainAgent receives user input, plans via WriteTodos, delegates via TaskTool
• SubAgents have isolated context (no shared history with MainAgent)
• GeneralPurpose sub-agent is added by default for generic tasks

Configuration

type Config struct {
    // Required: the LLM model
    Model model.ToolCallingChatModel

    // Optional: filesystem backend for file operations
    Backend filesystem.Backend

    // Optional: shell execution (mutually exclusive with StreamingShell)
    Shell filesystem.Shell

    // Optional: streaming shell execution
    StreamingShell filesystem.StreamingShell

    // Optional: custom tools added to the main agent
    Tools []tool.BaseTool

    // Optional: custom sub-agents
    SubAgents []adk.Agent

    // Optional: custom system prompt (appended to built-in prompt)
    Instruction string

    // Optional: disable WriteTodos tool
    WithoutWriteTodos bool

    // Optional: disable the default general-purpose sub-agent
    WithoutGeneralSubAgent bool

    // Optional: custom TaskTool description generator
    TaskToolDescriptionGenerator func(ctx context.Context, agents []adk.Agent) string

    // Optional: middleware
    Handlers []adk.ChatModelAgentMiddleware
}

Quick Start

import (
    "context"
    "fmt"
    "log"

    "github.com/cloudwego/eino-ext/components/model/openai"
    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/adk/filesystem"
    "github.com/cloudwego/eino/adk/prebuilt/deep"
)

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

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

    backend := filesystem.NewInMemoryBackend()

    agent, err := deep.New(ctx, &deep.Config{
        Model:   cm,
        Backend: backend,
    })
    if err != nil {
        log.Fatal(err)
    }

    runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
    iter := runner.Query(ctx, "Analyze the CSV file at /data/sales.csv and create a summary report")

    for {
        event, ok := iter.Next()
        if !ok {
            break
        }
        if event.Err != nil {
            log.Fatal(event.Err)
        }
        if event.Output != nil && event.Output.MessageOutput != nil {
            msg, _ := event.Output.MessageOutput.GetMessage()
            fmt.Printf("[%s] %s\n", event.AgentName, msg.Content)
        }
    }
}

Built-in Capabilities

WriteTodos

A planning tool that lets the agent create and track a structured task list. The agent calls WriteTodos to decompose complex tasks, then updates progress as it works.

Disable with WithoutWriteTodos: true.

File System Tools

When Backend is configured, the agent gets: read_file, write_file, edit_file, glob, grep.

When Shell or StreamingShell is configured, the agent also gets: execute.

Task Delegation (TaskTool)

When SubAgents are configured (or the default general-purpose sub-agent is enabled), the agent gets a task tool. The agent specifies which sub-agent to call and what task to perform.

Sub-agents run in isolated context -- they only receive the task description, not the full conversation history.

Comparison with Other Patterns