Direct Tool Calling

Call tools directly without agent orchestration. Use this when you need precise control over which tools run and when.

When to Use Direct Tool Calling

Scenario	Approach
Simple, single-step tasks	Direct tool calling
Multi-step, complex tasks	Agents with tool calling
Need full control over tool order	Direct tool calling
Want AI to decide tool usage	Agents
Performance-critical paths	Direct tool calling

Quick Example

curl -X POST http://localhost/api/v1/agent/tool-calling \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "rag_search",
    "parameters": {
      "query": "API key configuration",
      "collection": "documentation",
      "top_k": 5
    }
  }'

Response:

{
  "results": [
    {
      "document_id": "doc_123",
      "score": 0.92,
      "content": "To configure API keys, navigate to Settings...",
      "metadata": {
        "title": "API Configuration Guide",
        "path": "/guides/api-config.md"
      }
    }
  ]
}

Available Tools

RAG Search

Search your uploaded documents.

curl -X POST http://localhost/api/v1/agent/tool-calling \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "rag_search",
    "parameters": {
      "query": "How to reset password",
      "collection": "support_docs",
      "top_k": 3,
      "similarity_threshold": 0.7,
      "filters": {
        "category": "account"
      }
    }
  }'

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`collection`	string	Yes	RAG collection name
`top_k`	integer	No	Number of results (default: 5)
`similarity_threshold`	float	No	Minimum similarity (default: 0.5)
`filters`	object	No	Metadata filters

Web Search

Search the internet using Brave Search.

curl -X POST http://localhost/api/v1/agent/tool-calling \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "web_search",
    "parameters": {
      "query": "latest AI developments 2024",
      "count": 5,
      "time_range": "week"
    }
  }'

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query
`count`	integer	No	Number of results (default: 5)
`time_range`	string	No	Time filter: day, week, month, year

Code Execution

Run code in a secure sandbox.

curl -X POST http://localhost/api/v1/agent/tool-calling \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "code_execution",
    "parameters": {
      "code": "print(2 + 2)",
      "language": "python"
    }
  }'

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	Code to execute
`language`	string	No	Language: python, javascript (default: python)
`timeout`	integer	No	Timeout in seconds (default: 30)

Python Integration

import requests

class DirectToolClient:
    def __init__(self, api_key, base_url="http://localhost/api/v1"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def call_tool(self, tool_name, parameters):
        response = requests.post(
            f"{self.base_url}/agent/tool-calling",
            headers=self.headers,
            json={
                "tool_name": tool_name,
                "parameters": parameters
            }
        )
        response.raise_for_status()
        return response.json()

    def search_rag(self, query, collection, **kwargs):
        return self.call_tool("rag_search", {
            "query": query,
            "collection": collection,
            **kwargs
        })

    def search_web(self, query, **kwargs):
        return self.call_tool("web_search", {
            "query": query,
            **kwargs
        })

    def execute_code(self, code, language="python", **kwargs):
        return self.call_tool("code_execution", {
            "code": code,
            "language": language,
            **kwargs
        })

# Usage
client = DirectToolClient("YOUR_API_KEY")

# Search RAG
results = client.search_rag(
    query="API key configuration",
    collection="documentation",
    top_k=5
)

print("RAG Results:")
for result in results["results"]:
    print(f"  - {result['document_id']}: {result['score']:.2f}")

# Search web
web_results = client.search_web(
    query="latest AI news",
    count=3
)

print("\nWeb Results:")
for result in web_results["results"]:
    print(f"  - {result['title']}: {result['url']}")

# Execute code
code_result = client.execute_code("print('Hello, world!')")

print(f"\nCode Output: {code_result['output']}")

JavaScript Integration

class DirectToolClient {
  constructor(apiKey, baseUrl = 'http://localhost/api/v1') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async callTool(toolName, parameters) {
    const response = await fetch(`${this.baseUrl}/agent/tool-calling`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({
        tool_name: toolName,
        parameters
      })
    });

    if (!response.ok) {
      throw new Error(`Tool call failed: ${response.statusText}`);
    }

    return await response.json();
  }

  async searchRAG(query, collection, options = {}) {
    return await this.callTool('rag_search', {
      query,
      collection,
      ...options
    });
  }

  async searchWeb(query, options = {}) {
    return await this.callTool('web_search', {
      query,
      ...options
    });
  }

  async executeCode(code, language = 'python', options = {}) {
    return await this.callTool('code_execution', {
      code,
      language,
      ...options
    });
  }
}

async function main() {
  const client = new DirectToolClient('YOUR_API_KEY');

  const ragResults = await client.searchRAG(
    'API key configuration',
    'documentation',
    { top_k: 5 }
  );

  console.log('RAG Results:');
  ragResults.results.forEach(result => {
    console.log(`  - ${result.document_id}: ${result.score.toFixed(2)}`);
  });

  const webResults = await client.searchWeb('latest AI news', { count: 3 });

  console.log('\nWeb Results:');
  webResults.results.forEach(result => {
    console.log(`  - ${result.title}: ${result.url}`);
  });

  const codeResult = await client.executeCode("console.log('Hello, world!')", 'javascript');

  console.log(`\nCode Output: ${codeResult.output}`);
}

main().catch(console.error);

Use Cases

1. Document Retrieval

def find_relevant_documents(query):
    results = client.search_rag(
        query=query,
        collection="docs",
        top_k=10,
        similarity_threshold=0.7
    )

    relevant_docs = [r for r in results["results"] if r["score"] > 0.8]

    return relevant_docs

docs = find_relevant_documents("How to deploy Docker")
for doc in docs:
    print(f"{doc['metadata']['title']}: {doc['content'][:100]}...")

2. Web Research

def research_topic(topic, days_back=7):
    results = client.search_web(
        query=topic,
        count=10,
        time_range=f"{days_back}days"
    )

    summaries = []
    for result in results["results"]:
        summaries.append({
            "title": result["title"],
            "url": result["url"],
            "snippet": result["snippet"]
        })

    return summaries

news = research_topic("AI regulation", days_back=3)
for article in news:
    print(f"{article['title']}\n{article['url']}\n")

3. Data Analysis

def analyze_data(data):
    code = f"""
import json
import pandas as pd

data = {data}
df = pd.DataFrame(data)

print("Summary Statistics:")
print(df.describe())

print("\nCorrelations:")
print(df.corr())
"""

    result = client.execute_code(code)
    return result["output"]

# Example usage
data = [
    {"month": "Jan", "sales": 100},
    {"month": "Feb", "sales": 120},
    {"month": "Mar", "sales": 110}
]

analysis = analyze_data(data)
print(analysis)

4. Hybrid Search

def comprehensive_search(query):
    # Search internal docs
    rag_results = client.search_rag(query, "internal_docs", top_k=5)

    # Search web
    web_results = client.search_web(query, count=5)

    # Combine results
    combined = {
        "internal": rag_results.get("results", []),
        "external": web_results.get("results", [])
    }

    return combined

results = comprehensive_search("best practices for API security")

5. Batch Processing

def batch_search(queries):
    results = {}

    for query in queries:
        rag = client.search_rag(query, "docs", top_k=3)
        web = client.search_web(query, count=3)

        results[query] = {
            "rag": rag.get("results", []),
            "web": web.get("results", [])
        }

    return results

queries = [
    "API authentication",
    "Error handling",
    "Rate limiting"
]

batch_results = batch_search(queries)

Error Handling

Python

from requests.exceptions import RequestException

def safe_tool_call(tool_name, parameters, retries=3):
    for attempt in range(retries):
        try:
            result = client.call_tool(tool_name, parameters)
            return result
        except RequestException as e:
            if attempt == retries - 1:
                raise
            print(f"Attempt {attempt + 1} failed. Retrying...")
            time.sleep(2 ** attempt)

# Usage
try:
    result = safe_tool_call("web_search", {"query": "test"})
except Exception as e:
    print(f"All attempts failed: {e}")

JavaScript

async function safeToolCall(toolName, parameters, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      return await client.callTool(toolName, parameters);
    } catch (error) {
      if (attempt === retries - 1) throw error;
      console.log(`Attempt ${attempt + 1} failed. Retrying...`);
      await new Promise(resolve => setTimeout(resolve, 1000 * 2 ** attempt));
    }
  }
}

safeToolCall('web_search', { query: 'test' })
  .then(result => console.log(result))
  .catch(error => console.error('All attempts failed:', error));

Performance Tips

Batch Similar Queries: Process multiple related queries in one request
Use Filters: Narrow down RAG searches with metadata filters
Limit Results: Set appropriate top_k values to reduce processing time
Cache Results: Cache frequent RAG and web search results
Parallel Calls: Run independent tool calls in parallel

import asyncio
import aiohttp

async def parallel_tool_calls(queries):
    async with aiohttp.ClientSession() as session:
        tasks = []
        for query in queries:
            task = search_rag_async(session, query, "docs")
            tasks.append(task)

        results = await asyncio.gather(*tasks)
        return results

results = await parallel_tool_calls(["query 1", "query 2", "query 3"])

Troubleshooting

Tool Not Found

Problem: {"error": "Tool 'xxx' not found"}

Solution:

Verify tool name is correct
Check tool is enabled in your configuration
Review available tools list

RAG Returns No Results

Problem: RAG search returns empty results

Solution:

Verify collection name is correct
Lower similarity_threshold parameter
Increase top_k value
Check collection has uploaded documents

Web Search Fails

Problem: {"error": "Brave Search API error"}

Solution:

Verify BRAVE_SEARCH_API_KEY is configured
Check API key has sufficient quota
Review Brave Search service status

Code Execution Timeout

Problem: Code execution takes too long

Solution:

Reduce timeout parameter
Simplify code logic
Break into smaller steps
Check for infinite loops

Best Practices

Validate Inputs: Sanitize user queries before passing to tools
Set Timeouts: Always set reasonable timeouts for code execution
Handle Errors: Implement robust error handling and retry logic
Limit Results: Control top_k to avoid excessive data processing
Monitor Usage: Track tool usage for cost optimization
Use Filters: Apply metadata filters in RAG searches for precision

Next Steps

Tools Documentation - Learn about all available tools
Creating Agents - Build agents that use tools automatically
Examples - See integration examples
RAG Documentation - Upload and manage documents

When to Use Direct Tool Calling​

Quick Example​

Available Tools​

RAG Search​

Parameters​

Web Search​

Parameters​

Code Execution​

Parameters​

Python Integration​

JavaScript Integration​

Use Cases​

1. Document Retrieval​

2. Web Research​

3. Data Analysis​

4. Hybrid Search​

5. Batch Processing​

Error Handling​

Python​

JavaScript​

Performance Tips​

Troubleshooting​

Tool Not Found​

RAG Returns No Results​

Web Search Fails​

Code Execution Timeout​

Best Practices​

Next Steps​

When to Use Direct Tool Calling

Quick Example

Available Tools

RAG Search

Parameters

Web Search

Parameters

Code Execution

Parameters

Python Integration

JavaScript Integration

Use Cases

1. Document Retrieval

2. Web Research

3. Data Analysis

4. Hybrid Search

5. Batch Processing

Error Handling

Python

JavaScript

Performance Tips

Troubleshooting

Tool Not Found

RAG Returns No Results

Web Search Fails

Code Execution Timeout

Best Practices

Next Steps