Tools

Browse and manage AI tools that can be assigned to your agents. Tools extend agent capabilities with functions like web search, file operations, calculations, and custom integrations.

Overview

What Tools Do:

Extend agent capabilities with external functions
Enable web search, file operations, calculations, and more
Support custom tools for your specific use cases
Can be client-side, server-side, or hybrid

Tool Types:

Client - Runs in the browser/client environment
Server - Runs on the server/backend
Hybrid - Can run in both environments

Tool Categories:

Custom - Your own custom tools
File - File operations (read, write, upload)
Search - Web search and content extraction
Terminal - Command-line operations
Browser - Browser automation
Project - Project management operations
Web - Web-related operations

API Usage

List Tools

Browse all available tools with optional filters.

import { OblienClient } from 'oblien';
import { OblienAgents, Tools } from 'oblien/agents';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

// Option 1: Use Tools directly
const tools = new Tools(client);

// Option 2: Access through agents
const agents = new OblienAgents(client);
const toolsViaAgents = agents.tools;

// List all tools
const allTools = await tools.list();
console.log('All tools:', allTools.tools);

// Filter by type
const clientTools = await tools.list({ type: 'client' });
console.log('Client tools:', clientTools.tools);

// Filter by category
const searchTools = await tools.list({ category: 'search' });
console.log('Search tools:', searchTools.tools);

// Show only your custom tools
const myTools = await tools.list({ myCustomTools: true });
console.log('My custom tools:', myTools.tools);

// List all tools
const response = await fetch('https://api.oblien.com/ai/tools', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const allTools = await response.json();
console.log('All tools:', allTools.tools);

// Filter by type
const clientToolsResponse = await fetch('https://api.oblien.com/ai/tools?type=client', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const clientTools = await clientToolsResponse.json();
console.log('Client tools:', clientTools.tools);

# List all tools
curl -X GET "https://api.oblien.com/ai/tools" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

# Filter by type
curl -X GET "https://api.oblien.com/ai/tools?type=client" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

# Filter by category
curl -X GET "https://api.oblien.com/ai/tools?category=search" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

# Show only custom tools
curl -X GET "https://api.oblien.com/ai/tools?my_custom_tools=true" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "tools": [
    {
      "slug": "web-search",
      "tool_name": "Web Search",
      "tool_description": "Search the web for information",
      "type": "client",
      "category": "search",
      "icon": "search",
      "require_environment": false
    },
    {
      "slug": "calculator",
      "tool_name": "Calculator",
      "tool_description": "Perform mathematical calculations",
      "type": "client",
      "category": "custom",
      "icon": "calculator",
      "require_environment": false
    }
  ]
}

Search Tools

Search tools by name or description.

const tools = new Tools(client);

const results = await tools.search('search', {
  type: 'client',
  category: 'search'
});

console.log('Search results:', results.tools);

const response = await fetch('https://api.oblien.com/ai/tools/search?q=search&type=client&category=search', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const results = await response.json();
console.log('Search results:', results.tools);

curl -X GET "https://api.oblien.com/ai/tools/search?q=search&type=client&category=search" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "tools": [
    {
      "slug": "web-search",
      "tool_name": "Web Search",
      "tool_description": "Search the web for information",
      "type": "client",
      "category": "search"
    }
  ]
}

Get Tool

Get details for a specific tool.

const tools = new Tools(client);

const tool = await tools.get('web-search');
console.log('Tool details:', tool);

const response = await fetch('https://api.oblien.com/ai/tools/web-search', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const tool = await response.json();
console.log('Tool details:', tool);

curl -X GET "https://api.oblien.com/ai/tools/web-search" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "tool": {
    "slug": "web-search",
    "tool_name": "Web Search",
    "tool_description": "Search the web for the given query",
    "type": "client",
    "category": "search",
    "icon": "search",
    "input_scheme": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Search query"
        }
      },
      "required": ["query"]
    },
    "output_scheme": {
      "type": "object",
      "properties": {
        "results": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "prompt": "Search the web for the given query and return results",
    "require_environment": false
  }
}

Create Custom Tool

Create a custom tool for your agents.

const tools = new Tools(client);

const customTool = await tools.create({
  slug: 'my-custom-tool',
  tool_name: 'My Custom Tool',
  tool_description: 'A custom tool for my agents',
  type: 'client',
  category: 'custom',
  icon: 'tool',
  input_scheme: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'The query to process'
      }
    },
    required: ['query']
  },
  output_scheme: {
    type: 'object',
    properties: {
      result: {
        type: 'string',
        description: 'The processed result'
      }
    }
  },
  prompt: 'Use this tool to perform custom operations',
  require_environment: false
});

console.log('Custom tool created:', customTool);

const response = await fetch('https://api.oblien.com/ai/tools', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    slug: 'my-custom-tool',
    tool_name: 'My Custom Tool',
    tool_description: 'A custom tool for my agents',
    type: 'client',
    category: 'custom',
    icon: 'tool',
    input_scheme: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'The query to process'
        }
      },
      required: ['query']
    },
    output_scheme: {
      type: 'object',
      properties: {
        result: {
          type: 'string',
          description: 'The processed result'
        }
      }
    },
    prompt: 'Use this tool to perform custom operations',
    require_environment: false
  })
});

const customTool = await response.json();
console.log('Custom tool created:', customTool);

curl -X POST https://api.oblien.com/ai/tools \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-custom-tool",
    "tool_name": "My Custom Tool",
    "tool_description": "A custom tool for my agents",
    "type": "client",
    "category": "custom",
    "icon": "tool",
    "input_scheme": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "The query to process"
        }
      },
      "required": ["query"]
    },
    "output_scheme": {
      "type": "object",
      "properties": {
        "result": {
          "type": "string",
          "description": "The processed result"
        }
      }
    },
    "prompt": "Use this tool to perform custom operations",
    "require_environment": false
  }'

Response:

{
  "success": true,
  "tool": {
    "slug": "my-custom-tool",
    "tool_name": "My Custom Tool",
    "tool_description": "A custom tool for my agents",
    "type": "client",
    "category": "custom",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Validate Tools

Validate tool IDs before assigning them to agents.

const tools = new Tools(client);

const validation = await tools.validate(['web-search', 'calculator', 'invalid-tool']);

if (validation.valid) {
  console.log('All tools are valid:', validation.validIds);
} else {
  console.error('Invalid tools:', validation.invalidIds);
  console.error('Error:', validation.error);
}

// Validation is done client-side in SDK
// You can check if tools exist by listing them first
const response = await fetch('https://api.oblien.com/ai/tools', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const allTools = await response.json();
const toolSlugs = allTools.tools.map(t => t.slug);
const toolIdsToValidate = ['web-search', 'calculator', 'invalid-tool'];

const validIds = toolIdsToValidate.filter(id => toolSlugs.includes(id));
const invalidIds = toolIdsToValidate.filter(id => !toolSlugs.includes(id));

console.log('Valid tools:', validIds);
console.log('Invalid tools:', invalidIds);

# Validation is done client-side in SDK
# List tools first to check availability
curl -X GET "https://api.oblien.com/ai/tools" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response (SDK):

{
  "valid": false,
  "validIds": ["web-search", "calculator"],
  "invalidIds": ["invalid-tool"],
  "error": "Invalid tool IDs: invalid-tool"
}

Tool Parameters

Input Scheme

Define the parameters your tool accepts using JSON Schema:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of results",
      "default": 10
    }
  },
  "required": ["query"]
}

Output Scheme

Define the structure of your tool's response:

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string" }
        }
      }
    }
  }
}

Tool Prompt

Provide instructions for how the agent should use your tool:

Search the web for the given query and return the top results.
Use this tool when users ask about current events or need
information that requires web search.

Best Practices

Tool Design:

Use descriptive names and clear descriptions
Define clear input/output schemas
Provide helpful prompts for agents
Test tools before assigning to production agents

Tool Types:

Use client for browser-based operations
Use server for backend operations
Use hybrid for operations that can run in both

Validation:

Always validate tools before assigning to agents
Check tool availability before creating agents
Handle invalid tools gracefully

Next Steps

Agents - Assign tools to your agents
Sessions - Use agents in chat sessions

On this page