This note was generated with AI assistance, but the code reading order should be fine (all use official Eino examples; personally I felt the official tutorial was a bit hard to understand).

Eino Agentic Advanced Features Guide

📂 Source repo: github.com/cloudwego/eino-examples↗
📖 Series docs: Intro Notes | Agentic Advanced | Appendix I Flow | Appendix II Components | Appendix III Tools

📁 Code sources:
adk/agentic/research_assistant/ — AgenticModel + AgenticMessage full-featured research assistant
adk/agentic/retry_max_output_tokens/ — auto-retry on output truncation
📖 Prerequisites: This guide assumes you have already mastered the content of sections one through five in the Intro Notes.

Quick Look: ChatModel → AgenticModel Type Mapping Table (Read This First!)

Before diving into details, memorize the core mapping — Agentic means adding Typed to every type name, and replacing every Message with AgenticMessage:

Standard version (Chat Completions)	Agentic version (Responses API)
`openai.NewChatModel()`	`agenticopenai.New()` / `agenticark.New()`
`schema.UserMessage("...")`	`schema.UserAgenticMessage("...")`
`adk.NewChatModelAgent(...)`	`adk.NewTypedChatModelAgent[*schema.AgenticMessage](...)`
`adk.NewRunner(...)`	`adk.NewTypedRunner[*schema.AgenticMessage](...)`
`event.Output.MessageOutput.GetMessage()`	`adk.TypedGetMessage(event)`
`adk.ChatModelAgentMiddleware`	`adk.TypedChatModelAgentMiddleware[*schema.AgenticMessage]`
`adk.ModelRetryConfig`	`adk.TypedModelRetryConfig[*schema.AgenticMessage]`
`filesystem.New(...)`	`filesystem.NewTyped[*schema.AgenticMessage](...)`

🧠 One-line summary: The Agentic series is Eino’s complete wrapper for the Responses API — replace ChatModel with AgenticModel, replace Message with AgenticMessage, and the usage of other concepts (Agent / Runner / Middleware / Tool) stays the same, but all use the Typed generic variants.

Background: Chat Completions API → Responses API

In the Intro Notes, all code is based on the Chat Completions API (ChatModel + *schema.Message). This is the API form introduced by OpenAI in 2022.

But starting in 2025, mainstream model vendors began pushing the Responses API, which is a new generation of API form. The core differences between the two:

Dimension	Chat Completions API	Responses API
Message type	`*schema.Message` (single role + content)	`*schema.AgenticMessage` (contains ContentBlocks)
Model interface	`einoModel.ChatModel`	`einoModel.AgenticModel`
Agent type	`adk.NewChatModelAgent`	`adk.NewTypedChatModelAgent[*schema.AgenticMessage]`
Runner type	`adk.NewRunner`	`adk.NewTypedRunner[*schema.AgenticMessage]`
Single call return	One text reply	Multiple ordered structured events (reasoning → tool call → reasoning again → text)
Server-side tools	❌ All executed on the client	✅ Executed directly on the vendor side (e.g. web_search)
Output truncation detection	No standard signal	`status=incomplete` + `reason=max_output_tokens`

I. Core Concept: AgenticMessage and ContentBlock

1.1 Why do we need AgenticMessage?

In the Chat Completions API, a single model call returns only one message. The Responses API returns all structured intermediate steps in a single call. To carry this “multi-event” return, the original *schema.Message (with only one Role + Content string) is no longer enough:

1
ChatModel returns:  ┌──────────────────────────┐
2
                    │  Role: Assistant         │
3
                    │  Content: "The answer is 42" │
4
                    └──────────────────────────┘
5
                    Only a single flat message
6

7
AgenticModel      ┌──────────────────────────────────────────────┐
8
returns:          │ Role: Assistant                              │
9
                  │ ContentBlocks: [                             │
10
                  │   [0] type: reasoning                        │
11
                  │       text: "I need to search first..."      │
12
                  │   [1] type: server_tool_call                 │
13
                  │       name: web_search                       │
14
                  │   [2] type: reasoning                        │
15
                  │       text: "Search results show..."        │
16
                  │   [3] type: text                             │
17
                  │       text: "Based on the analysis, the answer is 42" │
18
                  │ ]                                            │
19
                  └──────────────────────────────────────────────┘
20
                  One message containing multiple ordered structured Blocks

1.2 ContentBlock Type Quick Reference

Each Block has a Type field indicating its category:

Block type	Meaning	Produced by	Appears in which message
`reasoning`	The model’s reasoning / thinking process	Model	Assistant message
`text`	Normal text output	Model	Assistant message
`server_tool_call`	Calling a server-side tool (e.g. web_search)	Model	Assistant message
`function_tool_call`	Calling a client-side local tool	Model	Assistant message
`function_tool_result`	Local tool execution result	Framework	User message (fed back to model)
`thinking`	Deep thinking content	Model	Assistant message

🧠 Key understanding: server_tool_call executes on the model vendor’s servers (your code can’t see the execution process), while function_tool_call is returned to your Agent for local execution.

II. AgenticModel: Connecting to the Responses API

2.1 Two Vendor Integrations

1
import (
2
    einoModel "github.com/cloudwego/eino/components/model"
3
    "github.com/cloudwego/eino-ext/components/model/agenticark"     // Volcengine ARK
4
    "github.com/cloudwego/eino-ext/components/model/agenticopenai"  // OpenAI
5
)
6

7
// ARK
8
model, err := agenticark.New(ctx, &agenticark.Config{
9
    APIKey:  os.Getenv("ARK_API_KEY"),
10
    Model:   os.Getenv("ARK_MODEL_ID"),
11
    BaseURL: os.Getenv("ARK_BASE_URL"),
12
})
13

14
// OpenAI
15
model, err := agenticopenai.New(ctx, &agenticopenai.Config{
16
    APIKey:  os.Getenv("OPENAI_API_KEY"),
17
    Model:   os.Getenv("OPENAI_MODEL_ID"),
18
    BaseURL: os.Getenv("OPENAI_BASE_URL"),
19
})

2.2 Server-side Tools: Web Search

You don’t need to write a search Tool yourself — just declare it, and the search is done on the vendor side:

1
// ARK server-side web_search
2
agenticark.WithServerTools([]*agenticark.ServerToolConfig{
3
    {WebSearch: &arkResponses.ToolWebSearch{
4
        Type:  arkResponses.ToolType_web_search,
5
        Limit: ptrOf[int64](6),
6
    }},
7
})
8

9
// OpenAI server-side web_search
10
agenticopenai.WithServerTools([]*agenticopenai.ServerToolConfig{
11
    {WebSearch: &openaiResponses.WebSearchToolParam{
12
        Type: openaiResponses.WebSearchToolTypeWebSearch,
13
    }},
14
})

💡 Server-side vs local tools: The call and execution of a server-side tool both happen on the vendor side. Your code will only see a server_tool_call block in content_blocks, and there will be no corresponding function_tool_result — the result is consumed internally by the model.

III. Typed Generic System

3.1 Complete Assembly Example (compared with Intro Notes §3)

The Agent assembly steps are exactly the same as Section III of the Intro Notes, only the types are switched to Typed + AgenticMessage:

1
func newResearchAssistant(ctx context.Context) (adk.TypedAgent[*schema.AgenticMessage], error) {
2
    // ─── Step 1: Create the AgenticModel ───
3
    agenticModel, _ := newAgenticModel(ctx)
4

5
    // ─── Step 2: Create local tools (same as before, InferTool) ───
6
    tools, _ := buildTools()
7

8
    // ─── Step 3: Create the TypedChatModelAgent ───
9
    agent, err := adk.NewTypedChatModelAgent[*schema.AgenticMessage](ctx,
10
        &adk.TypedChatModelAgentConfig[*schema.AgenticMessage]{
11
            Name:        "AgenticResearchAssistant",
12
            Instruction: "...",
13
            Model:       agenticModel,          // ← AgenticModel
14
            ToolsConfig: adk.ToolsConfig{       // ← Same as the ChatModel version!
15
                ToolsNodeConfig: compose.ToolsNodeConfig{
16
                    Tools: tools,
17
                },
18
            },
19
            MaxIterations: 8,
20
        })
21
    return agent, err
22
}

The rest of the logic (Middleware, etc.) is exactly the same as the ChatModel version, just add the Typed prefix

3.2 Using TypedRunner

1
// Create (same pattern as before)
2
runner := adk.NewTypedRunner[*schema.AgenticMessage](adk.TypedRunnerConfig[*schema.AgenticMessage]{
3
    Agent:           agent,
4
    EnableStreaming: true,
5
})
6

7
// Build input (use UserAgenticMessage instead of UserMessage)
8
input := schema.UserAgenticMessage("Please write a research report...")
9

10
// Run
11
iter := runner.Run(ctx, []*schema.AgenticMessage{input})
12

13
// Consume events — ⚠️ Key change: use TypedGetMessage
14
for {
15
    event, ok := iter.Next()
16
    if !ok { break }
17
    msg, _, err := adk.TypedGetMessage(event)  // ← Not GetMessage()
18
    if msg != nil {
19
        fmt.Print(msg.String())
20
    }
21
}

🧠 Comparison with Intro Notes:

1
// Old: ChatModel path
2
msg, err := event.Output.MessageOutput.GetMessage()
3
// New: AgenticModel path
4
msg, typedagentevent, err := adk.TypedGetMessage(event)

IV. ModelRetryConfig: Auto-retry on Output Truncation

4.1 Problem Scenario

The Responses API has a max_output_tokens limit per call. When set too small, the output gets truncated:

1
status=incomplete
2
incomplete_details.reason=max_output_tokens

4.2 Solution

Eino ADK provides TypedModelRetryConfig, which automatically discards incomplete output, increases the budget, and re-invokes:

1
var retryMaxTokens = []int{4096, 8192, 16384}
2

3
ModelRetryConfig: &adk.TypedModelRetryConfig[*schema.AgenticMessage]{
4
    MaxRetries: len(retryMaxTokens),
5
    ShouldRetry: func(ctx context.Context, retryCtx *adk.TypedRetryContext[*schema.AgenticMessage]) *adk.TypedRetryDecision[*schema.AgenticMessage] {
6
        if !isMaxOutputTokensIncomplete(retryCtx.OutputMessage) {
7
            return nil  // No retry needed
8
        }
9
        nextMaxTokens := retryMaxTokens[retryCtx.RetryAttempt-1]
10
        return &adk.TypedRetryDecision[*schema.AgenticMessage]{
11
            Retry:             true,
12
            AdditionalOptions: []einoModel.Option{einoModel.WithMaxTokens(nextMaxTokens)},
13
            Backoff:           100 * time.Millisecond,
14
        }
15
    },
16
},

4.3 Comparison with the ModelRetryConfig in Intro Notes §4.4

Dimension	ChatModel version	Agentic version
Type	`adk.ModelRetryConfig`	`adk.TypedModelRetryConfig[*schema.AgenticMessage]`
Detection basis	`err` (HTTP error)	`OutputMessage.ResponseMeta` (response status)
Retry method	Retry as-is	Retry after increasing `max_output_tokens`
Use case	Rate limiting, network errors	Output truncation

V. Agentic Panorama Quick Reference

5.1 New Capabilities

Capability	ChatModel have it?	How AgenticModel achieves it
Reasoning process visible	❌	`reasoning` ContentBlock
Server-side tools	❌	`server_tool_call` + `WithServerTools`
Output truncation detection	Indirect (finish_reason)	Direct: `status=incomplete`
Multiple events in one call	❌ Multiple round-trips	✅ Single call returns multiple ContentBlocks
Deep thinking	❌	`thinking` ContentBlock + `WithReasoning`

5.2 Common Import Paths

1
// AgenticModel implementations
2
"github.com/cloudwego/eino-ext/components/model/agenticopenai"  // OpenAI Responses API
3
"github.com/cloudwego/eino-ext/components/model/agenticark"     // Volcengine ARK
4

5
// Core interfaces
6
"github.com/cloudwego/eino/components/model"   // AgenticModel interface
7
"github.com/cloudwego/eino/schema"             // AgenticMessage, ContentBlock
8
"github.com/cloudwego/eino/adk"                // TypedChatModelAgent, TypedRunner, TypedModelRetryConfig
9

10
// Middleware (Typed version)
11
"github.com/cloudwego/eino/adk/middlewares/filesystem"  // filesystem.NewTyped
12

13
// Backend
14
"github.com/cloudwego/eino-ext/adk/backend/local"       // localbackend.NewBackend

5.3 Summary: When Should You Use Agentic?

1
Your scenario                                      → What to use
2
─────────────────────────────────────────────────────────
3
Simple Q&A, one-shot call                          → ChatModel (Intro Notes ./note §2)
4
Multi-turn dialogue + local tools + interrupt recovery → ChatModelAgent (Intro Notes ./note §3)
5
Need server-side search (web_search)              → AgenticModel ✅
6
Need to see the model's reasoning process         → AgenticModel ✅
7
Need auto-retry on output truncation              → AgenticModel ✅
8
Need to mix reasoning + tools + text in one call  → AgenticModel ✅
9
Existing ChatModelAgent code runs fine            → Don't migrate, unless you need the above

🧠 Progressive adoption: Agentic is not meant to replace ChatModel — they are two parallel systems. When you need advanced features, the migration path is also clear: change the types from ChatModel/Message to AgenticModel/AgenticMessage, and the rest of the logic is largely unchanged.

📇 Quick Reference Card for This Article

1
See Typed → use AgenticMessage:
2
  NewChatModelAgent → NewTypedChatModelAgent[*AgenticMessage]
3
  NewRunner          → NewTypedRunner[*AgenticMessage]
4
  GetMessage()       → TypedGetMessage()
5
  ModelRetryConfig   → TypedModelRetryConfig
6
  filesystem.New → filesystem.NewTyped[*AgenticMessage]
7

8
Six ContentBlock types: reasoning / text / server_tool_call
9
                       function_tool_call / function_tool_result / thinking
10

11
New capabilities:
12
  reasoning Block (visible reasoning), server_tool_call (server-side tools)
13
  web_search (no need to write your own search Tool), output truncation detection + retry

📂 Source repo: github.com/cloudwego/eino-examples↗
📖 Keep reading:
Intro Notes — Eino ADK from Hello World to Compose orchestration
Agentic Advanced — Responses API / AgenticMessage / Typed generics ← you are here
Appendix I: Flow module — ReAct Agent / Multi-Agent / state graph
Appendix II: Components module — A/B routing / HTTP logging / retrieval augmentation / document parsing
Appendix III: Lambda and debugging tools — Lambda syntax / Devops / Mermaid visualization

Thanks for reading! Follow me if you'd like~

Eino Notes — Agentic Advanced

Mon Jul 20 2026

1302 words · 10 minutes

Notes Go Learning eino AI