Agent Tools

Agent Tools

AgentForceAgent Auto-Loading Function Calling

Agent Tools enable AgentForceAgent instances to interact with external functions and APIs during conversation. Tools are automatically loaded and made available to the agent based on the tools configuration in AgentConfig, allowing for dynamic interactions and enhanced functionality.

Configuration

Tools are configured in the AgentConfig when creating an agent instance:

import { AgentForceAgent, type AgentConfig } from "@agentforce/adk";

const agentConfig: AgentConfig = {
    name: "FileAgent",
    tools: ["fs_read_file", "fs_write_file"] // Tool names from registry
};

Parameters

Parameter

Type

Default

Description

tools

string[]

undefined

Array of tool names that will be loaded from the tool registry and made available to the agent

How Tools Work

Auto-Loading Mechanism

1. Configuration: Tools are specified in the AgentConfig.tools array
2. Registry Lookup: Each tool name is resolved from the central tool registry
3. Auto-Loading: Tools are automatically loaded when the agent executes
4. LLM Integration: Tool definitions are passed to the LLM provider for function calling
5. Execution: When the LLM calls a tool, the implementation is executed automatically

Note

Tools are loaded automatically during agent execution - no manual loading methods are required.

Tool Execution Flow

// 1. Agent configured with tools
const agent = new AgentForceAgent({
    name: "FileAgent",
    tools: ["fs_read_file"]
});

// 2. Tools are auto-loaded during execution
const response = await agent
    .prompt("Read the README.md file and summarize it")
    .getResponse();

// 3. LLM can call fs_read_file tool during response generation
// 4. Tool results are fed back to LLM for final response

Available Tools

File System Tools

Tool

Description

Key Parameters

fs_read_file

Read the contents of a specified file

path, encoding, max_length

fs_write_file

Write content to a specified file

path, content, encoding, append

fs_list_dir

List contents of a directory

path, include_hidden, recursive

fs_move_file

Move or rename files

source, destination, overwrite

fs_find_files

Find files matching specified patterns

pattern, path, recursive, case_sensitive

fs_find_dirs_and_files

Find both directories and files

path, pattern, max_depth

fs_search_content

Search for content within files

query, path, file_pattern, case_sensitive

fs_get_file_tree

Get a complete file tree structure

path, max_depth, include_hidden

Web and API Tools

Tool

Description

Key Parameters

web_fetch

Web scraping with JavaScript rendering using Puppeteer

url, wait_for_selector, screenshot, extract_links

api_fetch

HTTP requests with security and resource limits

url, method, headers, body, timeout_ms

filter_content

Filter and process content

content, filter_type, options

Git and GitHub Tools

Tool

Description

Key Parameters

gh_list_repos

List GitHub repositories

username, type, sort, visibility

System Tools

Tool

Description

Key Parameters

os_exec

Execute system commands safely with allowlist

command, args, cwd, timeout_ms

Utility Tools

Tool

Description

Key Parameters

md_create_ascii_tree

Create ASCII tree representations in Markdown

structure, style, indentation

Examples

Basic Usage

File Operations

import { AgentForceAgent, type AgentConfig } from "@agentforce/adk";

const agentConfig: AgentConfig = {
    name: "FileAgent",
    tools: ["fs_read_file", "fs_write_file", "fs_list_dir"]
};

const agent = new AgentForceAgent(agentConfig)
    .useLLM("ollama", "devstral") // ✅ Great for file operations and coding
    .systemPrompt("You are a file management assistant.")
    .prompt("Read the package.json file, then create a summary file");

const response = await agent.getResponse();

Web Scraping

import { AgentForceAgent, type AgentConfig } from "@agentforce/adk";

const agentConfig: AgentConfig = {
    name: "WebScrapingAgent",
    tools: ["web_fetch", "fs_write_file"]
};

const agent = new AgentForceAgent(agentConfig)
    .useLLM("ollama", "qwen3:8b") // ✅ Versatile with strong tool calling
    .systemPrompt("You are a web scraping specialist.")
    .prompt("Scrape the latest news from example.com and save to news.md");

const response = await agent.output("md");

API Integration

import { AgentForceAgent, type AgentConfig } from "@agentforce/adk";

const agentConfig: AgentConfig = {
    name: "APIAgent",
    tools: ["api_fetch", "filter_content"]
};

const agent = new AgentForceAgent(agentConfig)
    .useLLM("ollama", "gpt-oss:20b") // ✅ Strong reasoning for API integration
    .systemPrompt("You are an API integration expert.")
    .prompt("Fetch data from the JSON API and extract key metrics");

const response = await agent.run();

System Operations

import { AgentForceAgent, type AgentConfig } from "@agentforce/adk";

const agentConfig: AgentConfig = {
    name: "DevOpsAgent",
    tools: ["os_exec", "fs_read_file", "fs_write_file"]
};

const agent = new AgentForceAgent(agentConfig)
    .useLLM("ollama", "deepseek-r1:14b") // ✅ Excellent for system operations
    .systemPrompt("You are a DevOps automation assistant.")
    .prompt("Check git status, read the latest commit, and create a deployment summary");

const response = await agent.output("json");

Advanced Tool Combinations

Research Assistant

const researchAgent = new AgentForceAgent({
    name: "ResearchAgent",
    tools: [
        "web_fetch",           // Web scraping
        "api_fetch",           // API calls
        "fs_write_file",       // Save results
        "filter_content",      // Content processing
        "md_create_ascii_tree" // Structure data
    ]
})
    .useLLM("ollama", "llama4:16x17b") // ✅ Latest with vision support
    .systemPrompt("You are a research assistant that can gather information from multiple sources.")
    .prompt("Research the latest AI developments and create a structured report");

const report = await researchAgent.output("md");

Code Analysis

const codeAnalyst = new AgentForceAgent({
    name: "CodeAnalyst",
    tools: [
        "fs_read_file",        // Read source files
        "fs_find_files",       // Find code files
        "fs_search_content",   // Search for patterns
        "os_exec",             // Run analysis tools
        "fs_write_file"        // Save reports
    ]
})
    .useLLM("ollama", "devstral") // ✅ Best for code analysis
    .systemPrompt("You are a code analysis specialist.")
    .prompt("Analyze the TypeScript project structure and identify potential improvements");

const analysis = await codeAnalyst.output("json");

Content Manager

const contentManager = new AgentForceAgent({
    name: "ContentManager",
    tools: [
        "fs_get_file_tree",    // Project structure
        "fs_read_file",        // Read content
        "web_fetch",           // External research
        "filter_content",      // Process content
        "fs_write_file"        // Save output
    ]
})
    .useLLM("ollama", "magistral") // ✅ Efficient reasoning model
    .systemPrompt("You are a content management specialist.")
    .prompt("Audit the documentation structure and suggest improvements");

const audit = await contentManager.run();

Tool Security and Limitations

Security Features

Input Validation

All tools validate parameters and data types before execution

Sanitization of file paths and user inputs to prevent injection attacks

Resource Limits

Timeout controls prevent long-running operations from hanging

Size limits on file operations and network responses

Allowlists

Command allowlists for system execution tools

Protocol restrictions (HTTP/HTTPS only) for network tools

Sandboxing

Working directory restrictions for file operations

No shell execution - direct command spawning only

Tool-Specific Limitations

File System Tools

Security Restrictions:

• Operations restricted to project directory
• Path traversal prevention
• File size limits for read operations
• Encoding validation

Performance Limits:

• Maximum file size: 5MB (configurable)
• Search depth limits
• Timeout controls

// Example: Safe file operations
{
  "path": "./data/safe-file.txt",    // ✅ Within project
  "max_length": 1000000              // ✅ Size limit
}

Network Tools

Security Restrictions:

• HTTP/HTTPS protocols only
• Request size limits
• Response size limits
• Timeout controls

Anti-Detection Features (web_fetch):

• Stealth mode with Puppeteer
• User agent rotation
• Cookie support
• JavaScript rendering

// Example: Safe API call
{
  "url": "https://api.example.com/data",  // ✅ HTTPS only
  "timeout_ms": 30000,                    // ✅ Timeout limit
  "max_response_bytes": 5000000           // ✅ Size limit
}

System Tools

Command Allowlist:

• node, bun, npm, yarn, git
• ls, cat, grep, sed, awk
• curl, wget, tar, zip
• mkdir, rm, cp, mv, find

Sandboxing:

• No shell access
• Working directory restrictions
• Environment variable controls

// Example: Safe command execution
{
  "command": "git",                    // ✅ Allowed command
  "args": ["status", "--porcelain"],  // ✅ Safe arguments
  "cwd": "./project",                 // ✅ Within project
  "timeout_ms": 15000                 // ✅ Timeout limit
}

Error Handling

Caution

Tools provide comprehensive error handling and graceful degradation:

Tool Loading Errors

// Missing tools are logged but don't break execution
const agent = new AgentForceAgent({
    name: "SafeAgent",
    tools: ["nonexistent_tool", "fs_read_file"] // First tool missing
})
    .systemPrompt("Base prompt")
    .prompt("Execute task");

// Agent will:
// 1. Log warning for missing tool
// 2. Load available tools (fs_read_file)
// 3. Continue execution normally

const response = await agent.getResponse();

Debug Log Output:

{
  "msg": "Loading tools for agent",
  "requestedTools": ["nonexistent_tool", "fs_read_file"]
}
{
  "level": "warn",
  "tool": "nonexistent_tool",
  "msg": "Tool not found in registry"
}
{
  "tool": "fs_read_file",
  "msg": "Tool loaded successfully"
}
{
  "loadedCount": 1,
  "msg": "Tools loaded for agent"
}

Tool Execution Errors

// Tools handle execution errors gracefully
const agent = new AgentForceAgent({
    name: "ErrorHandlingAgent",
    tools: ["fs_read_file"]
})
    .debug() // Enable debug logging
    .prompt("Read a file that doesn't exist");

// Tool execution returns error information instead of throwing
const response = await agent.getResponse();

Tool Error Response Format:

{
  "success": false,
  "error": "File not found: /path/to/nonexistent.txt",
  "path": "/path/to/nonexistent.txt"
}

Debugging Tools

Debug Logging

Enable detailed tool execution logging:

const agent = new AgentForceAgent({
    name: "DebugAgent",
    tools: ["fs_read_file", "api_fetch"]
})
    .debug() // Enable debug logging
    .systemPrompt("Debug agent")
    .prompt("Test tools");

const response = await agent.getResponse();

Tool Registry Inspection

import { getAvailableTools, hasTool, getTool } from "@agentforce/adk";

// List all available tools
const allTools = getAvailableTools();
console.log("Available tools:", allTools);

// Check if a tool exists
const hasFileReader = hasTool("fs_read_file");
console.log("Has fs_read_file:", hasFileReader);

// Get tool definition
const tool = getTool("fs_read_file");
console.log("Tool definition:", tool?.definition);

Provider Compatibility

Tool Support by Provider

Provider Compatibility

Tool Support by Provider

Provider

Tool Support

Notes

Ollama

✅ Full Support

Function calling integration with specific models only

OpenRouter

✅ Full Support

Supports models with function calling capabilities

Google

🚧 Coming Soon

Tool integration planned for future release

⚠️ Model Compatibility Requirements

Caution

IMPORTANT: Not all models support function calling/tools. You must use models specifically designed for tool use.

Ollama Models That Support Tools

All Current Tool-Capable Models:

Model

Sizes

Description

Features

gpt-oss

20b, 120b

OpenAI's open-weight models for reasoning and agentic tasks

tools, thinking

mistral-small3.2

24b

Improved function calling and instruction following

vision, tools

magistral

24b

Small, efficient reasoning model

tools, thinking

devstral

24b

Best open source model for coding agents

tools

qwen3

0.6b-235b

Latest Qwen series with comprehensive model sizes

tools, thinking

granite3.3

2b, 8b

IBM Granite with 128K context length

tools

mistral-small3.1

24b

Vision understanding with 128k token context

vision, tools

cogito

3b-70b

Hybrid reasoning models by Deep Cogito

tools

llama4

16x17b, 128x17b

Meta's latest multimodal models

vision, tools

deepseek-r1

1.5b-671b

Open reasoning models approaching O3 performance

tools, thinking

phi4-mini

3.8b

Multilingual with function calling support

tools

llama3.3

70b

Performance similar to Llama 3.1 405B model

tools

qwq

32b

Reasoning model of the Qwen series

tools

Tip

Top Recommendations for Tool Integration:

• deepseek-r1 - Excellent reasoning with tool calling
• qwen3 - Versatile with multiple size options
• devstral - Specialized for coding agents
• gpt-oss - Strong reasoning capabilities
• llama4 - Latest with vision support

Models That Do NOT Support Tools:

• gemma3:4b ❌ - Does not support function calling
• gemma2:2b ❌ - Does not support function calling
• phi3:mini ❌ - Does not support function calling (use phi4-mini instead)
• Basic completion models ❌ - Only chat models support tools

OpenRouter Models That Support Tools

Recommended Models:

• anthropic/claude-3.5-sonnet - Excellent tool support
• anthropic/claude-3-opus - Advanced function calling
• openai/gpt-4 - Full tool integration
• openai/gpt-4-turbo - Enhanced tool capabilities
• moonshotai/kimi-k2 - Supports function calling (free tier available)
• qwen/qwen-2-72b-instruct - Strong tool support

Model Selection Examples

Ollama - Recommended

// ✅ CORRECT: Using a model that supports tools
const agent = new AgentForceAgent({
    name: "ToolAgent",
    tools: ["fs_read_file", "web_fetch"]
})
    .useLLM("ollama", "deepseek-r1:7b") // ✅ Excellent tool support
    .systemPrompt("You are a helpful assistant with tool access.")
    .prompt("Read the README.md file and summarize it");

const response = await agent.run();

Ollama - Wrong Model

// ❌ WRONG: Using a model that doesn't support tools
const agent = new AgentForceAgent({
    name: "ToolAgent",
    tools: ["fs_read_file"] // Tools configured but...
})
    .useLLM("ollama", "gemma3:4b") // ❌ Does NOT support tools
    .prompt("Read a file");

// This will result in error:
// "registry.ollama.ai/library/gemma3:4b does not support tools"

// ✅ CORRECT: Use any of the tool-capable models instead
.useLLM("ollama", "qwen3:8b")      // ✅ Supports tools
.useLLM("ollama", "devstral")      // ✅ Great for coding
.useLLM("ollama", "deepseek-r1")   // ✅ Excellent reasoning

OpenRouter - Recommended

// ✅ CORRECT: Using OpenRouter with tool-capable model
const agent = new AgentForceAgent({
    name: "OpenRouterToolAgent",
    tools: ["fs_read_file", "api_fetch", "web_fetch"]
})
    .useLLM("openrouter", "anthropic/claude-3-haiku") // ✅ Supports tools
    .systemPrompt("You are a research assistant with file and web access.")
    .prompt("Research the latest AI developments and save findings");

const response = await agent.getResponse();

Model Configuration

import type { ModelConfig } from "@agentforce/adk";

const modelConfig: ModelConfig = {
    temperature: 0.7,
    maxTokens: 16384,
    maxToolRounds: 10, // Limit tool execution rounds
    timeout: 60000     // 60 second timeout
};

const agent = new AgentForceAgent({
    name: "ConfiguredAgent",
    tools: ["fs_read_file", "fs_write_file"]
})
    .useLLM("ollama", "deepseek-r1:7b", modelConfig) // ✅ Excellent tool support
    .prompt("Process files with controlled parameters");

Installing Tool-Compatible Models

Ollama Model Installation

Ollama Model Installation

# Install top recommended models for tool integration
ollama pull deepseek-r1:7b         # Excellent reasoning with tool support
ollama pull qwen3:8b               # Versatile with strong tool calling
ollama pull devstral               # Best for coding agents
ollama pull gpt-oss:20b            # Strong reasoning capabilities
ollama pull llama4:16x17b          # Latest with vision support

# Smaller models for resource-constrained environments
ollama pull phi4-mini              # 3.8B with function calling
ollama pull granite3.3:2b          # IBM's compact model
ollama pull smollm2:1.7b           # Smallest tool-capable model

# Verify model supports tools
ollama show deepseek-r1:7b

# List all available models
ollama list

OpenRouter Setup

# Set your OpenRouter API key
export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here

# Or add to .env file
echo "OPENROUTER_API_KEY=sk-or-v1-your-api-key-here" >> .env

Error Troubleshooting

Common Tool-Related Errors

Model Not Supporting Tools

Error: "registry.ollama.ai/library/gemma3:4b does not support tools"

Solution:

// ❌ Wrong - model doesn't support tools
.useLLM("ollama", "gemma3:4b")

// ✅ Correct - use tool-compatible model
.useLLM("ollama", "qwen2.5-coder:7b")

Model Not Found

Error: "model not found: deepseek-r1:7b"

Solution:

# Install the model first
ollama pull deepseek-r1:7b

# Then use in your agent
.useLLM("ollama", "deepseek-r1:7b")

Tool Execution Timeout

Error: "Tool execution timed out"

Solution:

const modelConfig: ModelConfig = {
    timeout: 120000,        // Increase timeout to 2 minutes
    maxToolRounds: 5        // Limit tool rounds
};

.useLLM("ollama", "deepseek-r1:7b", modelConfig) // ✅ Excellent tool support

Ollama Tool Integration

// Ollama has full tool support with compatible models
const ollamaAgent = new AgentForceAgent({
    name: "OllamaToolAgent",
    tools: ["fs_read_file", "api_fetch", "os_exec"]
})
    .useLLM("ollama", "deepseek-r1:7b") // ✅ Excellent tool calling
    .prompt("Use tools to analyze the project");

// Tools are automatically available during conversation
const response = await ollamaAgent.run();

Use Cases

Development Automation

Tools: fs_*, os_exec, gh_list_repos

Best for: Code analysis, file management, git operations, build automation

Content Research

Tools: web_fetch, api_fetch, filter_content

Best for: Web scraping, API integration, content aggregation

Data Processing

Tools: fs_*, filter_content, md_create_ascii_tree

Best for: File processing, data transformation, report generation

System Administration

Tools: os_exec, fs_*, gh_list_repos

Best for: System monitoring, deployment automation, infrastructure management

Best Practices

✅ Effective Tool Usage

// Combine complementary tools
const agent = new AgentForceAgent({
    name: "EffectiveAgent",
    tools: [
        "fs_read_file",      // Read source data
        "filter_content",    // Process data
        "fs_write_file"      // Save results
    ]
})
    .useLLM("openrouter", "moonshotai/kimi-k2");

// Provide clear context
.systemPrompt(`You have access to file operations and content filtering tools.
Use them to read, process, and save data efficiently.`)

// Give specific instructions
.prompt("Read data.json, extract important fields, and save a summary to summary.md");

❌ Common Issues

// Too many tools (performance impact)
tools: ["fs_read_file", "fs_write_file", "fs_list_dir", "web_fetch",
        "api_fetch", "os_exec", "gh_list_repos"] // Too many

// Wrong tool selection
tools: ["web_fetch"] // For local file operations

// Missing required tools
tools: ["fs_read_file"] // But need to write files too

// Tool overkill
tools: ["os_exec"] // Just to run "ls" command

Related Features

• Agent Skills - Combine tools with skills for enhanced capabilities
• .systemPrompt() - Define how agents should use tools
• Agent Configuration - Complete agent configuration options
• Provider Integration - Tool support varies by provider

See Also

• Tool Development Guide - Creating custom tools
• Security Best Practices - Safe tool usage patterns
• Advanced Examples - Complex tool integration examples
• API Reference - Detailed tool documentation