Skip to content

Tool Usage Guide

The Tool system is a core component of the tRPC-Agent-Go framework, enabling Agents to interact with external services and functions. The framework supports multiple tool types, including Function Tools and external tools integrated via the MCP (Model Context Protocol) standard.

Overview

🎯 Key Features

  • 🔧 Multiple Tool Types: Supports Function Tools and MCP standard tools.
  • 🌊 Streaming Responses: Supports both real-time streaming responses and normal responses.
  • ⚡ Parallel Execution: Tool invocations support parallel execution to improve performance.
  • 🔄 MCP Protocol: Full support for STDIO, SSE, and Streamable HTTP transports.
  • 🛠️ Configuration Support: Provides configuration options and filter support.
  • 🧹 Arguments Repair: Optionally enable agent.WithToolCallArgumentsJSONRepairEnabled(true) to best-effort repair tool_calls arguments, improving robustness for tool execution and external parsing.

Core Concepts

🔧 Tool

A Tool is an abstraction of a single capability that implements the tool.Tool interface. Each Tool provides specific functionality such as mathematical calculation, search, time query, etc.

1
2
3
4
5
6
7
8
type Tool interface {
    Declaration() *Declaration  // Return tool metadata.
}

type CallableTool interface {
    Call(ctx context.Context, jsonArgs []byte) (any, error)
    Tool
}

📦 ToolSet

A ToolSet is a collection of related tools that implements the tool.ToolSet interface. A ToolSet manages the lifecycle of tools, connections, and resource cleanup.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
type ToolSet interface {
    // Tools returns the current tools in this set.
    Tools(context.Context) []tool.Tool

    // Close releases any resources held by the ToolSet.
    Close() error

    // Name returns the identifier of the ToolSet, used for
    // identification and conflict resolution.
    Name() string
}

Relationship between Tool and ToolSet:

  • One "Tool" = one concrete capability (e.g., calculator).
  • One "ToolSet" = a group of related Tools (e.g., all tools provided by an MCP server).
  • An Agent can use multiple Tools and multiple ToolSets simultaneously.

🌊 Streaming Tool Support

The framework supports streaming tools to provide real-time responses:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// Streaming tool interface.
type StreamableTool interface {
    StreamableCall(ctx context.Context, jsonArgs []byte) (*StreamReader, error)
    Tool
}

// Streaming data unit.
type StreamChunk struct {
    Content  any      `json:"content"`
    Metadata Metadata `json:"metadata,omitempty"`
}

Streaming tool characteristics:

  • 🚀 Real-time responses: Data is returned progressively without waiting for the complete result.
  • 📊 Large data handling: Suitable for scenarios such as log queries and data analysis.
  • ⚡ User experience: Provides instant feedback and progress display.

Tool Types

Tool Type Definition Integration Method
Function Tools Tools implemented by directly calling Go functions Tool interface, in-process calls
Agent Tool (AgentTool) Wrap any Agent as a callable tool Tool interface, supports streaming inner forwarding
DuckDuckGo Tool Search tool based on DuckDuckGo API Tool interface, HTTP API
MCP ToolSet External toolset based on MCP protocol ToolSet interface, multiple transports

📖 Related docs: For Agent Tool and Transfer Tool used in multi-Agent collaboration, see the Multi-Agent System document.

Function Tools

Function Tools implement tool logic directly via Go functions and are the simplest tool type.

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import "trpc.group/trpc-go/trpc-agent-go/tool/function"

// 1. Define a tool function.
func calculator(ctx context.Context, req struct {
    Operation string  `json:"operation"`
    A         float64 `json:"a"`
    B         float64 `json:"b"`
}) (map[string]interface{}, error) {
    switch req.Operation {
    case "add":
        return map[string]interface{}{"result": req.A + req.B}, nil
    case "multiply":
        return map[string]interface{}{"result": req.A * req.B}, nil
    default:
        return nil, fmt.Errorf("unsupported operation: %s", req.Operation)
    }
}

// 2. Create the tool.
calculatorTool := function.NewFunctionTool(
    calculator,
    function.WithName("calculator"),
    function.WithDescription("Perform mathematical operations."),
)

// 3. Integrate into an Agent.
agent := llmagent.New("math-assistant",
    llmagent.WithModel(model),
    llmagent.WithTools([]tool.Tool{calculatorTool}))

Streaming Tool Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
// 1. Define input and output structures.
type weatherInput struct {
    Location string `json:"location"`
}

type weatherOutput struct {
    Weather string `json:"weather"`
}

// 2. Implement the streaming tool function.
func getStreamableWeather(input weatherInput) *tool.StreamReader {
    stream := tool.NewStream(10)
    go func() {
        defer stream.Writer.Close()

        // Simulate progressively returning weather data.
        result := "Sunny, 25°C in " + input.Location
        for i := 0; i < len(result); i++ {
            chunk := tool.StreamChunk{
                Content: weatherOutput{
                    Weather: result[i : i+1],
                },
                Metadata: tool.Metadata{CreatedAt: time.Now()},
            }

            if closed := stream.Writer.Send(chunk, nil); closed {
                break
            }
            time.Sleep(10 * time.Millisecond) // Simulate latency.
        }
    }()

    return stream.Reader
}

// 3. Create the streaming tool.
weatherStreamTool := function.NewStreamableFunctionTool[weatherInput, weatherOutput](
    getStreamableWeather,
    function.WithName("get_weather_stream"),
    function.WithDescription("Get weather information as a stream."),
)

// 4. Use the streaming tool.
reader, err := weatherStreamTool.StreamableCall(ctx, jsonArgs)
if err != nil {
    return err
}

// Receive streaming data.
for {
    chunk, err := reader.Recv()
    if err == io.EOF {
        break // End of stream.
    }
    if err != nil {
        return err
    }

    // Process each chunk.
    fmt.Printf("Received: %v\n", chunk.Content)
}
reader.Close()

Built-in Tools

DuckDuckGo Search Tool

The DuckDuckGo tool is based on the DuckDuckGo Instant Answer API and provides factual and encyclopedia-style information search capabilities.

Basic Usage

1
2
3
4
5
6
7
8
9
import "trpc.group/trpc-go/trpc-agent-go/tool/duckduckgo"

// Create a DuckDuckGo search tool.
searchTool := duckduckgo.NewTool()

// Integrate into an Agent.
searchAgent := llmagent.New("search-assistant",
    llmagent.WithModel(model),
    llmagent.WithTools([]tool.Tool{searchTool}))

Advanced Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import (
    "net/http"
    "time"
    "trpc.group/trpc-go/trpc-agent-go/tool/duckduckgo"
)

// Custom configuration.
searchTool := duckduckgo.NewTool(
    duckduckgo.WithBaseURL("https://api.duckduckgo.com"),
    duckduckgo.WithUserAgent("my-app/1.0"),
    duckduckgo.WithHTTPClient(&http.Client{
        Timeout: 15 * time.Second,
    }),
)

MCP Tools

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. MCP tools are based on JSON-RPC 2.0 and provide standardized integration with external services for Agents.

MCP ToolSet Features:

  • 🔗 Unified interface: All MCP tools are created via mcp.NewMCPToolSet().
  • ✅ Explicit initialization: (*mcp.ToolSet).Init(ctx) lets you fail fast on MCP connection / tool loading errors during startup.
  • 🚀 Multiple transports: Supports STDIO, SSE, and Streamable HTTP.
  • 🔧 Tool filters: Supports including/excluding specific tools.

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import "trpc.group/trpc-go/trpc-agent-go/tool/mcp"

// Create an MCP ToolSet (STDIO example).
mcpToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "stdio",           // Transport method.
        Command:   "go",              // Command to execute.
        Args:      []string{"run", "./stdio_server/main.go"},
        Timeout:   10 * time.Second,
    },
    mcp.WithToolFilterFunc(tool.NewIncludeToolNamesFilter("echo", "add")), // Optional: tool filter.
)

// (Optional but recommended) Explicitly initialize MCP: connect + initialize + list tools.
if err := mcpToolSet.Init(ctx); err != nil {
    log.Fatalf("failed to initialize MCP toolset: %v", err)
}

// Integrate into an Agent.
agent := llmagent.New("mcp-assistant",
    llmagent.WithModel(model),
    llmagent.WithToolSets([]tool.ToolSet{mcpToolSet}))

Transport Configuration

MCP ToolSet supports three transports via the Transport field:

1. STDIO Transport

Communicates with external processes via standard input/output. Suitable for local scripts and CLI tools.

1
2
3
4
5
6
7
8
mcpToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "stdio",
        Command:   "python",
        Args:      []string{"-m", "my_mcp_server"},
        Timeout:   10 * time.Second,
    },
)

2. SSE Transport

Uses Server-Sent Events for communication, supporting real-time data push and streaming responses.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
mcpToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "sse",
        ServerURL: "http://localhost:8080/sse",
        Timeout:   10 * time.Second,
        Headers: map[string]string{
            "Authorization": "Bearer your-token",
        },
    },
)

3. Streamable HTTP Transport

Uses standard HTTP for communication, supporting both regular HTTP and streaming responses.

1
2
3
4
5
6
7
mcpToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "streamable_http",  // Use the full name.
        ServerURL: "http://localhost:3000/mcp",
        Timeout:   10 * time.Second,
    },
)

Session Reconnection Support

MCP ToolSet supports automatic session reconnection to recover from server restarts or session expiration.

1
2
3
4
5
6
7
8
9
// SSE/Streamable HTTP transports support session reconnection
sseToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "sse",
        ServerURL: "http://localhost:8080/sse",
        Timeout:   10 * time.Second,
    },
    mcp.WithSessionReconnect(3), // Enable session reconnection with max 3 attempts
)

Reconnection Features:

  • 🔄 Auto Reconnect: Automatically recreates session when connection loss or expiration is detected
  • 🎯 Independent Retries: Each tool call gets independent reconnection attempts
  • 🛡️ Conservative Strategy: Only triggers reconnection for clear connection/session errors to avoid infinite loops

Dynamic MCP Tool Discovery (LLMAgent Option)

For MCP ToolSets, the list of tools on the server side can change over time (for example, when a new MCP tool is registered). To let an LLMAgent automatically see the latest tools from a ToolSet on each run, use llmagent.WithRefreshToolSetsOnRun(true) together with WithToolSets.

LLMAgent configuration example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import (
    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/model/openai"
    "trpc.group/trpc-go/trpc-agent-go/tool"
    "trpc.group/trpc-go/trpc-agent-go/tool/mcp"
)

// 1. Create an MCP ToolSet (can be STDIO, SSE, or Streamable HTTP).
mcpToolSet := mcp.NewMCPToolSet(connectionConfig)

// 2. Create an LLMAgent and enable dynamic ToolSets refresh.
agent := llmagent.New(
    "mcp-assistant",
    llmagent.WithModel(openai.New("gpt-4o-mini")),
    llmagent.WithToolSets([]tool.ToolSet{mcpToolSet}),
    llmagent.WithRefreshToolSetsOnRun(true),
)

When WithRefreshToolSetsOnRun(true) is enabled:

  • Each time the LLMAgent builds its tool list, it calls ToolSet.Tools(context.Background()) again.
  • If the MCP server adds or removes tools, the next run of this LLMAgent will use the updated tool list automatically.

This option focuses on dynamic discovery of tools. If you also need per-request HTTP headers (for example, authentication headers that come from context.Context), keep using the pattern shown in the examples/mcptool/http_headers example, where you manually call toolSet.Tools(ctx) and pass the tools via WithTools.

Agent Tool (AgentTool)

AgentTool lets you expose an existing Agent as a tool to be used by a parent Agent. Compared with a plain function tool, AgentTool provides:

  • ✅ Reuse: Wrap complex Agent capabilities as a standard tool
  • 🌊 Streaming: Optionally forward the child Agent’s streaming events inline to the parent flow
  • 🧭 Control: Options to skip post-tool summarization and to enable/disable inner forwarding

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import (
    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/model"
    "trpc.group/trpc-go/trpc-agent-go/tool"
    agenttool "trpc.group/trpc-go/trpc-agent-go/tool/agent"
)

// 1) Define a reusable child Agent (streaming recommended)
mathAgent := llmagent.New(
    "math-specialist",
    llmagent.WithModel(modelInstance),
    llmagent.WithInstruction("You are a math specialist..."),
    llmagent.WithGenerationConfig(model.GenerationConfig{Stream: true}),
)

// 2) Wrap as an Agent tool
mathTool := agenttool.NewTool(
    mathAgent,
    // Optional, defaults to false. When set to true, the outer model summary will be skipped, 
    // and the current round will end directly after tool.response.
    agenttool.WithSkipSummarization(false),
    // forward child Agent streaming events to parent flow.
    agenttool.WithStreamInner(true),
)

// 3) Use in parent Agent
parent := llmagent.New(
    "assistant",
    llmagent.WithModel(modelInstance),
    llmagent.WithGenerationConfig(model.GenerationConfig{Stream: true}),
    llmagent.WithTools([]tool.Tool{mathTool}),
)

Streaming Inner Forwarding

When WithStreamInner(true) is enabled, AgentTool forwards child Agent events to the parent flow as they happen:

  • Forwarded items are actual event.Event instances, carrying incremental text in choice.Delta.Content
  • To avoid duplication, the child Agent’s final full message is not forwarded again; it is aggregated into the final tool.response content for the next LLM turn (to satisfy providers requiring tool messages)
  • UI guidance: show forwarded child deltas; avoid printing the aggregated final tool.response content unless debugging

Example: Only show tool fragments when needed to avoid duplicates

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
if ev.Response != nil && ev.Object == model.ObjectTypeToolResponse {
    // Tool response contains aggregated content; skip printing by default to avoid duplicates
}

// Child Agent forwarded deltas (author != parent)
if ev.Author != parentName && len(ev.Choices) > 0 {
    if delta := ev.Choices[0].Delta.Content; delta != "" {
        fmt.Print(delta)
    }
}

Options

  • WithSkipSummarization(bool):

    • false (default): Allow an additional summarization/answer call after the tool result
    • true: Skip the outer summarization LLM call once the tool returns

  • WithStreamInner(bool):

    • true: Forward child Agent events to the parent flow (recommended: enable GenerationConfig{Stream: true} for both parent and child Agents)
    • false: Treat as a callable-only tool, without inner event forwarding
  • WithHistoryScope(HistoryScope):
    • HistoryScopeIsolated (default): Keep the child Agent fully isolated; it only sees the current tool arguments (no inherited history).
    • HistoryScopeParentBranch: Inherit parent conversation history by using a hierarchical filter key parent/child-uuid. This allows the content processor to include parent events via prefix matching while keeping child events isolated under a sub-branch. Typical use cases: “edit/optimize/continue previous output”.

Example:

1
2
3
4
5
6
child := agenttool.NewTool(
    childAgent,
    agenttool.WithSkipSummarization(false),
    agenttool.WithStreamInner(true),
    agenttool.WithHistoryScope(agenttool.HistoryScopeParentBranch),
)

Notes

  • Completion signaling: Tool response events are marked RequiresCompletion=true; Runner sends completion automatically
  • De-duplication: When inner deltas are forwarded, avoid printing the aggregated final tool.response text again by default
  • Model compatibility: Some providers require a tool message after tool_calls; AgentTool automatically supplies the aggregated content

Tool Integration and Usage

Create an Agent and Integrate Tools

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
import (
    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/tool"
    "trpc.group/trpc-go/trpc-agent-go/tool/function"
    "trpc.group/trpc-go/trpc-agent-go/tool/duckduckgo"
    "trpc.group/trpc-go/trpc-agent-go/tool/mcp"
)

// Create function tools.
calculatorTool := function.NewFunctionTool(calculator,
    function.WithName("calculator"),
    function.WithDescription("Perform basic mathematical operations."))

timeTool := function.NewFunctionTool(getCurrentTime,
    function.WithName("current_time"),
    function.WithDescription("Get the current time."))

// Create a built-in tool.
searchTool := duckduckgo.NewTool()

// Create MCP ToolSets (examples for different transports).
stdioToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "stdio",
        Command:   "python",
        Args:      []string{"-m", "my_mcp_server"},
        Timeout:   10 * time.Second,
    },
)
if err := stdioToolSet.Init(ctx); err != nil {
    return fmt.Errorf("failed to initialize stdio MCP toolset: %w", err)
}

sseToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "sse",
        ServerURL: "http://localhost:8080/sse",
        Timeout:   10 * time.Second,
    },
)
if err := sseToolSet.Init(ctx); err != nil {
    return fmt.Errorf("failed to initialize sse MCP toolset: %w", err)
}

streamableToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "streamable_http",
        ServerURL: "http://localhost:3000/mcp",
        Timeout:   10 * time.Second,
    },
)
if err := streamableToolSet.Init(ctx); err != nil {
    return fmt.Errorf("failed to initialize streamable MCP toolset: %w", err)
}

// Create an Agent and integrate all tools.
agent := llmagent.New("ai-assistant",
    llmagent.WithModel(model),
    llmagent.WithInstruction("You are a helpful AI assistant that can use various tools to help users."),
    // Add single tools (Tool interface).
    llmagent.WithTools([]tool.Tool{
        calculatorTool, timeTool, searchTool,
    }),
    // Add ToolSets (ToolSet interface).
    llmagent.WithToolSets([]tool.ToolSet{
        stdioToolSet, sseToolSet, streamableToolSet,
    }),
)

MCP Tool Filters

MCP ToolSets support filtering tools at creation time. It's recommended to use the unified tool.FilterFunc interface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import (
    "trpc.group/trpc-go/trpc-agent-go/tool"
    "trpc.group/trpc-go/trpc-agent-go/tool/mcp"
)

// ✅ Recommended: Use the unified filter interface
includeFilter := tool.NewIncludeToolNamesFilter("get_weather", "get_news", "calculator")
excludeFilter := tool.NewExcludeToolNamesFilter("deprecated_tool", "slow_tool")

// Apply filter
toolSet := mcp.NewMCPToolSet(
    connectionConfig,
    mcp.WithToolFilterFunc(includeFilter),
)

// Optional: initialize once at startup to catch MCP connection / tool loading errors early.
if err := toolSet.Init(ctx); err != nil {
    return fmt.Errorf("failed to initialize MCP toolset: %w", err)
}

Per-Run Tool Filtering

  • Option one: Per-run tool filtering enables dynamic control of tool availability for each runner.Run invocation without modifying Agent configuration. This is a "soft constraint" mechanism for optimizing token consumption and implementing role-based tool access control. apply to all agents
  • Option two: Configure the runtime filtering function through 'llmagent. WhatToolFilter' to only apply to the current agent Key Features:
  • 🎯 Per-Run Control: Independent configuration per invocation, no Agent modification needed
  • 💰 Cost Optimization: Reduce tool descriptions sent to LLM, lowering token costs
  • 🛡️ Smart Protection: Framework tools (transfer_to_agent, knowledge_search) automatically preserved, never filtered
  • 🔧 Flexible Customization: Support for built-in filters and custom FilterFunc

Tool Search (Automatic Tool Selection)

In addition to rule-based filtering (Tool Filter), the framework provides Tool Search: before each main model call, it runs a lightweight “tool selection” step to shrink the available tool set to TopK (for example, 3 tools), then sends only those tools to the main model. This typically reduces token usage (especially PromptTokens) when the full tool list is large.

Trade-offs to keep in mind:

  • Latency: Tool Search adds extra work (another LLM call and/or embedding + vector search), so end-to-end latency may increase.
  • Prompt caching: the tool list can change every turn, which may reduce prompt caching hit rate on some providers.

How it differs from Tool Filter:

  • Tool Filter: you (or your business logic) decide which tools are allowed/blocked (access control / cost control).
  • Tool Search: the framework picks tools automatically based on the current user query (automation / cost optimization).

They can be combined: use Tool Filter for permissions/allow-lists first, then use Tool Search to select TopK from the remaining tools.

Two strategies:

  • LLM Search: put the candidate tool list (name + description) into the prompt and ask an LLM to output the selected tool names.
    • Pros: no vector store needed; simple to adopt.
    • Cons: the prompt cost grows roughly linearly with the number/length of tool descriptions, and repeats every turn.
  • Knowledge Search: rewrite the query with an LLM, then use embeddings + vector search to find relevant tools.
    • Pros: you don’t need to send the full tool list to the selection LLM every turn; and tool embeddings are cached within the same ToolKnowledge instance (so tools are not re-embedded repeatedly).
    • Note: the query is still embedded each turn (a fixed per-turn cost).

Tool Search can be used either as a Runner plugin or as a per-agent callback.

Option A: Runner Plugin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import (
    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/plugin/toolsearch"
    "trpc.group/trpc-go/trpc-agent-go/runner"
)

ts, err := toolsearch.New(modelInstance,
    toolsearch.WithMaxTools(3),
    toolsearch.WithFailOpen(), // optional: fallback to full tool set on failure
)
if err != nil { /* handle */ }

ag := llmagent.New("assistant",
    llmagent.WithModel(modelInstance),
    llmagent.WithTools(allTools), // register full tools; Tool Search picks TopK
)

r := runner.NewRunner("app", ag,
    runner.WithPlugins(ts),
)

Option B: Per-Agent BeforeModel Callback

Register Tool Search as a BeforeModel callback. It will mutate req.Tools before the main model call:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
    import (
        "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
        "trpc.group/trpc-go/trpc-agent-go/plugin/toolsearch"
        "trpc.group/trpc-go/trpc-agent-go/model"
    )

modelCallbacks := model.NewCallbacks()
tc, err := toolsearch.New(modelInstance,
    toolsearch.WithMaxTools(3),
    toolsearch.WithFailOpen(), // optional: fallback to full tool set on failure
)
if err != nil { /* handle */ }
modelCallbacks.RegisterBeforeModel(tc.Callback())

agent := llmagent.New("assistant",
    llmagent.WithModel(modelInstance),
    llmagent.WithTools(allTools), // register full tools; Tool Search will pick TopK per run
    llmagent.WithModelCallbacks(modelCallbacks),
)

Create a ToolKnowledge (embedder + vector store) and enable it via toolsearch.WithToolKnowledge(...):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
    import (
        "trpc.group/trpc-go/trpc-agent-go/plugin/toolsearch"
        openaiembedder "trpc.group/trpc-go/trpc-agent-go/knowledge/embedder/openai"
        vectorinmemory "trpc.group/trpc-go/trpc-agent-go/knowledge/vectorstore/inmemory"
    )

toolKnowledge, err := toolsearch.NewToolKnowledge(
    openaiembedder.New(openaiembedder.WithModel(openaiembedder.ModelTextEmbedding3Small)),
    toolsearch.WithVectorStore(vectorinmemory.New()),
)
if err != nil { /* handle */ }

tc, err := toolsearch.New(modelInstance,
    toolsearch.WithMaxTools(3),
    toolsearch.WithToolKnowledge(toolKnowledge),
    toolsearch.WithFailOpen(),
)
if err != nil { /* handle */ }
modelCallbacks.RegisterBeforeModel(tc.Callback())
Token Usage (Optional)

Tool Search stores usage in context.Context, which you can use for metrics/cost analysis:

1
2
3
4
5
    import "trpc.group/trpc-go/trpc-agent-go/plugin/toolsearch"

if usage, ok := toolsearch.ToolSearchUsageFromContext(ctx); ok && usage != nil {
    // usage.PromptTokens / usage.CompletionTokens / usage.TotalTokens
}

Basic Usage

1. Exclude Specific Tools (Exclude Filter)

Use blacklist approach to exclude unwanted tools:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import "trpc.group/trpc-go/trpc-agent-go/tool"

// Option 1:
// Exclude text_tool and dangerous_tool, all other tools available
filter := tool.NewExcludeToolNamesFilter("text_tool", "dangerous_tool")
eventChan, err := runner.Run(ctx, userID, sessionID, message,
    agent.WithToolFilter(filter),
)

// Option 2:
agent := llmagent.New("ai-assistant",
    llmagent.WithModel(model),
    llmagent.WithInstruction("You are a helpful AI assistant that can use various tools to help users."),
    llmagent.WithTools([]tool.Tool{
        calculatorTool, timeTool, searchTool,
    }),
    llmagent.WithToolSets([]tool.ToolSet{
        stdioToolSet, sseToolSet, streamableToolSet,
    }),
    llmagent.WithToolFilter(filter),
)

2. Include Only Specific Tools (Include Filter)

Use whitelist approach to allow only specified tools:

1
2
3
4
5
// Only allow calculator and time tool
filter := tool.NewIncludeToolNamesFilter("calculator", "time_tool")
eventChan, err := runner.Run(ctx, userID, sessionID, message,
    agent.WithToolFilter(filter),
)

3. Custom Filtering Logic (Custom FilterFunc)

Implement custom filter function for complex filtering logic:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Option 1:
// Custom filter: only allow tools with names starting with "safe_"
filter := func(ctx context.Context, t tool.Tool) bool {
    declaration := t.Declaration()
    if declaration == nil {
        return false
    }
    return strings.HasPrefix(declaration.Name, "safe_")
}

eventChan, err := runner.Run(ctx, userID, sessionID, message,
    agent.WithToolFilter(filter),
)

// Option 2:
agent := llmagent.New("ai-assistant",
    llmagent.WithModel(model),
    llmagent.WithInstruction("You are a helpful AI assistant that can use various tools to help users."),
    llmagent.WithTools([]tool.Tool{
        calculatorTool, timeTool, searchTool,
    }),
    llmagent.WithToolSets([]tool.ToolSet{
        stdioToolSet, sseToolSet, streamableToolSet,
    }),
    llmagent.WithToolFilter(filter),

4. Per-Agent Filtering

Use agent.InvocationFromContext to implement different tool sets for different Agents:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// Define allowed tools for each Agent
agentAllowedTools := map[string]map[string]bool{
    "math-agent": {
        "calculator": true,
    },
    "time-agent": {
        "time_tool": true,
    },
}

// Custom filter function: filter based on current Agent name
filter := func(ctx context.Context, t tool.Tool) bool {
    declaration := t.Declaration()
    if declaration == nil {
        return false
    }
    toolName := declaration.Name

    // Get current Agent information from context
    inv, ok := agent.InvocationFromContext(ctx)
    if !ok || inv == nil {
        return true // fallback: allow all tools
    }

    agentName := inv.AgentName

    // Check if this tool is in the current Agent's allowed list
    allowedTools, exists := agentAllowedTools[agentName]
    if !exists {
        return true // fallback: allow all tools
    }

    return allowedTools[toolName]
}

eventChan, err := runner.Run(ctx, userID, sessionID, message,
    agent.WithToolFilter(filter),
)

Complete Example: See examples/toolfilter/ directory

Smart Filtering Mechanism

The framework automatically distinguishes user tools from framework tools, filtering only user tools:

Tool Category Includes Filtered?
User Tools Tools registered via WithTools
Tools registered via WithToolSets		 ✅ Subject to filtering
Framework Tools transfer_to_agent (multi-Agent coordination)
knowledge_search (knowledge base retrieval)
agentic_knowledge_search		 ❌ Never filtered, auto-preserved

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// Agent registers multiple tools
agent := llmagent.New("assistant",
    llmagent.WithTools([]tool.Tool{
        calculatorTool,  // User tool
        textTool,        // User tool
    }),
    llmagent.WithSubAgents([]agent.Agent{subAgent1, subAgent2}), // Auto-adds transfer_to_agent
    llmagent.WithKnowledge(kb),                                   // Auto-adds knowledge_search
)

// Runtime filtering: only allow calculator
filter := tool.NewIncludeToolNamesFilter("calculator")
runner.Run(ctx, userID, sessionID, message,
    agent.WithToolFilter(filter),
)

// Tools actually sent to LLM:
// ✅ calculator        - User tool, in allowed list
// ❌ textTool          - User tool, filtered out
// ✅ transfer_to_agent - Framework tool, auto-preserved
// ✅ knowledge_search  - Framework tool, auto-preserved

Important Notes

⚠️ Security Notice: Per-run tool filtering is a "soft constraint" primarily for optimization and user experience. Tools must still implement their own authorization logic:

Manual Tool Execution (Interrupt Tool Calls)

By default, when the model returns tool_calls, the framework executes those tools automatically, then sends the tool results back to the model.

In some systems, you may want the caller (for example, a client, an upstream service, or an external tool runtime such as Model Context Protocol (MCP)) to execute tools instead. You can interrupt tool execution with agent.WithToolExecutionFilter(...).

Key idea:

  • agent.WithToolFilter(...) controls tool visibility (what the model can see and call).
  • agent.WithToolExecutionFilter(...) controls tool execution (what the framework will auto-run after the model requests it).

Basic Flow

  1. Run the agent with WithToolExecutionFilter so the framework does not execute selected tools.
  2. Read tool_calls from the model response.
  3. Execute the tool externally.
  4. Send a role=tool message back so the model can continue.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
execFilter := tool.NewExcludeToolNamesFilter("external_search")

// Step 1: model returns tool_calls, but the tool is NOT executed.
ch, err := r.Run(ctx, userID, sessionID, model.NewUserMessage("search ..."),
    agent.WithToolExecutionFilter(execFilter),
)

// Step 2: extract tool_call_id + arguments from events (omitted).
toolCallID := "call_123"
toolResultJSON := `{"status":"ok","data":"..."}`

// Step 3/4: send tool result as role=tool, then model continues.
toolMsg := model.NewToolMessage(toolCallID, "external_search", toolResultJSON)
ch, err = r.Run(ctx, userID, sessionID, toolMsg,
    agent.WithToolExecutionFilter(execFilter),
)

Complete example: examples/toolinterrupt/

1
2
3
4
5
6
7
8
9
func sensitiveOperation(ctx context.Context, req Request) (Result, error) {
    // ✅ Required: internal tool authorization
    if !hasPermission(ctx, req.UserID, "sensitive_operation") {
        return nil, fmt.Errorf("permission denied")
    }

    // Execute operation
    return performOperation(req)
}

Reason: LLMs may know about tool existence and usage from context or memory and attempt to call them. Tool filtering reduces this possibility but cannot completely prevent it.

Parallel Tool Execution

1
2
3
4
5
6
7
// Enable parallel tool execution (optional, for performance optimization).
agent := llmagent.New("ai-assistant",
    llmagent.WithModel(model),
    llmagent.WithTools(tools),
    llmagent.WithToolSets(toolSets),
    llmagent.WithEnableParallelTools(true), // Enable parallel execution.
)

Graph workflows can also enable parallelism for a Tools node:

1
stateGraph.AddToolsNode("tools", tools, graph.WithEnableParallelTools(true))

Parallel execution effect:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Parallel execution (enabled).
Tool 1: get_weather     [====] 50ms
Tool 2: get_population  [====] 50ms
Tool 3: get_time       [====] 50ms
Total time: ~50ms (executed simultaneously)

# Serial execution (default).
Tool 1: get_weather     [====] 50ms
Tool 2: get_population       [====] 50ms
Tool 3: get_time                  [====] 50ms
Total time: ~150ms (executed sequentially)

Dynamic ToolSet Management (Runtime)

WithToolSets is a static configuration: it wires ToolSets when constructing the Agent. In many real‑world scenarios you also need to add, remove, or replace ToolSets at runtime without recreating the Agent.

LLMAgent exposes three methods for this:

  • AddToolSet(toolSet tool.ToolSet) — add or replace a ToolSet by ToolSet.Name().
  • RemoveToolSet(name string) bool — remove all ToolSets whose Name() matches name.
  • SetToolSets(toolSets []tool.ToolSet) — replace all ToolSets with the provided slice.

These methods are concurrency‑safe and automatically recompute:

  • Aggregated tools (direct tools + ToolSets + knowledge tools + skill tools)
  • User tool tracking (used by the smart filtering logic above)

Typical usage pattern:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// 1. Create Agent with base tools only.
agent := llmagent.New("dynamic-assistant",
    llmagent.WithModel(model),
    llmagent.WithTools([]tool.Tool{calculatorTool}),
)

// 2. Later, attach an MCP ToolSet at runtime.
mcpToolSet := mcp.NewMCPToolSet(connectionConfig)
if err := mcpToolSet.Init(ctx); err != nil {
    return fmt.Errorf("failed to init MCP ToolSet: %w", err)
}
agent.AddToolSet(mcpToolSet)

// 3. Replace all ToolSets from configuration (declarative control plane).
toolSetsFromConfig := []tool.ToolSet{mcpToolSet, fileToolSet}
agent.SetToolSets(toolSetsFromConfig)

// 4. Remove a ToolSet by name (e.g., feature rollback).
removed := agent.RemoveToolSet(mcpToolSet.Name())
if !removed {
    log.Printf("ToolSet %q not found", mcpToolSet.Name())
}

Runtime ToolSet updates integrate seamlessly with the tool filtering logic described earlier:

  • Tools coming from WithTools or any ToolSet (including dynamically added ones) are treated as user tools and are subject to WithToolFilter and per‑run filters.
  • Framework tools such as transfer_to_agent, knowledge_search, and agentic_knowledge_search remain never filtered and are always available.

Tool Call Arguments Auto Repair

Some models may emit non-strict JSON arguments for tool_calls (for example, unquoted object keys or trailing commas), which can break tool execution or external parsing.

Tool call arguments auto repair is useful when the caller needs to parse toolCall.Function.Arguments outside the framework, or when tools require strictly valid JSON input.

When agent.WithToolCallArgumentsJSONRepairEnabled(true) is enabled in runner.Run, the framework will attempt to repair toolCall.Function.Arguments on a best-effort basis.

1
2
3
ch, err := r.Run(ctx, userID, sessionID, model.NewUserMessage("..."),
    agent.WithToolCallArgumentsJSONRepairEnabled(true),
)

Quick Start

Environment Setup

1
2
# Set API key.
export OPENAI_API_KEY="your-api-key"

Simple Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
package main

import (
    "context"
    "fmt"

    "trpc.group/trpc-go/trpc-agent-go/runner"
    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/model/openai"
    "trpc.group/trpc-go/trpc-agent-go/model"
    "trpc.group/trpc-go/trpc-agent-go/tool/function"
)

func main() {
    // 1. Create a simple tool.
    calculatorTool := function.NewFunctionTool(
        func(ctx context.Context, req struct {
            Operation string  `json:"operation"`
            A         float64 `json:"a"`
            B         float64 `json:"b"`
        }) (map[string]interface{}, error) {
            var result float64
            switch req.Operation {
            case "add":
                result = req.A + req.B
            case "multiply":
                result = req.A * req.B
            default:
                return nil, fmt.Errorf("unsupported operation")
            }
            return map[string]interface{}{"result": result}, nil
        },
        function.WithName("calculator"),
        function.WithDescription("Simple calculator."),
    )

    // 2. Create model and Agent.
    llmModel := openai.New("DeepSeek-V3-Online-64K")
    agent := llmagent.New("calculator-assistant",
        llmagent.WithModel(llmModel),
        llmagent.WithInstruction("You are a math assistant."),
        llmagent.WithTools([]tool.Tool{calculatorTool}),
        llmagent.WithGenerationConfig(model.GenerationConfig{Stream: true}), // Enable streaming output.
    )

    // 3. Create Runner and execute.
    r := runner.NewRunner("math-app", agent)

    ctx := context.Background()
    userMessage := model.NewUserMessage("Please calculate 25 times 4.")

    eventChan, err := r.Run(ctx, "user1", "session1", userMessage)
    if err != nil {
        panic(err)
    }

    // 4. Handle responses.
    for event := range eventChan {
        if event.Error != nil {
            fmt.Printf("Error: %s\n", event.Error.Message)
            continue
        }

        // Display tool calls.
        if len(event.Response.Choices) > 0 && len(event.Response.Choices[0].Message.ToolCalls) > 0 {
            for _, toolCall := range event.Response.Choices[0].Message.ToolCalls {
                fmt.Printf("🔧 Call tool: %s\n", toolCall.Function.Name)
                fmt.Printf("   Params: %s\n", string(toolCall.Function.Arguments))
            }
        }

        // Display streaming content.
        if len(event.Response.Choices) > 0 {
            fmt.Print(event.Response.Choices[0].Delta.Content)
        }

        if event.Done {
            break
        }
    }
}

Run the Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Enter the tool example directory.
cd examples/tool
go run .

# Enter the MCP tool example directory.
cd examples/mcp_tool

# Start the external server.
cd streamalbe_server && go run main.go &

# Run the main program.
go run main.go -model="deepseek-chat"

Summary

The Tool system provides rich extensibility for tRPC-Agent-Go, supporting Function Tools, the DuckDuckGo Search Tool, and MCP protocol tools.