Utility Service API

A collection of utility functions for your AI applications

Overview

The Utility Service API provides a collection of useful functions that can be integrated into your AI applications. These utilities include date/time operations, GitHub integrations, web content extraction, Google search functionality, and database operations.

By leveraging these utilities, you can enhance your AI agents with powerful capabilities without having to implement them from scratch.

Base URL

https://api.agent-base.ai

Authentication

All API requests require user authentication. Currently, authentication is handled through the user_id and conversation_id parameters that must be included in each request.

Required Parameters

user_id:The unique identifier for the user making the request.
conversation_id:The unique identifier for the conversation context.

Endpoints

POST/utility

Execute a utility operation. This is the main endpoint for interacting with the Utility Service.

Request Body

{
  "operation": "string",    // Required: The utility operation to execute
  "user_id": "string",      // Required: User identifier
  "conversation_id": "string", // Required: Conversation context
  "input": object           // Optional: Input parameters for the operation
}

Response

{
  "message": "string",      // Optional: Success message
  "data": object,           // Optional: Result data
  "timestamp": "string",    // Optional: Timestamp of the operation
  "error": "string",        // Optional: Error message (if operation failed)
  "details": "string"       // Optional: Additional error details
}

GET/utilities

Get a list of all available utility operations.

Query Parameters

user_id:Required. The unique identifier for the user.
conversation_id:Required. The unique identifier for the conversation context.

Response

{
  "utilities": ["string"]   // Array of utility operation names
}

GET/utility/:id

Get detailed information about a specific utility operation.

Path Parameters

id:Required. The identifier of the utility operation.

Query Parameters

user_id:Required. The unique identifier for the user.
conversation_id:Required. The unique identifier for the conversation context.

Response

{
  "name": "string",         // Utility operation name
  "description": "string",  // Description of the utility
  "schema": {               // Input schema for the utility
    "type": "object",
    "properties": {
      // Property definitions
    },
    "required": ["string"]  // Required properties
  }
}

Available Utilities

The Utility Service provides a variety of operations. Below is a list of available utilities grouped by category.

Basic

utility_get_current_datetime

Basic

Get the current date and time in different formats

Input Schema

{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "description": "Optional date format (ISO, UTC, or custom format)",
      "default": "ISO"
    }
  }
}

GitHub

utility_github_create_codespace

GitHub

Create a GitHub Codespace

Input Schema

{
  "type": "object",
  "properties": {}
}

utility_github_destroy_codespace

GitHub

Destroy a GitHub Codespace

Input Schema

{
  "type": "object",
  "properties": {
    "codespaceId": {
      "type": "string",
      "description": "ID of the codespace to destroy"
    }
  },
  "required": [
    "codespaceId"
  ]
}

Content

utility_firecrawl_extract_content

Content

Extract content from web pages using FireCrawl API

Input Schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to fetch content from"
    },
    "onlyMainContent": {
      "type": "boolean",
      "description": "Whether to extract only the main content",
      "default": true
    }
  },
  "required": [
    "url"
  ]
}

Search

utility_google_search

Search the web using Google Search API

Input Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query to send to Google Search"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of results to return",
      "default": 5
    }
  },
  "required": [
    "query"
  ]
}

Database

utility_get_database

Database

Get information about the database

Input Schema

{
  "type": "object",
  "properties": {}
}

Examples

Below are examples of how to use the Utility Service API in different programming languages.

// Send a request to the Utility Service
const response = await fetch('https://api.agent-base.ai/utility', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    operation: 'utility_get_current_datetime',
    user_id: 'user-123',
    conversation_id: 'conv-456',
    input: { format: 'ISO' }
  })
});

const result = await response.json();
console.log(result);

Error Handling

The API uses standard HTTP response codes to indicate success or failure of requests.

Code	Description
200 - OK	The request was successful.
400 - Bad Request	The request was invalid or missing required parameters.
401 - Unauthorized	Authentication failed or was not provided.
404 - Not Found	The requested resource was not found.
500 - Internal Server Error	An error occurred on the server.

Error Response Format

{
  "error": "Error message",
  "details": "Additional error details"
}