Skip to content

AI Tools Service Overview

The AI Tools service is a critical component that enables AI agents to perform real-world actions through integration with third-party services. It acts as a middleware layer between the AI Engine and various external APIs, providing a standardized interface for AI agents to execute specific tasks during conversations.

Core Responsibilities

  • Implement tool logic for AI agent actions
  • Handle authentication and API calls to third-party services
  • Process and validate tool parameters
  • Return structured responses to the AI Engine

Architecture Overview

sequenceDiagram participant AE as AI Engine participant AT as AI Tools participant TP as Third Party API Note over AE: Fetch OAuth tokens from DB AE->>AT: Tool execution request with OAuth tokens AT->>TP: API call with auth TP-->>AT: Service response AT->>AE: Processed result

Tool Implementation Pattern

Each tool in the AI Tools service follows a consistent pattern:

  1. Endpoint Definition: Tools are exposed as REST endpoints
  2. Parameter Validation: Validate and process incoming parameters
  3. Authentication: Handle OAuth token retrieval and management
  4. API Integration: Make calls to third-party services
  5. Response Processing: Format and return results to AI Engine

Example: HubSpot Meeting Booking Tool

sequenceDiagram participant Agent as AI Agent participant Engine as AI Engine participant Tools as AI Tools participant HubSpot as HubSpot API Agent->>Engine: "I'll book a meeting" Note over Engine: Fetch OAuth tokens from DB Engine->>Tools: POST /tools/hubspot/book-meeting with OAuth tokens Note over Tools: Validate parameters Tools->>HubSpot: Create meeting API call HubSpot-->>Tools: Meeting details Tools->>Engine: Success + meeting link Engine->>Agent: Meeting booked successfully

Available Tools

The service can implement various tools that enable AI agents to:

  1. Calendar Management

    • Book meetings (HubSpot)
    • Check availability
    • Schedule appointments

  2. CRM Operations

    • Create/update contacts
    • Add notes to deals
    • Update ticket status

  3. Communication

    • Send emails
    • Schedule follow-ups
    • Send SMS notifications

Tool Development

1. Adding a New Tool

To implement a new tool:

  1. Create a new endpoint in the AI Tools service
  2. Define the required parameters and validation
  3. Implement third-party API integration
  4. Add error handling and response formatting
  5. Register the tool with AI Engine

2. Required Components

Each tool implementation should include:

  • Input parameter schema
  • Authentication handling
  • Error handling
  • Response formatting
  • Documentation
  • Usage examples

Security Considerations

  1. Authentication

    • OAuth token management
    • Secure token storage
    • Token refresh handling

  2. Access Control

    • Tool-level permissions
    • Rate limiting
    • Request validation

  3. Data Protection

    • Sensitive data handling
    • Audit logging
    • Error masking

Integration with AI Engine

The AI Engine integrates with AI Tools through:

  1. Tool Registration

    • Tools are registered with specific capabilities
    • Parameter schemas are defined
    • Response formats are documented

  2. Runtime Integration

    • AI Engine calls tools via REST API
    • Responses are incorporated into conversation context
    • Errors are handled gracefully

Error Handling

You are expected to implement standardized error handling, with a message so that the AI Engine can understand and react accordingly.

Monitoring and Logging

The service includes:

  1. Metrics

    • Tool usage statistics
    • Success/failure rates
    • Response times
    • Error rates

  2. Logging

    • Tool invocations
    • Authentication attempts
    • API call details
    • Error details