Tools

Tools are callable capabilities the LLM can invoke during a run. Agent SDK for Go converts each registered tool into a JSON schema the model sees, executes the tool when the model returns a tool call, and feeds the result back into the next LLM round.

Register tools

At creation — pass tools directly or via a registry:

reg := agent.NewToolRegistry()
if err := agent.RegisterTools(reg, calculator.New(), weather.New()); err != nil {
    log.Fatal(err)
}

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithToolRegistry(reg),
    agent.WithToolApprovalPolicy(agent.AutoToolApprovalPolicy()),
)

Option	When to use
`WithTools`	Fixed tool set known at startup
`WithToolRegistry`	Add or remove tools after `NewAgent` — see Dynamic Capabilities

Built-in tools live under pkg/tools/ (calculator, weather, search, and others).

Custom tools

Implement interfaces.Tool. All five methods are required:

Method	Purpose
`Name() string`	Stable identifier the LLM uses in tool calls — must be unique across all tool sources
`DisplayName() string`	Human-readable label for UI and logs
`Description() string`	When and how the model should use this tool — quality here affects routing accuracy
`Parameters() JSONSchema`	JSON Schema for tool arguments — build with `pkg/tools` helpers
`Execute(ctx, args) (any, error)`	Run the tool and return a result

Complete implementation

package search

import (
    "context"
    "fmt"

    "github.com/agenticenv/agent-sdk-go/pkg/interfaces"
    "github.com/agenticenv/agent-sdk-go/pkg/tools"
)

// SearchTool implements interfaces.Tool for a product search capability.
type SearchTool struct {
    client *SearchClient
}

func New(client *SearchClient) *SearchTool {
    return &SearchTool{client: client}
}

func (t *SearchTool) Name() string {
    return "search_products"
}

func (t *SearchTool) DisplayName() string {
    return "Product Search"
}

func (t *SearchTool) Description() string {
    return "Search the product catalog by keyword. Use when the user asks about products, availability, or pricing."
}

func (t *SearchTool) Parameters() interfaces.JSONSchema {
    return tools.Params(
        map[string]interfaces.JSONSchema{
            "query": tools.ParamString("Search keywords or product name"),
            "limit": tools.ParamInteger("Maximum results to return (default 10, max 50)"),
        },
        "query", // required parameters
    )
}

func (t *SearchTool) Execute(ctx context.Context, args map[string]any) (any, error) {
    query, ok := args["query"].(string)
    if !ok || query == "" {
        return nil, fmt.Errorf("query is required")
    }

    limit := 10
    if l, ok := args["limit"].(float64); ok && l > 0 {
        limit = int(l)
    }

    return t.client.Search(ctx, query, limit)
}

Tool arguments from the LLM arrive as map[string]any. JSON numbers decode as float64 — cast accordingly (see limit above).

schema helpers

pkg/tools provides type-safe helpers for Parameters():

Helper	JSON type
`tools.ParamString(desc)`	`"string"`
`tools.ParamInteger(desc)`	`"integer"`
`tools.ParamNumber(desc)`	`"number"`
`tools.ParamBool(desc)`	`"boolean"`
`tools.ParamEnum(desc, vals...)`	`"string"` with `"enum"`
`tools.ParamArray(desc, items)`	`"array"`
`tools.Params(properties, required...)`	Full `"object"` schema

Optional tool interfaces

Interface	Purpose
`ToolApproval`	Tool-level hint for interactive human approval — overridden by the agent’s `WithToolApprovalPolicy`
`ToolAuthorizer`	Programmatic gate (scopes, tenancy, feature flags) before approval or execution

// ToolAuthorizer example — check tenant scope before execution
func (t *SearchTool) Authorize(ctx context.Context, args map[string]any) (interfaces.ToolAuthorizationDecision, error) {
    if !hasSearchPermission(ctx) {
        return interfaces.ToolAuthorizationDecision{Allow: false, Reason: "search not permitted"}, nil
    }
    return interfaces.ToolAuthorizationDecision{Allow: true}, nil
}

See Approvals for the full approval and authorization flow.

Tool execution context

The agent runtime sets a ToolExecMeta value on the context.Context passed to Execute. Use it to access a stable idempotency key, the run ID, and other per-invocation metadata:

func (t *PaymentTool) Execute(ctx context.Context, args map[string]any) (any, error) {
    meta, ok := interfaces.ToolExecMetaFromContext(ctx)
    if ok && meta.IdempotencyKey != "" {
        // Safe to forward to a non-idempotent external API — the key is stable
        // across Temporal activity retries and ContinueAsNew boundaries.
        return t.client.Charge(ctx, amount, meta.IdempotencyKey)
    }
    return t.client.Charge(ctx, amount, "")
}

Field	Description
`IdempotencyKey`	Stable 32-char hex key derived from `RunID`, `Iteration`, and `ToolCallID` — safe to forward to external APIs
`RunID`	Agent run identifier
`ToolCallID`	Identifier the LLM assigned to this tool call
`Iteration`	LLM round (zero-based) in which the call was made

ToolExecMetaFromContext returns false only when Execute is called outside the agent runtime (e.g. in unit tests that invoke it directly). When the model returns multiple tool calls in one turn, the SDK runs them in parallel by default:

// Default — independent tools run concurrently
agent.WithAgentToolExecutionMode(agent.AgentToolExecutionModeParallel)

// Ordered — each tool completes before the next starts (model order)
agent.WithAgentToolExecutionMode(agent.AgentToolExecutionModeSequential)

Use sequential when tools share mutable state, hit rate limits, or must run in strict order.

Use the same WithAgentToolExecutionMode on NewAgent, NewAgentWorker, and all sub-agents in a deployment. A mismatch between the agent and worker causes a fingerprint error on the Temporal runtime.

How tools merge at run time

Each Run or Stream resolves the full tool list from all registered sources:

Native / custom tools in ToolRegistry
MCP tools (MCP)
A2A skills (A2A)
Sub-agent delegation tools (Sub-agents)
Retriever tools when mode is agentic or hybrid (Retrieval)
save_memory when memory store mode is on-demand (Memory)

Tool names must be unique across all sources — validation fails fast at NewAgent and on each run.

MCP tool names are prefixed as mcp_<serverKey>_<toolName> and A2A skills as a2a_<server>_<skillId>. This prevents collisions when multiple servers expose tools with the same logical name.

Examples

Built-in, approval, authorizer, custom, and dynamic registry

Approvals

Require human approval before tool execution

MCP

External tools via Model Context Protocol

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Tools

Register tools

Custom tools

Complete implementation

schema helpers

Optional tool interfaces

Tool execution context

How tools merge at run time

Examples

Tools

Approvals

MCP

​Register tools

​Custom tools

​Complete implementation

​schema helpers

​Optional tool interfaces

​Tool execution context

​How tools merge at run time

​Examples

Tools

​Related

Approvals

MCP

Register tools

Custom tools

Complete implementation

schema helpers

Optional tool interfaces

Tool execution context

How tools merge at run time

Examples

Related