ToolSelector Component

Overview

The ToolSelector component is the central UI system for managing tool selection, configuration, and compatibility in the Aitana Labs frontend. It provides a comprehensive interface for users to discover, configure, and enable AI assistant tools ranging from data sources to output formatting and advanced behaviors.

Location: src/components/tools/ToolSelector.tsx
Dependencies: ToolConfigurator.tsx, ToolContext.tsx, Firebase authentication, tag-based access control
Lines of Code: ~1,460

Core Functionality

Tool Management

  • 24 Available Tools across 4 main categories
  • Dynamic filtering by category and tag-based access control
  • Real-time configuration with validation
  • Compatibility checking and conflict resolution
  • Preview demos for each tool

Architecture Components

interface ToolSelectorProps {
  selectedTools: string[];
  onChange: (tools: string[]) => void;
  toolConfigs?: Record<string, Record<string, any>>; 
  onConfigChange?: (toolId: string, config: Record<string, any>) => void; 
  defaultTools?: string[];
  defaultOpen?: boolean;
  availableAssistants?: AssistantDisplay[];
}

Tool Categories

Data Sources (9 tools)

Tools that provide external data and content to AI assistants:

  • Data Store Search (vertex_search) - Vertex AI Search DataStores
  • Knowledge Search (vertex_search_app) - Vertex AI Search Apps in Sidebar
  • Initial Data Store Search (vertex_search_first) - Generic search before first impression
  • Google Web Search (google_search_retrieval) - Real-time Google search access
  • File Browser (file-browser) - Select files from cloud storage
  • Document Search Agent (document_search_agent) - AI-powered document discovery and extraction
  • Chat Memory (user-history) - Access to your previous conversations
  • Company Memory (domain-history) - Access previous conversations across the company
  • Global Memory (global-history) - Access global previous conversations
  • Web URL Reader (url_processing) - Extract and analyze web content
  • MCP Connection (mcp) - Connect to MCP Services

Output (7 tools)

Tools that enhance response formatting and visualization:

  • Content Preview (preview) - Preview documents and media files
  • Text Highlights (highlights) - Highlight key phrases in responses
  • Data Visualization (plots) - Generate charts and graphs using Recharts
  • Network Graphs (network) - Visualize relationships and workflows
  • Alert Messages (alerts) - Display important notifications
  • Tooltips (tooltips) - Show contextual information
  • Dynamic UI Components (dynamic-ui) - Generate interactive UI elements dynamically
  • Interactive Artifacts (artifacts) - Generate interactive code components and applications

Integration (3 tools)

Tools that connect with external systems and services:

  • Code Execution (code_execution) - Execute code to help inform answers
  • Aitana Agents (aitana-agent) - Call other Aitana Assistants
  • MCP Connection (mcp) - Connect to MCP Services

Behaviour (5 tools)

Tools that modify AI assistant behavior and capabilities:

  • Advanced Models (advanced_models) - Access enhanced reasoning capabilities (Anthropic 4.0, Gemini 2.5, etc.)
  • Suppress First Impression (no-first-impression) - Disables AI tool selection
  • Suppress Tool Streaming (suppress-tool-streaming) - Tools will not stream intermediate answers
  • Echo (only-echo) - Will only echo user input

Key Features

Tag-Based Access Control

The ToolSelector integrates with Firebase authentication and tag-based permissions:

// Tool access is controlled by tags
interface Tool {
  id: string;
  name: string;
  description: string;
  category: string;
  icon: React.FC<{ className?: string }>;
  demo: React.ComponentType;
  configFields?: TagAwareConfigField[];
  tags?: string[]; // Tags for access control
}

Common Tags:

  • admin-tools - Administrative access required
  • beta-testers - Beta testing access
  • ONE - Our New Energy company access
  • dev-team - Development team access

Tool Configuration System

Each tool can define configuration fields that are filtered by user access:

interface ConfigField {
  key: string;
  label: string;
  type: 'text' | 'number' | 'select' | 'checkbox' | 'radio' | 'assistant_multiselect';
  placeholder?: string;
  options?: TagRestrictedOption[];
  required?: boolean;
  defaultValue?: any;
}

Compatibility Management

The component includes sophisticated logic for tool compatibility:

Always Incompatible with no-first-impression:

  • Chat Memory tools (user-history, domain-history, global-history)
  • Code Execution (code_execution)

Conditionally Incompatible:

  • Search tools (google_search_retrieval, vertex_search, vertex_search_first) - Compatible only when configured with hardcoded queries

Demo System

Each tool includes an interactive demo component to preview functionality:

interface Tool {
  demo: React.ComponentType; // Live preview component
}

Integration Points

  1. ToolConfigurator (src/components/tools/ToolConfigurator.tsx)
    • Handles individual tool configuration
    • Validates required fields
    • Processes custom configuration logic
    • Manages assistant selection for multi-agent tools
  2. ToolContext (src/contexts/ToolContext.tsx)
    • Provides React context for tool configurations
    • Shares tool state across components
  3. Tool Orchestrator System (Backend)
    • Executes selected tools on the backend
    • Manages tool permissions and configurations
    • Handles streaming and parallel execution

Backend Integration

The selected tools and configurations are sent to the backend via:

API Endpoint: /vac/assistant/<assistantId>
Tool Execution: backend/tools/tool_orchestrator.py
Permissions: backend/tool_permissions.py

# Backend receives tool configuration
{
  "tools_to_use": ["vertex_search", "plots"],
  "toolConfigs": {
    "vertex_search": {
      "datastore_id": "aitana_public_welcome",
      "no-stream": false
    }
  }
}

Firebase Integration

The component integrates deeply with Firebase for:

  • Authentication: User access control
  • Tag Management: Permission-based tool filtering
  • Assistant Management: Available assistants for multi-agent tools
// Firebase integration points
const [user, setUser] = React.useState(getAuth().currentUser);
const [availableTags, setAvailableTags] = React.useState<Tag[]>([]);
const filteredTools = AVAILABLE_TOOLS.filter(tool => 
  checkTagAccess(tool.tags, availableTags, user)
);

Usage Examples

Basic Implementation

import { ToolSelector } from '@/components/tools';

function AssistantCreator() {
  const [selectedTools, setSelectedTools] = useState(['preview', 'highlights']);
  const [toolConfigs, setToolConfigs] = useState({});

  return (
    <ToolSelector
      selectedTools={selectedTools}
      onChange={setSelectedTools}
      toolConfigs={toolConfigs}
      onConfigChange={(toolId, config) => {
        setToolConfigs(prev => ({ ...prev, [toolId]: config }));
      }}
      defaultTools={['preview', 'highlights', 'plots', 'alerts']}
      defaultOpen={false}
    />
  );
}

Advanced Multi-Agent Configuration

<ToolSelector
  selectedTools={selectedTools}
  onChange={setSelectedTools}
  toolConfigs={toolConfigs}
  onConfigChange={handleConfigChange}
  availableAssistants={userAssistants} // For aitana-agent tool
  defaultTools={['aitana-agent', 'advanced_models']}
/>

Access-Controlled Environment

// Tools automatically filtered by user's tags
// Admin users see all tools, others see filtered subset
<ToolSelector
  selectedTools={selectedTools}
  onChange={setSelectedTools}
  // Tool visibility determined by Firebase auth + tags
/>

Configuration Examples

Data Store Search Tool

{
  "vertex_search": {
    "datastore_id": "aitana_public_welcome",
    "datastore_filter": "vector_name: ANY(\"aitana3\")",
    "hardcode-query": "AI documentation", // Optional preset query
    "no-stream": false
  }
}

Multi-Agent Tool

{
  "aitana-agent": {
    "assistant_ids": "assistant-1, assistant-2",
    "call_strategy": "sequential", // or "parallel"
    "max_iterations": "3",
    "emissary_configs": [
      {
        "assistant_id": "assistant-1",
        "name": "Data Analyst",
        "template_id": "data-analysis",
        "tools": ["plots", "vertex_search"]
      }
    ]
  }
}

File Browser Tool

{
  "file-browser": {
    "bucketUrl": "aitana-public-bucket", // or custom bucket
    "rootPath": "/documents",
    "no-stream": false
  }
}

State Management

Tool Selection State

// Managed tool selection with validation
const [selectedTools, setSelectedTools] = useState<string[]>([]);

// Automatic compatibility checking
const toggleTool = (toolId: string) => {
  // Check compatibility with existing tools
  // Handle no-first-impression conflicts
  // Validate configuration requirements
};

Configuration State

// Tool-specific configurations
const [toolConfigs, setToolConfigs] = useState<Record<string, Record<string, any>>>({});

// Configuration validation
const isToolConfigured = (toolId: string): boolean => {
  const tool = AVAILABLE_TOOLS.find(t => t.id === toolId);
  const config = toolConfigs[toolId] || {};
  return tool?.configFields?.every(field => /* validation logic */);
};

Performance Considerations

Lazy Loading

  • Tool demos are rendered only when selected
  • Configuration components mount only when needed
  • Tag filtering happens client-side after initial load

Optimization

  • React.memo used for expensive computations
  • Configuration validation is debounced
  • Tool compatibility checking is memoized

Testing

The ToolSelector component has comprehensive test coverage:

Test Files:

  • src/components/__tests__/ToolSelector-tag-integration.test.tsx
  • src/components/__tests__/ToolSelector-tag-config-fields.test.tsx
  • src/components/__tests__/ToolSelector-document-search-agent-tag-filtering.test.tsx

Test Coverage:

  • Tag-based access control
  • Tool configuration validation
  • Compatibility logic
  • State management
  • Integration with Firebase
# Run ToolSelector tests
npm test src/components/__tests__/ToolSelector*.test.tsx

Common Issues & Troubleshooting

Configuration Not Saving

  • Ensure all required fields are filled
  • Check if user has permission for selected options
  • Verify Firebase authentication state

Tools Not Appearing

  • Check user’s tag assignments in Firebase
  • Verify tool tags match user permissions
  • Check console for authentication errors

Compatibility Conflicts

  • Review no-first-impression compatibility rules
  • Ensure search tools have hardcoded queries when needed
  • Check tool requirement documentation

Development Guide

Adding New Tools

  1. Define the tool in AVAILABLE_TOOLS array: 
    {
  id: 'new-tool',
  name: 'New Tool',
  description: 'Tool description',
  category: 'Data Sources',
  icon: IconComponent,
  demo: DemoComponent,
  configFields: [...],
  tags: ['beta-testers'] // Optional access control
}
  2. Implement backend support in /backend/tools/
  3. Add configuration logic in ToolConfigurator
  4. Update documentation and tests

For detailed guidance, see: How to Add Tools to Aitana

Modifying Existing Tools

  1. Update tool definition in AVAILABLE_TOOLS
  2. Modify configuration fields if needed
  3. Update compatibility logic if necessary
  4. Test thoroughly with different user permission levels

API Reference

Props

Prop Type Required Description
selectedTools string[] Yes Array of selected tool IDs
onChange (tools: string[]) => void Yes Callback when tool selection changes
toolConfigs Record<string, Record<string, any>> No Tool configuration objects
onConfigChange (toolId: string, config: Record<string, any>) => void No Callback when tool config changes
defaultTools string[] No Default tools to select initially
defaultOpen boolean No Whether component starts expanded
availableAssistants AssistantDisplay[] No Available assistants for multi-agent tools

Exports

export { default as ToolSelector, AVAILABLE_TOOLS } from './ToolSelector';
export type { Tool } from './ToolSelector';

File Structure

src/components/tools/
├── ToolSelector.tsx      # Main component (1,460 lines)
├── ToolConfigurator.tsx  # Configuration component (547 lines)
└── index.ts              # Exports

src/contexts/
└── ToolContext.tsx       # React context (26 lines)

backend/tools/
├── tool_orchestrator.py  # Backend orchestration
├── tool_permissions.py   # Permission management
└── [individual tools]/   # Tool implementations