doc(Eino): update chat template & react agent & tools node docs (#1274)

Author: JonXSnow

content/en/docs/eino/core_modules/components/chat_template_guide.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2025-02-21"
+date: "2025-03-12"
 lastmod: ""
 tags: []
 title: 'Eino: ChatTemplate guide'
@@ -19,6 +19,8 @@ The Prompt component is a tool for processing and formatting prompt templates. I
 
 ### **Interface Definition**
 
+> Code Location：eino/components/prompt/interface.go
+
 ```go
 type ChatTemplate interface {
     Format(ctx context.Context, vs map[string]any, opts ...Option) ([]*schema.Message, error)
@@ -63,6 +65,11 @@ ChatTemplate is generally used for context preparation before ChatModel.
 ### **Standalone Usage**
 
 ```go
+import (
+    "github.com/cloudwego/eino/components/prompt"
+    "github.com/cloudwego/eino/schema"
+)
+
 // Create template
 template := prompt.FromMessages(schema.FString,
   &schema.Message{
@@ -91,6 +98,12 @@ if err != nil {
 ### **Usage in Orchestration**
 
 ```go
+import (
+    "github.com/cloudwego/eino/components/prompt"
+    "github.com/cloudwego/eino/schema"
+    "github.com/cloudwego/eino/compose"
+)
+
 // Use in Chain
 chain := compose.NewChain[map[string]any, []*schema.Message]()
 chain.AppendChatTemplate(template)
@@ -112,8 +125,17 @@ graph.AddChatTemplateNode("template_node", template)
 ### **Callback Usage Example**
 
 ```go
+import (
+    "context"
+
+    callbackHelper "github.com/cloudwego/eino/utils/callbacks"
+    "github.com/cloudwego/eino/callbacks"
+    "github.com/cloudwego/eino/compose"
+    "github.com/cloudwego/eino/components/prompt"
+)
+
 // Create callback handler
-handler := &prompt.CallbackHandler{
+handler := &callbackHelper.PromptCallbackHandler{
     OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *prompt.CallbackInput) context.Context {
         fmt.Printf("Starting template formatting, variables: %v\n", input.Variables)
         return ctx
@@ -144,6 +166,10 @@ result, err := runnable.Invoke(ctx, variables, compose.WithCallbacks(helper))
 If necessary, component implementers can create custom prompt options:
 
 ```go
+import (
+    "github.com/cloudwego/eino/components/prompt"
+)
+
 // Define Option struct
 type MyPromptOptions struct {
     StrictMode bool
@@ -168,6 +194,8 @@ func WithDefaultValues(values map[string]string) prompt.Option {
 
 Prompt implementation needs to trigger callbacks at the appropriate times. The following structure is predefined by the component:
 
+> Code Location: eino/components/prompt/callback_extra.go
+
 ```go
 // Define callback input and output
 type CallbackInput struct {

content/en/docs/eino/core_modules/components/tools_node_guide.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2025-02-11"
+date: "2025-03-12"
 lastmod: ""
 tags: []
 title: 'Eino: ToolsNode guide'
@@ -22,6 +22,8 @@ The ToolsNode component is a module designed to extend the capabilities of a mod
 
 The Tool component provides three levels of interfaces:
 
+> Code Location: eino/compose/tool/interface.go
+
 ```go
 // Basic tool interface, provides tool information
 type BaseTool interface {
@@ -74,6 +76,8 @@ type StreamableTool interface {
 
 ### **ToolInfo Struct**
 
+> Code Location：eino/schema/tool.go
+
 ```go
 type ToolInfo struct {
     // Unique name of the tool, used to clearly express its purpose
@@ -157,6 +161,8 @@ chain.AddToolsNode(toolsNode)
 Custom Tools can implement specific Options according to their needs:
 
 ```go
+import "github.com/cloudwego/eino/components/tool"
+
 // Define Option struct
 type MyToolOptions struct {
     Timeout time.Duration
@@ -166,7 +172,7 @@ type MyToolOptions struct {
 
 // Define Option function
 func WithTimeout(timeout time.Duration) tool.Option {
-    return tool.WrapToolImplSpecificOptFn(func(o *MyToolOptions) {
+    return tool.WrapImplSpecificOptFn(func(o *MyToolOptions) {
         o.Timeout = timeout
     })
 }
@@ -177,6 +183,15 @@ func WithTimeout(timeout time.Duration) tool.Option {
 ### **Callback Usage Example**
 
 ```go
+import (
+    "context"
+
+    callbackHelper "github.com/cloudwego/eino/utils/callbacks"
+    "github.com/cloudwego/eino/callbacks"
+    "github.com/cloudwego/eino/compose"
+    "github.com/cloudwego/eino/components/tool"
+)
+
 // Create callback handler
 handler := &callbackHelper.ToolCallbackHandler{
     OnStart: func(ctx context.Context, info *callbacks.RunInfo, input *tool.CallbackInput) context.Context {

content/en/docs/eino/core_modules/flow_integration_components/_index.md

@@ -1,9 +1,9 @@
 ---
 Description: ""
-date: "2025-02-21"
+date: "2025-03-12"
 lastmod: ""
 tags: []
-title: 'Eino: Flow integration components'
+title: 'Eino: Flow integration'
 weight: 0
 ---
 

content/en/docs/eino/core_modules/flow_integration_components/react_agent_manual.md

@@ -1,6 +1,6 @@
 ---
 Description: ""
-date: "2025-02-21"
+date: "2025-03-12"
 lastmod: ""
 tags: []
 title: 'Eino: React Agent Manual'
@@ -275,6 +275,11 @@ agent, err := react.NewAgent(ctx, &react.AgentConfig{
 
 Some models output a piece of text first when they output tool calls in streaming mode (such as Claude), which may cause the default StreamToolCallChecker to mistakenly determine that there is no tool call and directly return. When using such models, you must implement the correct StreamToolCallChecker yourself.
 
+> 💡
+> For models that output a piece of text before outputting tool calls in streaming mode, you can try adding prompts to constrain the model from generating extra text during the tool call, thus addressing this issue. For example, "If you decide to call the tool, simply output the tool, do not output text."
+>
+> Different models may be affected differently by prompts, so adjustments to the prompt and validation of the effect are necessary when actually using them.
+
 ## **Invocation**
 
 ### **Generate**

content/en/docs/eino/ecosystem/_index.md

@@ -1,9 +1,9 @@
 ---
 Description: ""
-date: "2025-02-11"
+date: "2025-03-12"
 lastmod: ""
 tags: []
-title: 'Eino: Ecosystem'
+title: 'Eino: Component Integration'
 weight: 0
 ---
 

content/en/docs/eino/ecosystem/chat_template/_index.md

@@ -0,0 +1,10 @@
+---
+Description: ""
+date: "2025-03-12"
+lastmod: ""
+tags: []
+title: ChatTemplate
+weight: 0
+---
+
+

content/en/docs/eino/ecosystem/chat_template/chat_template_mcp.md

@@ -0,0 +1,92 @@
+---
+Description: ""
+date: "2025-03-12"
+lastmod: ""
+tags: []
+title: ChatTemplate - MCP
+weight: 0
+---
+
+## Introduction
+
+Model Context Protocol(MCP) is a standardized open protocol for model access introduced by Anthropic. Eino provides adapters, which can directly access resources on existing MCP Servers.
+
+This section introduces the adapter of MCPPrompt, which implements the [Eino ChatTemplate interface](/en/docs/eino/core_modules/components/chat_template_guide).
+
+<a href="/img/eino/ZiP5b3fivouCBbxCggYcWHqanRv.png" target="_blank"><img src="/img/eino/ZiP5b3fivouCBbxCggYcWHqanRv.png" width="100%" /></a>
+
+Other adapters：
+
+[Tool - MCP](/en/docs/eino/ecosystem/tool/tool_mcp)
+
+## HowToUse
+
+Eino MCP adapters referenced the open-source SDK [mcp-go](https://github.com/mark3labs/mcp-go), first initialize a MCP client：
+
+```go
+import "github.com/mark3labs/mcp-go/client"
+
+// stdio client
+cli, err := client.NewStdioMCPClient(myCommand, myEnvs, myArgs...)
+
+// sse client
+cli, err := client.NewSSEMCPClient(myBaseURL)
+// sse client  needs to manually start asynchronous communication
+// while stdio does not require it.
+err = cli.Start(ctx)
+```
+
+Considering the reusability of multiple adapters for the MCP client, the adapter assumes that the client has completed initialization with the Server's [Initialize](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/), so users need to complete the client initialization themselves, for example:
+
+```go
+import "github.com/mark3labs/mcp-go/mcp"
+
+initRequest := mcp.InitializeRequest{}
+initRequest.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
+initRequest.Params.ClientInfo = mcp.Implementation{
+    Name:    "example-client",
+    Version: "1.0.0",
+}
+_, err = cli.Initialize(ctx, initRequest)
+```
+
+Then use the Client to create the adapter , which implements Eino ChatTemplate:
+
+```go
+import "github.com/cloudwego/eino-ext/components/tool/mcp"
+
+tpl, err := mcp.NewPromptTemplate(ctx, &mcp.Config{
+    Cli: cli,
+    Name: "your prompt name",     
+})
+```
+
+You can call this adapter directly:
+
+```
+result, err := tpl.Format(ctx, map[string]interface{}{/* input k-v */})
+```
+
+It can also be used in any Eino Agent, taking the simplest llm chain as an example:
+
+```
+import (
+    "github.com/cloudwego/eino/compose"
+    "github.com/cloudwego/eino-ext/components/prompt/mcp"  
+)
+
+llm, err := /*create a chat model*/
+tpl, err := mcp.NewPromptTemplate(ctx, &mcp.Config{
+    Cli: cli,
+    Name: "your prompt name",     
+})
+
+runner, err := compose.NewChain[map[string]any, *schema.Message]().
+    AppendChatTemplate(tpl).
+    AppendChatModel(llm).
+    Compile(ctx)
+```
+
+## More Information
+
+Examples can be referred to: [https://github.com/cloudwego/eino-ext/blob/main/components/prompt/mcp/examples/mcp.go](https://github.com/cloudwego/eino-ext/blob/main/components/prompt/mcp/examples/mcp.go)

content/en/docs/eino/ecosystem/tool/tool_mcp.md

@@ -0,0 +1,108 @@
+---
+Description: ""
+date: "2025-03-12"
+lastmod: ""
+tags: []
+title: Tool - MCP
+weight: 0
+---
+
+## Introduction
+
+Model Context Protocol(MCP) is a standardized open protocol for model access introduced by Anthropic. Eino provides adapters, which can directly access resources on existing MCP Servers.
+
+This section introduces the adapter of MCPTool, which implements the [Eino Tool](/en/docs/eino/core_modules/components/tools_node_guide).
+
+<a href="/img/eino/HotzbOFL6oZFQWxWP10caT9Wnuc.png" target="_blank"><img src="/img/eino/HotzbOFL6oZFQWxWP10caT9Wnuc.png" width="100%" /></a>
+
+Other adapters：
+
+[ChatTemplate - MCP](/en/docs/eino/ecosystem/chat_template/chat_template_mcp)
+
+## HowToUse
+
+Eino MCP adapters referenced the open-source SDK [mcp-go](https://github.com/mark3labs/mcp-go), first initialize a MCP client：
+
+```go
+import "github.com/mark3labs/mcp-go/client"
+
+// stdio client
+cli, err := client.NewStdioMCPClient(myCommand, myEnvs, myArgs...)
+
+// sse client
+cli, err := client.NewSSEMCPClient(myBaseURL)
+// sse client  needs to manually start asynchronous communication
+// while stdio does not require it.
+err = cli.Start(ctx)
+```
+
+Considering the reusability of multiple adapters for the MCP client, the adapter assumes that the client has completed initialization with the Server's [Initialize](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/), so users need to complete the client initialization themselves, for example:
+
+```go
+import "github.com/mark3labs/mcp-go/mcp"
+
+initRequest := mcp.InitializeRequest{}
+initRequest.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
+initRequest.Params.ClientInfo = mcp.Implementation{
+    Name:    "example-client",
+    Version: "1.0.0",
+}
+_, err = cli.Initialize(ctx, initRequest)
+```
+
+Then use the Client to create the adapter , which implements Eino Tool:
+
+```go
+import "github.com/cloudwego/eino-ext/components/tool/mcp"
+
+tools, err := mcp.GetTools(ctx, &mcp.Config{Cli: cli})
+```
+
+You can call this adapter directly:
+
+```
+for i, mcpTool := range mcpTools {
+    fmt.Println(i, ":")
+    info, err := mcpTool.Info(ctx)
+    if err != nil {
+       log.Fatal(err)
+    }
+    fmt.Println("Name:", info.Name)
+    fmt.Println("Desc:", info.Desc)
+    fmt.Println()
+}
+```
+
+It can also be used in any Eino Agent, taking the  [ReAct Agent](/en/docs/eino/core_modules/flow_integration_components/react_agent_manual) as an example:
+
+```
+import (
+    "github.com/cloudwego/eino/flow/agent/react"
+    "github.com/cloudwego/eino-ext/components/tool/mcp"    
+)
+
+llm, err := /*create a chat model*/
+tools, err := mcp.GetTools(ctx, &mcp.Config{Cli: cli})
+
+agent, err := react.NewAgent(ctx, &react.AgentConfig{
+    Model:                 llm,
+    ToolsConfig:           compose.ToolsNodeConfig{Tools: tools},
+})
+```
+
+### SpecifyToolName
+
+You can use the field ToolNameList in config to specify the tools you want to call, avoiding calling unexpected tools：
+
+```go
+import "github.com/cloudwego/eino-ext/components/tool/mcp"
+
+tools, err := mcp.GetTools(ctx, &mcp.Config{
+    Cli: cli,
+    ToolNameList: []string{"your tool name"},
+})
+```
+
+## More Information
+
+Examples can be referred to: [https://github.com/cloudwego/eino-ext/blob/main/components/tool/mcp/examples/mcp.go](https://github.com/cloudwego/eino-ext/blob/main/components/tool/mcp/examples/mcp.go)